Define planning-chat lifecycle and replay contract

CHANGELOG.md

@@ -29,6 +29,8 @@ All notable changes to this portable workflow pack are documented here.
 
 - **Adopt the recommended Codex GPT-5.6 routing profile: Sol/xhigh multi-lane coordination, adversarial QA, and high-risk escalation; Terra/high only for positively classified simple workers; and Sol/high for uncertainty and routine deterministic QA.**
 - **Default autonomously clearable blocked Goal-mode batches to one deduplicated 15-minute current-thread monitor when supported, with manual-resume fallback and no polling for user-input blockers.**
+- **Clarify the portable planning-chat lifecycle: batch coordinators own completed-batch audits, prompt-only chats may archive after durable worker handoff, and parents reconcile only durable audit handoffs before release or archive.**
+- **Clarify same-chat launch selection, complete triage response ordering, and completed-batch audit handoffs so only outstanding work blocks archival while fully evidenced terminal dispositions remain durable.**
 - **Harden model-routed batches with fail-closed launch assurance, Sol-controlled conservative GPT-5.6 coordination and checking, bounded Terra execution envelopes, and auditable worker assignment evidence.**
 - **Change the public Codex native-plugin identifier from `agent-workflows` to `scw`; existing native-plugin users must remove the old entry and reinstall `scw`, while the repository, marketplace, helper, installer, status, and upgrade identities remain `agent-workflows`.**
 - **Make `$pr-batch` the sole workflow for one or more targets, with a default single-target worker subagent, staged cost-aware model routing, and explicit merge authority before launch.**

skills/plan-pr-batch/SKILL.md

@@ -354,6 +354,9 @@ Plan a PR batch
    - Do not start `$pr-batch` unless the user asks; then hand them the fenced
      goal prompt and any Batch Plan path appendix that the prompt explicitly
      depends on, in the same request.
+   - Response order: Batch Plan; generated goal prompt; `Goal prompt character count: N characters (target: codex|claude|generic)`; selected exact `Conversation status: Ready for archiving.` or `Conversation status: Follow-ups remain — <each exact action or blocker>.` line. The selected exact Conversation status line is the actual final user-visible line.
+
+Use the canonical [Planning-Chat Lifecycle](../../workflows/pr-processing.md#planning-chat-lifecycle): a prompt-only planning chat may hand off stable planning state; a planning parent supervises worker execution and performs narrow read-only cross-batch reconciliation; batch coordinators execute and own live lanes and closeout.
 
 ## Canonical Readiness Vocabulary
 
@@ -385,6 +388,21 @@ or validator, but they are not required and JSON is not mandatory.
   `UNKNOWN` route out of a ready prompt.
 - Batch size target: `codex`, `claude`, or `generic`; max items per wave and
   split rationale.
+- While the chat remains a planning chat, Planning-chat role: exactly one of `prompt-only` or `parent-orchestrator`.
+- Planning-chat role selector: default to `prompt-only`.
+- While the chat remains a planning chat, select `parent-orchestrator` only when the planner explicitly retains one or more cross-batch dependency, release, or shared-follow-up responsibilities.
+- Prompt-only is eligible only after durable handoff to a distinct batch coordinator.
+- After same-chat self-launch, transition to the batch-coordinator lifecycle only when no cross-batch, dependency, release, or shared-follow-up responsibility is retained.
+- While the chat remains a planning chat, Retained responsibilities: list each exact retained responsibility.
+- While the chat remains a planning chat, Archive/closeout owner: prompt-only chat archives; parent-orchestrator archives after reconciliation.
+- After same-chat self-launch with no retained responsibility, record: Lifecycle transition: transitioned-to-batch-coordinator. Planning-chat role: not applicable after self-launch. Archive/closeout owner: batch coordinator. Retained responsibilities: none (no cross-batch, dependency, release, or shared-follow-up responsibility is retained).
+- This is a transition out of planning, not a third planning role; neither `prompt-only` nor `parent-orchestrator` is selectable after the transition.
+- For same-chat launch with retained cross-batch, dependency, release, or shared-follow-up duties, select and record `parent-orchestrator` immediately because retained duties determine the mandatory planning role; list each exact retained responsibility, do not use `prompt-only`, and do not record `Retained responsibilities: none`.
+- Before durable handoff/launch of a distinct batch coordinator succeeds, this is a BLOCKED parent-orchestrator: it stays read-only, starts no workers, records the exact distinct-coordinator handoff blocker/follow-up, and uses final `Conversation status: Follow-ups remain — <each exact action or blocker>.`
+- Once durable handoff/launch of a distinct batch coordinator succeeds, workers may start under that coordinator, which owns PR/check/QA/merge/completed-batch-audit closeout, while the parent remains read-only.
+- Prompt-only conversation-status/archive expectation: use exactly `Conversation status: Ready for archiving.` only when all prompts are delivered or registered and stable batch/lane/dependency/ownership state is durable outside the chat; no unhanded-off question or planner-owned `UNKNOWN` remains; a durably handed-off coordinator-owned worker state, including a worker `UNKNOWN`, does not block prompt-only archive; otherwise use exactly `Conversation status: Follow-ups remain — <each exact action or blocker>.` and list each exact action or blocker.
+- Parent-orchestrator conversation-status/archive expectation: clean only when parent reconciliation has no OUTSTANDING follow-up or `UNKNOWN`; then use exactly `Conversation status: Ready for archiving.` Otherwise use exactly `Conversation status: Follow-ups remain — <each exact action or blocker>.` and list each exact action or blocker.
+- Keep this lifecycle metadata in the Batch Plan, outside the generated goal prompt.
 - `merge_authority`:
 - Concurrent activity and dependency status:
 - Coordination hooks, including backend claim exclusions:

skills/plan-pr-batch/scripts/check_goal_prompt_size.rb

@@ -141,6 +141,14 @@
   "A pasted handoff with no exact PR/issue refs stops and asks for targets instead of broadening to all open PRs.",
   "A normal resume prompt routes to bounded status recovery, not cancellation/relaunch."
 ].freeze
