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

README.md

@@ -168,7 +168,7 @@ Open the part relevant to your current question. Use the resource links above fo
 <details id="sessions">
 <summary>How many conversations do you need?</summary>
 
-<p>A practical arrangement is one planning conversation and one fresh implementation conversation for each PR. The planning conversation can cover requirements, the overall plan, the current step, and the next PR design; these do not each need their own chat. The workflow requires a fresh implementation context for each new PR, not a separate chat for every commit or test. This separation matters because planning often contains rejected proposals and superseded assumptions. A fresh implementation session starts from the approved files and current code, reducing the chance that an old discussion is mistaken for the final requirement.</p><div class="table-wrap"><table><thead><tr><th scope='col'>Conversation</th><th scope='col'>What you do there</th><th scope='col'>When to switch</th></tr></thead><tbody><tr><td>Planning conversation</td><td>Discuss requirements, ask the agent to inspect the repo and write the plans, review the current PR design, and approve its execution contract.</td><td>When that PR is approved, ask for a kickoff with the actual document paths and open a fresh implementation conversation.</td></tr><tr><td>Implementation conversation for PR A</td><td>Give the approved design and contract to the agent. Let it implement, validate, review, commit, and handle authorized PR/CI work.</td><td>Keep ordinary fixes, commits, and compact/resume in the same PR context. Do not start PR B here.</td></tr><tr><td>Review of PR A</td><td>Read the diff and handoff. Request repairs in the same implementation conversation, or explicitly authorize merge after you are satisfied.</td><td>A separate reviewer conversation is optional, not required. Repairs need updated evidence and CI for the final HEAD.</td></tr><tr><td>Planning and implementation for PR B</td><td>After A is confirmed merged, have the agent update A, its parent step, and the overall plan. Use those records to detail and approve B.</td><td>You can return to the planning conversation or open a replacement that reads the saved plans. Start B in another fresh implementation conversation.</td></tr></tbody></table></div><p>For a feature with two PRs, that usually means three working conversations: planning, implementation A, and implementation B. This is an example, not a fixed quota. A long planning conversation may need replacement, and an interrupted implementation may need recovery. Saved project documents, rather than another chat&#x27;s memory, carry the agreement between sessions. A handoff is the agent&#x27;s saved continuation note: what is done, what is still running, and what to do next.</p>
+<p>A practical arrangement is one planning conversation and one fresh implementation conversation for each PR. The planning conversation can cover requirements, the overall plan, the current step, and the next PR design; these do not each need their own chat. The workflow requires a fresh implementation context for each new PR, not a separate chat for every commit or test. This separation matters because planning often contains rejected proposals and superseded assumptions. A fresh implementation session starts from the approved files and current code, reducing the chance that an old discussion is mistaken for the final requirement.</p><div class="table-wrap"><table><thead><tr><th scope='col'>Conversation</th><th scope='col'>What you do there</th><th scope='col'>When to switch</th></tr></thead><tbody><tr><td>Planning conversation</td><td>Discuss requirements, ask the agent to inspect the repo and write the plans, review the current PR design, and approve its execution contract.</td><td>When that PR is approved, ask for a kickoff with the actual document paths and open a fresh implementation conversation.</td></tr><tr><td>Implementation conversation for PR A</td><td>Give the approved design and contract to the agent. Let it implement, validate, review, commit, and handle authorized PR/CI work.</td><td>Keep ordinary fixes, commits, and compact/resume in the same PR context. Do not start PR B here.</td></tr><tr><td>Review of PR A</td><td>Read the diff and handoff. Request repairs in the same implementation conversation, or explicitly authorize merge after you are satisfied.</td><td>A separate reviewer conversation is optional, not required. Repairs need updated evidence and CI for the final HEAD.</td></tr><tr><td>Planning and implementation for PR B</td><td>After A is confirmed merged, the implementation conversation records A&#x27;s merge identity and evidence; the synchronization owner — by default this planning conversation — updates A&#x27;s parent step and the overall plan, then uses those records to detail and approve B.</td><td>Finishing A does not finish the plan: the overall stays open until every step it listed is delivered or you drop it. You can return to the planning conversation or open a replacement that reads the saved plans. Start B in another fresh implementation conversation.</td></tr></tbody></table></div><p>For a feature with two PRs, that usually means three working conversations: planning, implementation A, and implementation B. This is an example, not a fixed quota. A long planning conversation may need replacement, and an interrupted implementation may need recovery. Saved project documents, rather than another chat&#x27;s memory, carry the agreement between sessions. A handoff is the agent&#x27;s saved continuation note: what is done, what is still running, and what to do next.</p>
 
 </details>
 

