docs(adr): deprecate per-org installation mode

[ggallen]

Closes #2350

Summary

• Add ADR proposing deprecation and removal of the per-org installation mode in favor of per-repo (ADR 0033) as the sole supported model.
• References ADR-0038 (universal harness access) and ADR-0045 (forge-portable harness schema) which together eliminate the .fullsend config repo's role as resource distribution point and customization hub.
• Includes a detailed implementation plan in docs/plans/deprecate-per-org-install.md covering a 15-PR rollout across two phases:
  • Phase 1 (v1.x): Deprecation warnings, documentation updates, migration guide, fullsend admin migrate command, migration e2e test
  • Phase 2 (v2.0): Remove all per-org CLI commands, layers, config structs, scaffold templates, forge methods, dispatch infrastructure, mint validation patterns, reusable workflow branching, and e2e tests

Key points

• Per-repo achieves feature parity with per-org while eliminating content exposure risk, enrollment machinery, three-level workflow nesting, and dual code paths
• ADR-0045's base harness composition replaces the .fullsend config repo as the mechanism for sharing org defaults
• ADR-0038's URL-based resource references replace the config repo as the resource distribution point
• Detailed migration plan covers per-repo migration steps, org-level cleanup, rollback procedure, and --all automation for large orgs
• ADR number may need renumbering before merge via /renumber-adr

Intentional deferrals

• docs/architecture.md update deferred to Phase 1 PR 2. AGENTS.md requires updating docs/architecture.md when an ADR is accepted. This is intentionally deferred so architecture updates ship alongside the deprecation warnings in PR 2, rather than before users can see them. The implementation plan documents this deferral with rationale.

Test plan

• make lint passes (ADR status, number, frontmatter linters)
• ADR number verified against target branch at merge time via /renumber-adr
• Review ADR content for accuracy against current codebase
• Review implementation plan PR dependency graph for completeness

🤖 Generated with Claude Code

[github-actions]

Site preview

Preview: https://ddc744ad-site.fullsend-ai.workers.dev

Commit: 246287b937738d8675220c5daf5bb9889384fc48

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 3:38 PM UTC · Completed 3:53 PM UTC
Commit: 622a47f · View workflow run →

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-review]

Review

Findings

Medium

• [stale-doc] docs/architecture.md — ADR 0044 has status "Accepted" but docs/architecture.md has not been updated to reflect the deprecation of per-org installation mode. AGENTS.md line 100 requires: "When status is Accepted, update docs/architecture.md and related problem docs in the same PR per the writing-adrs skill." The current docs/architecture.md extensively describes the per-org model (layer stack with enrollment, .fullsend config repo, cross-repo dispatch, repo-maintenance workflow) without any deprecation context. The implementation plan explicitly defers this to Phase 1 PR 2 with the rationale that architecture updates should ship alongside deprecation warnings — a reasonable deferral but a deviation from AGENTS.md policy.
  Remediation: Either update docs/architecture.md in this PR to add deprecation annotations alongside per-org references, or document in the PR description why the deferral to PR 2 is intentional and acceptable.

Previous run

Review

Findings

Medium