+PARENT_RELEASE_OR_ARCHIVE_RECONCILIATION_SOURCE_PIN = "After terminal batch handoffs, parent reconciliation is a post-batch/pre-release-or-archive gate, not a per-PR/pre-merge gate. Before a coordinated release action or parent archive, the parent determines applicability for every exact target/surface and performs a bounded read-only refresh and comparison with durable terminal handoffs/manifests only for applicable GitHub, coordination-backend/claim, head/merge, issue, QA, and release-note surfaces. Explicit durable `n/a`, `no-PR`, or `no-code/not-required` evidence with rationale satisfies an inapplicable surface. `UNKNOWN` applicability or missing applicable evidence blocks both release action and parent archive."
+PARENT_AUDIT_HANDOFF_SOURCE_PIN = "The completed-batch audit handoff is an always-applicable parent-reconciliation surface for every batch, independent of all target-level `n/a` decisions. The durable coordinator-owned handoff records audit status, verdict, verified scope evidence, checker evidence, findings, and follow-ups/dispositions. Missing handoff, or missing or `UNKNOWN` audit status or verdict, blocks both coordinated release and parent archive. Its marker has separate well-formed, archive-ready, and blocker-union outputs; only `complete`/`clean`/`none` with fully evidenced terminal records is archive-ready, and every OUTSTANDING ref or non-ready record remains in the normalized blocker union. The parent only reconciles this handoff; it never reruns or owns the audit."
+PARENT_AUDIT_MARKER_GRAMMAR_SOURCE_PIN = "The completed-batch marker has separate well-formed, archive-ready, and blocker-union outputs. A completed-batch audit is release/archive-ready only when `audit_status: complete`, `verdict: clean`, `findings: none`, and `followups_dispositions` is `none` or only fully evidenced terminal records."
+PARENT_RELEASE_OR_ARCHIVE_PRESSURE_SCENARIO = "Parent-orchestrated multi-batch: the parent stays open and read-only while workers execute; each batch coordinator owns checklist+replay closeout; parent cross-batch reconciliation is checklist+replay over durable terminal handoffs/manifests. The completed-batch audit handoff is an always-applicable parent-reconciliation surface for every batch, independent of all target-level `n/a` decisions. Preserve the durable completed-batch handoff, reconcile only applicable surfaces, and use the marker grammar above; `UNKNOWN` applicability or missing applicable evidence blocks release action and parent archive. For each exact batch/target scope the durable record captures evidence, owner, status, and follow-up for exact scope coverage, dependency outcomes, issue closed or no-PR evidence, released claims, exact-final-head QA replay, changelog/release-note ownership, and shared-path interactions; clean only when parent reconciliation has no OUTSTANDING follow-up or `UNKNOWN`; then final status: use exactly `Conversation status: Ready for archiving.` Otherwise final status: use exactly `Conversation status: Follow-ups remain — <each exact action or blocker>.`"
+PARENT_RELEASE_OR_ARCHIVE_PRESSURE_SCENARIOS = [
+  "Prompt-only single-batch: after all prompts are delivered or registered and stable batch/lane/dependency/ownership state is durable outside the chat, it archives without waiting for workers; closeout owner: the batch coordinator; an unhanded-off question or planner-owned `UNKNOWN` blocks archive, while a durably handed-off coordinator-owned worker state, including worker `UNKNOWN`, does not; final status: use exactly `Conversation status: Ready for archiving.` when prompt-only is clean; otherwise use exactly `Conversation status: Follow-ups remain — <each exact action or blocker>.` and list each exact action or blocker.",
+  PARENT_RELEASE_OR_ARCHIVE_PRESSURE_SCENARIO
+].freeze
 
 ALLOWED_PRESSURE_SCENARIO_REFS = %w[
   #101
@@ -365,6 +373,11 @@ def assert_prompt_budget(label, prompt_template, codex_prefix:)
   "Pressure scenarios this prompt must satisfy:",
   /^###\s+/
 )