README.zh-CN.md

@@ -168,7 +168,7 @@ scope 按工具分别设置，因为正确答案本来就因工具而异：只
 <details id="sessions">
 <summary>到底要开几个会话？</summary>
 
-<p>一个方便的安排是：保留一个 planning 会话，每个 PR 再开一个新的 implementation 会话。需求、overall plan、当前 step 和下一个 PR design，可以在同一个 planning 会话里讨论，不用各开一个。工作流要求的是每个新 PR 用新的 implementation context，不是每次 commit 或 test 都换聊天。 这样分开，是因为 planning 里常有被否决的方案和后来改变的假设。新的 implementation 会话从已批准的文件和当前 code 开始，减少把讨论中的旧想法当成最终要求的机会。</p><div class="table-wrap"><table><thead><tr><th scope='col'>会话</th><th scope='col'>你在这里做什么</th><th scope='col'>什么时候切换</th></tr></thead><tbody><tr><td>Planning 会话</td><td>讨论需求，让 agent 检查 repo、写计划，review 当前 PR design，并批准 execution contract。</td><td>当前 PR 批准后，让 agent 准备带真实文档路径的 kickoff，再开新的 implementation 会话。</td></tr><tr><td>PR A 的 implementation 会话</td><td>把已批准的 design 和 contract 交给 agent，让它实现、验证、review、commit，并完成已授权的 PR 和 CI 工作。</td><td>普通修复、commit、compact 和 resume 都继续处理这个 PR，不在这里启动 PR B。</td></tr><tr><td>PR A 的 review</td><td>你看 diff 和 handoff。有问题，就在原 implementation 会话里要求修复；满意以后，再明确授权 merge。</td><td>可以另开 reviewer 会话，但不是必须。修复后，要更新证据，并确认最终 HEAD 的 CI。</td></tr><tr><td>PR B 的 planning 和 implementation</td><td>确认 A 已 merge 后，让 agent 更新 A 的记录、所属 step 和 overall plan，再据此设计并批准 B。</td><td>你可以回原 planning 会话，也可以新开一个，让它读已保存的计划。B 的 implementation 必须另开新会话。</td></tr></tbody></table></div><p>比如一个功能拆成两个 PR，通常就是三个工作会话：planning、implementation A、implementation B。这是示例，不是硬性数量限制。Planning 聊得太长可以换会话，implementation 中断了也可以恢复。会话之间传递约定，靠的是项目里保存的文档，不是指望另一个聊天自动记得前面的事。 Handoff 就是 agent 保存的接续说明，告诉恢复后的会话：做到哪儿了、什么还在跑、下一步是什么。</p>
+<p>一个方便的安排是：保留一个 planning 会话，每个 PR 再开一个新的 implementation 会话。需求、overall plan、当前 step 和下一个 PR design，可以在同一个 planning 会话里讨论，不用各开一个。工作流要求的是每个新 PR 用新的 implementation context，不是每次 commit 或 test 都换聊天。 这样分开，是因为 planning 里常有被否决的方案和后来改变的假设。新的 implementation 会话从已批准的文件和当前 code 开始，减少把讨论中的旧想法当成最终要求的机会。</p><div class="table-wrap"><table><thead><tr><th scope='col'>会话</th><th scope='col'>你在这里做什么</th><th scope='col'>什么时候切换</th></tr></thead><tbody><tr><td>Planning 会话</td><td>讨论需求，让 agent 检查 repo、写计划，review 当前 PR design，并批准 execution contract。</td><td>当前 PR 批准后，让 agent 准备带真实文档路径的 kickoff，再开新的 implementation 会话。</td></tr><tr><td>PR A 的 implementation 会话</td><td>把已批准的 design 和 contract 交给 agent，让它实现、验证、review、commit，并完成已授权的 PR 和 CI 工作。</td><td>普通修复、commit、compact 和 resume 都继续处理这个 PR，不在这里启动 PR B。</td></tr><tr><td>PR A 的 review</td><td>你看 diff 和 handoff。有问题，就在原 implementation 会话里要求修复；满意以后，再明确授权 merge。</td><td>可以另开 reviewer 会话，但不是必须。修复后，要更新证据，并确认最终 HEAD 的 CI。</td></tr><tr><td>PR B 的规划与实现</td><td>确认 A 已 merge 之后，implementation 对话记录 A 的 merge 身份和证据；synchronization owner——默认就是这个 planning 对话——回写 A 的 parent step 和 overall plan，再拿这些记录去细化并批准 B。</td><td>做完 A 不等于做完计划：overall 里列出的每个 step 都交付、或者被你去掉之前，它一直是未完成的。你可以回到 planning 对话，也可以开一个替代对话去读已保存的 plans。B 要在另一个全新的 implementation 对话里开始。</td></tr></tbody></table></div><p>比如一个功能拆成两个 PR，通常就是三个工作会话：planning、implementation A、implementation B。这是示例，不是硬性数量限制。Planning 聊得太长可以换会话，implementation 中断了也可以恢复。会话之间传递约定，靠的是项目里保存的文档，不是指望另一个聊天自动记得前面的事。 Handoff 就是 agent 保存的接续说明，告诉恢复后的会话：做到哪儿了、什么还在跑、下一步是什么。</p>
 
 </details>
 

