@danmoisan/drm-copilot-mcp 1.0.0 → 1.0.7

package/resources/claude-customizations/.claude/skills/epic-orchestrate/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: epic-orchestrate
+description: Route a multi-feature epic through the deterministic wave-scheduling, integration-branch, and fan-in workflow for the epic-orchestrator agent.
+argument-hint: "[epic-manifest-path]"
+---
+
+# Epic Orchestrate Skill
+
+This skill frames work for the `epic-orchestrator` agent, parallel to how
+`.claude/skills/orchestrate/SKILL.md` frames work for `orchestrator`. It documents the epic
+checkpoint handling, wave computation, integration-branch lifecycle, wave barrier,
+merge-conflict handling, worktree cleanup, and documentation-maintenance procedures so the
+procedure is not re-derived ad hoc on each epic run.
+
+## Prerequisites
+
+Before proceeding, `epic-orchestrator` must:
+
+1. Read `CLAUDE.md` for repository tone policy and architectural context.
+2. Read applicable `.claude/rules/` files for the languages in scope.
+3. Read the policy files listed in the compliance reading order section of `CLAUDE.md`.
+
+## Epic Dependency Manifest
+
+The epic manifest is Markdown with YAML frontmatter, at
+`docs/features/epics/<epic-slug>/epic-plan.md`. The frontmatter carries the fields that must be
+parsed deterministically; the Markdown body below the frontmatter carries free-text epic
+narrative (goal, scope, non-goals) that is not machine-parsed.
+
+Frontmatter schema:
+
+```yaml
+---
+epic: <epic-slug>
+integration_branch: epic/<epic-slug>-integration
+created_at: <iso8601>
+features:
+  - feature_folder: <feature-folder-basename>
+    issue_num: <int>
+    depends_on: [<feature-folder-basename>, ...]
+---
+```
+
+- `feature_folder` is the canonical identifier: the exact active-feature-folder basename,
+  matching the vocabulary already used by the per-feature checkpoint's `feature-folder` field.
+- `depends_on` is an array of `feature_folder` values that must each already exist as another
+  entry in `features[]`. A `depends_on` entry that does not resolve to a defined `feature_folder`,
+  or a duplicate `feature_folder` value, is a malformed manifest and is rejected before epic
+  kickoff as a synthetic Blocking finding — `epic-orchestrator` does not guess.
+
+## Wave Assignment
+
+Wave assignment is computed deterministically by longest-path layering over the dependency DAG,
+not by an arbitrary valid topological order:
+
+```
+wave(f) = 0                                   if depends_on(f) is empty
+wave(f) = 1 + max(wave(d) for d in depends_on(f))   otherwise
+```
+
+`scripts/dev_tools/epic_wave_computation.py` is the canonical, tested reference implementation
+of this formula.
+
+Compute this via memoized recursion with cycle detection: a `feature_folder` encountered while
+still being resolved (i.e., it appears in its own dependency chain) indicates a cycle in the
+manifest, which is rejected as a malformed manifest before kickoff. Within a wave, feature
+ordering for emission into checkpoint arrays is lexicographic by `feature_folder`, purely for
+deterministic serialization; wave *membership* itself has no ties to break since it is a pure
+function of the DAG.
+
+## Epic Integration Branch Lifecycle
+
+1. Before wave 0's launch, `epic-orchestrator` creates the integration branch off the tip of
+   `main`: `git fetch origin main`, `git checkout -b epic/<epic-slug>-integration origin/main`,
+   `git push -u origin epic/<epic-slug>-integration`.
+2. Before starting each wave, `epic-orchestrator` runs
+   `git fetch origin epic/<epic-slug>-integration` so the wave's child worktrees branch off the
+   current remote tip, not a stale local ref.
+3. Each child feature's worktree/branch (created via
+   `Agent(orchestrator, isolation: "worktree", run_in_background: true)`) is branched from
+   `origin/<integration_branch>`, not `origin/main`. The child's own `orchestrator` instance
+   honors this via the epic-mode kickoff line below.
+4. Each child feature's PR base branch is the integration branch, not `main` — an explicit
+   epic-mode override recorded in the checkpoint, not a reliance on `pr-base-branch-merge-base`'s
+   ancestry heuristic. Non-epic (standalone) orchestration is unchanged.
+5. At epic completion (every feature in the final wave has `merge_status: "merged"`),
+   `epic-orchestrator` drives a final PR merging `epic/<epic-slug>-integration` into `main`,
+   delegating PR authoring to `Agent(pr-author)` and refreshing context via
+   `mcp__drm-copilot__collect_pr_context`. `epic-orchestrator` runs the same S9 CI-green
+   procedure (`scripts/orchestration/Invoke-CiGateParser.ps1`) directly against this PR, records
+   the result under the epic checkpoint's `epic_merge_pr` object, then executes
+   `gh pr merge --merge` once green, gated by `enforce-epic-merge-gate.ps1`.
+
+## Merge-on-Green Kickoff Parameter
+
+When `epic-orchestrator` delegates a child feature to `Agent(orchestrator)`, the prompt includes
+the literal epic-mode kickoff line:
+
+> `Epic mode: true. epic_feature_folder: <epic-slug>. integration_branch: epic/<epic-slug>-integration. epic_checkpoint_path: artifacts/orchestration/epic-orchestrator-state.json. PR base branch MUST be <integration_branch>, not main; pass --base <integration_branch> to gh pr create.`
+
+The child's own `orchestrator`, on reading this line, records `epic_mode: true` and
+`epic_context: { epic_feature_folder, integration_branch, epic_checkpoint_path }` at its first
+checkpoint write, and on CI-green (S9 step 6) merges its own PR into the integration branch,
+recording `epic_merge: { merge_commit_sha, target_branch, merged_at }`. Standalone (non-epic)
+orchestration is unchanged: `epic_mode` absent or `false` makes S9 step 6 a no-op.
+
+## Model Selection
+
+When `epic-orchestrator` delegates a child feature to `Agent(orchestrator)`, the prompt appends the
+session model-budget kickoff marker line, following the existing kickoff-marker pattern:
+
+> `model_budget.fable_policy: <disabled|available|preferred>.`
+
+The child's own `orchestrator` reads this line and applies the two-axis model-selection mechanism
+documented in `.claude/skills/orchestrate/SKILL.md` (`## Model Selection`): it assesses a
+judgment-based `complexity_band`, records `complexity_assessments[]` and `model_routing_receipts[]`,
+and resolves each delegation's model tier under the given `fable_policy`. The two canonical, tested
+reference implementations are `scripts/dev_tools/compute_complexity_floor.py`
+(`compute_complexity_floor`) and `scripts/dev_tools/resolve_delegation_model.py`
+(`resolve_delegation_model`). Default `fable_policy` is `disabled` when the marker is absent.
+
+`route` is never an input to model selection; `route` remains file-count driven and governs only
+agents, skills, and MCP tools. A skill whose frontmatter `context` field holds the value `fork`
+inherits the parent model and ignores a model override, so model selection applies to agent
+delegations, not to fork-routed skill invocations.
+
+## Context Handoff to Dependent Features
+
+When `epic-orchestrator` kicks off a feature with a non-empty `depends_on`, the delegation prompt
+includes one literal citation line per dependency, appended after the epic-mode kickoff line
+above:
+
+> `Upstream context for <feature_folder>: depends on <dep_feature_folder> (spec: docs/features/active/<dep_feature_folder>/spec.md — or docs/features/completed/<dep_feature_folder>/spec.md if already promoted to completed; plan: docs/features/active/<dep_feature_folder>/plan.<ts>.md; merged as PR #<dep_pr_number>, commit <dep_merge_commit_sha>, into <integration_branch>).`
+
+`epic-orchestrator` resolves the concrete `<dep_...>` values from its own checkpoint's
+`features[]` records for each dependency before emitting the line, so the dependent feature's own
+`orchestrator`/`atomic-planner` is told exactly which upstream artifacts are relevant rather than
+being expected to rediscover prior design decisions from the diff alone.
+
+## Merge-Conflict Handling (Fan-In)
+
+The merge-conflict remediation loop runs inside the child feature's own `orchestrator` instance
+(the same one that executes S9 step 6), reusing the existing R1–R5 loop
+(`.claude/skills/orchestrate/SKILL.md` "Remediation Loop (R1–R5)") unmodified — no new loop is
+owned by `epic-orchestrator`.
+
+Procedure, triggered by S9 step 6's merge failure:
+
+1. The child's `atomic-executor` runs `git fetch origin <integration_branch>`,
+   `git merge --no-commit origin/<integration_branch>`, and on non-zero exit captures
+   `git diff --name-only --diff-filter=U` (the conflicted file list) plus the raw conflict-marker
+   (`<<<<<<<`/`=======`/`>>>>>>>`) content of each conflicted file.
+2. This is written as `remediation-inputs.<timestamp>.md` in the **child feature's own active
+   folder** (not the epic folder), severity `Blocking`, naming the conflicting branches, carrying
+   the conflicted-file list and marker excerpts — the same shape the existing CI-failure handling
+   already uses, substituting the conflict-detection output for `gh run view --log-failed`.
+3. The existing R1–R5 loop processes this finding exactly as a local blocking finding:
+   `atomic-planner` (R1) plans the resolution, `atomic-executor` performs preflight (R2) then
+   resolves the conflict markers, stages, and commits (R3), `feature-review` re-audits (R4).
+4. The child's own `remediation_pass` counter is shared with local-finding and CI-failure passes
+   (cap 3), unmodified.
+5. On the third conflict pass without resolution, the child's `orchestrator` records
+   `step9_status: "blocked_conflict_loop_limit"` (parallel to `blocked_ci_loop_limit`), does not
+   write DONE, and halts. It reports this status to `epic-orchestrator`, which mirrors it into
+   the epic checkpoint's per-feature `merge_status: "blocked_conflict_loop_limit"` field.
+
+## Wave Barrier (Two-Layer Design)
+
+Wave-barrier enforcement is a two-layer design: no single hook mechanism can validate a whole
+batch of concurrent `Agent` calls, since `PreToolUse` hooks fire per call with no
+cross-call/conversation-state visibility.
+
+- **Layer 1 — per-call deterrent:** `.claude/hooks/enforce-epic-wave-barrier.ps1`, a `PreToolUse`
+  hook on the `Agent` matcher. It fires when `subagent_type == "orchestrator"` and the serialized
+  prompt contains the marker `Epic mode: true`, resolves the target `feature_folder` from the
+  prompt text, reads `artifacts/orchestration/epic-orchestrator-state.json`, looks up that
+  feature's `depends_on`, and denies with reason `EPIC_WAVE_BARRIER_BLOCKED` unless every
+  dependency's `merge_status` is `merged` or `worktree_removed`.
+- **Layer 2 — retrospective backstop:** the wave-barrier ordering invariant inside
+  `validate_epic_orchestrator_state_text`, enforced at `epic-orchestrator` `SubagentStop` time via
+  the parameterized `validate-orchestrator-output.ps1` hook. It appends
+  `EPIC_WAVE_BARRIER_VIOLATION: <f> started before dependency <d> merged` when a dependency edge's
+  timing invariant is violated.
+
+Both layers are required; neither alone closes the gap. `epic-orchestrator` does not launch wave
+N+1 until every wave-N feature's dependency edges are durably confirmed merged, verified against
+`git worktree list --porcelain`, `git branch`, and `gh pr view --json state,mergedAt,headRefOid`
+on resume, not from in-memory completion notifications alone.
+
+## Worktree Cleanup
+
+After a child feature's `epic_merge.merge_commit_sha` is recorded (S9 step 6 succeeds) and
+`epic-orchestrator` mirrors that into its own checkpoint's `merge_status: "merged"` and
+`merge_confirmed_at`, `epic-orchestrator` (running from the main repository checkout, not any
+child worktree) issues `git worktree remove <worktree_path>`, gated by
+`.claude/hooks/enforce-epic-worktree-removal-gate.ps1`, which denies with reason
+`EPIC_WORKTREE_REMOVAL_BLOCKED` unless the epic checkpoint's matching `features[]` record has
+`merge_status` in `{merged, worktree_removed}`. On success, `epic-orchestrator` sets
+`merge_status: "worktree_removed"` and `worktree_removed_at`.
+
+## Documentation Maintenance Boundaries
+
+`epic-plan.md` (the manifest) and `epic-status.md` (a separate, epic-orchestrator-maintained
+status document) are kept distinct. `epic-plan.md`'s frontmatter is the human-authored, largely
+static input; automatic epic decomposition is out of scope, so this file is not repeatedly
+rewritten. `epic-orchestrator` instead maintains
+`docs/features/epics/<epic-slug>/epic-status.md`, regenerated (not hand-edited) from the epic
+checkpoint at each of the following boundaries, not only at final completion:
+
+- Epic kickoff — initial status table seeded from the manifest (one row per feature: wave,
+  status `not_started`).
+- Each time a feature's `merge_status` changes (`worktree_created`, `pr_open`, `ci_green`,
+  `merge_conflict`, `merged`, `worktree_removed`) — the corresponding row is updated in place.
+- Each wave transition (`current_wave` increments).
+- Final integration PR opened, green, and merged.
+
+Each row records: `feature_folder`, `issue_num`, `wave_number`, `merge_status`, PR link
+(`pr_url`), `merge_commit_sha`, and the four lifecycle timestamps from the epic checkpoint.
+`epic-status.md` is a human-readable projection of the epic checkpoint's `features[]` array; the
+checkpoint JSON remains the durable, machine-authoritative source.
+
+## Epic-Level Checkpoint
+
+`artifacts/orchestration/epic-orchestrator-state.json` carries `objective`, `route_id: "epic"`,
+`epic_feature_folder`, `epic_manifest_path`, `epic_status_doc_path`, `integration_branch`,
+`completed_steps`, `next_step`, `last_updated`, `current_wave`, `waves[]`, `features[]`,
+`epic_merge_pr`, and the three receipt arrays (`delegation_receipts[]`, `skill_receipts[]`,
+`mcp_call_receipts[]`) — the full schema is defined in `spec.md` §6 of this feature. The
+`merge_status` enum is: `not_started`, `worktree_created`, `pr_open`, `ci_green`,
+`merge_conflict`, `blocked_conflict_loop_limit`, `merged`, `worktree_removed`.
+
+Every field needed to re-derive state durably on resume (`worktree_path`, `branch_name`,
+`pr_number`, `merge_status`) is re-derivable from `git worktree list --porcelain`, `git branch`,
+and `gh pr view --json state,mergedAt,headRefOid` — the checkpoint is a cache of that durable
+state, not the source of truth.
+
+Validate the checkpoint via
+`python -m scripts.dev_tools.validate_orchestration_artifacts epic-orchestrator-state <path> --require-complete`
+(or the equivalent `mcp__drm-copilot__validate_orchestration_artifacts` call with
+`artifact_type: "epic-orchestrator-state"`), implemented in
+`scripts/dev_tools/validate_epic_orchestrator_state.py`.
+
+## Completion Requirements
+
+`epic-orchestrator` must not report completion until:
+
+1. Every feature in the manifest has `merge_status` in `{merged, worktree_removed}`.
+2. The final integration-to-`main` PR has merged and `epic_merge_pr.merge_commit_sha` is
+   recorded.
+3. `docs/features/epics/<epic-slug>/epic-status.md` reflects the completed state.
+4. The epic checkpoint passes `validate_epic_orchestrator_state_text` with
+   `require_complete=True`.

