feat: Spawn Drift detects drift but nothing regenerates — wire the self-heal PR

[Jammy2211]

Overview

Spawn Drift is a drift check with no generator behind it. The templates are declared a generated view, but the only thing that ever regenerates them is a human typing /spawn --apply. So the scheduled leg goes red, stays red, and is cleared by hand.

Both legs run identical code — the workflow has no trigger-dependent behaviour beyond the PR-only if: added in #118. The difference is when each runs relative to a human --apply:

date	template force-synced	dispatch run	gap	result
2026-07-13	11:08:46Z	11:09:02Z	16 s	PASS
2026-07-27	19:30:29Z	19:30:48Z	19 s	PASS

A leg fired seconds after the human stamped the templates cannot fail. Every green run in the workflow's history is one of those.

Plan

Mirror the lifecycle_drift.yml self-heal (#116), which solved the same shape of problem — an alarm-only check just emails a human once per push.

On schedule: regenerate and, if the tree differs, open a PR on the affected template repo rather than pushing. Do NOT copy lifecycle_drift's direct bot-push: these are force-synced generated views, so an automated push is a force-push to a published repo's main. A PR keeps the sanctioned-force-push exception a human act while removing the "nothing regenerates" gap — and #118 is the argument for a human seeing what is about to be published.

Detailed implementation plan

Affected Repositories

• PyAutoMind (primary)

Branch Survey

Repository	Current Branch	Dirty?
./PyAutoMind	main	clean

Suggested branch: feature/spawn-drift-self-heal

Implementation Steps

1. scripts/spawn.py — distinguish the two failure classes, which --check currently collapses into exit 1:
   • 0 clean
   • 1 content drift only → auto-fixable, safe to propose
   • 2 unsafe generation (UNMATCHED or canary hits) → a human decision, must NEVER be auto-PRed
     The distinction is the safety interlock: a canary hit means the generated tree contains instance content, so opening a PR would propose publishing a leak.
2. .github/workflows/spawn_drift.yml — on schedule/workflow_dispatch, branch on that exit code. On 1: regenerate, push a stable spawn/auto-sync branch to each drifted template repo, open or update a PR. On 2: fail, no PR.
3. Idempotence: a fixed branch name force-updated each run, so a weekly rerun refreshes the existing PR rather than opening a new one.
4. Tests for the exit-code contract.

Key Files

• scripts/spawn.py — main() exit path
• .github/workflows/spawn_drift.yml
• tests/test_spawn_template_contract.py

Known external dependency — flagging explicitly

Opening a PR on PyAutoMind-template / PyAutoMemory-template needs a token with write access to those repos; secrets.GITHUB_TOKEN is scoped to PyAutoMind only. The org's established cross-repo token is secrets.PAT_PYAUTOLABS (used by nightly-release.yml and PyAutoHands/release.yml).

Whether that PAT actually grants write to the two template repos cannot be verified from a local session — only a real run reveals it. The workflow therefore fails with an explicit, actionable message rather than silently doing nothing if the push or PR is refused.

Original Prompt

Click to expand starting prompt

draft/maintenance/pyautomind/spawn_drift_has_no_generator.md — filed during the #118 investigation.

[Jammy2211]

Shipped

PR #126 merged (8314b59). Template published: PyAutoMind-template d4c8104 (Memory already current).
Completion record: complete/2026/08/spawn-drift-self-heal.md.

Verified

• spawn --check against freshly cloned published repos: exit 0.
• The published template now carries exactly one workflow (lifecycle_drift.yml) and no configured secrets.
• 79 tests pass locally and on GitHub runners.
• Dry-run under bash -e with git push/gh stubbed: clean → no PR; drift → PR opened, already-current repo skipped; open PR → refreshed, no duplicate; merged PR → new one opened; canary → job fails, code=2, nothing proposed.

Two defects found by executing the workflow rather than reading it

1. A latent bug from fix: stamp the template's complete/index.md so its self-heal stops causing drift #120 — stamp_complete_index() broke on a relative --write DIR, which is exactly what a CI step passes. Every invocation to date happened to use an absolute path.
2. A crash was indistinguishable from drift (Python exits 1), so the self-heal would have read defect 1 as "templates are stale" and proposed a PR from a partial tree.

The review finding worth recording

This change broke rule 9, which it had established one PR earlier — the template would have shipped secrets.PAT_PYAUTOLABS. The root cause was in the tests: the .github fixtures were hand-written miniatures, so the secret check was inspecting a toy workflow while the real one had grown a PAT. Fixtures now read the real workflow files; control-tested, shipping spawn_drift.yml again fails four tests. Rule 9b became DROP.

Genuinely pending — merging settled neither

1. Whether PAT_PYAUTOLABS grants write to the template repos. Only a real run establishes it. The step fails with an explicit, actionable message rather than silently doing nothing; if the PAT is not scoped for this, the fix is a token change, not a code change.
2. The scheduled leg has still never passed on its own. Monday 06:17 UTC is its first honest test — and the first chance to see the self-heal open a PR instead of just going red.

Closes the #118 arc

#118/#119 (the EMPTY leak) → #120 (the drift loop publishing the fix created) → #121/#122 (.github instance automation) → #123/#124 (the last live-byte parse) → #125/#126 (this).

[Jammy2211]

The PAT question is settled — and my earlier framing of it was wrong

I recorded this as "only a real run tells us". That was a failure to look, not a genuine limit. Two corrections:

1. The secret was absent, which was checkable all along. gh api repos/PyAutoLabs/PyAutoMind/actions/secrets lists names. PAT_PYAUTOLABS was not on PyAutoMind — it is a repo-level secret on PyAutoBrain and PyAutoHands, and repo secrets do not cross repos. There were no org-level secrets either. Monday's scheduled run would have hit the guard and failed. Not silently — the explicit message did its job — but the self-heal was inert.

2. Once a fine-grained PAT was added, the path was proved rather than assumed. Instead of waiting for Monday: pushed a trivial drift marker to PyAutoMind-template, fired workflow_dispatch, and 24 seconds later the self-heal opened PR #1 with exactly the right diff:

README.md      +0/-2   removes the test marker
SPAWNED_FROM   +1/-1   9e872b9 -> 0a2085d

PyAutoMemory-template was correctly skipped as already current — so the per-repo drift detection works against real repos, not just the stubs used in the dry-run. PR merged as 7f8576f; --check back to exit 0; spawn/auto-sync auto-deleted.

So the scheduled leg should now work unattended for the first time. Monday 06:17 UTC remains the honest confirmation, but the mechanism it depends on is no longer an assumption.

Residual risk

The fine-grained token expires. When it does, the Monday run fails at the clone or gh pr create with a message naming the repo — visible rather than silent, but worth a calendar note. A scheduled job with an expiring credential is a slow trap.