• [internal-consistency] docs/ADRs/0044-deprecate-per-org-installation-mode.md:352 — The sentence "ADR 0045 is accepted and its implementation (Phases 1–4) is complete" is factually incorrect. The Phase 4 implementation plan (docs/plans/adr-0045-forge-portable-harness-phase4.md) shows PR 1 is still "In Review (feat(harness): require role field in Validate() #2446)" and PR 3 has no shipped marker; only PRs 2 (refactor(config): stop writing agents block during install (ADR-0045 Phase 4, PR 2) #2447) and 4 (refactor(config): remove OrgConfig.Agents field (ADR-0045 Phase 4 PR 4) #2517) are shipped. The same inaccurate claim appears in the plan’s context section (docs/plans/deprecate-per-org-install.md:662), and the v2.0 release checklist (docs/plans/deprecate-per-org-install.md:1612) marks "[x] Confirm ADR 0045 Phases 1–4 are merged and functional" as already checked.
  Remediation: Change the sentence to accurately reflect the status, e.g., "ADR 0045 is accepted and its implementation is in progress (Phases 1–3 complete, Phase 4 partially shipped)." Update the plan’s context section to match, and change the release checklist from [x] to [ ] until Phase 4 is actually complete.

Low

• [logic-error] docs/plans/deprecate-per-org-install.md:1060 — PR 8 proposes adding StatusNotifications *StatusNotificationConfig directly to the renamed Config struct (flattened), creating a YAML schema change relative to OrgConfig where it is nested under defaults:. Since per-org configs are being removed entirely in Phase 2 (v2.0 breaking change), backward compatibility with the nested format is moot — but the plan should note this is intentional.

• [stale-reference] docs/plans/deprecate-per-org-install.md — PR 10 removes PerRepoGuardVar from the codebase but the plan does not mention that the actual GitHub Actions variable (FULLSEND_PER_REPO_INSTALL) referenced in documentation files would become stale after v2.0. PR 15’s grep pattern per.repo would catch FULLSEND_PER_REPO_INSTALL, but explicit coverage in the plan would reduce implementation ambiguity.

• [edge-case] docs/plans/deprecate-per-org-install.md:1098 — After PR 8 renames both DefaultAgentRoles() and PerRepoDefaultRoles() to DefaultRoles(), github.go line 111 (conditionally sets PerRepoDefaultRoles()) and line 132 (flag default DefaultAgentRoles()) would both call DefaultRoles(), making the conditional at line 111 dead code. The plan should note this for cleanup.

• [stale-doc] docs/architecture.md — ADR 0044 has status "Accepted" but docs/architecture.md has not been updated. AGENTS.md line 100 requires updating docs/architecture.md in the same PR. The implementation plan explicitly defers this to Phase 1 PR 2 with the rationale that architecture updates should ship alongside deprecation warnings — a reasonable deferral but a deviation from AGENTS.md policy.

• [stale-doc] docs/reference/installation.md, docs/reference/github-setup.md, docs/guides/getting-started/org-mode.md — These guides present per-org mode without deprecation context. All are explicitly tracked for update in Phase 1 PR 2 per the implementation plan. No action needed in this PR.

Previous run (2)

Review

Findings

Medium

• [stale-doc] docs/architecture.md — ADR 0044 has status "Accepted" but docs/architecture.md has not been updated to reflect the deprecation of per-org installation mode. AGENTS.md line 100 requires: "When status is Accepted, update docs/architecture.md and related problem docs in the same PR per the writing-adrs skill." The implementation plan defers this to PR 2 with a rationale that architecture updates should ship alongside deprecation warnings — this is a reasonable deferral but contradicts the AGENTS.md requirement.
  Remediation: Update docs/architecture.md in this PR to comply with AGENTS.md line 100, or document in the PR description why the deferral to PR 2 is intentional and acceptable.

• [internal-consistency] docs/plans/deprecate-per-org-install.md — PR 7 references removing a ConfigRepoName branch at "~lines 34-36" in vendor.go, but the actual functions containing ConfigRepoName checks are prepareVendorFiles() (line 95) and vendorPathPrefix() (line 224). Additionally, removeStaleVendoredAssets() (line 230) has its own per-repo branching that is not mentioned. An implementer following the plan as written would miss these functions, leaving stale ConfigRepoName references.
  Remediation: Update PR 7's vendor.go section to reference prepareVendorFiles() (line 95), vendorPathPrefix() (line 224), and removeStaleVendoredAssets() (line 230).

• [internal-consistency] docs/plans/deprecate-per-org-install.md:1103 — PR 8 identifies that run.go accesses orgCfg.Defaults.StatusNotifications (line 1977) but offers two options without choosing one: either add Defaults RepoDefaults to the renamed Config struct or migrate to a separate org-level config source. PerRepoConfig has no Defaults sub-struct, and StatusNotificationConfig is currently only accessible through OrgConfig.Defaults. This is an unresolved design decision that will block PR 8 implementation.
  Remediation: Choose one approach and document it: either add a StatusNotifications *StatusNotificationConfig field directly to the renamed Config struct (flattened), or make status notifications use a hardcoded default in per-repo mode.

• [logic-error] docs/plans/deprecate-per-org-install.md:1042 — PR 8 identifies that NewPerRepoConfig() (config.go:271) falls back to DefaultAgentRoles() when roles is nil, but this is actually a latent bug: DefaultAgentRoles() returns roles including the per-org fullsend dispatch role and excludes fix, while PerRepoDefaultRoles() returns the correct per-repo set. The plan inherits this bug via the rename but does not flag it as a behavioral change. Existing per-repo installs generated with nil roles have the wrong defaults.
  Remediation: Add a note in the PR 8 section that this fixes a latent bug in NewPerRepoConfig() and add a release note that existing per-repo configs may contain the unused fullsend role (harmless but unnecessary).

Low

• [stale-reference] docs/ADRs/0044-deprecate-per-org-installation-mode.md — The BREAKING CHANGE trailer references fullsend admin migrate which is removed in Phase 2 (PR 6). The phasing is actually correct — users run migrate on v1.x before upgrading to v2.0 — but the wording could be clearer about this sequencing dependency.

• [stale-reference] docs/plans/deprecate-per-org-install.md — PR 10 removes PerRepoGuardVar from the codebase definition but the plan does not address cleanup of the actual GitHub Actions variable (FULLSEND_PER_REPO_INSTALL) that has been set on repos via the API. After v2.0 these become orphaned.

• [stale-reference] docs/ADRs/0044-deprecate-per-org-installation-mode.md:352 — The sentence "ADR 0045 is accepted and its implementation (Phases 1–4) is complete" reads as a present-tense factual claim, but ADR 0045 Phase 4 appears still in progress. Rephrasing as a prerequisite statement ("must be complete") would be clearer.

• [stale-doc] docs/plans/deprecate-per-org-install.md — Multiple documentation files (installation.md, github-setup.md, org-mode.md, cli-internals.md, infrastructure-reference.md) reference per-org without deprecation context. Tracked by Phase 1 PR 2 — no immediate action needed in this PR.

• [edge-case] docs/plans/deprecate-per-org-install.md — PR 7 says to rename VendoredBinaryPathPerRepo to VendoredBinaryPath in vendorbinary.go, but both constants are defined in vendor.go (lines 17 and 19), not vendorbinary.go. Additionally, vendor.go in internal/cli/ references both constants at lines 100-102 and 236-239 — these callers must be updated in the same PR.

Previous run (3)

Review

Findings

Medium

• [internal-consistency] docs/plans/deprecate-per-org-install.md — The v2.0 release checklist's BREAKING CHANGE trailer instructs users to "Migrate to per-repo mode using fullsend admin migrate", but PR 6 explicitly removes newMigrateCmd(), runMigrate(), and deletes internal/cli/migrate.go. By v2.0, the migrate command no longer exists. The breaking change message directs users to a command that does not exist in the version they just installed.
  Remediation: Change the BREAKING CHANGE trailer to reference fullsend admin install <owner/repo> instead of fullsend admin migrate, or instruct users to migrate using v1.x before upgrading to v2.0.

• [architectural-coherence] docs/architecture.md — ADR 0044 has status Accepted but docs/architecture.md was not updated in this PR. Per AGENTS.md: "When status is Accepted, update docs/architecture.md and related problem docs in the same PR per the writing-adrs skill." The implementation plan explicitly defers this to Phase 1 PR 2.
  Remediation: Update docs/architecture.md to reflect ADR 0044's deprecation decision in this PR, or document the justification for deferring to PR 2.

Low

• [internal-consistency] docs/plans/deprecate-per-org-install.md — PR 8 describes the StatusNotifications migration ambiguously. run.go:1974 accesses orgCfg.Defaults.StatusNotifications, but PerRepoConfig has no Defaults sub-struct. The plan offers two options (add the field to the renamed Config struct, or remove the code path) but does not choose one.

• [edge-case] docs/plans/deprecate-per-org-install.md — PR 10 removes PerRepoGuardVar constant but does not discuss cleanup of already-deployed FULLSEND_PER_REPO_INSTALL variables on existing repos after v2.0 ships. No tooling exists after v2.0 to clean up these inert-but-orphaned variables.

• [edge-case] docs/plans/deprecate-per-org-install.md — PR 8 changes the default roles from DefaultAgentRoles() (includes fullsend) to DefaultRoles() (excludes fullsend). The plan correctly identifies this as intentional but does not note whether existing per-repo config.yaml files containing the fullsend role need a release note.

• [architectural-coherence] docs/ADRs/0044-deprecate-per-org-installation-mode.md — The ADR states "ADR 0045 is accepted and its implementation (Phases 1–4) is complete" and the release checklist marks this as checked. Verify this claim against actual implementation state before beginning Phase 2 work.

• [stale-reference] docs/reference/installation.md, docs/reference/github-setup.md, docs/guides/getting-started/org-mode.md, docs/guides/dev/cli-internals.md, docs/guides/infrastructure/infrastructure-reference.md — These guides present per-org mode without deprecation context. All are explicitly planned for update in Phase 1 PR 2 per the implementation plan.

Previous run (4)

Review

Findings

Medium

• [internal-consistency] docs/ADRs/0044-deprecate-per-org-installation-mode.md — In the Decision section, Phase 2's first bullet reads "PRs 5–6: Remove per-org CLI commands and layer stack" but PR 5 is the migration e2e test (Phase 1). The companion implementation plan's dependency graph shows Phase 2 starting at PR 6 (CLI removal) and PR 7 (layer removal). The ADR's "PRs 5–6" should be "PRs 6–7". This off-by-one means Phase 2 appears to list 11 PR slots (5–15) while claiming "10 PRs," and it incorrectly pulls a Phase 1 PR into the Phase 2 description.
  Remediation: Change "PRs 5–6" to "PRs 6–7" in the ADR's Phase 2 bullet list to match the implementation plan.

Low

• [logic-error] docs/plans/deprecate-per-org-install.md — PR 8 instructs migrating AllowedRemoteResources from OrgConfig into the renamed Config struct. The plan also mentions updating the config.ParseOrgConfig() call at run.go:1974 "for StatusNotifications", but this is ambiguous — PerRepoConfig (which becomes Config) has no Defaults sub-struct and no StatusNotifications field. Clarify in PR 8's scope that StatusNotifications must be added to the new Config struct, not just that the call site needs updating.

• [edge-case] docs/plans/deprecate-per-org-install.md — PR 10 removes PerRepoGuardVar constant and its creation in the per-repo install path, but does not discuss cleanup of already-deployed FULLSEND_PER_REPO_INSTALL variables on existing repos after v2.0 ships. The migration command (PR 4) is removed in PR 6, so no tooling exists after v2.0 to clean up these inert-but-orphaned variables. Consider adding a note in the v2.0 release checklist or migration guide.

• [edge-case] docs/plans/deprecate-per-org-install.md — The plan correctly identifies the behavioral change when NewPerRepoConfig() falls back to DefaultRoles() (formerly PerRepoDefaultRoles()) instead of DefaultAgentRoles(), and calls it intentional. However, it does not note whether existing per-repo config.yaml files that already contain the fullsend role (from the current default) need a migration step or release note.

• [naming-alignment] docs/plans/deprecate-per-org-install.md — Plan says ValidRoles() should retain fullsend after v2.0 because existing configs may reference it, stating "The role becomes unused but still valid." This is clear rationale but does not specify whether this is permanent or whether a future cleanup should remove it.

• [architectural-coherence] docs/ADRs/0044-deprecate-per-org-installation-mode.md — The ADR states "ADR 0045 is accepted and its implementation (Phases 1–4) is complete" as a Phase 2 prerequisite. The release checklist marks this as checked. Verify this claim against actual implementation state before beginning Phase 2 work.

• [architectural-coherence] docs/ADRs/0044-deprecate-per-org-installation-mode.md — The ADR discusses the loss of centralized allowed_remote_resources enforcement in three separate sections (Context, Cons §1, Consequences). The trade-off is well-documented. Consider whether a future enhancement for org-level allowlist inheritance should be noted as a potential follow-up in Option C or Consequences.

Previous run (5)

Review

Findings

Medium

• [logic-error] docs/plans/deprecate-per-org-install.md — PR 8 removes OrgConfig entirely and renames PerRepoConfig to Config, but the plan does not account for AllowedRemoteResources. This field exists only on OrgConfig (config.go:80), not on PerRepoConfig. Runtime code in run.go (lines 189, 192, 201, 205, 237, 243) and lock.go (lines 170, 173, 181, 185, 264, 268) accesses AllowedRemoteResources via tryLoadOrgConfig()/requireOrgConfig() in orgconfig.go, which calls config.ParseOrgConfig(). None of these files (orgconfig.go, run.go, lock.go) appear in the plan's 15-PR breakdown. If PR 8 deletes OrgConfig without migrating AllowedRemoteResources into the renamed Config struct and updating these callers, URL-based harness resolution and remote resource validation will break at compile time.
  Remediation: Add to PR 8's scope: (1) add AllowedRemoteResources []string to the renamed Config struct and ParseConfig(), (2) update orgconfig.go to use config.ParseConfig() instead of config.ParseOrgConfig() and rename functions/file accordingly, (3) list run.go, lock.go, and orgconfig.go as files requiring updates.

Low

• [internal-consistency] docs/ADRs/0044-deprecate-per-org-installation-mode.md — The ADR's Decision section says "Phase 2 (15 PRs, ordered by dependency)" but Phase 2 contains PRs 6–15 (10 PRs). The number 15 is the total across both phases. Read after "Phase 1 (5 PRs)", a reader expects the Phase 2 parenthetical to indicate Phase 2's count specifically.

• [cross-reference-consistency] docs/guides/getting-started/org-mode.md — Guide documents per-org installation without deprecation notice. Planned for Phase 1 PR 2.

• [cross-reference-consistency] docs/reference/installation.md — Installation reference presents per-org and per-repo as equal alternatives without deprecation notice. Planned for Phase 1 PR 2.

• [cross-reference-consistency] docs/guides/infrastructure/private-repositories.md — Guide documents per-org as supported option without deprecation notice. Planned for Phase 1 PR 2.

---

Labels: PR adds an ADR and implementation plan for deprecating the per-org installation mode — touches installation architecture documentation.

Previous run (6)

Looks good to me

Findings

Low

• [cross-reference-consistency] docs/guides/getting-started/org-mode.md — Guide documents per-org installation without deprecation notice. Planned for Phase 1 PR 2.

• [cross-reference-consistency] docs/reference/installation.md — Installation reference presents per-org and per-repo as equal alternatives without deprecation notice. Planned for Phase 1 PR 2.

• [cross-reference-consistency] docs/guides/infrastructure/private-repositories.md — Guide documents per-org as supported option without deprecation notice. Planned for Phase 1 PR 2.

Info

• [living-document-update-deferred] docs/architecture.md — Per AGENTS.md, accepted ADRs should update docs/architecture.md in the same PR. The implementation plan explicitly defers this to Phase 1 PR 2. A human reviewer should decide whether to enforce this policy or grant an exception for this ADR-only PR.

Previous run (7)

Review

Findings

Medium

• [behavioral-change] docs/plans/deprecate-per-org-install.md:1167 — PR 8's caller update list for config.DefaultAgentRoles() in admin.go lists lines 551, 1617, 1624, and 1792 as needing updates. However, lines 1617, 1624 (runUninstall()) and 1792 (runAnalyze()) are deleted by PR 6. Only line 551 (the --agents flag default in newInstallCmd()) survives. Additionally, the plan flags the behavioral consequence of this rename for mint.go but not for the --agents flag default: the default agent set changes from fullsend,triage,coder,review,retro,prioritize to triage,coder,review,fix,retro,prioritize.
  Remediation: Remove lines 1617, 1624, and 1792 from the PR 8 caller list (deleted by PR 6). Add a behavioral consequence note for line 551 similar to the mint.go note.

• [stale-reference] docs/plans/deprecate-per-org-install.md:1336 — PR 10 lists PerRepoGuardVar references at admin.go lines 455, 682, 826, 987 as "per-repo code paths, not removed by per-org CLI cleanup in PR 6." Line 455 is inside the if enrollAll { branch (per-org enrollment discovery), which IS removed by PR 6. The remaining three references (682, 826, 987) are correctly classified as per-repo paths.
  Remediation: Remove line 455 from PR 10's guard variable list — it is already covered by PR 6.

• [stale-reference] docs/plans/deprecate-per-org-install.md:1195 — PR 8's test update section lists admin_test.go lines 51, 1774, 1811, 1829, and 1837 for config.DefaultAgentRoles() updates. Lines 1774, 1811, 1829, and 1837 are inside per-org test functions calling runDryRun() / runInstall(), both deleted by PR 6. Only line 51 (TestInstallCmd_Flags) survives.
  Remediation: Update the PR 8 admin_test.go line list to only include line 51; note that lines 1774+ are deleted by PR 6.

Low

• [stale-reference] docs/plans/deprecate-per-org-install.md:1177 — PR 8 notes internal/forge/github/types.go has its own DefaultAgentRoles() (line 39) and says to "evaluate whether to rename for consistency." The function is only referenced by its own test (types_test.go:12), making it effectively dead code after per-org removal. The plan leaves this as an open evaluation rather than a concrete decision, risking the reference persisting through all 15 PRs.

• [logic-error] docs/plans/deprecate-per-org-install.md:1148 — The plan correctly identifies NewPerRepoConfig() falling back to DefaultAgentRoles() as fixed by the rename. However, it does not address whether ValidRoles() (config.go:93-95, which includes fullsend) should be updated. If ValidRoles() removes fullsend, existing per-repo configs containing that role will fail validation. If retained, fullsend becomes a valid but unused role.

• [cross-reference-consistency] docs/guides/getting-started/org-mode.md — Guide documents per-org installation without deprecation notice. Planned for Phase 1 PR 2.

• [cross-reference-consistency] docs/reference/installation.md — Installation reference presents per-org and per-repo as equal alternatives without deprecation notice. Planned for Phase 1 PR 2.

• [cross-reference-consistency] docs/guides/infrastructure/private-repositories.md — Guide documents per-org as supported option without deprecation notice. Planned for Phase 1 PR 2.

Info

• [living-document-update-deferred] docs/architecture.md — Per AGENTS.md, accepted ADRs should update docs/architecture.md in the same PR. The implementation plan explicitly defers this to Phase 1 PR 2. A human reviewer should decide whether to enforce this policy or grant an exception for this ADR-only PR.

Previous run (8)

Review

Findings

Medium

• [incomplete-removal] docs/plans/deprecate-per-org-install.md:1595 — PR 15's TypeScript cleanup list omits web/admin/src/lib/layers/analyzeOrg.ts and its test file. These files import from configRepo.ts, dispatch.ts, and enrollment.ts (all three explicitly listed for deletion in PR 15). Deleting those modules without also deleting analyzeOrg.ts will cause a TypeScript compilation failure. Also omits companion test files dispatch.test.ts, enrollment.test.ts, orgConfigParse.test.ts, and configRepo.test.ts.
  Remediation: Add analyzeOrg.ts, analyzeOrg.test.ts, dispatch.test.ts, enrollment.test.ts, orgConfigParse.test.ts, and configRepo.test.ts to PR 15's explicit TypeScript deletion list.

• [behavioral-change] docs/plans/deprecate-per-org-install.md:1171 — PR 8's caller update list for config.DefaultAgentRoles() → config.DefaultRoles() includes internal/cli/mint.go (line 44) but does not flag the behavioral consequence. defaultMintRoles() currently returns the per-org role set including "fullsend" (dispatch role). After the rename, it will return the per-repo role set which excludes "fullsend" and includes "fix". This means the mint will no longer provision WIF for the fullsend dispatch role.
  Remediation: Add a note in PR 8's mint.go caller update section acknowledging that defaultMintRoles() will no longer include the "fullsend" dispatch role, and confirm that orphaned fullsend-role WIF providers are cleaned up.

• [stale-reference] docs/plans/deprecate-per-org-install.md:1171 — PR 8's caller update section omits internal/cli/mint_test.go:587 which asserts config.DefaultAgentRoles(). After the rename to config.DefaultRoles(), this test assertion will fail to compile. The test also has a semantic concern: it currently expects the per-org role set; after rename it should expect the per-repo role set.
  Remediation: Add internal/cli/mint_test.go (line 587) to PR 8's test update section. Note that the assertion value must change.

• [prerequisite-dependency] docs/ADRs/0044-deprecate-per-org-installation-mode.md:349 — Phase 2 declares "ADR 0045 Phases 1–2 must be complete before Phase 2 begins" but the implementation plan's v2.0 release checklist does not include a verification step confirming ADR 0045 completion.
  Remediation: Add verification step to v2.0 release checklist: "Confirm ADR 0045 Phases 1–2 are merged and functional (harness base composition available)."

Low

• [stale-reference] docs/plans/deprecate-per-org-install.md:1171 — PR 8's caller update section does not account for admin_test.go:51 and github_test.go:62 which test the --agents flag default value using config.DefaultAgentRoles(). After rename, these tests will fail to compile. See also: [behavioral-change] finding at this location.

• [edge-case] docs/plans/deprecate-per-org-install.md:1263 — PR 9 evaluates whether CollectInstallFiles() and ManagedPaths() should be removed as dead code after PR 7 deletes workflows.go. The assessment is correct but the callsite enumeration is incomplete — ManagedPaths() is also called from workflows_test.go (deleted with workflows.go in PR 7) and from installfiles_test.go (scaffold package tests that survive PR 7).

• [internal-consistency] docs/ADRs/0044-deprecate-per-org-installation-mode.md:362 — The ADR Decision section step 10 lists 10 methods (5 secret + 5 variable) for removal and handles ListOrgRepos in a separate paragraph, while the Context table summarizes as "11 org-level methods to remove (5 secret, 5 variable, ListOrgRepos)." Count is consistent but the presentation could mislead readers.

• [breaking-change-communication] docs/plans/deprecate-per-org-install.md:1635 — v2.0 release checklist includes "BREAKING CHANGE: trailer in commit body" but does not specify the trailer content. The trailer should direct users to the migration guide and list removed commands.

• [naming-consistency] docs/plans/deprecate-per-org-install.md:809 — PR dependency graph arrow notation doesn't distinguish code dependencies from process dependencies. The prose below the graph explains this, but a visual distinction or note in the graph itself would improve clarity.

• [cross-reference-consistency] docs/guides/getting-started/org-mode.md — Guide documents per-org installation without deprecation notice. Planned for Phase 1 PR 2.

• [cross-reference-consistency] docs/reference/installation.md — Installation reference presents per-org and per-repo as equal alternatives without deprecation notice. Planned for Phase 1 PR 2.

• [cross-reference-consistency] docs/guides/infrastructure/private-repositories.md — Guide documents per-org as supported option without deprecation notice. Planned for Phase 1 PR 2.

• [cross-reference-consistency] README.md — Implementation plan (Phase 1 PR 2) says README quick-start should use per-repo example. This PR correctly limits its README change to adding a link to the new plan; the quick-start update is deferred to PR 2.

Info

• [living-document-update-deferred] docs/architecture.md — Per AGENTS.md, accepted ADRs should update docs/architecture.md in the same PR. The implementation plan explicitly defers this to Phase 1 PR 2. A human reviewer should decide whether to enforce this policy or grant an exception for this ADR-only PR.

Previous run (9)

Review

Findings

Medium

• [behavioral-change] docs/plans/deprecate-per-org-install.md:1146 — PR 8 correctly identifies the NewPerRepoConfig fallback behavioral change but does not mention that TestNewPerRepoConfig_DefaultRoles (config_test.go:568) asserts DefaultAgentRoles() as the expected fallback. This test needs its assertion value changed (not just renamed) when PerRepoDefaultRoles is promoted to DefaultRoles, because the role sets differ: DefaultAgentRoles includes fullsend and excludes fix, while PerRepoDefaultRoles excludes fullsend and includes fix.
  Remediation: In PR 8's test update section, explicitly note that TestNewPerRepoConfig_DefaultRoles must update its assertion from DefaultAgentRoles() to the new DefaultRoles() (formerly PerRepoDefaultRoles()).

• [stale-reference] docs/plans/deprecate-per-org-install.md:1565 — PR 15's grep sweep omits PerRepo as a pattern. After the renames in PRs 8–9 (PerRepoConfig, PerRepoDefaultRoles, PerRepoCustomizedDirs, PerRepoShimTemplate, VendoredBinaryPathPerRepo, PerRepoGuardVar, CollectPerRepoInstallFiles), any remaining PerRepo references in Go code would be stale. None of the existing grep patterns (per.org, per_org, PerOrg, etc.) would catch these.
  Remediation: Add grep -rn "PerRepo" --include="*.go" to the PR 15 grep sweep.

Low

• [incomplete-removal] docs/plans/deprecate-per-org-install.md:1029 — PR 6's github.go section says "Remove per-org path (runGitHubSetupPerOrg())" without enumerating the per-org helpers inside it (buildLayerStack callers at lines 454/490, ensureConfigRepoExists at line 472). These would all be removed when the function is deleted, and the compiler would catch any orphaned definitions, but more explicit enumeration would reduce implementation ambiguity.

• [edge-case] docs/plans/deprecate-per-org-install.md:1253 — PR 9's customizedDirsForPrefix() removal is only safe after PR 7 removes workflows.go (the sole caller of CollectInstallFiles/ManagedPaths). The dependency graph shows PR 7 and PR 9 can be developed in parallel. The plan should clarify that CollectInstallFiles and ManagedPaths become dead code after PR 7 merges.

• [incomplete-removal] docs/plans/deprecate-per-org-install.md:1243 — PR 9 deletes reconcile-repos.sh and reconcile-repos-test.sh while separately mentioning "Remove or update script-test target" in the Makefile. Both the file deletion and Makefile update must be in the same PR to avoid CI breakage.

Info

• [living-document-update-deferred] docs/architecture.md — Per AGENTS.md, accepted ADRs should update docs/architecture.md in the same PR. The implementation plan explicitly defers this to Phase 1 PR 2. A human reviewer should decide whether to enforce this policy or grant an exception for this ADR-only PR.

Previous run (10)

Review

Findings

Medium

• [stale-reference] docs/plans/deprecate-per-org-install.md:736 — PR 14's install_mode removal checklist (8 files) does not cover internal/scaffold/workflow_call_alignment_test.go, which asserts at line 178 that every reusable stage workflow declares an install_mode input. After PR 14 removes install_mode from the reusable workflows, this test will fail.
  Remediation: Add internal/scaffold/workflow_call_alignment_test.go to PR 14's scope. Remove install_mode from the commonInputs slice at line 178.

• [incomplete-removal] docs/plans/deprecate-per-org-install.md:459 — PR 9 says to update render_test.go at lines 37 and 41 only, but the file contains five additional test functions (TestRenderThinCallerNotVendored, TestRenderThinCallerVendoredPerOrg, TestRenderPrioritizeThinCallerVendored, TestThinStageWorkflowRegistryMatchesTemplates, TestRenderAllThinCallersFreeOfPlaceholders) that exercise thin caller templates deleted in PR 9. These tests will fail when the embedded files are gone. Also, render.go contains thinStageWorkflows, isThinStageCaller, thinStageName, and the thin-caller branch in RenderTemplate — all dead code after thin caller deletion.
  Remediation: Add deletion of these five test functions and render.go thin-caller utilities to PR 9's scope.

Low

• [incomplete-removal] docs/plans/deprecate-per-org-install.md:481 — PR 9 lists installfiles.go for function renames but does not address customizedDirsForPrefix() (line 53) which branches on prefix to choose between PerRepoCustomizedDirs() and CustomizedDirs(). After renaming, both branches call the same function, making customizedDirsForPrefix() dead logic. Additionally, CollectInstallFiles() and ManagedPaths() are only called from internal/layers/workflows.go (deleted in PR 7); they become dead code with no production callers.

• [incomplete-removal] docs/plans/deprecate-per-org-install.md:755 — PR 15's grep sweep identifies web/admin TypeScript files (configRepo.ts, enrollment.ts, dispatch.ts, orgConfigParse.ts, constants.ts, orgListRow.ts, installReadinessProbes.ts) as containing per-org references, but no PR is assigned to delete or modify them. Also, batchOrganizationsFullsendRepoGraphql.ts queries for .fullsend repos and is not mentioned in the grep patterns.

• [edge-case] docs/ADRs/0044-deprecate-per-org-installation-mode.md:291 — PR 8's rename of PerRepoDefaultRoles() to DefaultRoles() and update of NewPerRepoConfig()'s fallback from DefaultAgentRoles() to DefaultRoles() is a behavioral fix (removes the fullsend dispatch role from per-repo defaults), not just a rename. The plan's wording doesn't highlight this behavioral change, which could be missed during implementation review.

Info

• [living-document-update-deferred] docs/architecture.md — Per AGENTS.md, accepted ADRs should update docs/architecture.md in the same PR. The implementation plan explicitly defers this to Phase 1 PR 2. A human reviewer should decide whether to enforce this policy or grant an exception for this ADR-only PR.

Previous run (11)

Review

Findings

Medium

• [stale-reference] docs/plans/deprecate-per-org-install.md:1186 — PR 9 lists scripts/reconcile-repos.sh for deletion but omits related files that will become stale: (1) scripts/reconcile-repos-test.sh (the test script), (2) the Makefile script-test target at line 114 which runs reconcile-repos-test.sh, (3) internal/scaffold/scaffold.go line 37 which registers reconcile-repos.sh in the executableFiles map, (4) internal/scaffold/scaffold_test.go lines 78, 729-738 which reference and test reconcile-repos.sh.
  Remediation: Add to PR 9's delete/update list: delete scripts/reconcile-repos-test.sh, remove reconcile-repos.sh entry from scaffold.go executableFiles map, remove references from scaffold_test.go, and update Makefile script-test target.

• [stale-reference] docs/plans/deprecate-per-org-install.md:1216 — PR 9 renames PerRepoCustomizedDirs() to CustomizedDirs() and PerRepoShimTemplate() to ShimTemplate() in internal/scaffold/scaffold.go, but does not list internal/scaffold/installfiles.go as a caller that needs updating. installfiles.go calls PerRepoCustomizedDirs() at lines 55 and 79, and PerRepoShimTemplate() at line 64. Also internal/scaffold/render_test.go line 41 calls PerRepoShimTemplate().
  Remediation: Add internal/scaffold/installfiles.go and internal/scaffold/render_test.go to PR 9's caller update section.

Low

• [stale-reference] docs/plans/deprecate-per-org-install.md:1534 — PR 15's grep sweep section mentions web/admin/src/lib/layers/ TypeScript files as containing per-org layer implementations but does not assign their cleanup to any specific PR. The sweep patterns only search for CONFIG_REPO_NAME|ConfigRepoName in *.ts files, missing other per-org patterns (enrollment, analyzeOrg, configRepo, orgConfigParse).

• [edge-case] docs/plans/deprecate-per-org-install.md:1275 — PR 10 lists admin_test.go guard variable assertions at ~lines 2261, 2283, but actual references are at lines 2324 and 2346.

• [missing-deprecation-notice] docs/guides/getting-started/org-mode.md, docs/guides/user/customizing-agents.md, docs/guides/infrastructure/private-repositories.md, docs/reference/installation.md, docs/guides/getting-started/README.md, docs/reference/github-setup.md, docs/guides/infrastructure/infrastructure-reference.md, docs/guides/infrastructure/mint-administration.md — Eight documentation files present per-org mode without deprecation context. All are planned for update in Phase 1 PR 2 per the implementation plan.

Info

• [living-document-update-deferred] docs/architecture.md — Per AGENTS.md: "When status is Accepted, update docs/architecture.md and related problem docs in the same PR." The implementation plan explicitly defers this to Phase 1 PR 2.

• [decision-rationale-completeness] docs/ADRs/0044-deprecate-per-org-installation-mode.md — The ADR's "Cons" section acknowledges substantial downsides (loss of centralized policy enforcement, weaker config governance, per-repo setup overhead) but the "Decision" section does not explicitly explain why these trade-offs are acceptable. Mitigations are addressed inline in the Cons section, but a brief rationale summary before the implementation details would strengthen the decision record.

Previous run (12)

Review

Findings

Medium

• [logic-error] docs/ADRs/0044-deprecate-per-org-installation-mode.md:485 — The ADR step 12 says "remove Config.GitHubOrgs (org-wide WIF conditions), keep Config.Repo (per-repo WIF)." This contradicts the implementation plan's PR 11, which correctly says "Retain Config.GitHubOrgs — used by per-repo install path (admin.go lines 713, 930, 952) for EnsureOrgInMint()." The ADR's removal directive is wrong: GitHubOrgs is actively used in per-repo flows — admin.go:713,930,952 pass GitHubOrgs: []string{owner}, Provision() at provisioner.go:509 iterates GitHubOrgs to call EnsureOrgInMint(), and provisioner.go:436 errors if GitHubOrgs is empty. The plan got it right; the ADR got it wrong.
  Remediation: Fix ADR step 12 to say "Retain Config.GitHubOrgs (needed by EnsureOrgInMint in per-repo flows); consider renaming to Org (singular)" to match the implementation plan.

Low

• [edge-case] docs/plans/deprecate-per-org-install.md:1144 — PR 8 removes DefaultAgentRoles() and renames PerRepoDefaultRoles() to DefaultRoles(). The plan's "Update all callers" section lists admin.go, github.go, scaffold.go, and a catch-all. However, mint.go:44 calls config.DefaultAgentRoles() (not config.PerRepoConfig), so it would not be caught by the catch-all. Additionally, internal/forge/github/types.go has its own DefaultAgentRoles() function that is not mentioned.

• [stale-reference] docs/plans/deprecate-per-org-install.md:1184 — PR 9 lists prioritize-scheduler.yml for deletion. The plan's scaffold_test.go update section mentions "Remove 3 references to prioritize-scheduler.yml (lines 96, 768, 792)" but omits line 828 (TestPrioritizeSchedulerSkipsWhenProjectNumberUnset test which creates a script named prioritize-scheduler-run.sh).

• [missing-deprecation-notice] docs/guides/getting-started/org-mode.md — This guide presents per-org mode without any deprecation context. Planned for Phase 1 PR 2 per the implementation plan.

• [missing-deprecation-notice] docs/guides/user/customizing-agents.md — This guide describes both per-org and per-repo modes without indicating per-org deprecation status. Planned for Phase 1 PR 2.

• [missing-deprecation-notice] docs/guides/infrastructure/private-repositories.md — This guide discusses per-org install mode without mentioning the broader deprecation. Planned for Phase 1 PR 2.

• [missing-deprecation-notice] docs/reference/installation.md — The installation guide presents per-org and per-repo modes as equal choices without mentioning deprecation. Planned for Phase 1 PR 2.

• [missing-deprecation-notice] docs/guides/getting-started/README.md — The getting started overview mentions both modes without indicating deprecation status. Planned for Phase 1 PR 2.

Info

• [living-document-update-deferred] docs/architecture.md — Per AGENTS.md: "When status is Accepted, update docs/architecture.md and related problem docs in the same PR." The implementation plan explicitly defers this to Phase 1 PR 2.

Previous run (13)

Review

Findings

Medium

• [logic-error] docs/ADRs/0044-deprecate-per-org-installation-mode.md:485 — The ADR step 12 says "remove Config.GitHubOrgs (org-wide WIF conditions), keep Config.Repo (per-repo WIF)." This contradicts the implementation plan's PR 11, which correctly says "Retain Config.GitHubOrgs — used by per-repo install path (admin.go lines 713, 930, 952) for EnsureOrgInMint()." The ADR's removal directive is wrong: GitHubOrgs is actively used in per-repo flows — admin.go:713,930,952 pass GitHubOrgs: []string{owner}, Provision() at provisioner.go:509 iterates GitHubOrgs to call EnsureOrgInMint(), and provisioner.go:436 errors if GitHubOrgs is empty. The plan got it right; the ADR got it wrong.
  Remediation: Fix ADR step 12 to say "Retain Config.GitHubOrgs (needed by EnsureOrgInMint in per-repo flows); consider renaming to Org (singular)" to match the implementation plan.

Low

• [edge-case] docs/plans/deprecate-per-org-install.md:1144 — PR 8 removes DefaultAgentRoles() and renames PerRepoDefaultRoles() to DefaultRoles(). The plan's "Update all callers" section lists admin.go, github.go, scaffold.go, and a catch-all. However, mint.go:44 calls config.DefaultAgentRoles() (not config.PerRepoConfig), so it would not be caught by the catch-all. Additionally, internal/forge/github/types.go has its own DefaultAgentRoles() function that is not mentioned.

• [stale-reference] docs/plans/deprecate-per-org-install.md:1184 — PR 9 lists prioritize-scheduler.yml for deletion. The plan's scaffold_test.go update section mentions "Remove 3 references to prioritize-scheduler.yml (lines 96, 768, 792)" but omits line 828 (TestPrioritizeSchedulerSkipsWhenProjectNumberUnset test which creates a script named prioritize-scheduler-run.sh).

• [missing-deprecation-notice] docs/guides/getting-started/org-mode.md — This guide presents per-org mode without any deprecation context. Planned for Phase 1 PR 2 per the implementation plan.

• [missing-deprecation-notice] docs/guides/user/customizing-agents.md — This guide describes both per-org and per-repo modes without indicating per-org deprecation status. Planned for Phase 1 PR 2.

• [missing-deprecation-notice] docs/guides/infrastructure/private-repositories.md — This guide discusses per-org install mode without mentioning the broader deprecation. Planned for Phase 1 PR 2.

• [missing-deprecation-notice] docs/reference/installation.md — The installation guide presents per-org and per-repo modes as equal choices without mentioning deprecation. Planned for Phase 1 PR 2.

• [missing-deprecation-notice] docs/guides/getting-started/README.md — The getting started overview mentions both modes without indicating deprecation status. Planned for Phase 1 PR 2.

Info

• [living-document-update-deferred] docs/architecture.md — Per AGENTS.md: "When status is Accepted, update docs/architecture.md and related problem docs in the same PR." The implementation plan explicitly defers this to Phase 1 PR 2.

Previous run (14)

Review

Findings

Medium

• [logic-error] docs/ADRs/0044-deprecate-per-org-installation-mode.md:469 — The ADR states "Keep ListOrgRepos — used by detectSharedApps for app discovery." This is factually incorrect. detectSharedApps in internal/cli/admin.go:1273 uses ListOrgInstallations (line 1290), not ListOrgRepos. All ListOrgRepos callers (admin.go:439,1169,1479,1779,2247,2266,2498; github.go:352; dispatch.go:151) are in per-org code paths. After per-org removal, ListOrgRepos would have zero callers in Go code. See also: [internal-consistency] finding for the plan's inconsistent justification.
  Remediation: Remove the false claim about detectSharedApps. Either mark ListOrgRepos for removal in PR 10 (since all callers are per-org), or retain it with an honest justification (e.g., "retained speculatively for future org-wide automation tooling").

• [logic-error] docs/plans/deprecate-per-org-install.md:1336 — PR 11 says "Remove Config.GitHubOrgs field (org-wide WIF conditions)" from the gcf provisioner. However, GitHubOrgs is actively used in the per-repo install path: internal/cli/admin.go lines 930 and 952 create provisioners with GitHubOrgs: []string{owner}, and Provision() at provisioner.go:509 iterates GitHubOrgs to call EnsureOrgInMint() which registers the org in ALLOWED_ORGS. Removing this field would break per-repo mint provisioning.
  Remediation: Change the plan from "Remove Config.GitHubOrgs field" to "Retain Config.GitHubOrgs (needed by EnsureOrgInMint in per-repo flows)". Alternatively, rename it to Org (singular string) since per-repo always passes exactly one org.

Low

• [missing-consumer-coverage] docs/plans/deprecate-per-org-install.md:784 — The subsystem table lists web/admin/src/lib/layers/ but per-org references also exist in web/admin/src/lib/orgs/ files (orgListRow.ts imports CONFIG_REPO_NAME and checks config-repo layer reports; installReadinessProbes.ts references config-repo). These files are not listed in the subsystem table.

• [edge-case] docs/plans/deprecate-per-org-install.md:1144 — PR 8 removes DefaultAgentRoles() and renames PerRepoDefaultRoles() to DefaultRoles(). However, NewPerRepoConfig() at config.go:291 currently falls back to DefaultAgentRoles(). The compiler will catch it, but the plan should explicitly note this required fix to avoid confusion about whether the role set change is intentional.

• [stale-reference] docs/plans/deprecate-per-org-install.md:1184 — PR 9 lists prioritize-scheduler.yml for deletion but scaffold_test.go has test coverage referencing this file (lines 96, 768, 792) that is not mentioned in PR 9's test update section.
  Remediation: Add prioritize-scheduler.yml test references to PR 9's test update section.

• [architectural-coherence] docs/plans/deprecate-per-org-install.md:1415 — PR 14 removes install_mode from 8 files but does not include a verification grep. PR 15's grep sweep covers this (install_mode|install-mode|installMode at line 1518), but a cross-reference to PR 15's verification would strengthen PR 14.

• [edge-case] docs/plans/deprecate-per-org-install.md:1195 — PR 9 renames shim-per-repo.yaml to shim.yaml and PR 14 removes install_mode from it. Between PR 9 and PR 14, the template has a transient install_mode: per-repo input. This is harmless (functionally correct during transition).

• [missing-deprecation-notice] docs/guides/getting-started/org-mode.md, docs/guides/user/customizing-agents.md, docs/guides/infrastructure/private-repositories.md — These guides present per-org mode without deprecation context. Planned for Phase 1 PR 2 per the implementation plan.

Info

• [living-document-update-deferred] docs/architecture.md — Per AGENTS.md: "When status is Accepted, update docs/architecture.md and related problem docs in the same PR." The implementation plan explicitly defers this to Phase 1 PR 2.

• [prior-finding-resolved] docs/ADRs/0044-deprecate-per-org-installation-mode.md:349 — Prior architectural-coherence finding addressed: ADR now includes explicit prerequisite statement gating Phase 2 on ADR 0045 Phase 1-2 completion.

Previous run (15)

Review

Findings

Low

• [missing-consumer-coverage] docs/plans/deprecate-per-org-install.md — The subsystem table and PR breakdown omit web/admin/src/lib/layers/ which contains TypeScript per-org layer implementations (configRepo.ts, enrollment.ts, dispatch.ts, orgConfigParse.ts, constants.ts). PR 15's grep sweep would likely catch these, but explicitly listing the web/admin frontend subsystem in the plan would prevent the gap from being overlooked.
  Remediation: Add web/admin/ to the subsystem table and include cleanup scope in PR 15.

• [edge-case] docs/plans/deprecate-per-org-install.md — PR 9 renames shim-per-repo.yaml to shim.yaml, and PR 14 references the renamed shim.yaml for install_mode removal. The dependency graph shows PR 14 depending on PR 6 but not PR 9, creating a cross-PR filename dependency gap.
  Remediation: Add PR 9 as a dependency of PR 14 in the dependency graph, or handle the shim template's install_mode removal in PR 9 itself.

• [internal-consistency] docs/plans/deprecate-per-org-install.md — PR 9 deletes shim-workflow-call.yaml but does not explicitly mention removing scaffold_test.go references to this template (5 references confirmed in scaffold_test.go).
  Remediation: Explicitly list the scaffold test references in PR 9's scope.

• [stale-reference] docs/plans/deprecate-per-org-install.md — PR 9 lists prioritize-scheduler.yml for deletion conditionally ("if per-org only"). The file is per-org only (checks out .fullsend repo, uses dispatch role) and should be explicitly listed in the deletion set.

• [missing-consumer-coverage] docs/plans/deprecate-per-org-install.md — PR 15's grep sweep patterns partially cover ConfigRepoName (the ConfigRepo|configrepo pattern matches it as a substring), but the TypeScript constant CONFIG_REPO_NAME in web/admin/src/lib/layers/constants.ts would not be caught by the current patterns.
  Remediation: Add CONFIG_REPO_NAME to the grep sweep.

• [missing-consumer-coverage] docs/ADRs/0044-deprecate-per-org-installation-mode.md — Step 10 retains ListOrgRepos for speculative "future org-wide automation tooling." While low-cost to keep, documenting a concrete current caller or marking it as a follow-up removal candidate would strengthen the plan.

• [readme-listing-sort-order] README.md — The ADR-0044 plan entry is inserted between ADR-0045 Phase 3 and ADR-0046, breaking ascending ADR number order.
  Remediation: Move the ADR-0044 entry before the ADR-0045 Phase 1 entry.

• [architectural-coherence] docs/ADRs/0044-deprecate-per-org-installation-mode.md — The dependency on ADR 0045 (harness composition) is implicit. The ADR references ADR 0045 extensively but lacks a formal prerequisite statement gating Phase 2 removal on ADR 0045 Phase 1-2 completion.

• [missing-deprecation-notice] docs/guides/getting-started/org-mode.md, docs/guides/user/customizing-agents.md, docs/guides/infrastructure/private-repositories.md — These guides present per-org mode without deprecation context. Planned for Phase 1 PR 2 per the implementation plan.

Info

• [living-document-update-deferred] docs/architecture.md — Per AGENTS.md: "When status is Accepted, update docs/architecture.md and related problem docs in the same PR." The implementation plan explicitly defers this to Phase 1 PR 2, showing awareness of the requirement but choosing to sequence it separately.

Previous run (16)

Review

Findings

Medium

• [missing-file-coverage] docs/plans/deprecate-per-org-install.md — PR 10 explicitly enumerates PerRepoGuardVar callers in admin.go, github.go, test files, and cross-references PR 7 (enrollment.go) and PR 9 (reconcile-repos.sh). However, the plan does not mention internal/scaffold/fullsend-repo/templates/shim-per-repo.yaml (line 47, install_mode: per-repo) or internal/scaffold/render_test.go (line 37, asserts install_mode: per-org). These install_mode references in scaffold templates and tests need to be addressed in a specific PR (likely PR 9 scaffold cleanup or PR 14 workflow cleanup).
  Remediation: Confirm whether shim-per-repo.yaml and render_test.go install_mode references are covered by existing PRs, or add explicit line items.

• [missing-supersession] docs/ADRs/0044-deprecate-per-org-installation-mode.md — ADR 0033 (per-repo installation mode) section 8 "Coexistence" establishes that per-repo and per-org coexist within the same org. ADR 0044 removes the per-org side of this coexistence but does not cross-reference or annotate ADR 0033. Per AGENTS.md: minor annotations (cross-references, short notes linking to newer decisions) are welcome on accepted ADRs.
  Remediation: Add a brief annotation to ADR 0033's Coexistence section noting that ADR 0044 removes the per-org side, or include a cross-reference link.

Low

• [missing-consumer-coverage] docs/plans/deprecate-per-org-install.md — PR 14 lists all 7 reusable workflows and the validate-enrollment action for install_mode removal. A checklist-style confirmation enumerating all 8 files would strengthen the plan and reduce implementation risk.

• [edge-case] docs/plans/deprecate-per-org-install.md — The scaffold workflows in internal/scaffold/fullsend-repo/.github/workflows/ all hardcode install_mode: per-org (confirmed in code.yml, fix.yml, prioritize.yml, retro.yml, review.yml, triage.yml). The plan should specify which PR handles scaffold workflow template updates or removal.

• [design-fit-readme] README.md — The plans listing does not include an entry for the new deprecate-per-org-install.md file added by this PR.

Info

• [living-document-update-deferred] docs/architecture.md — Per AGENTS.md line 71: "When status is Accepted, update docs/architecture.md and related problem docs in the same PR." The implementation plan explicitly defers this to Phase 1 PR 2, showing awareness of the requirement but choosing to sequence it separately.

• [cross-reference-opportunity] docs/ADRs/0033-per-repo-installation-mode.md — ADR 0033 does not cross-reference ADR 0044 noting per-repo's promotion to sole supported mode. Expected since ADR 0044 has not yet been merged.

Previous run (17)

Review

Findings

Medium

• [missing-file-coverage] docs/plans/deprecate-per-org-install.md — PR 10 removes the PerRepoGuardVar constant from internal/forge/forge.go, but the plan does not explicitly assign removal of all callers of this constant to any PR. Confirmed references remain in: admin.go:456,683,827,988, github.go:243,367,557, layers/enrollment.go:373, admin_test.go:2324,2346, github_test.go:333,341, and internal/scaffold/fullsend-repo/scripts/reconcile-repos.sh:167-516. Without explicit assignment, the constant removal will break compilation.
  Remediation: Add an explicit step to one of the PRs (likely PR 10 or an earlier PR) that enumerates and removes or updates every caller of PerRepoGuardVar before or in the same PR that removes the constant definition.

Low

• [missing-consumer-coverage] docs/plans/deprecate-per-org-install.md — The install_mode input parameter exists on 7 reusable workflows (reusable-code.yml, reusable-dispatch.yml, reusable-fix.yml, reusable-prioritize.yml, reusable-retro.yml, reusable-review.yml, reusable-triage.yml). PR 14 covers workflow cleanup but should explicitly confirm install_mode removal from all 7 workflows.

• [internal-consistency] docs/ADRs/0044-deprecate-per-org-installation-mode.md:158 — The ADR says "org-level variable/secret management in the forge interface (~12 methods)" but the actual count is 10 methods to remove (5 secret + 5 variable). The plan's subsystem table and the ADR's own step 10 enumeration both say 10.

• [edge-case] docs/plans/deprecate-per-org-install.md — The reconcile-repos.sh script (internal/scaffold/fullsend-repo/scripts/) has a check_per_repo_guard function (line 170) called at lines 393 and 516. After per-org removal, this script becomes dead code. The plan should confirm this script is removed as part of scaffold cleanup in PR 9.

• [edge-case] docs/plans/deprecate-per-org-install.md — PR 4 migration step (c) says the migration command should "generate thin harness wrappers with base: when harness files exist in the source config." The detection heuristic does not specify what constitutes a harness file vs a legacy customized/ override.

• [design-fit-readme] README.md — The plans listing does not include an entry for the new deprecate-per-org-install.md file added by this PR.

Info

• [living-document-update-deferred] docs/architecture.md — Per AGENTS.md: "When status is Accepted, update docs/architecture.md and related problem docs in the same PR." The implementation plan explicitly defers this to Phase 1 PR 2, showing awareness of the requirement but choosing to sequence it separately.

• [cross-reference-opportunity] docs/ADRs/0033-per-repo-installation-mode.md — ADR 0033 does not cross-reference ADR 0044 noting per-repo's promotion to sole supported mode. Expected since ADR 0044 has not yet been merged.

Previous run (18)

Review

Findings

Medium

• [missing-file-coverage] docs/plans/deprecate-per-org-install.md — PR 10 removes PerRepoGuardVar constant from internal/forge/forge.go, but the plan does not explicitly assign removal of per-repo callers of this constant to any PR. Confirmed references in: admin.go:455,682,826,987, github.go:243,367,557, layers/enrollment.go:373, admin_test.go:2261,2283, github_test.go:333,341, and scaffold/fullsend-repo/scripts/reconcile-repos.sh:170-195. These are per-repo code paths, not per-org code paths, and would be missed by PRs focused solely on removing per-org functionality.
  Remediation: Add explicit line items to PR 10 (or PR 15) covering removal of PerRepoGuardVar references from per-repo code paths in admin.go, github.go, layers/enrollment.go, and their test files.

Low

• [missing-consumer-coverage] docs/plans/deprecate-per-org-install.md — The install_mode input parameter exists on 7 reusable workflows. PR 14 covers workflow cleanup but should explicitly confirm install_mode removal from all 7 workflows (reusable-dispatch.yml, reusable-triage.yml, reusable-code.yml, reusable-review.yml, reusable-fix.yml, reusable-retro.yml, reusable-prioritize.yml).

• [internal-consistency] docs/ADRs/0044-deprecate-per-org-installation-mode.md:158 — The ADR says "org-level variable/secret management in the forge interface (~12 methods)" but the actual count is 10 methods to remove (5 secret + 5 variable) per both the plan's subsystem table and the ADR's own step 10 enumeration.

• [edge-case] docs/plans/deprecate-per-org-install.md — The reconcile-repos.sh script (scaffold) has a check_per_repo_guard function that calls the GitHub API. After per-org removal, this entire script becomes dead code. The plan should confirm this script is removed as part of scaffold cleanup in PR 9.

• [edge-case] docs/plans/deprecate-per-org-install.md — PR 4 migration step (c) says the migration command should "generate thin harness wrappers with base: when harness files exist in the source config." The detection heuristic does not specify what constitutes a harness file vs a legacy customized/ override.

• [design-fit-readme] README.md — The plans listing does not include an entry for the new deprecate-per-org-install.md file added by this PR.

Info

• [living-document-update-deferred] docs/architecture.md — Per AGENTS.md: "When status is Accepted, update docs/architecture.md and related problem docs in the same PR." The implementation plan explicitly defers this to Phase 1 PR 2, showing awareness of the requirement but choosing to sequence it separately.

• [cross-reference-opportunity] docs/ADRs/0033-per-repo-installation-mode.md — ADR 0033 does not cross-reference ADR 0044 noting per-repo's promotion to sole supported mode. A minor annotation per AGENTS.md ADR policy would be appropriate follow-up.

• [consistency-check] docs/guides/infrastructure/private-repositories.md — States "Per-repo install (recommended for private repos)" which could be broadened to "recommended for all repos" per ADR-0044 post-v2.0.

[fullsend-ai-review]

See the review comment for full details.

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 7:14 PM UTC · Completed 7:26 PM UTC
Commit: 1f2d3aa · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 7:47 PM UTC · Completed 8:01 PM UTC
Commit: ac80bd2 · View workflow run →

[fullsend-ai-review]

See the review comment for full details.

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 8:12 PM UTC · Completed 8:26 PM UTC
Commit: 283d75e · View workflow run →

[fullsend-ai-review]

See the review comment for full details.

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 8:43 PM UTC · Completed 8:58 PM UTC
Commit: 6e3c1b7 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 11:19 PM UTC · Completed 11:33 PM UTC
Commit: 26d696f · View workflow run →

[fullsend-ai-review]

See the review comment for full details.

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:59 PM UTC · Completed 11:14 PM UTC
Commit: bc90a22 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 12:08 AM UTC · Completed 12:20 AM UTC
Commit: cb0a825 · View workflow run →

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 11:52 AM UTC · Ended 11:59 AM UTC
Commit: 4e21a60 · View workflow run →

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 12:02 PM UTC · Ended 12:08 PM UTC
Commit: 4e21a60 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 12:11 PM UTC · Completed 12:26 PM UTC
Commit: 235ba49 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 12:32 PM UTC · Completed 12:46 PM UTC
Commit: 0f74614 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 12:56 PM UTC · Completed 1:10 PM UTC
Commit: 94d9099 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ❌ Failure · Started 1:42 PM UTC · Completed 1:59 PM UTC
Commit: e8b2087 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ❌ Failure · Started 2:13 PM UTC · Completed 2:26 PM UTC
Commit: 861fe53 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 12:35 AM UTC · Completed 12:46 AM UTC
Commit: 246287b · View workflow run →

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 3:31 PM UTC · Completed 3:38 PM UTC
Commit: 246287b · View workflow run →

[fullsend-ai-retro]

Retro: PR #2340 — docs(adr): deprecate per-org installation mode

Timeline: Opened 2026-06-16, merged 2026-06-26 (10 days). Human-authored documentation PR adding ADR-0044 and an implementation plan across 4 files (1603 additions). The review agent ran 20+ times across many author commits.

What worked well:

• The review agent caught 3 concrete factual errors in code references: incorrect function name (runGitHubSetup() → runGitHubSetupPerOrg()), nonexistent function (CopyAgentPEM()), and wrong API call attribution (ListOrgRepos vs ListOrgInstallations). These are high-value findings that prevent misleading documentation from shipping.
• Human reviewers (maruiz93, ifireball) complemented the bot by catching strategic/architectural concerns: credential sharing model gaps, ADR-0045 dependency risk, ADR/plan content duplication, TypeScript import chain tracing needs, and e2e test migration strategy (convert vs delete).
• The review agent and humans operated in complementary bands — bot handled factual accuracy, humans handled strategic judgment. This is a healthy pattern.

Existing issues already cover most improvement areas:

• #2664 — verify docs claims against source code before flagging
• #2678 — deprioritize findings on planning/design documents
• #1906 — detect omissions in ADRs by exploring project context
• #1659 — comment-only on ADR PRs
• #2172 — cross-reference external identifiers in docs against codebase

1 new proposal filed covering a gap not addressed by existing issues: the review agent should flag implementation plans that propose deleting tests/functionality rather than migrating them.

Proposals filed

• Review agent should flag plans that propose deleting tests rather than migrating them (in fullsend-ai/fullsend)