Add supervised task subagent dispatch

.codex/README.md

@@ -14,10 +14,33 @@ In this framework repository, worked product artifacts live under `examples/even
 
 - `skills/`: repository-local maintenance skills for Codex. They are not mirrored into adopter repositories.
 
+## Ownership and routing
+
+| Surface | Canonical owner | Use it for |
+| --- | --- | --- |
+| `FRAMEWORK.md` | Framework method | Gates, lifecycle, authority, and architecture. |
+| `framework/skills/` | Distributed framework skills | Product-facing specialist and orchestrator contracts. |
+| `.codex/skills/` | Repository maintenance skills | Reviewing, testing, packaging, and preserving this repository. |
+| `starter/` | Clean adopter skeleton | New-product content only. |
+| `examples/events/` | Worked product fixture | Learning and validation; never a starter source. |
+| Git history | Maintenance record | Evolution of the framework method and contracts. |
+
+Use `framework-change-reviewer` before or after a method-level change; use `distribution-impact-analyzer` and `upgrade-compatibility` whenever embedded, starter, installer, or packaging assets change. Use `runtime-contract-tester` for CLI or runtime changes, `agent-target-smoke` for harness output, `fixture-governor` for starter/example boundaries, `skill-contract-auditor` for skill contracts, and `ci-matrix-maintainer` to select and maintain mechanical gates.
+
+## Maintenance rules
+
+- Read `FRAMEWORK.md` before changing framework behavior.
+- Update every affected contract, validator, template, starter asset, documentation surface, and test in the same change.
+- Do not edit generated agent trees as canonical sources or create product artifacts under `.codex/`.
+- Preserve adopter-owned content and approval records during `upgrade`; never use an overwrite to repair a migration.
+- Keep optional capabilities explicit, disabled by default when they change execution behavior, and covered by combination tests.
+- Report unavailable environment gates as limitations, never as passing evidence.
+- Record framework method evolution directly in `FRAMEWORK.md`, affected contracts, validators, and tests; Git is the maintenance record.
+
 ## Responsible Skill
 
-Primary owner: Documentation Orchestrator.
+Primary owner: Documentation Orchestrator. Use the specialist maintenance skill matching the changed surface before handoff.
 
 ## Next Step
 
-When a skill changes, validate that its `SKILL.md` still has frontmatter with `name` and `description`, and that the instructions resolve product paths through the active product root instead of assuming product folders at the framework repository root.
+When a skill changes, run `skill-contract-auditor` or at minimum validate that its `SKILL.md` has frontmatter with `name` and `description`, that its instructions resolve product paths through the active product root, and that its guidance remains consistent with `FRAMEWORK.md`.

.codex/skills/agent-target-smoke/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: agent-target-smoke
+description: Smoke-test Spec Framework initialization and upgrade output for Codex, Cursor, and Claude Code agent targets and their Guide-first dispatchers.
+---
+
+# Agent Target Smoke
+
+## Purpose
+
+Verify the generated harness entry points without treating any target-specific tree as the source of truth.
+
+## Required reading
+
+- `FRAMEWORK.md`
+- `internal/install/`
+- `internal/dispatcher/`
+- relevant init, upgrade, and dispatcher tests
+
+## Workflow
+
+1. Initialize an isolated temporary product for each requested target: Codex, Cursor, and Claude Code.
+2. Verify the target receives only its supported dispatcher and that the dispatcher requires a valid `product/.product/framework.json`.
+3. Verify that framework skills and templates resolve from the versioned runtime, not from repository-local copied trees.
+4. Upgrade the fixture and verify dispatcher refresh while product content remains unchanged.
+5. Check target instructions for portable paths and absence of unsupported harness-specific instructions.
+
+## Output
+
+Report target, generated paths, activation result, upgrade result, unsupported-target findings, and exact test evidence.

.codex/skills/ci-matrix-maintainer/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: ci-matrix-maintainer
+description: Maintain the Spec Framework verification matrix by mapping changed surfaces to unit, integration, race, validation, packaging, and release-smoke gates.
+---
+
+# CI Matrix Maintainer
+
+## Purpose
+
+Keep mechanical confidence proportional to the change. Do not suppress a failing, skipped, or environment-blocked gate.
+
+## Required reading
+
+- `AGENTS.md`
+- `.github/workflows/`
+- `.codex/skills/verify/SKILL.md`
+- changed code, assets, and tests
+
+## Workflow
+
+1. Map each changed surface to its required checks: formatting, unit, integration, example validation, race, target smoke, init/upgrade, packaging, and release smoke.
+2. Verify the workflow contains the required gate or document a justified local-only check.
+3. Add combination tests when optional runtime capabilities interact with imports, dispatch, reviews, approvals, or upgrade.
+4. Run the applicable checks and preserve exact output for failures.
+5. Report App Control, unavailable binaries, or other environment limits as blocked evidence, never as passing evidence.
+
+## Output
+
+Return a check matrix with status, command or workflow, coverage rationale, blockers, and recommended next gate owner.

.codex/skills/distribution-impact-analyzer/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: distribution-impact-analyzer
+description: Analyze the distribution impact of a Spec Framework asset or packaging change across embedding, install, upgrade, documentation, agent targets, and release verification.
+---
+
+# Distribution Impact Analyzer
+
+## Purpose
+
+Make distribution effects explicit before a framework asset or packaging change is committed.
+
+## Required reading
+
+- `FRAMEWORK.md`
+- `assets.go`
+- affected `starter/` and `framework/` assets
+- installer, release, and smoke-test code
+
+## Workflow
+
+1. Determine whether the change is embedded, generated, copied at init, materialized at runtime, or documentation-only.
+2. Complete an impact matrix for assets, init, upgrade, Codex/Cursor/Claude targets, documentation, CI, archives, checksums, and release smoke.
+3. Identify managed versus adopter-owned paths and verify that removals remain safe after upgrade.
+4. Require the smallest relevant install, upgrade, target, and release tests.
+5. State whether a version bump, migration note, or rollback plan is required.
+
+## Output
+
+Return the impact matrix, affected paths, required verification, release impact, compatibility verdict, and migration/rollback notes.

.codex/skills/fixture-governor/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: fixture-governor
+description: Govern changes across Spec Framework starter assets, the Events worked-product fixture, and embedded runtime assets without mixing their ownership boundaries.
+---
+
+# Fixture Governor
+
+## Purpose
+
+Protect the distinction between reusable starter content and the Events validation fixture.
+
+## Required reading
+
+- `FRAMEWORK.md`
+- `AGENTS.md`
+- affected `starter/`, `examples/events/`, `framework/`, and `assets.go` files
+
+## Workflow
+
+1. Classify every changed artifact as framework-owned, clean starter content, generated target output, or Events product-owned fixture content.
+2. Reject copying Events scope, approvals, decisions, or narratives into reusable framework or starter assets.
+3. When a starter contract changes, verify initialization, upgrade preservation, embedded assets, and the matching fixture assertions.
+4. When Events changes, read its relevant context and preserve its product lifecycle, approvals, and evidence.
+5. Check whether empty directories can be created declaratively rather than retained through placeholder documentation.
+
+## Output
+
+Return the ownership map, required synchronization, preservation evidence, validation fixture impact, and unresolved boundary risks.

.codex/skills/framework-change-reviewer/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: framework-change-reviewer
+description: Review a proposed Spec Framework maintenance change for method, contract, compatibility, distribution, and test impact before it is committed or released.
+---
+
+# Framework Change Reviewer
+
+## Purpose
+
+Review framework-maintenance diffs. Do not author product artifacts, create approvals, or replace the implementation owner.
+
+## Required reading
+
+- `FRAMEWORK.md`
+- `AGENTS.md`
+- affected contracts, templates, validators, tests, and installer code
+
+## Workflow
+
+1. Classify the change: method, skill contract, template, CLI/runtime, starter, validator, or documentation.
+2. Map affected surfaces: `FRAMEWORK.md`, `framework/`, `starter/`, `examples/events/`, `assets.go`, init, upgrade, agent targets, documentation, CI, and release packaging.
+3. Check that the default behavior and existing adopter content remain compatible, or that a migration is explicit and reversible.
+4. Check that product decisions and approval history are not edited by framework maintenance.
+5. Require tests for each affected executable boundary and report omitted surfaces as findings.
+
+## Output
+
+Return a concise verdict: `ready`, `needs_changes`, or `blocked`; the impact matrix; compatibility and migration notes; required tests; residual risks; and the next owner.

.codex/skills/new-framework-skill/SKILL.md

@@ -16,7 +16,7 @@ Answer these first; if any answer is unclear, stop and ask:
 - **Specialist or orchestrator?** Specialists own exactly one canonical artifact's content. Orchestrators own flow, gates, sequencing, and handoff across artifacts — they never author artifact content themselves.
 - **Which artifact does it own?** A specialist without an owned artifact, or an artifact already owned by another skill, means the skill should not exist — extend the existing owner instead.
 - **Does the owned artifact have a template?** If the artifact is new, a matching template in `framework/template/` must be created in the same change.
-- **Does this change the method?** Adding or reshaping a skill usually alters the framework contract — record an FDR (use the `fdr` skill) unless the change is purely editorial.
+- **Does this change the method?** Adding or reshaping a skill usually alters the framework contract — update `FRAMEWORK.md`, affected contracts, validators, and tests in the same change. Git history is the maintenance record.
 
 ## Canonical SKILL.md structure
 
@@ -55,7 +55,7 @@ description: "<Name> Skill. Use when Codex needs to <responsibility, lowercase c
 - Approved product decisions in the active product root's `knowledge/decisions/` and `.product/decisions.json`.
 
 ## Workflow
-<Numbered steps. Reference gates, statuses, and FDR routing rules where they apply.>
+<Numbered steps. Reference applicable gates, statuses, and routing rules.>
 
 ## Quality checklist
 - [ ] Preserves traceability to affected artifacts.
@@ -86,7 +86,7 @@ After writing the SKILL.md:
 2. Check `FRAMEWORK.md` for skill rosters, flow diagrams, or step tables that must mention it, and `AGENTS.md` / `framework/AGENTS.framework.md` for flow references.
 3. If it owns a new artifact: create the template in `framework/template/`, add the artifact to the canonical flow documentation, and update the readiness/validator rules if the artifact is gate-relevant.
 4. Update the `Handoff` sections of neighboring skills whose flow now includes the new skill.
-5. Record the FDR if the method changed.
+5. When the method changed, verify that `FRAMEWORK.md`, affected contracts, validators, and tests express the new behavior.
 
 No package manifest changes are needed: `assets.go` embeds `framework/skills/` wholesale. Update installer and rendering tests when target-specific metadata changes.
 

.codex/skills/runtime-contract-tester/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: runtime-contract-tester
+description: Test CLI and runtime contract changes in the Spec Framework, including optional capabilities, dispatch, imports, persistence, concurrency, and failure behavior.
+---
+
+# Runtime Contract Tester
+
+## Purpose
+
+Turn runtime changes into explicit, compatible contracts. Do not declare an unavailable external or sandboxed command as passing.
+
+## Required reading
+
+- `FRAMEWORK.md`
+- changed `cmd/` and `internal/` packages
+- related CLI help, JSON contracts, and tests
+
+## Workflow
+
+1. List changed commands, flags, persisted files, defaults, and external process boundaries.
+2. Verify new optional capabilities are disabled by default and can be enabled, disabled, and removed safely.
+3. Test success, invalid input, interrupted execution, resume/idempotency, and backward-compatible absence of configuration.
+4. For concurrent work, test lease ownership, dependency ordering, write scopes, and deterministic reconciliation.
+5. Combine changed features with import, dispatch, review, approval, and upgrade boundaries when applicable.
+
+## Output
+
+Return the contract matrix, commands run, compatible defaults, combination-test evidence, failures, and residual runtime risks.

.codex/skills/skill-contract-auditor/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: skill-contract-auditor
+description: Audit repository-maintenance and shipped Spec Framework skills for valid metadata, ownership, portable paths, handoffs, and consistency with the canonical method.
+---
+
+# Skill Contract Auditor
+
+## Purpose
+
+Keep skills actionable and non-overlapping. This skill audits contracts; it does not silently change a skill's product ownership or workflow.
+
+## Required reading
+
+- `FRAMEWORK.md`
+- `AGENTS.md`
+- `.codex/README.md` for maintenance skills
+- `framework/skills/README.md` for shipped skills
+
+## Workflow
+
+1. Validate each `SKILL.md` has only `name` and `description` frontmatter and a precise activation description.
+2. Verify the skill has one clear responsibility, explicit exclusions, required reading, and a safe handoff.
+3. Check paths work from the framework runtime and active product root; reject lab-specific or generated-tree source assumptions.
+4. Check for stale concepts, nonexistent commands, duplicated ownership, bypassed gates, or approval authority violations.
+5. Route method-level corrections to `FRAMEWORK.md`, contracts, validators, and tests in the same change.
+
+## Output
+
+Report compliant skills, findings by severity, affected owners, exact corrective surface, and verification required after correction.

.codex/skills/upgrade-compatibility/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: upgrade-compatibility
+description: Verify that a Spec Framework distribution change can initialize new products and upgrade existing products without overwriting adopter-owned content or approvals.
+---
+
+# Upgrade Compatibility
+
+## Purpose
+
+Protect adopter-owned product content during distribution changes. Do not change an adopter product or approval record merely to make an upgrade pass.
+
+## Required reading
+
+- `FRAMEWORK.md`
+- `AGENTS.md`
+- `internal/install/`
+- affected starter assets and upgrade tests
+
+## Workflow
+
+1. Identify changed embedded assets and whether they are framework runtime assets or product-owned starter assets.
+2. Exercise a fresh `init` for each affected starting point and agent target.
+3. Exercise `upgrade` over an initialized fixture containing changed product files, decisions, and approval history.
+4. Verify upgrade refreshes only the runtime, manifest, and selected dispatchers; it must not replay initialization or overwrite adopter content.
+5. For removed assets, verify no stale reference remains and document whether the removal is safe, retained, or requires an explicit migration.
+
+## Output
+
+Report init and upgrade evidence, preserved paths, changed managed paths, compatibility status, rollback path, and any human migration decision required.

FRAMEWORK.md

@@ -535,6 +535,16 @@ Runtime v2 makes execution resumable and safely parallel. The complete workspace
 
 Runtime commands include `runtime`, `resume`, `handoff`, `checkpoint`, `lease`, `commands`, `schedule`, `integrate`, and local `reviews import`. Imported review findings are immutable, provider-neutral evidence with provenance and an advisory owner route; import cannot resolve a remote review, alter code, or advance an approval.
 
+`dispatch` is an optional supervised orchestration layer. It assigns only ready
+units through persisted envelopes and leases. Independent QA, Code Review and
+Security Review envelopes pin the same returned diff hash and remain read-only.
+Dispatch execution and waves require explicit per-run enablement; they cannot
+approve, commit, push, merge, release, or resolve external reviews.
+
+`dispatch-orchestrator` owns assignment and observation. `subagent-return-reviewer`
+owns the structured return record and routes gaps without changing product
+lifecycle or approval state.
+
 Skills are specialists. They can operate in modes such as `create`, `update`, `audit`, `evolve`, `explain`, `compare`, and `refactor`, but each must have a clear responsibility.
 
 Definition and planning skills follow the shared Discovery and Challenge contract before substantive creation or material revision. They inspect repository and CLI evidence first, then use the harness-native structured question capability for human choices that cannot be discovered. Each round asks one to three focused questions; meaningful choices present concrete options, trade-offs, a recommendation, and a free-form path. Skills proactively warn about material scope, dependency, usability, security, operability, reversibility, approval, and delivery risks and propose safer alternatives. They must not finalize or hand off while a blocking question is unanswered, and conversational answers never grant formal approval. Harness adapters map the canonical `native_user_question` capability to their default question tool; a concise conversational question is the explicit fallback only when no structured tool is exposed.
@@ -720,7 +730,7 @@ The runtime behavior shared by all agents is defined in the pinned `AGENTS.frame
 
 - `init` resolves one strict declarative starting-point contract, validates its complete materialization plan, stages it, and atomically publishes `product/`. Data contracts cannot execute arbitrary commands or escape the product root.
 - A starting point changes the initial evidence, registry, bootstrap, and first gate; it never removes later rigor or approval requirements. Existing code and documents remain evidence, not approved truth. `audit-only` remains read-only until an explicit supported transition.