package/resources/claude-customizations/.claude/skills/orchestrate/SKILL.md

@@ -44,7 +44,7 @@ When a step cannot be performed without a human, the orchestrator chooses exactl
 
 ### Exception-runbook requirement
 
-On a permitted `exception`, the orchestrator emits a human-readable runbook at `<FEATURE>/runbooks/<name>.runbook.md` and records its repo-root-relative path in `human_interaction.requirements[].runbook_path`. The runbook contract — canonical path, the five required sections (Cue, Prerequisites, Step-by-step Instructions, Verification, Source and Citation), and the MCP-first / web-second sourcing rule — is defined authoritatively in `.claude/skills/human-exception-runbook/SKILL.md`.
+On a permitted `exception`, the orchestrator delegates runbook authoring to `Agent(human-exception-runbook)`, which emits a human-readable runbook at `<FEATURE>/runbooks/<name>.runbook.md` and returns the `runbook_path`. The orchestrator records the returned repo-root-relative path in `human_interaction.requirements[].runbook_path`. The runbook contract — canonical path, the five required sections (Cue, Prerequisites, Step-by-step Instructions, Verification, Source and Citation), and the MCP-first / web-second sourcing rule — is defined authoritatively in `.claude/skills/human-exception-runbook/SKILL.md`.
 
 ### Enforcement points
 