dist/claude-code/structured-coding/README.md

@@ -105,7 +105,7 @@ A practical arrangement is one planning conversation and one fresh implementatio
 | Planning conversation | Discuss requirements, ask the agent to inspect the repo and write the plans, review the current PR design, and approve its execution contract. | When that PR is approved, ask for a kickoff with the actual document paths and open a fresh implementation conversation. |
 | Implementation conversation for PR A | Give the approved design and contract to the agent. Let it implement, validate, review, commit, and handle authorized PR/CI work. | Keep ordinary fixes, commits, and compact/resume in the same PR context. Do not start PR B here. |
 | Review of PR A | Read the diff and handoff. Request repairs in the same implementation conversation, or explicitly authorize merge after you are satisfied. | A separate reviewer conversation is optional, not required. Repairs need updated evidence and CI for the final HEAD. |
-| Planning and implementation for PR B | After A is confirmed merged, have the agent update A, its parent step, and the overall plan. Use those records to detail and approve B. | You can return to the planning conversation or open a replacement that reads the saved plans. Start B in another fresh implementation conversation. |
+| Planning and implementation for PR B | After A is confirmed merged, the implementation conversation records A's merge identity and evidence; the synchronization owner — by default this planning conversation — updates A's parent step and the overall plan, then uses those records to detail and approve B. | Finishing A does not finish the plan: the overall stays open until every step it listed is delivered or you drop it. You can return to the planning conversation or open a replacement that reads the saved plans. Start B in another fresh implementation conversation. |
 
 For a feature with two PRs, that usually means three working conversations: planning, implementation A, and implementation B. This is an example, not a fixed quota. A long planning conversation may need replacement, and an interrupted implementation may need recovery. Saved project documents, rather than another chat's memory, carry the agreement between sessions. A handoff is the agent's saved continuation note: what is done, what is still running, and what to do next.
 

dist/claude-code/structured-coding/README.zh-CN.md

