chore: expand orchestration and discovery infrastructure

[drmoisan]

Suggested title

chore: expand orchestration and discovery infrastructure

Summary

• Adds a Codex-native two-axis routing system: production-file-count topology selection (codex_topology_policy) and complexity-band model/reasoning selection (codex_model_policy), with generated per-band agent profiles (C1–C4 plus c3-elevated) for every delegated agent family.
• Adds epic-scale planning and orchestration surfaces: epic-plan, epic-run, and epic-orchestrate skills under .agents/skills/, epic-planner/epic-orchestrator Codex agent definitions, and the Codex hooks and scripts that enforce epic invocation origin, planning-only scope, wave barriers, child worktree binding, and merge gating.
• Adds a domain-neutral legacy discovery and parity-definition workflow: seven discovery-* skills, four analyst agents (legacy-parity-analyst, migration-coverage-reviewer, requirements-reconciler, runtime-characterization-analyst), and a two-sided artifact gate wired into .claude/settings.json.
• Updates config/orchestration-routing.json with the new policy blocks, a codex_topology_requirement on the small route, a preparation-route description aligned to epic-planner ownership, and model_budget.fable_policy moved from available to preferred.
• Corrects the small route's required_skills list by removing two entries (orchestrator-workflow, repo-automation-adapter) that do not exist as .claude/skills/ directories in this repository.
• Adds a cleanup-merged-worktrees skill for post-epic consolidation and deletion of fully merged drm-copilot-wt-* worktrees and branches.

This change is confined to governance, configuration, hook, and script surfaces. No first-party application source file (.cs, .ts, .py) is modified.

Why

The PR Intent fields in the context bundle were left blank, so the motivation below is stated only from what the diff itself establishes; no feature-doc excerpts were available in the context bundle.

• The existing routing configuration selected a delegation model from a single complexity axis. Codex-native execution additionally needs to select an implementation topology from production-file count, and the two decisions have different inputs. The diff separates them into codex_topology_policy and codex_model_policy so neither axis silently overrides the other.
• Epic-scale work previously had no enforced structure for wave scheduling, child-worktree binding, or integration-branch merge gating. The new hooks make those constraints deterministic rather than advisory.
• Legacy discovery and parity definition had no repeatable staged workflow. The discovery-* skill set defines the stage order (inventory → coverage → runtime characterization → parity → behavior reconciliation → validation) and the artifact gate enforces that each stage produced its artifact before the next one runs.
• The small route declared two required skills with no corresponding skill directory, which forced downstream receipt recording to reference names that could not be read. Removing them makes the route's declared requirements satisfiable.

What Changed

Codex routing and agent profiles (.codex/, .agents/)

• config/orchestration-routing.json: new codex_topology_policy (execution contexts, per-language production/test budgets, forced root personas, parallelism caps, escalation precedence) and codex_model_policy (profile order, complexity-to-profile model/reasoning mapping, c3-elevated activation, ceiling-transition policy, forced personas, generated agent families). model_budget.fable_policy changed to preferred.
• .agents/skills/codex-model-routing/ (SKILL.md plus agents/openai.yaml): the routing contract and provider agent mapping.
• Five generated per-band profiles for each of atomic-executor, atomic-planner, csharp-typed-engineer, powershell-typed-engineer, orchestrator, feature-reviewer, task-researcher, prd-feature, and pr-author, plus base-profile updates for each family.
• .codex/agents/epic-planner.toml, .codex/agents/epic-orchestrator.toml: forced-persona epic definitions.
• .codex/config.toml: substantial expansion (+239/-…) wiring the profiles and hooks.

Epic enforcement hooks and scripts (.codex/hooks/, .codex/scripts/)

• Hooks: authorize-root-epic-invocation, enforce-epic-root-invocation, enforce-epic-planning-only, enforce-epic-wave-barrier, enforce-epic-child-worktree-binding, enforce-epic-worktree-removal-gate, enforce-epic-merge-gate, enforce-codex-model-routing, validate-codex-subagent-routing, record-subagent-routing-attestation, codex-agent-profile-attestation, codex-epic-child-launch-attestation, codex-authority-store.
• Scripts: epic-child-launch-contract, epic-child-launch-runtime, epic-child-persistence-runtime, epic-child-sandbox-preflight, launch-epic-child-wave, resume-epic-child.