@@ -65,18 +65,40 @@ After reading `artifacts/orchestration/orchestrator-state.json`, the main sessio
 
 The orchestrator does not perform deep implementation itself. It coordinates, tracks state, and enforces completion.
 
-## PR Creation Delegation
+## Model Selection
 
-PR creation and PR body edits are delegated work, not orchestrator work. The orchestrator MUST NOT call `gh pr create` or `gh pr edit --body*` directly from the main thread; the `enforce-pr-author-skill.ps1` PreToolUse hook blocks those commands unless a valid authorization sentinel issued by the `pr-author` agent is present.
+Model selection is a second axis, strictly separate from `route`. `route` (`small | large | remediation | epic`) is deterministic and file-count driven; it governs `required_agents`, `required_skills`, and `required_mcp_tools` only. `route` is NOT an input to model selection anywhere. The sole feature-level input to the delegation model tier is a judgment-based `complexity_band` (`C1 | C2 | C3 | C4`). The authoritative values live in the `model_policy` block of `config/orchestration-routing.json`.
+
+The two canonical, tested reference implementations express the formulas the orchestrator applies by judgment:
+
+- `scripts/dev_tools/compute_complexity_floor.py` (`compute_complexity_floor`) — the deterministic complexity-floor formula. Each present `[floor]` signal contributes a candidate band of `C3`; the floor is the maximum triggered candidate band; the floor never exceeds `C3`. C4 is never floor-forced; it is reached only by judgment.
+- `scripts/dev_tools/resolve_delegation_model.py` (`resolve_delegation_model`) — the delegation-model selection formula (base `complexity_to_model` table, the `preferred` overlay, and the `disabled` clamp).
+
+End-to-end procedure:
+
+1. **Parse the kickoff marker.** Read the session `model_budget.fable_policy` value (`disabled | available | preferred`, default `disabled`) from the kickoff marker line. This is the only session-level model-budget switch.
+2. **Assess `complexity_band` and record it.** For each assessed phase, judge the `complexity_band` against the `model_policy.complexity` signal catalog and anchors, then record a `complexity_assessments[]` entry `{ phase, band, floor, signals_present[], rationale, assessed_at }`. The recorded `floor` must equal `compute_complexity_floor(signals_present)`, and the assessed `band` must satisfy `band >= floor`. The floor is a lower bound only; it never raises a judgment or evaluates its merit.
+3. **Run the per-delegation selection order.** For each delegation, resolve the model as `resolve_delegation_model(agent, complexity_band, fable_policy)`: the `table_model` is the `preferred` overlay value when (`fable_policy == "preferred"` and the agent is in the overlay set `{atomic-planner, prd-feature, feature-review, task-researcher}` and `band == "C3"`), otherwise the base `complexity_to_model[band]`. Under `fable_policy == "disabled"`, a `fable` `table_model` clamps to `model = "opus"` with `clamped_from = "fable"`. `atomic-executor` and `pr-author` C3 cells stay `opus` under every policy.
+4. **Emit a routing receipt.** Record a `model_routing_receipts[]` entry `{ agent, phase, complexity_band, fable_policy, table_model, clamped_from | null, model }`. `table_model` is the pre-clamp lookup; `model` is the post-clamp result.
+
+The `complexity_assessments[]` and `model_routing_receipts[]` invariants are enforced by `scripts/dev_tools/validate_orchestrator_state.py` per `.claude/rules/orchestrator-state.md`; both arrays are additive and optional.
+
+**`fork` caveat.** A skill whose frontmatter `context` field holds the value `fork` inherits the parent model and ignores a model override. Model selection therefore applies to agent delegations, not to fork-routed skill invocations.
+
+## PR Authoring (pr-author Handoff)
+
+PR creation and PR body edits are delegated work, not orchestrator work. The orchestrator MUST NOT call `gh pr create` or `gh pr edit --body*` directly from the main thread; the `enforce-pr-author-skill.ps1` PreToolUse hook blocks those commands unless the `--body-file` argument resolves to a canonical `artifacts/pr_body_<N>.md` path with a matching, verified `artifacts/pr_body_<N>.receipt.json`.
 
 The mandatory sequence is:
 
-1. The orchestrator first produces the PR-context artifact via `mcp__drm-copilot__collect_pr_context` (or the equivalent context-collection mechanism), which writes `artifacts/pr_context.summary.txt`.
-2. The orchestrator then delegates PR creation and any PR body edits to `Agent(pr-author)`. The `pr-author` agent runs the `pr-author` skill, writes the short-lived authorization sentinel `artifacts/pr_author_authorization.json` immediately before each `gh` command, issues `gh pr create`/`gh pr edit --body-file ...` within the TTL, deletes the sentinel afterward, and reports the resulting PR URL or PR number.
+1. The orchestrator first refreshes the PR-context artifact via `mcp__drm-copilot__collect_pr_context` (or the equivalent context-collection mechanism), which writes `artifacts/pr_context.summary.txt`.
+2. The orchestrator runs the orchestrator-state validator (`mcp__drm-copilot__validate_orchestration_artifacts` or the equivalent local CLI call) against `artifacts/orchestration/orchestrator-state.json --require-pr-creation-ready` and records the pass/fail result under a new `pr_author_preflight` field in the checkpoint, alongside `pr_author_receipt`: `{status ("pass"|"fail"), checked_at (ISO-8601 UTC), checkpoint_path, validator_command, output_summary}`. The orchestrator must not delegate to `Agent(pr-author)` when this preflight fails. The validator's full-lifecycle completion flag (`ci_gate`/`pr_gate`/routing-contract receipts) remains reserved for the post-PR/CI completion context (Step S9 / PR Creation Gate condition 6), not this pre-PR-creation preflight, because those values cannot exist before the first `gh pr create` of a branch.
+3. The orchestrator then delegates PR creation and any PR body edits to `Agent(pr-author)`. The `pr-author` agent runs the `pr-author` skill to author the body, writes the body file `artifacts/pr_body_<N>.md` and the sibling receipt `artifacts/pr_body_<N>.receipt.json` with the shape `{skill, pr_body_path, number, sha256 (lowercase hex of the body bytes), context_summary_path, created_at (ISO-8601 UTC, strictly newer than `artifacts/pr_context.summary.txt` last-write)}`, issues `gh pr create --body-file artifacts/pr_body_<N>.md` (or `gh pr edit --body-file ...`), and reports the resulting PR URL or PR number.
+4. The orchestrator records `pr_author_receipt` in the checkpoint, citing the body-file path and the receipt path that were verified.
 
-`Agent(pr-author)` is the mandatory delegate for PR creation and PR body edits. Direct `gh pr create`/`gh pr edit --body*` from the main thread is prohibited and is blocked by the hook.
+`Agent(pr-author)` is the mandatory delegate for PR creation and PR body edits. Direct `gh pr create`/`gh pr edit --body*` from the main thread is prohibited and is blocked by the hook. Before the five receipt checks, the `enforce-pr-author-skill.ps1` PreToolUse hook independently re-validates the orchestrator-state checkpoint against `--require-pr-creation-ready` (via an injectable `$Invoker` subprocess seam) and blocks with `ORCHESTRATOR_STATE_PREFLIGHT_FAILED` when the checkpoint is missing or invalid — this is the local, hook-level enforcement mechanism that closes the bypass path (it runs inside the same hook that already intercepts `gh pr create`/`gh pr edit`, not as a CI check). The PreToolUse hook then verifies the receipt in five ordered checks: canonical body-file path, receipt present, `number` match, `sha256` match against the body bytes, and `created_at` strictly newer than the context summary last-write.
 
-The authorization sentinel is a policy guardrail, not a cryptographic or security control; any actor with `Write(/artifacts/**)` access can forge it. It prevents accidental bypass and requires a deliberate, documented act to circumvent.
+The SHA-256 receipt is a policy-level integrity check, not a cryptographic or security boundary; any actor with `Write(/artifacts/**)` access can replace both the body file and its receipt together with a matching SHA-256. It binds the body bytes to the receipt, prevents accidental bypass, and requires a deliberate, documented act to circumvent.
 
 ## Evidence Location Authority
 
@@ -110,8 +132,8 @@ The orchestrator must not report completion until:
 Before delegating to the `feature-review` subagent, the orchestrator must:
 
 1. Stage all modified and new files: `git add -A`.
-2. Invoke the `commit-message` skill to generate a conventional commit message from the staged diff.
-3. Commit using the generated message: `git commit -m "<generated message>"`.
+2. Delegate to `Agent(commit-message)` to generate a conventional commit message from the staged diff. The agent is read-only and returns message text only; it does not commit.
+3. Commit using the generated message: `git commit -m "<generated message>"`. The `git add` and `git commit` actions remain on the orchestrator.
 4. Only after a successful commit may the orchestrator proceed to the `feature-review` delegation.
 
 The review subagent compares against a base branch; uncommitted changes are invisible to the diff tool and cannot be audited.
@@ -131,7 +153,7 @@ A bounded loop consisting of five steps. The loop variable `remediation_pass` st
 - **R1 — Remediation planning:** Delegate to `atomic-planner` with `remediation-inputs.<timestamp>.md` path as primary context. Receive `remediation-plan.<timestamp>.md` in the active feature folder.
 - **R2 — Preflight clearance:** Delegate to `atomic-executor` for precondition validation only (no implementation). If the executor does not return `PREFLIGHT: ALL CLEAR`, return to R1 and re-delegate to `atomic-planner` with the required-changes output from the executor. Only after `PREFLIGHT: ALL CLEAR` may the orchestrator advance to R3.
 - **R3 — Remediation execution:** Delegate to `atomic-executor` with full execution authorization. Each task's toolchain loop (format → lint → type-check → test) is mandatory; no skipping.
-- **Pre-R4 commit:** Stage all changes (`git add -A`), invoke the `commit-message` skill to generate a commit message from the staged diff, commit with the generated message. Advance to R4 only after a successful commit.
+- **Pre-R4 commit:** Stage all changes (`git add -A`), delegate to `Agent(commit-message)` to generate a commit message from the staged diff (the agent returns message text only and does not commit), then commit with the generated message. The `git commit` action remains on the orchestrator. Advance to R4 only after a successful commit.
 - **R4 — Re-audit:** Delegate to `feature-review` with the same inputs as the original review (resolved base branch, feature folder, refreshed PR context artifacts, acceptance-criteria source). No scope narrowing. The canonical issue number line must be included.
 - **R5 — Loop-exit decision:** If the re-audit produces zero blocking findings, exit the loop and advance to the PR creation gate. Otherwise, record `remediation_pass` increment in the checkpoint and return to R1.
 
@@ -158,6 +180,7 @@ S9 procedure:
 3. Parse the JSON via `scripts/orchestration/Invoke-CiGateParser.ps1`, which emits the `ci_gate` object defined below and derives `ci_gate.conclusion` as `success` when all required checks pass, `failure` when any required check failed, and `pending` when any required check is still in progress.
 4. Poll with a bounded interval and a documented total timeout while `conclusion == "pending"`. When the timeout is exhausted, set `step9_status: "failed_remediation_required"` and enter the remediation-loop CI-failure handling below with a timeout log.
 5. Write the `ci_gate` object and `last_verified_ci_sha` to the checkpoint, and set `step9_status` to `passed` only when `ci_gate.conclusion == "success"` AND `ci_gate.head_sha` equals the current PR head SHA.
