fix(agent-policy): generation 21 blocks every agent PR in sdk, pdf, and happyvertical.com on pre-existing main drift

[willgriffin]

Generation 21 promoted 2026-07-30 06:10Z (channel revision 24, #103). Three repositories now fail the lifecycle check on every agent-authored pull request, including PRs that touch nothing but .github/workflows/.

This is not caused by any one branch. It is drift on origin/main that generation 21 began enforcing.

Evidence

Generation 21 ships two kernels:

• diagnostic — policy/agent-development-kernel.md, sha256 2524e6ee…
• compatibility — policy/agent-development-kernel-compat-v1.0.9.md, sha256 187a3882…

Each repository's managed AGENTS.md block must match the kernel for its runtime.agent_lifecycle_stage. Read from origin/main:

Repo	Stage	Managed block on main	lifecycle
smrt	diagnostic	2524e6ee…	pass
iac	compatibility	187a3882…	pass
sdk	diagnostic	9a4cf725… — neither kernel	fail
pdf	diagnostic	9a4cf725… — neither kernel	fail
happyvertical.com	compatibility	187a3882… (block is fine)	fail

sdk and pdf fail with AGENTS.md: stale or edited managed policy block. The 9a4cf725… block predates both shipped kernels and is present on origin/main in both repos.

happyvertical.com fails differently — .github/workflows/agent-policy.yml: missing or differs from the canonical lifecycle workflow. Its AGENTS.md block is correct. Confirmed pre-existing: the failure reproduces with the candidate branch's change reverted, and #136 passed lifecycle before generation 21 promoted.

Why it is not self-serve

The documented remedy is to regenerate managed policy output per repository:

hv-agent migrate-repo . --profile happyvertical --apply

The pinned generation-21 artifact exposes only audit, check-pr, claim, heartbeat, release, reconcile, project-sync. There is no migrate-repo subcommand, so the documented remedy cannot be run from the pinned tool.

Hand-patching a managed policy block from a feature branch would be an agent editing generated control-plane output to make its own gate pass, which is exactly the thing the check exists to catch. So this needs control-plane action, not a per-repo workaround.

Impact

Every agent PR in sdk, pdf, and happyvertical.com is blocked at lifecycle until this is regenerated. Three currently open and otherwise-mergeable PRs are affected — happyvertical/sdk#1177, happyvertical/pdf#120, happyvertical/happyvertical.com#141 — all part of the CI-latency epic willgriffin/nixos-config#176, and all touching only workflow files.

Note happyvertical/sdk#1177 is worth unblocking on its own merits: it fixes on-merge-main.yml cancelling its own releases mid-publish, between npm publish, git tag -f, and gh release create.

Asks

1. Regenerate the managed AGENTS.md block in sdk and pdf against the generation-21 diagnostic kernel.
2. Reconcile happyvertical.com's .github/workflows/agent-policy.yml with the canonical compatibility lifecycle workflow.
3. Ship migrate-repo in the pinned artifact, or document the supported path for repairing drift when the promoted tool cannot.

[willgriffin]

All three asks are addressed. Everything reproduced exactly as reported.

1 & 2 — the drift itself

Repo	Fix	PR
sdk	managed AGENTS.md block regenerated against the generation-21 diagnostic kernel 2524e6ee…	happyvertical/sdk#1179
pdf	same	happyvertical/pdf#124
happyvertical.com	.github/workflows/agent-policy.yml restored to the canonical compatibility rendering	happyvertical/happyvertical.com#143

Generated with the control-plane migrate-repo, not hand-patched, and each verified with the pinned artifact (sha256:a19abb22…) — the tool CI runs — going from the reported errors to Agent Policy / lifecycle passed.

Two things worth recording:

happyvertical.com's canonical file is byte-identical to iac's, which is the same stage (compatibility) and runner (arc-happyvertical) and passes today. Generation 21 rewrote that template — the channel bootstrap now resolves the trusted source over the GitHub API with redirects rejected instead of shelling out to gh api, and the checkout pin advances — and main matched neither it nor either accepted predecessor.

migrate-repo also wanted to add a forge block to all three manifests. No repository in the fleet has one yet, and the check does not require it, so it is excluded from these PRs; adding it to three of six would be its own change.

3 — migrate-repo is absent by design, and the corrective text is the real defect

Not a packaging oversight. scripts/build-policy-artifact publishes the sanitized checker as the artifact's hv-agent:

cp "$ROOT/scripts/hv-agent-policy-check" "$DIST/scripts/hv-agent"

Shipping migrate-repo there would export the private fleet registry and organization-ruleset mutation to every consumer. The defect is that the checker appends ; run scripts/hv-agent migrate-repo . --profile happyvertical --apply to its errors — this repository's tool, named in the one place it cannot be run. An agent trying to comply is pushed toward exactly the hand-patching the check exists to catch, which is what this issue correctly refused to do.

Documented instead, per the ask's second option: happyvertical/have-config#366 adds Repairing managed-output drift to the handbook and a README note that consumers get only the sanitized subset.

Why it was not self-serve even with the right tool

Worth flagging, because it is the more durable problem. migrate-repo on sdk and pdf fails before touching a file:

ERROR diagnostic lifecycle cutover preflight failed before file mutation:
happyvertical/smrt: repository merge queue authority drifted
happyvertical/.github: current default-branch lifecycle canary no longer proves the active source channel
happyvertical/ocr: current default-branch lifecycle canary no longer proves the active source channel
happyvertical/pdf: current default-branch lifecycle canary no longer proves the active source channel
happyvertical/smrt: current default-branch lifecycle canary no longer proves the active source channel

require_diagnostic_lifecycle_cutover fires whenever the target stage is diagnostic, including a stage-preserving regeneration, and requires a current default-branch canary for every required repository. That canary's not_before follows the last commit to the channel state — so a promotion invalidates every canary in the fleet at once, and post-promotion drift repair is blocked in exactly the window when post-promotion drift appears. Tracked as happyvertical/have-config#365.

happyvertical/smrt: repository merge queue authority drifted is a separate live finding, not a promotion artifact, and currently blocks every diagnostic migration in the org. Also in #365.

Root cause

Rollout checklist step 5 — "during smoke, migrate every affected repository" — did not complete for the whole affected fleet when generation 21 promoted. The repositories it missed fail closed on their own main, which is why this reads as unattributable drift rather than as an incomplete rollout.

Closing once the four PRs merge. happyvertical/sdk#1177 unblocks with #1179.

[willgriffin]

Resolved. All four pull requests are merged and all three repositories now pass the lifecycle check on their own main.

Verification

Auditing each repository's post-merge origin/main with the pinned generation-21 artifact (sha256:a19abb22…) — the same tool CI runs:

sdk                  Agent Policy / lifecycle passed
pdf                  Agent Policy / lifecycle passed
happyvertical.com    Agent Policy / lifecycle passed

Ask	Repo	Landed	Evidence on main
1	sdk	happyvertical/sdk#1179 (d5ed12e6)	managed block now 2524e6ee…
1	pdf	happyvertical/pdf#124 (5ecd46f1)	managed block now 2524e6ee…
2	happyvertical.com	happyvertical/happyvertical.com#143 (32229863)	agent-policy.yml hashes c143d7e6…, byte-identical to the canonical compatibility rendering
3	have-config	happyvertical/have-config#366 (cca08b83)	Repairing managed-output drift in the handbook, plus a README note

All generated with the control-plane migrate-repo, never hand-patched.

On ask 3

migrate-repo is absent from the artifact by design, so it was documented rather than shipped. scripts/build-policy-artifact publishes the sanitized checker as the artifact's hv-agent:

cp "$ROOT/scripts/hv-agent-policy-check" "$DIST/scripts/hv-agent"

Shipping the renderer would export the private fleet registry and organization-ruleset mutation to every consumer. The real defect was the corrective text naming scripts/hv-agent migrate-repo in the one place it cannot run — which is what pushes an agent toward hand-patching generated output, exactly as this issue declined to do.

Why it was not self-serve even with the right tool

migrate-repo on sdk and pdf fails before touching a file. require_diagnostic_lifecycle_cutover fires whenever the target stage is diagnostic — including a stage-preserving regeneration — and demands a current default-branch canary for every required repository. That canary's not_before follows the last commit to the channel state, so a promotion invalidates every canary in the fleet at once, blocking post-promotion drift repair in precisely the window when post-promotion drift appears. Tracked as happyvertical/have-config#365, which also records happyvertical/smrt: repository merge queue authority drifted — a separate live finding.

Root cause

Rollout checklist step 5 — "during smoke, migrate every affected repository" — did not complete for the whole affected fleet when generation 21 promoted. Repositories it missed fail closed on their own main, which is why this presented as unattributable drift rather than as an incomplete rollout.

Follow-through

happyvertical/sdk#1177, happyvertical/pdf#120, and happyvertical/happyvertical.com#141 are no longer blocked by policy drift. Each still needs its branch updated onto the repaired main and a re-claim/re-release bound to the new head before it can merge — one cycle each, not tracked here.