@@ -105,7 +105,7 @@ Specification 是写下来的要求，不是一个盯着所有操作的程序。
 | Planning 会话 | 讨论需求，让 agent 检查 repo、写计划，review 当前 PR design，并批准 execution contract。 | 当前 PR 批准后，让 agent 准备带真实文档路径的 kickoff，再开新的 implementation 会话。 |
 | PR A 的 implementation 会话 | 把已批准的 design 和 contract 交给 agent，让它实现、验证、review、commit，并完成已授权的 PR 和 CI 工作。 | 普通修复、commit、compact 和 resume 都继续处理这个 PR，不在这里启动 PR B。 |
 | PR A 的 review | 你看 diff 和 handoff。有问题，就在原 implementation 会话里要求修复；满意以后，再明确授权 merge。 | 可以另开 reviewer 会话，但不是必须。修复后，要更新证据，并确认最终 HEAD 的 CI。 |
-| PR B 的 planning 和 implementation | 确认 A 已 merge 后，让 agent 更新 A 的记录、所属 step 和 overall plan，再据此设计并批准 B。 | 你可以回原 planning 会话，也可以新开一个，让它读已保存的计划。B 的 implementation 必须另开新会话。 |
+| PR B 的规划与实现 | 确认 A 已 merge 之后，implementation 对话记录 A 的 merge 身份和证据；synchronization owner——默认就是这个 planning 对话——回写 A 的 parent step 和 overall plan，再拿这些记录去细化并批准 B。 | 做完 A 不等于做完计划：overall 里列出的每个 step 都交付、或者被你去掉之前，它一直是未完成的。你可以回到 planning 对话，也可以开一个替代对话去读已保存的 plans。B 要在另一个全新的 implementation 对话里开始。 |
 
 比如一个功能拆成两个 PR，通常就是三个工作会话：planning、implementation A、implementation B。这是示例，不是硬性数量限制。Planning 聊得太长可以换会话，implementation 中断了也可以恢复。会话之间传递约定，靠的是项目里保存的文档，不是指望另一个聊天自动记得前面的事。 Handoff 就是 agent 保存的接续说明，告诉恢复后的会话：做到哪儿了、什么还在跑、下一步是什么。
 

dist/claude-code/structured-coding/SKILL.md

@@ -39,7 +39,7 @@ The original long prompts are deliberately preserved. Do not replace them with t
 7. Audit uncertainty before asking. Resolve bounded details and ordinary failures autonomously. Record departures immediately. Escalate material changes or work outside existing authorization with concrete evidence and a proposed next step.
 8. Respect test ownership and the approved cost envelope. Real Gates require real evidence. CI evidence must match the exact final PR head; do not repeat expensive full suites without an independent reason.
 9. Continue authorized execution until the PR is ready for operator review, including CI repair when needed. Present the complete handoff and retain the explicit merge-approval boundary.
-10. After confirmed merge, update progress and implications in the step and overall documents. Detail one step ahead; do not begin the next PR in the old implementation context.
+10. After confirmed merge, update progress and implications in the step and overall documents. Completing a PR does not complete its overall; record what remains. Detail one step ahead; do not begin the next PR in the old implementation context.
 
 ## Authority and packaging boundaries
 

dist/claude-code/structured-coding/prompts/implementation-working-rules.md

@@ -199,6 +199,17 @@ ENDPOINT AUTHORITY:
   that restriction has a source: the operator's instruction. The absence of any  
   instruction does not.
 
+POST-MERGE SYNCHRONIZATION OWNER:  
+  <default: the planning session owns the step and overall updates; THIS  
+   implementation session owns the PR document, the merge identity, the  
+   evidence, the deviations and the remaining issues>
+
+  One conversation may own both. Record which, so neither session assumes the  
+  other did it. Only the owner writes the parent documents; the other reports  
+  to the owner. Do not overwrite parent content that has moved on — reconcile.
+
+  Owning this is not merge authority and does not confer it.
+
 NORMAL STOP CONDITION:  
   <e.g. PR 01a READY FOR OPERATOR REVIEW — DO NOT MERGE>