Fix: route Engine development to its runbook from the mechanic

[StarshipSuperjam]

A green mechanical check below shows this change conforms to the engine's rules — not that it is correct. What covers correctness is the behavioural steps in Review you can run yourself and the change's honest self-report — not a reading of the diff for defects; a green check is never a substitute for that. Your merge is the binding gate.

About those checks: only the one that runs when the change is proposed for merge can stop a risky merge — a check that ran while the change was still being written is early advice. The engine's checks are proven against deliberately broken examples they must catch — the custom ones each against their own, the standard kinds against one shared example — so a passing check can't be one that quietly did nothing; a few are openly-noted exceptions where that kind of proof doesn't apply. Either way that speaks to the check, not to whether this change is right. And a check that could not run leaves its area unverified.

Closes #1046

Purpose

Make the Engine's own development governance reachable from the workshop where Engine development actually starts.

The runbook at .engine/operations/engine-development.md carries the trust model (a non-engineer sole gate-holder who cannot read code, so review is informed consent on evidence rather than code review), the twelve development invariants, and the three frozen check names. It was written as though the only way to work on the Engine were to sit in its home repository. Engine development now normally starts from an engine-mechanic deployment, which cuts an isolated worktree of the home repository and delivers one direct pull request. Every such worktree already contains that runbook — but no operation told a session to read it there, and the engine-develop-engine route declined outright anywhere but the home repository, so on a mechanic it matched the operator's intent and then dead-ended. Filed as #1046.

• The route now selects a lane by which repository holds the files the change edits, and is the authored home of that discriminator because it travels to every deployment and is read before a lane is chosen.
• The owned-product build runbook gains one product-agnostic step that grounds a Build in the product's own development runbook, read at a resolved base commit rather than the mutable working tree.
• The development runbook keeps the reasoning and the discipline, and states which lanes exist and why — with its trust model and all seven steps left byte-identical.

Impact: The disciplines that govern how the Engine is changed are now reachable from the path used to change it, instead of sitting behind a route that refused.

Scope

Routing prose across three surfaces, plus the two generated indexes that derive from them.

• .engine/operations/engine-development.md — the Purpose section becomes a lane block placed below the byte-frozen trust model; the frontmatter title drops its home-repo binding; step 1 gains a lane-confirmation clause that keeps the original step-1 text verbatim as its suffix.
• .engine/operations/owned-product-build.md — one inserted step, fail-closed: verify the base with rev-parse --verify and refuse if it does not resolve, probe presence with ls-tree across three stated outcomes, read at the resolved commit, and grant governing authority only on a positive repo_identity.slug_eq match.
• .claude/skills/engine-develop-engine/SKILL.md — a lane-neutral description (the trigger text a model matches on), a five-branch body, and a second declared engine-target for owned-product-build.md; the Codex twin is regenerated from it.
• .engine/knowledge/graph.json and .engine/self-map.md — regenerated, never hand-edited.

Change profile — the shape of this pull request at a glance:

• Size: 6 files changed, +93 / −24 lines.
• Kinds of thing touched: 2 operations, 1 codex-skill, 1 skill, 2 other files (not in the engine's map).
• Where: .engine/operations, .agents/skills, .claude/skills, .engine, .engine/knowledge.
• Shape: 5 commits on this branch — a standalone change unless a Part of #N line below says it is one slice of a larger effort.

This is a description, not a gate — it never blocks a merge. It is here so you can weigh the change by what it touches, not by its line count.

Impact: No code, schema, check, CLI, or manifest field changes; the change is prose plus the indexes that mirror it.

Behaviors

The capabilities this change delivers, each with the test that exercises it.

• The trust model, all seven steps, 'Done when', the twelve development invariants, and the three frozen check names survive the rewrite byte-for-byte. — Two region digests recomputable from git against base b6c6c2e: sed -n '/^It rests on the **trust model/,/protected-branch merge.$/p' FILE | shasum -a 256yieldsd8329b2d…, and awk '/^## Steps$/{s=1} s && /^2. /{f=1} f' FILE | shasum -a 256yieldsdf8ba629…, identical at base and at head., ``tools.test_build_coordinator_preservation — BO-06's prose anchor 'Codex adapter surfaces' still resolves in its owner file.
• The seven phrases pinned against owned-product-build.md survive the inserted step and the renumbering, including the line break that keeps 'mechanic_build.py worktree' intact. — ``tools.test_build_coordinator — the owned-product phrase-pin assertions at its historical-scenario corpus.
• The route's declared delegation is visible to the generated maps rather than left in prose. — tools/self_map.py check` — the Automatic-routes row for `engine-develop-engine` now renders both targets.`, tools/codex_gen.py check — the regenerated Codex twin matches its canonical source.

Out of scope

Three things this deliberately does not do, each for a stated reason rather than as deferred work.

• The runbook does not become a travelling asset and stays on both first-run retirement lists. — Shipping a guide for developing the Engine to every deployed project would contradict the root floor those projects load every session — 'changing the Engine's own machinery isn't this project's job', a line the runbook itself quotes. (deferred by Operator chose minimal rewiring over the supplied travelling-asset proposal.)
• The runbook is not removed. — The trust model, the twelve development invariants, and the three frozen check names exist nowhere else that travels, and both valid lanes need them.
• The session-start grounding in boot.py is untouched, including the mechanic overlay. — The mechanic-only surface was the natural home for this routing and is foreclosed by its Tier-0 budget: the render is 834 characters against a 900 cap, roughly 66 characters of headroom, with its clauses test-pinned including their rationale phrases. The consequence is recorded rather than hidden — in the mechanic lane nothing at session start names this runbook; the owned-product build step is what reaches it. (deferred by Operator decision after being shown the measured headroom.)
• No new decision record is cut for the two-lane routing rule. — eADR-0026 is silent on who may develop the Engine, so this Build makes a new routing decision rather than restoring conformance with an old one — but it is reversible prose that misses the contract bar, so it is recorded here in this body instead.

Impact: The lifecycle, the published route availability, and the boot output are all unchanged, so nothing here alters what an existing deployment receives until it upgrades.

Risk

4 risks, ranked, each with the bound that contains it.

• The rewrite could soften a development discipline while reading as a tidy reorganization, and no automatic signal would catch it — these paths sit entirely outside the weakening guard, whose prefixes cover only .github/workflows/ and .engine/check/, so even deleting this file would produce no finding (the most safety-sensitive edit). Two region digests recomputable from git against a recorded base sha, covering the trust model and everything from step 2 to end of file; the complete before/after diff in this body; and an enumerated discipline inventory handed to two cold reviewers as their checklist. The Purpose framing sentences are the residual the digests do not cover, and are named as lens-only.
• A session could be told to trust a governance document planted in a product repository it builds. Authority is granted only on a positive repo_identity.slug_eq match between the verified product slug and the home_repository recorded in the mechanic's own manifest — never a value read from the product. slug_eq returns false on any unreadable or mismatched value. The step also records why is_home_repo must not be used here.
• The route's new branches travel to every deployed copy, while the runbook does not. The refusal branch lives in the route itself, and the discriminator is keyed on where the edited files live rather than on a configuration flag any deployment can set. What actually protects the arrangement is code, not this prose: the guardrail-ack that fires on first arming an executable build target, and the fail-closed host-anchored checkout belt in mechanic_build.py.
• Routing prose is model-followed, with no enforcement behind it. Disclosed rather than mitigated. The lanes carry a stated fail direction — refuse when the lane cannot be established — but that is posture, not a guarantee.
• Guardrail disclosure. No guarded or floored file is touched, and .engine/uv.lock is absent from the diff. That is not reassurance: it is the reason this body carries digests and a full diff, because the file defining the merge gate produces no automatic signal when it changes.

Impact: The most safety-sensitive edit is the authority test in the owned-product step; it was wrong in an earlier revision of this branch and is now fail-closed.

Validation

Green on the final commit: 6,399 tests, the CI suite, both regenerated indexes in sync, and the Codex twin in parity.

• Engine CI — the full mechanical check suite — passed at a0d45ced3b5f (log sha256:4b0d74567e33e3d14a2273f53862143206f1f5effcd9ea4f5851528575f299a5)
• Engine self-tests — the full behavioural self-test run — passed at a0d45ced3b5f (log sha256:6583ae3c531fc9b0f5fd69df58dcf30489c6ea4fa985a725be73853872078195)
• Caveat: The guardrail-weakening check cannot pass locally — it fails closed without a pull-request context. It is reported here as not-locally-verified, never as green; it enforces in CI.
• Caveat: Four CI-only checks had no witness in the local run (dependency-review, pr-body-completeness, product-lock-integrity, protection). They enforce when this is proposed for merge.
• Caveat: The behavioral demonstration is post-upgrade, not post-merge, and therefore cannot inform this merge decision. engine-mechanic runs its own installed copies of the route and the owned-product runbook, so the new text reaches it only after a release is cut and the mechanic is upgraded. Its declared fate: run after the upgrade, with the result recorded on Fix: route Engine development to its runbook when the work starts from the mechanic #1046.
• Caveat: One review round read the tree while repairs were in flight, so its verdict on the authority predicate quotes text since replaced; the scoped re-review was run against the final commit and closed the finding.
• The engine's live helpers answered this session.
• Regeneration updated 2 of the engine's generated index files (.engine/knowledge/graph.json, .engine/self-map.md) from the final tree — generated paths only.

Impact: Mechanical green covers the frozen regions, the pinned phrases, and the indexes; it cannot judge whether the routing prose is right, which is what the reviews and the demonstration are for.

Review

Three plan rounds and one deliverable round across four cold lenses each, plus a scoped re-review of the repaired seam; five blocking findings, all fixed before submission.

• Coverage. standard depth. Plan review ran before any code; the deliverable review (divergence-hunter, security-governance, spec-conformance, technical-integrity, usability) ran after.
• Code execution. With this PR, a reviewer ran the change's code in a throwaway copy to judge it — it never touched your project.
• Plan round 1 — four lenses found that grounding in the mutable worktree would make the governance reflexive (a build editing the runbook would be governed by its own unmerged edits), that the discriminator keyed on repository configuration and so would sweep mechanic-local work into a product worktree, that the route's description is the trigger text and left home-bound would make the fix unreachable, and that two of my claims were overstated.
• Plan round 2 — the revision introduced new defects the lenses caught: an enumeration that excluded step 4, which is the plan gate itself; the trust model losing the byte-identity protection round 1 had given it; and the base read failing open, which I then reproduced (an unset base makes git show read the index and return the mutable copy with exit 0 and no stderr).
• Plan round 3 — established that activation is post-upgrade rather than post-merge, that the discriminator belongs in the route rather than in a runbook retired from every deployed copy, and that the authority leg needed a predicate rather than prose.
• Deliverable round — security-governance found the authority predicate failed open: is_home_repo returns true for any product carrying no engine manifest, so a planted file would have governed. Reproduced against a throwaway repo, then replaced with a fail-closed positive match. Usability found the spanning case buried where a session would fall through to refusal, and a refusal with no next action.
• Scoped re-review — the repaired seam was re-reviewed against the final commit by the lens that found it; the blocking finding is closed, with both frozen regions still matching base.
• Finding PG-1. The one-line description on this route is what decides whether it is offered at all, and it said the work happens in the home repository — so from the mechanic the route would likely never have been picked up. Fixed before any code was written.
• Finding PG-2. The plan would have had a session read the rules it works under from the same copy it was editing. It now reads the settled version instead. Fixed before any code was written.
• Finding PG-3. The first attempt at that fix had a hole: if one value was missing the command quietly returned the edited copy anyway. I reproduced it, then made it check first and stop if it cannot. Fixed before any code was written.
• Finding PG-4. A draft listed which steps of the runbook apply and accidentally left out the step requiring plan review. All steps now apply. Fixed before any code was written.
• Finding PG-5. The lane test looked at how the repository is configured rather than at where the change lands, which would have sent your workshop-local work into an engine-template worktree.
• Finding PG-6. I had overstated what was unreachable. Two of the four things I named already reach the mechanic; the corrected, narrower gap is what this change closes.
• Finding PG-7. I first reported the absence of automatic guarding as reassurance. It is the opposite, and this body now says so plainly.
• Finding PG-8. My own revision dropped the protection on the trust-model paragraph. There are now two digests, and the first one pins exactly that paragraph.
• Finding PG-9. Where the route sends a session was left in prose, so the generated maps would have been silently wrong about it. It is now declared as data.
• Finding PG-10. I had said this takes effect when you merge it. That was wrong: your workshop runs its own installed copy, so it arrives only after a release and an upgrade.
• Finding PG-11. The routing rule was written into a file that does not exist in deployed copies, where the refusal branch could never be read. The rule now lives in the route.
• Finding PG-12. The decision about whether another repository's document may set your rules had no actual test behind it. It now has one.
• Finding DG-1. A reviewer found a real hole. The test I used to decide whether another repository's document may redefine your rules is built to answer yes when it cannot tell — safe for its original job, exactly wrong for this one. I reproduced it, then switched to a test that demands a positive match and refuses otherwise.
• Finding DG-2. A request touching both repositories fell through to the refusal branch instead of being handled. It now has its own branch.
• Finding DG-3. Two seven-step lists had to be reconciled by guesswork; the runbook now says they are different axes, not two copies of one sequence.
• Finding DG-4. The can't-tell-which-lane path told a session to refuse with no way forward. It now names the files and asks you which repository they are in.
• Finding DG-5. My rewrite weakened a pronoun just above the frozen trust model; fixed from the line above, since the paragraph itself could not be touched.
• Finding DG-6. The step said to record the base commit but not why it matters; the reason is now stated.
• Reviewer disagreement PG-1: The one-line description on this route is what decides whether it is offered at all. It said the work happens in the Engine's home repository, so from the mechanic the route would likely never have been picked up - the fix would have looked right and done nothing. The line now names both places. Fixed before any code was written.
• Reviewer disagreement PG-2: The plan would have had a session read the rules it works under from the same copy it was editing - so a change to those rules would have started governing the very change that made it. It now reads the settled version instead, and says so in words. Fixed before any code was written.
• Reviewer disagreement PG-3: The first attempt at that fix had a hole: if one value was missing, the command quietly handed back the edited copy anyway, with no error. I reproduced it to be sure. It now checks that value first and stops if it cannot, rather than carrying on. Fixed before any code was written.
• Reviewer disagreement PG-4: A draft of the plan listed which steps of the runbook apply, and the list accidentally left out the step that requires plan review. A session reading it could have concluded it was allowed to skip that review. All steps now apply. Fixed before any code was written.
• Reviewer disagreement PG-10: I had said this fix takes effect once you merge it. That was wrong. Your workshop repo runs its own installed copy of these files, so the change reaches it only after a release is cut and the workshop is upgraded to it. The plan and the checks you would run now say so plainly, so you are not expecting a change that has not arrived yet.
• Reviewer disagreement DG-1: A reviewer found a real hole in my work, and it was the serious kind. The step I wrote decides whether a document found in another repository may redefine the rules your Engine works under. I reused an existing test for that, but that test is deliberately built to answer yes when it cannot tell - safe for its original job, exactly wrong for this one. So a file placed at the right path in almost any product repo would have been obeyed. I reproduced it to be certain, then switched to a test that demands a positive match and refuses otherwise. Fixed before this reached you.
• Reviewed vs submitted. reviewed bf8a09ec0930, submitted a0d45ced3b5f — 5 files changed, 28 insertions(+), 15 deletions(-)

Spec-derived acceptance steps

There is no settled spec criterion governing how a session ENTERS the Engine-development runbook or the lane routing this Build adds, so the plan's own success obligations govern conformance review. The nearest settled criterion — that the engine-mechanic is non-reflexive and delivers a direct pull request into its owned product — is unaffected in its own terms (this Build changes neither the delivery route nor the executable upgrade rule) and is extended in spirit: the plan gate found that reading GOVERNANCE PROSE from an unmerged branch is a reflexivity the record never covered, and this Build closes it by grounding at the merged base. Reconciling the mechanic-side corpus is separately tracked and, by standing decision, is not gated on this Build.

Impact: Five blocking findings were found and fixed before this reached you; the two most serious — a reflexive read of the governance text, and an authority test that failed open — were both defects I introduced and neither would have been caught by any automatic check.

Demonstration

A step you can run yourself that drives the changed surface and can genuinely fail.

• Run: In engine-mechanic, after this merges AND a release is cut AND the mechanic is upgraded to it, start a fresh session and say: "Let's work on the Engine's own machinery." Then, in a second fresh session, say: "Update the spec corpus for platform currency."
• It PASSES when: The first session names owned-product-build.md, cuts an isolated worktree, and quotes the trust model or a named invariant read at the worktree's base before it plans. The second session treats the work as an ordinary Build in engine-mechanic and does not cut an engine-template worktree.
• It FAILS when: The first session declines, or grounds from the worktree's working tree instead of its base, or plans before grounding. The second session cuts an engine-template worktree for work whose files live in the mechanic.

Impact: Run it to watch the change work — an unrun step is a promise, not proof.

Files of interest

The paths that most determine this change.

• .engine/operations/owned-product-build.md — Carries the whole safety argument: the fail-closed base resolution, the three-outcome presence probe, and the positive-match authority test that decides whether another repository's document may redefine this session's gates.
• .claude/skills/engine-develop-engine/SKILL.md — The authored home of the lane discriminator, and the only surface present in every deployment — so the refusal branch that protects adopters can only live here.
• .engine/operations/engine-development.md — The governance itself. Read the Purpose diff closely; everything from the trust model down is digest-pinned and unchanged.

Impact: Two of the three are prose a session follows; the third is the rulebook the merge gate rests on.

AI involvement

How this change was produced and who decided what.

• Claude Code (Fable 5) — Orchestrated the Build: assessment, plan authoring and revision, all edits, and ground-truthing every reviewer claim against the source before recording it.
• Claude Code subagents (Opus 4.8) — Four cold design lenses across three plan rounds — architecture, feasibility, product-intent, risk-governance.
• Claude Code subagents (Sonnet 5) — Four cold QA lenses at the deliverable gate — divergence-hunter, spec-conformance, usability, security-governance — plus the scoped repair re-review.
• Operator decision: Chose minimal rewiring over the supplied proposal, which would have made the runbook a travelling asset, flipped the route's published availability, and changed a preservation obligation's scope.
• Operator decision: Chose to leave the session-start grounding untouched after being shown its measured budget headroom.
• Operator decision: Settled the governance boundary for work whose files live in the mechanic, and directed that the rule be phrased by which repository holds the edited files so it survives the planned retirement of the ADR and eADR record systems.
• Operator decision: Chose Standard review depth after a risk assessment at kickoff.
• The mechanical parts — digests, greps, regenerated indexes, test runs — are deterministic and recomputable. The load-bearing judgment is in the routing prose itself, which no check enforces: which lane a session picks, and whether another repository's document may redefine this session's gates. That second one is where I was wrong twice, and both times a cold reviewer caught it rather than a test.

Impact: Design judgment carries this change; the mechanical evidence bounds only what did not change.

Release-Impact: patch — backward-compatible correction or change to an existing feature