spec: plan the whole route, and name who propagates after a merge

[yuema137]

Closes #26. Closes #27.

Both land on the After-merge route and the overall document, so they ship together rather than in two passes over §10 and its mirror.

#26 — progressive detail became progressive omission

An adopting project's bounded organizing effort produced one inventory PR, and the agent reported that PR's completion as the completion of the effort. The narrow PR was correct; treating its scope as the effort's completion criterion was not.

§2 required "step boundaries" and §3 keeps later PRs at medium scope. Neither said the overall must enumerate all currently identifiable necessary steps before the first freeze, nor that finishing a PR does not finish its overall — so the omission was available.

• §2 now states the checkpoint at the moment it applies — before the operator accepts the overall and before the first PR is frozen: the complete effort and its outcomes; every identifiable necessary step with intended output, broad order and acceptance checkpoint; each operator requirement matched to a step or to an explicit unresolved decision; discovery-dependent work as conditional steps rather than omissions; and which subset the current PR covers.
• Two guards against overreading it: a requirement leaves the effort only through an explicit scope decision, never because it does not fit the first PR; and this is a completeness check on the route, not a demand for speculative architecture or a minimum step count. A genuinely single-step effort stays one step.
• §3 gains one sentence, because that was the neighbouring confusion: expanding a step document in place is a document-layout rule about one step and says nothing about how many steps the overall has.
• §10 separates the two claims: a merged PR completes that PR; the overall is complete only when every enumerated step is delivered or explicitly dropped by an operator scope decision. Work the merge revealed is added at its own level — a frozen, bounded PR stays bounded, which the issue asks for by name since the obvious wrong fix is to expand it until it covers the gap.
• SKILL.md rule 10 carries the one sentence, since the issue's premise is that the rule must sit on the path an agent actually reads.

Worth recording: this repository's own overall plan for this effort made the same mistake three days into the same work — its step list was missing a PR because its author read the issue bodies and not their comments. That is why the checkpoint is written down rather than assumed.

#27 — the decision, not a menu

§10 listed four post-merge actions and said "the agent" throughout. With a planning conversation and an implementation conversation both alive, the responsible session was undecided: either both assume the other updated the overall, or one invents a rule and states it as the workflow's.

The decision is a split, not a single owner:

Action	Default owner	Why
PR document to MERGED, merge identity, evidence, deviations, remaining issues	the implementation session	it holds the evidence
Step and overall updates	the contract's synchronization owner — by default the planning session	it holds the agreement and designs the next PR from these records
Re-audit and detail the next PR	the planning session	already required to be there

One conversation may own all of it; a project wanting implementation-side propagation says so once in POST-MERGE SYNCHRONIZATION OWNER. The split exists so an interruption between the two loses nothing — it does not require another agent.

• The handoff is explicit: implementation marks parent synchronization pending and names the owner; the owner records the parent updates and acknowledges, in the same place, what it recorded.
• Only the owner writes the parent documents; the other reports. Parent content that has moved on is reconciled, never overwritten, so the two cannot clobber each other.
• Owning propagation is not merge authority and does not confer it — who executes an authorized merge stays separate from who owns planning updates.
• An implementation conversation may close once its record is durable, where durable does not mean published: a project keeping plans out of version control keeps them there.
• The README session table's fourth row says all of this in the user's language, including Validate overall-plan scope coverage before detailing or freezing the first PR #26's sentence — finishing A does not finish the plan.

This is the one decision made on the operator's behalf. Their approval covered the order of work, not this specific split. It is a default in a template, so overruling it costs one line in a contract; flagged here rather than buried.

Validation

• Both specification baselines (SKILL.md, implementation-working-rules.md) updated deliberately; the pin refuses the edits until they are
• Shipped text read back from dist/ and from the regenerated README, not only from source
• Ran 171 tests ... OK (skipped=1); all five --check validations PASS; packages at codex 23 / claude-code 22 files
• Both languages; mirror and presentation hashes refreshed

Limits

No mechanical check is added and none is claimed. §2's checkpoint is a semantic review — no filename or checkbox can establish that a route is complete. What changed is that the requirement is stated where the work happens, and that "PR merged" and "effort complete" can no longer be the same sentence.

🤖 Generated with Claude Code