-- `existing-documents` creates an analysis-only import run with `traceability.json` as the dedicated per-source ledger. The Artifact Importer agent reads each source, records evidence, extracted claims, candidate destinations, and unmapped gaps there, then proposes mappings. Human review of inventory, traceability, conflicts, and selected mappings is required before explicit draft materialization; imported artifacts retain their normal owners, parents, and individual approval gates.
+- `existing-documents` creates an analysis-only import run with a dedicated per-source ledger. Scalable runs page their inventory, apply explicit file/byte budgets and filters before copying, and divide analysis into leased resumable chunks. The Artifact Importer records evidence, extracted claims, candidate destinations, and unmapped gaps for every non-excluded source, then proposes mappings. Human review of inventory, traceability, conflicts, and selected mappings is required before explicit draft materialization; imported artifacts retain their normal owners, parents, and individual approval gates.
 - Materialized import artifacts carry machine-readable `provenance.kind: import-draft` and `provenance.import_run`. The owning normalization skill must replace this with `skill-normalized` and identify itself before approval; import provenance is lineage, not canonical readiness.
 - `init` never overwrites an existing `product/`. `upgrade` refreshes only the pinned runtime, manifest, and selected dispatchers; it never replays initialization over adopter-owned content.
 - Starting-point details belong to `docs/starting-points.md`, `framework/init/`, and generated `BOOTSTRAP.md` rather than this operational summary.