+6. If the checkpoint's `epic_mode` is `true`, execute `gh pr merge --merge <PR>` merging the feature branch into `epic_context.integration_branch` (already the PR's base branch per the epic-mode `--base` override applied at S8). On success, record `epic_merge: { merge_commit_sha, target_branch, merged_at }` in the checkpoint. On failure due to merge conflict (non-mergeable PR), do not retry blindly: convert the conflict into a synthetic Blocking finding per "Merge-Conflict Remediation" below and re-enter the standard R1–R5 remediation loop; do not proceed to DONE.
 
 DONE is not written while `step9_status` is anything other than `passed`.
 
@@ -173,6 +196,10 @@ The orchestrator checkpoint (`artifacts/orchestration/orchestrator-state.json`)
   - `verified_at` — ISO-8601 timestamp of when S9 recorded the result.
 - a top-level `last_verified_ci_sha` — the most recent head SHA for which S9 recorded a result.
 - a top-level `step9_status` — an enumeration with at minimum the values `pending`, `passed`, `failed_remediation_required`, and `blocked_ci_loop_limit`.
+- a top-level `epic_merge` object (populated only in epic mode) containing:
+  - `merge_commit_sha` — the merge commit SHA produced by merging the feature branch into `epic_context.integration_branch`.
+  - `target_branch` — the integration branch the feature branch was merged into.
+  - `merged_at` — ISO-8601 timestamp of when S9 step 6 recorded the merge.
 
 Illustrative shape:
 
@@ -207,15 +234,17 @@ When S9 records `step9_status: "failed_remediation_required"` (a failed required
 
 ## PR Creation Gate
 
-The orchestrator must not create a PR, push a branch for PR purposes, or report work complete until all five conditions are simultaneously true:
+The orchestrator must not create a PR, push a branch for PR purposes, or report work complete until all six conditions are simultaneously true:
 
 1. `blocking_findings_resolved: true` — the most recent `feature-review` produced zero blocking findings.
 2. The AC verification artifact (`p14-acceptance-criteria-checkoff.md` or equivalent) confirms all acceptance criteria pass.
 3. The mandatory toolchain passed in its most recent run on the branch (no linting/type-check/test failures).
 4. The checkpoint `next_step` is `S8_create_pr` (precondition to entering S9).
-5. `ci_gate.conclusion == "success"` AND `ci_gate.head_sha == current head SHA of the PR branch`. DONE is not written while either sub-condition is false.
+5. PR body produced via the pr-author handoff: `artifacts/pr_body_<N>.md` exists with a matching `artifacts/pr_body_<N>.receipt.json`, created with `--body-file`.
+6. `ci_gate.conclusion == "success"` AND `ci_gate.head_sha == current head SHA of the PR branch`. DONE is not written while either sub-condition is false.
+7. `epic_mode` is `false`, OR (`epic_mode` is `true` AND the integration-branch merge (`gh pr merge --merge`) has completed and `epic_merge.merge_commit_sha` is recorded in the checkpoint).
 
-This gate is non-negotiable. Each condition is independently verified before PR creation proceeds. Conditions 1-4 are unchanged from the prior contract; condition 5 is additive.
+This gate is non-negotiable. Each condition is independently verified before PR creation proceeds. Conditions 1-4 are unchanged from the prior contract; conditions 5-7 (receipt handoff, CI-green gate, and epic-mode merge-on-green gate) are additive.
 
 ## Step 6 Delegation — Prohibited Prompt Language
 

package/resources/claude-customizations/.claude/skills/pr-author/SKILL.md

@@ -42,6 +42,34 @@ Use these sections in this order:
 10. **Follow-ups** — known TODOs, deferred cleanup, next PRs
 11. **GitHub Auto-close** — `- Closes #NNN` only from verified autoclose lists; do not invent issue numbers
 
+## Output Artifact
+
+The PR body produced by this skill is persisted as a body file plus a sibling receipt so the
+PreToolUse hook can verify the body passed to `gh pr create --body-file` is the one this skill
+produced:
+
+1. Write the body text to `artifacts/pr_body_<N>.md`, where `<N>` is the target issue or PR number.
+2. Compute the SHA-256 of the body file bytes and render it as lowercase hexadecimal.
+3. Write the sibling receipt `artifacts/pr_body_<N>.receipt.json` with the shape:
+
+   ```json
+   {
+     "skill": "pr-author",
+     "pr_body_path": "artifacts/pr_body_<N>.md",
+     "number": <N>,
+     "sha256": "<lowercase-hex SHA-256 of the body bytes>",
+     "context_summary_path": "artifacts/pr_context.summary.txt",
+     "created_at": "<ISO-8601 UTC timestamp newer than pr_context.summary.txt last-write>"
+   }
+   ```
+
+4. Pass the body to the pull request via `--body-file artifacts/pr_body_<N>.md`; do not use inline
+   `--body`.
+
+The body-file and receipt write operations remain in the pr-author agent scope, which holds
+`Write(/artifacts/**)`. This skill authors the body text; the pr-author agent performs the file
+writes and the `gh pr create` / `gh pr edit --body-file` handoff.
+
 ## Issue/PR Reference Rules
 
 - Only mention an issue/PR number if it appears verbatim in the provided context.

package/resources/claude-customizations/.claude/skills/remediation-handoff-atomic-planner/SKILL.md

@@ -21,9 +21,9 @@ Use this skill when:
 
 ```
 orchestrator
-  -> writes remediation-inputs.<entry-ts>.md
+  -> writes remediation/<entry-ts>/remediation-inputs.md
   -> delegates to atomic-planner
-     -> atomic-planner authors remediation-plan.<entry-ts>.md
+     -> atomic-planner authors remediation/<entry-ts>/remediation-plan.md
         (plan shape per .claude/skills/atomic-plan-contract/SKILL.md)
      -> orchestrator hands plan to atomic-executor for preflight
         -> atomic-executor returns one of:
@@ -34,13 +34,15 @@ orchestrator
      -> atomic-executor executes the cleared plan task-by-task
         (workers are invoked by atomic-executor only)
      -> orchestrator delegates to feature-review
-        -> feature-review writes code-review.<exit-ts>.md,
-           feature-audit.<exit-ts>.md, and policy-audit.<exit-ts>.md
+        -> feature-review writes audit/<exit-ts>/code-review.md,
+           audit/<exit-ts>/feature-audit.md, and audit/<exit-ts>/policy-audit.md
   -> orchestrator evaluates exit condition:
      blocking_count == 0 -> mark exit_condition_met = true, end loop
-     blocking_count > 0  -> begin cycle N+1 with new remediation-inputs.<new-ts>.md
+     blocking_count > 0  -> begin cycle N+1 with new remediation/<new-ts>/remediation-inputs.md
 ```
 
+Every audit (including the initial, non-remediation-triggered `feature-review` pass that first discovers findings) is written under an `audit/<timestamp>/` folder. Every remediation cycle's entry artifacts are written under a `remediation/<timestamp>/` folder. This folder-per-cycle layout is the canonical pattern for multi-cycle remediation: it keeps each cycle's inputs, plan, and reaudit artifacts visually and structurally grouped, rather than relying on filename timestamp suffixes alone to disambiguate cycles sharing a feature folder.
+
 The orchestrator must not call typed-engineer workers directly during any phase of the cycle. The orchestrator must not act on a preflight delta itself; revisions are routed to `atomic-planner`.
 
 ## Trigger Conditions
@@ -54,7 +56,7 @@ Trigger remediation when any of these are true:
 
 ## Required Remediation Inputs
 
-The orchestrator authors `remediation-inputs.<entry-ts>.md` with:
+The orchestrator authors `remediation/<entry-ts>/remediation-inputs.md` with:
 
 - Enumerated fix list with file paths, expected behavior, and verification commands.
 - A "do not do" list (no scope creep, no policy weakening, no silent skips).
@@ -62,24 +64,26 @@ The orchestrator authors `remediation-inputs.<entry-ts>.md` with:
 
 ## Required Artifacts
 
-Each remediation cycle produces exactly five artifacts under the active feature folder:
+Each remediation cycle produces exactly five artifacts under the active feature folder, grouped into one `remediation/<entry-ts>/` folder and one `audit/<exit-ts>/` folder:
+
+1. `docs/features/active/<slug>/remediation/<entry-ts>/remediation-inputs.md` — orchestrator authors at cycle entry.
+2. `docs/features/active/<slug>/remediation/<entry-ts>/remediation-plan.md` — `atomic-planner` authors at cycle entry.
+3. `docs/features/active/<slug>/audit/<exit-ts>/code-review.md` — `feature-review` authors at cycle exit.
+4. `docs/features/active/<slug>/audit/<exit-ts>/feature-audit.md` — `feature-review` authors at cycle exit.
+5. `docs/features/active/<slug>/audit/<exit-ts>/policy-audit.md` — `feature-review` authors at cycle exit.
 
-1. `docs/features/active/<slug>/remediation-inputs.<entry-ts>.md` — orchestrator authors at cycle entry.
-2. `docs/features/active/<slug>/remediation-plan.<entry-ts>.md` — `atomic-planner` authors at cycle entry.
-3. `docs/features/active/<slug>/code-review.<exit-ts>.md` — `feature-review` authors at cycle exit.
-4. `docs/features/active/<slug>/feature-audit.<exit-ts>.md` — `feature-review` authors at cycle exit.
-5. `docs/features/active/<slug>/policy-audit.<exit-ts>.md` — `feature-review` authors at cycle exit.
+The initial, non-remediation-triggered `feature-review` pass (the audit that first discovers findings and opens cycle 1) also writes its three artifacts under `docs/features/active/<slug>/audit/<its-own-timestamp>/`, for the same reason: one timestamped folder per audit event, regardless of whether that audit opens, closes, or does not trigger a remediation cycle.
 
 Timestamp rule:
 
-- `<entry-ts>` is the ISO-8601 timestamp at cycle entry, in the `yyyy-MM-ddTHH-mm` format defined in `.claude/skills/evidence-and-timestamp-conventions/SKILL.md`. It applies to both `remediation-inputs.<entry-ts>.md` and `remediation-plan.<entry-ts>.md`.
-- `<exit-ts>` is the ISO-8601 timestamp at cycle exit (when `feature-review` runs), in the same `yyyy-MM-ddTHH-mm` format. It applies to all three reaudit artifacts: `code-review.<exit-ts>.md`, `feature-audit.<exit-ts>.md`, and `policy-audit.<exit-ts>.md`.
+- `<entry-ts>` is the ISO-8601 timestamp at cycle entry, in the `yyyy-MM-ddTHH-mm` format defined in `.claude/skills/evidence-and-timestamp-conventions/SKILL.md`. It names both the `remediation/<entry-ts>/` folder and, within it, `remediation-inputs.md` and `remediation-plan.md`.
+- `<exit-ts>` is the ISO-8601 timestamp at cycle exit (when `feature-review` runs), in the same `yyyy-MM-ddTHH-mm` format. It names the `audit/<exit-ts>/` folder and, within it, all three reaudit artifacts: `code-review.md`, `feature-audit.md`, and `policy-audit.md`.
 
-A cycle with fewer than five artifacts is malformed. A cycle that uses a single timestamp for both entry and exit is malformed unless both phases ran within the same minute.
+A cycle with fewer than five artifacts is malformed. A cycle that uses the same timestamp value for both its `remediation/<ts>/` and `audit/<ts>/` folders is malformed unless entry and exit genuinely ran within the same minute — the two folders remain distinct either way, since one is named `remediation/` and the other `audit/`.
 
 ## Plan Shape
 
-`remediation-plan.<entry-ts>.md` MUST conform to `.claude/skills/atomic-plan-contract/SKILL.md`. In particular:
+`remediation/<entry-ts>/remediation-plan.md` MUST conform to `.claude/skills/atomic-plan-contract/SKILL.md`. In particular:
 
 - Phase headings: `### Phase N — <Title>`.
 - Tasks: `- [ ] [P#-T#]` with sequential per-phase IDs.
@@ -102,11 +106,11 @@ The orchestrator records the preflight outcome in `remediation_loop.cycles[curre
 
 When preflight is clear, `atomic-executor` executes the plan task-by-task. The executor invokes workers (`python-typed-engineer`, `typescript-engineer`, `csharp-typed-engineer`, `powershell-typed-engineer`) internally as needed. The orchestrator does not call workers.
 
-When execution is complete, the orchestrator delegates to `feature-review`. `feature-review` produces the three reaudit artifacts under the active feature folder using the exit timestamp.
+When execution is complete, the orchestrator delegates to `feature-review`. `feature-review` produces the three reaudit artifacts under `docs/features/active/<slug>/audit/<exit-ts>/` using the exit timestamp.
 
 ## Exit Gate
 
-The orchestrator reads the latest cycle's three reaudit artifacts and computes `blocking_count` as the total number of FAIL findings plus material PARTIAL findings flagged as blocking. Only when `blocking_count == 0` does the orchestrator set `exit_condition_met = true` on the current cycle and mark the remediation loop complete. Otherwise, the orchestrator opens cycle N+1 with a new `remediation-inputs.<new-ts>.md` and runs the full chain again.
+The orchestrator reads the latest cycle's three reaudit artifacts and computes `blocking_count` as the total number of FAIL findings plus material PARTIAL findings flagged as blocking. Only when `blocking_count == 0` does the orchestrator set `exit_condition_met = true` on the current cycle and mark the remediation loop complete. Otherwise, the orchestrator opens cycle N+1 with a new `remediation/<new-ts>/remediation-inputs.md` and runs the full chain again.
 
 ## Context Package (When Required)
 

package/resources/claude-customizations/pack-manifests/core.json

@@ -5,8 +5,11 @@
     ".claude/settings.json",
     ".claude/agents/atomic-executor.md",
     ".claude/agents/atomic-planner.md",
+    ".claude/agents/commit-message.md",
+    ".claude/agents/epic-orchestrator.md",
     ".claude/agents/epic-review.md",
     ".claude/agents/feature-review.md",
+    ".claude/agents/human-exception-runbook.md",
     ".claude/agents/orchestrator.md",
     ".claude/agents/prd-feature.md",
     ".claude/agents/staged-review.md",
@@ -14,9 +17,13 @@
     ".claude/agents/task-researcher.md",
     ".claude/hooks/enforce-checkpoint-monotonic.ps1",
     ".claude/hooks/enforce-completion-consistency.ps1",
+    ".claude/hooks/enforce-epic-merge-gate.ps1",
+    ".claude/hooks/enforce-epic-wave-barrier.ps1",
+    ".claude/hooks/enforce-epic-worktree-removal-gate.ps1",
     ".claude/hooks/enforce-evidence-locations.ps1",
     ".claude/hooks/enforce-feature-folder-order.ps1",
     ".claude/hooks/enforce-orchestration-preimplementation-gate.ps1",
+    ".claude/hooks/enforce-pr-author-skill.epic-base-branch.ps1",
     ".claude/hooks/enforce-pr-author-skill.ps1",
     ".claude/hooks/enforce-prd-feature-before-planner.ps1",
     ".claude/hooks/enforce-promotion-mcp-only.ps1",
@@ -39,6 +46,7 @@
     ".claude/skills/acceptance-criteria-tracking/SKILL.md",
     ".claude/skills/atomic-plan-contract/SKILL.md",
     ".claude/skills/commit-message/SKILL.md",
+    ".claude/skills/epic-orchestrate/SKILL.md",
     ".claude/skills/evidence-and-timestamp-conventions/SKILL.md",
     ".claude/skills/execute-hard-lock/SKILL.md",
     ".claude/skills/feature-promotion-lifecycle/SKILL.md",

package/resources/codex-and-agents-customizations/.agents/skills/orchestrate/SKILL.md

@@ -141,9 +141,12 @@ There is no fallback. If the MCP server or validation tool is unavailable, or
 if validation fails, the orchestrator must update blocked state and stop rather
 than reporting completion.
 
-The repository CI gate `Orchestrator State Gate` runs the same validator when a
-checkpoint is present. Branch protection should require this check for branches
-that use orchestrated completion.
+No CI workflow performs this validation. The `artifacts/` directory is gitignored,
+so the orchestrator-state checkpoint is never present in a CI checkout; a prior
+CI gate (`validate-orchestrator-state.yml`) that attempted this check was a
+structural no-op for that reason and has been removed. The MCP-server-based
+validation described above is this ecosystem's enforcement mechanism for the
+orchestrator-state checkpoint.
 
 Completion validation requires the checkpoint to prove mandatory handoffs and
 skill use. The checkpoint must include:

package/resources/codex-and-agents-customizations/.agents/skills/remediation-handoff-atomic-planner/SKILL.md

@@ -22,7 +22,7 @@ Trigger remediation when any of these are true:
 
 ## Required Remediation Inputs
 
-Create `remediation-inputs.<timestamp>.md` with:
+Create `remediation/<timestamp>/remediation-inputs.md` (one timestamped `remediation/` folder per cycle; reaudit artifacts from a triggering or exit review live under the sibling `audit/<timestamp>/` folder, per the canonical pattern documented in the Claude-side `remediation-handoff-atomic-planner` skill) with:
 - Enumerated fix list with file paths, expected behavior, and verification commands.
 - A “do not do” list (no scope creep, no policy weakening, no silent skips).