Discovery workflow (.claude/skills/discovery-*, .claude/agents/, .claude/hooks/)

• Skills: discovery-workflow (umbrella sequencing and the Referenced Contracts registry), discovery-repo-inventory, discovery-coverage-ledger, discovery-runtime-characterization, discovery-parity-matrix, discovery-behavior-reconciliation, discovery-validate-artifacts.
• Agents: legacy-parity-analyst, migration-coverage-reviewer, requirements-reconciler, runtime-characterization-analyst — all scoped to Write(discovery/**) only.
• Hooks: enforce-discovery-artifact-gate.ps1 (PreToolUse-side) and validate-discovery-artifact-gate.ps1 (SubagentStop-side), both registered in .claude/settings.json.

Skills and settings

• .agents/skills/epic-plan/, epic-run/, epic-orchestrate/: new epic lifecycle skills.
• .claude/skills/cleanup-merged-worktrees/: merged-worktree detection, consolidation, and deletion workflow.
• .agents/skills/orchestrate/SKILL.md (+98), .agents/skills/orchestrator-workflow/SKILL.md (+43), .claude/skills/execute-hard-lock/SKILL.md (+2/-2): updated for root-session entry points and topology deployment.
• .claude/settings.json: registers the two discovery gate hooks on the existing PreToolUse and SubagentStop chains.

Architecture / How It Fits Together

Two independent selection axes feed a Codex delegation:

1. Topology axis — codex_topology_policy.language_budgets maps a language to a direct-mode production/test file budget and a logical agent. When the estimate exceeds budget, or the request is cross-language, cross-cutting, or originates in an epic child context, escalation_precedence decides which escalation applies and routing hands off to the orchestrator persona instead of a typed engineer. The small route now carries a codex_topology_requirement block declaring the receipt key, required execution context, and the resolved-engineer delegation source.
2. Model axis — codex_model_policy.complexity_to_profile maps C1–C4 to an exact model slug and reasoning effort; there is no silent fallback when a profile is unavailable. c3-elevated activates only in epic child contexts. epic-planner and epic-orchestrator are forced personas that bypass the band table.

Epic execution flows root → epic-planner (planning only, enforced by enforce-epic-planning-only) → epic-orchestrator, which launches child waves via launch-epic-child-wave under the epic-child-launch-contract. enforce-epic-wave-barrier blocks a wave from starting before its predecessor completes, enforce-epic-child-worktree-binding ties each child to its assigned worktree, and enforce-epic-merge-gate gates the integration-to-main merge. record-subagent-routing-attestation and codex-agent-profile-attestation write the attestation receipts that validate-codex-subagent-routing and enforce-codex-model-routing check.

The discovery workflow is a linear seven-stage pipeline. discovery-workflow sequences the stages and holds the contract registry; each stage skill produces its artifact under the profile artifacts root; discovery-validate-artifacts runs the per-artifact validators after each stage and the completion gate at the end, with empty-error-list pass semantics. The two new .claude/hooks/ scripts enforce that gate from both directions — before a tool call proceeds and when a subagent stops — so a stage cannot be skipped by invoking the next one directly.

Verification

Completed

Not verified in this PR. The context bundle records no CI status for HEAD (CI status (HEAD): (not available)) and no canonical verification evidence (No canonical verification evidence parsed). No test files are added or modified by this change.

Recommended

• CI (.github/workflows/ci.yml) on this PR head: actionlint plus the windows-latest format/build/analyze/test job. No .github/workflows/** file and no .cs file is changed, so both jobs exercise unchanged inputs; confirm they pass on the PR head before merge.
• PowerShell toolchain over the new hook and script files, in order:
  • mcp__drm-copilot__run_poshqc_format
  • mcp__drm-copilot__run_poshqc_analyze
  • mcp__drm-copilot__run_poshqc_test
• Behavioral smoke check of the two new .claude/hooks/ gate scripts against a discovery artifact tree, since they are now registered in .claude/settings.json and affect every session.
• JSON parse check of config/orchestration-routing.json and .claude/settings.json.

Backward Compatibility / Migration Notes

• Active session behavior changes. .claude/settings.json registers enforce-discovery-artifact-gate.ps1 on PreToolUse and validate-discovery-artifact-gate.ps1 on SubagentStop. These run in every session after merge, not only in discovery work. A defect in either script affects all agent sessions.
• model_budget.fable_policy changes from available to preferred. Under preferred, the preferred_overlay redirects the C3 cell to fable for the overlay agents only (atomic-planner, prd-feature, feature-review, task-researcher); atomic-executor and pr-author C3 cells stay at opus. Existing model_routing_receipts[] recorded under available will not match a recomputation under preferred.
• small route required_skills shrinks by two entries. Any checkpoint or receipt set that enumerated orchestrator-workflow or repo-automation-adapter for the small route will no longer match the config. require_complete validation compares the checkpoint arrays against this config, so in-flight small-route checkpoints must be updated.
• preparation route drops requires_pr_gate: false. The key is removed rather than changed; consumers that read it explicitly should treat its absence as the prior false.
• No public application API changes. No file renames or removals.

Risks and Mitigations

Risk	Mitigation
The two new .claude/hooks/ gate scripts run in every session and could block unrelated tool calls or subagent completions.	Exercise both scripts locally before merge. Rollback is reverting the two .claude/settings.json hook registrations, which disables the gates without removing the scripts.
No Pester tests accompany the 13 new .codex/hooks/ and 6 new .codex/scripts/ PowerShell files, so their enforcement logic is unverified.	The .codex/ surface is not loaded by Claude Code sessions, limiting blast radius to Codex-native runs. Tracked as a follow-up below.
fable_policy: preferred changes model selection for four agent families and will invalidate previously recorded routing receipts.	The change is a one-line config revert if the preferred overlay proves undesirable.
The generated per-band .codex/agents/*.toml profiles (45 files) pin exact model slugs with no fallback, so an unavailable slug fails rather than degrading.	This is the stated design intent (exact model slugs are mandatory and unavailable profiles do not fall back silently); a slug change requires a config edit, which is a visible diff.
Indentation in the new config/orchestration-routing.json policy blocks is inconsistent with the surrounding file.	Cosmetic only; the JSON parses. Worth a formatting pass, noted as a follow-up.

Review Guide

Suggested order, highest-signal first:

1. config/orchestration-routing.json — the contract every other file in this PR implements. Read the two new policy blocks and the three edits to existing routes.
2. .claude/settings.json — the only change with immediate, repo-wide session effect.
3. .claude/hooks/enforce-discovery-artifact-gate.ps1 and .claude/hooks/validate-discovery-artifact-gate.ps1 (+237) — the enforcement logic behind item 2.
4. .claude/skills/discovery-workflow/SKILL.md — the umbrella that defines stage order and the contract registry; read before the six stage skills.
5. .codex/scripts/epic-child-launch-contract.ps1 (+475), .codex/scripts/launch-epic-child-wave.ps1 (+471), .codex/scripts/epic-child-launch-runtime.ps1 (+445) — the largest new logic files.
6. .codex/hooks/record-subagent-routing-attestation.ps1 (+414), enforce-epic-child-worktree-binding.ps1 (+325), enforce-epic-wave-barrier.ps1 (+295), enforce-epic-planning-only.ps1 (+292) — the enforcement layer.
7. .codex/config.toml (+239) — wiring.
8. .agents/skills/orchestrate/SKILL.md (+98) and orchestrator-workflow/SKILL.md (+43) — prose updates.

Low-signal bulk: the 45 generated .codex/agents/*-c{1,2,3,3-elevated,4}.toml profiles are near-identical per family and differ only in model slug, reasoning effort, and suffix. Review one family in full (for example atomic-executor-c1 through atomic-executor-c4), then diff the remaining families against it rather than reading each file.

Follow-ups

• Add Pester coverage for the 13 new .codex/hooks/ scripts and 6 new .codex/scripts/ files; repository PowerShell policy requires >= 85% line and >= 75% branch coverage, and this PR adds none.
• Add Pester coverage for the two new .claude/hooks/ discovery gate scripts.
• Normalize indentation in the new config/orchestration-routing.json policy blocks.
• Confirm whether the preparation route's removed requires_pr_gate key has any remaining readers.

GitHub Auto-close

• None (no verified closing issues; the context bundle reports GitHub CLI unavailable during collection and no author-asserted autoclose issues)