+planning_chat_lifecycle_text = extract_section(
+  workflow_text,
+  "### Planning-Chat Lifecycle",
+  /^###\s+/
+)
 continuation_section = extract_section(
   workflow_text,
   "### Generic PR-Batch Continuation Prompt",
@@ -611,6 +624,29 @@ def assert_prompt_budget(label, prompt_template, codex_prefix:)
 require_phrases(workflow_text, CANONICAL_CONTINUATION_SNIPPET_PHRASES, "canonical workflow continuation snippet")
 require_phrases(workflow_text, PRESSURE_SCENARIOS, "canonical workflow pressure scenarios")
 
+if enforce_restart_docs_drift
+  require_phrases(
+    planning_chat_lifecycle_text,
+    [PARENT_RELEASE_OR_ARCHIVE_RECONCILIATION_SOURCE_PIN, PARENT_AUDIT_HANDOFF_SOURCE_PIN,
+     PARENT_AUDIT_MARKER_GRAMMAR_SOURCE_PIN],
+    "source checkout parent release-or-archive reconciliation pin"
+  )
+end
+
+require_phrases(
+  planning_chat_lifecycle_text,
+  PARENT_RELEASE_OR_ARCHIVE_PRESSURE_SCENARIOS,
+  "canonical parent release-or-archive pressure scenarios"
+)
+
+if enforce_restart_docs_drift
+  require_phrases(
+    planning_chat_lifecycle_text,
+    PARENT_RELEASE_OR_ARCHIVE_PRESSURE_SCENARIOS,
+    "source checkout parent release-or-archive pressure scenarios"
+  )
+end
+
 unless continuation_prompt.start_with?("#{CONTINUATION_BATCH_TITLE_LINE}\n")
   abort_with_failure("canonical workflow continuation prompt must start with the batch title line")
 end

skills/post-merge-audit/SKILL.md

@@ -355,17 +355,47 @@ Only the coordinator should create issues. Independent Codex and Claude audits s
 
 ## Output
 
-When this audit is invoked by a parent orchestration agent after a batch
-completes, the agent must make the audit part of its final handoff rather than
-leaving it as a separate optional task. Once it detects that every batch target
-has a final state, the parent orchestration agent must run the completed-batch
-audit before its final handoff. If the audit is clean and there are no findings,
-follow-ups, unresolved questions, pending work, or `UNKNOWN` facts, the final
-user-visible line must be `Conversation status: Ready for archiving.`
-Otherwise the final user-visible line must be
-`Conversation status: Follow-ups remain — <each exact action or blocker>.`; it
-must repeat every outstanding follow-up or blocker even if it appears earlier
-in the handoff.
+In completed-batch mode only:
+
+Once every batch target has a final state, the batch coordinator must run its
+completed-batch audit before its final handoff. Each completed-batch audit is
+owned by its batch coordinator. A parent orchestration agent only reconciles
+the durable audit handoff.
+
+Only the batch coordinator emits the `completed-batch-audit v1` marker and final `Conversation status` archive/follow-up line, in its final combined handoff after it compares qualifying-checker and advisory-auditor reports and dispositions findings.
+Qualifying-checker and advisory-auditor reports return evidence/results for coordinator comparison; they must not emit the coordinator handoff marker or coordinator handoff readiness/status line.
+Advisory auditors must not issue the qualifying clean/ready verdict.
+
+A conversation is archive-ready only when the audit is clean and there are no OUTSTANDING findings, follow-ups, unresolved questions, pending work, or `UNKNOWN` facts. A completed-batch audit has separate well-formed, archive-ready, and blocker-union outputs. A completed-batch audit is release/archive-ready only when `audit_status: complete`, `verdict: clean`, `findings: none`, and `followups_dispositions` is `none` or only fully evidenced terminal records. Replay only the exact versioned `<!-- completed-batch-audit v1` wrapper through its single final `-->`, with exactly one each of `batch_id`, `audit_status`, `verdict`, `scope_evidence`, `checker_evidence`, `findings`, and `followups_dispositions`; malformed, missing, duplicate, comment-token, newline, nested/case-varied `UNKNOWN`, or cross-field-inconsistent data fails.
+
+A coordination-backed `batch_id` is an opaque nonempty single-line string and may contain `:` or `;`. Only exact lowercase `non-backend:` and `not-applicable:` prefixes trigger their typed rules; those forms require their rationale and `scope_evidence: targets=<exact refs>; source=<durable ref>`. Each record has `ref`, `owner`, `current status`, `disposition`, and `evidence`; current status is exactly `open`, `unresolved`, `pending`, `UNKNOWN`, or `terminal`; duplicate refs block case-insensitively. `ref` and `owner` are nonempty. Nonterminal evidence is nonempty. Terminal evidence may be exact `UNKNOWN` or empty only as an explicitly non-ready blocker; nested/case-varied `UNKNOWN` is invalid. Terminal dispositions are exactly `resolved`, `accepted-waiver`, `accepted-deferral`, or `not-applicable`; nonterminal actions are exactly `investigate`, `fix`, `await-input`, `retry`, `replay`, or `track`. Terminal dispositions are invalid for nonterminal records and nonterminal actions are invalid for terminal records. Every top-level scalar and record value is one physical line; reject embedded CR, LF, CRLF, NUL, control line breaks, and HTML comment tokens. Each completed-batch follow-up ref uses one canonical normalization: Unicode NFKC, collapse Unicode whitespace with `[[:space:]]+`, trim, and reject empty results; preserve the canonical display and derive identity with Ruby full case-fold (`downcase(:fold)`). Use that identity for record duplicates, findings-to-record lookup, and blocker deduplication; `ß` and `SS` collide. External blockers may share the safe canonical display, while record identity stays consistent. Duplicate canonical refs are invalid; every accepted distinct ref remains in the blocker union. After normalization, record and finding refs reject any canonical display that is empty, contains control line breaks, contains `<!--` or `-->`, or is exact/nested `UNKNOWN`. External blockers separately reject empty/control/HTML canonical displays but preserve `UNKNOWN` facts; normalize, dedupe, and render them in the exact Follow-ups union.
+
+Clean/none permits no records or only fully evidenced terminal records. A blocked/follow-ups marker permits `findings: none` with valid open, pending, unresolved, `UNKNOWN`, or imperfect terminal records, but it is non-ready; an `UNKNOWN` current-status record is valid only in that non-clean state or the all-`UNKNOWN` scalar state. A `findings: OUTSTANDING <refs>` value contributes every exact ref to the blocker union even without a record. Every nonterminal record and every record with imperfect terminal evidence contributes its ref and action/block reason; normalize and dedupe without dropping a distinct ref. In the marker, `findings` is `none`, `UNKNOWN`, or `OUTSTANDING <refs>`; every OUTSTANDING ref is visible in the final blocker union even when no action record exists, while operational action refs need not be duplicated in findings. For `OUTSTANDING`, before comma/delimiter fallback, an entire canonical findings payload that exactly matches an accepted record ref is that one ref; otherwise retain comma- or whitespace-separated standalone refs, and consume a whitespace-bearing canonical record ref that matches the remaining findings text before standalone fallback.
+
+A marker has separate well-formed, archive-ready, and blocker-union outputs. Clean/none accepts only no records or fully evidenced terminal records; blocked/follow-ups/OUTSTANDING accepts non-ready records. `UNKNOWN` current status is never ready and cannot appear in a clean/none marker.
+
+Replay the final visible status line from the normalized blocker union: render a nonterminal record as `<ref> (<current status>): <action>`, imperfect terminal evidence as `<ref> (terminal): evidence UNKNOWN` or `evidence missing`, and exact `UNKNOWN` scalars as `<field>: UNKNOWN`. External blockers must be nonempty single-line text without HTML comment tokens; normalize and dedupe them with marker blockers. If marker parsing fails, replay `well=false`, `ready=false`, and the nonempty blocker `completed-batch-audit marker invalid`; normalize and union any sanitized external blockers. Its final status must be exact nonempty `Follow-ups`, never `Ready` or an empty blocker line. Use `Ready` iff archive-ready and the union is empty; otherwise use nonempty `Follow-ups` with that exact union.
+
+Use exactly `Conversation status: Ready for archiving.` only when archive-ready and the blocker union is empty. Otherwise use exactly `Conversation status: Follow-ups remain — <each exact action or blocker>.`
+
+Only in completed-batch mode, include this visible report marker and fill every
+field explicitly; use `none` rather than omitting a field:
+
+```markdown
+<!-- completed-batch-audit v1
+batch_id: <opaque coordination batch id (may contain : or ;)|non-backend: identity; rationale: why no backend applies|not-applicable: rationale|UNKNOWN>
+audit_status: <complete|blocked|UNKNOWN>
+verdict: <clean|follow-ups-remain|UNKNOWN>
+scope_evidence: <concise refs|UNKNOWN>
+checker_evidence: <identity/route/independence refs|UNKNOWN>
+findings: <none|OUTSTANDING concise refs|UNKNOWN>
+followups_dispositions: <none|one or more ` | `-separated records with ref, owner, current status, disposition, and evidence; terminal disposition is resolved|accepted-waiver|accepted-deferral|not-applicable; nonterminal action is investigate|fix|await-input|retry|replay|track>
+-->
+```
+
+For `non-backend` and `not-applicable`, the structured `scope_evidence` grammar is `targets=<exact refs>; source=<durable ref>`: name the exact verified target set and durable evidence source. `batch_id: UNKNOWN` is allowed only for genuinely unresolved batch identity, never for release/archive readiness.
+
+The replay rule above is fail-closed: malformed, missing, duplicate, `UNKNOWN`, or cross-field-inconsistent marker data blocks; the parent later replays only this durable handoff and never reruns or owns the audit.
 
 Return high-risk findings first, then: