codex-orchestrator 2.0.2 → 2.0.4

package/internal-workflow/skills/diagnosing-bugs/scripts/hitl-loop.template.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Human-in-the-loop reproduction loop.
+# Copy this file, edit the steps below, and run it.
+# The agent runs the script; the user follows prompts in their terminal.
+#
+# Usage:
+#   bash hitl-loop.template.sh
+#
+# Two helpers:
+#   step "<instruction>"          → show instruction, wait for Enter
+#   capture VAR "<question>"      → show question, read response into VAR
+#
+# At the end, captured values are printed as KEY=VALUE for the agent to parse.
+
+set -euo pipefail
+
+step() {
+  printf '\n>>> %s\n' "$1"
+  read -r -p "    [Enter when done] " _
+}
+
+capture() {
+  local var="$1" question="$2" answer
+  printf '\n>>> %s\n' "$question"
+  read -r -p "    > " answer
+  printf -v "$var" '%s' "$answer"
+}
+
+# --- edit below ---------------------------------------------------------
+
+step "Open the app at http://localhost:3000 and sign in."
+
+capture ERRORED "Click the 'Export' button. Did it throw an error? (y/n)"
+
+capture ERROR_MSG "Paste the error message (or 'none'):"
+
+# --- edit above ---------------------------------------------------------
+
+printf '\n--- Captured ---\n'
+printf 'ERRORED=%s\n' "$ERRORED"
+printf 'ERROR_MSG=%s\n' "$ERROR_MSG"

package/internal-workflow/skills/implementation-spec-maker/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: "implementation-spec-maker"
+description: "Turn an approved plan, implementation issue, contract-discovery task, or existing spec into the smallest deterministic implementation spec. Use when downstream coding needs an executable checklist with confirmed scope, targets, commands, contracts, validation, and review evidence; do not use for product discovery or implementation."
+---
+
+# Implementation Spec Maker
+
+Create or revise an execution-ready specification for a downstream coding agent. Do not implement code or reopen approved product scope.
+
+## Core Contract
+
+- Treat the supplied plan, issue, discovery task, or existing spec as source authority.
+- Preserve approved scope, exclusions, guardrails, rejected approaches, blockers, validation, and required docs.
+- Confirm execution-critical facts from repository evidence or trusted external contracts. Never invent paths, symbols, commands, fixtures, env vars, schemas, ownership, or API behavior.
+- Produce the smallest spec another agent can execute without guessing. Save a useful `blocked` spec when a material unknown cannot be resolved.
+- Reference approved source content instead of repeating it; write only the missing execution delta.
+
+## Preflight
+
+1. Read the source authority, applicable repository instructions, and only the evidence needed to confirm targets, commands, contracts, consumers, fixtures, and validation.
+2. Reuse valid Evidence Maps and `$research` artifacts. Refresh only claims invalidated by changed files, versions, dates, contracts, or conflicts.
+3. Read the relevant section of [source modes](references/source-modes.md). Stop or mark the spec blocked when its source-specific requirements are not satisfied.
+4. Classify and record these independent facts:
+   - `spec_mode`: `compact | full` — document and coordination density.
+   - `implementation_size`: `small | medium | large` — expected delivery shape.
+   - `review_profile`: `simple | medium | high` — consequence and uncertainty,
+     resolved through the review loop owned by `$implementation-spec-review`.
+   - `expected_repositories`: exact positive integer from approved scope.
+
+Do not infer one classification from another. For ticket work, `direct` returns
+to `$tdd`, `compact spec` requests compact mode, and `standard spec` asks the
+maker to choose the smallest deterministic shape. Start a standard ticket in
+compact mode and expand to full only when repository evidence proves a concrete
+ambiguity that compact form cannot remove safely.
+
+## Choose The Smallest Shape
+
+Default to `compact`, including coherent high-risk or cross-repository work, when ownership, sequencing, stop conditions, and proof fit clearly.
+
+Use `full` only when compact form would leave a concrete ambiguity in safety, contract, ownership, sequencing, validation, revision history, or multi-agent integration. Add only the conditional controls that resolve that ambiguity. Risk alone does not require a long document.
+
+Keep `execution_model: "single-agent"` unless write scopes are perfectly disjoint and one integrator contract is necessary. Never assign overlapping ownership of files, schemas, generated artifacts, migrations, source-of-truth rules, or shared contracts.
+
+## Minimum Solution Gate
+
+Before drafting slices:
+
+1. Reduce the approved outcome to required behavior, material invariants, and proof.
+2. State the direct `Minimum Solution` through existing owners, public seams, and repository patterns.
+3. Set `Added Complexity: None` unless the minimum solution cannot satisfy a named requirement or evidenced failure path.
+4. For every added mechanism, including a new service, helper, adapter, layer, schema object, transaction, retry policy, job, cache, flag, compatibility path, or coordination boundary, record the exact invariant or failure that requires it and what breaks without it.
+5. Run the deletion challenge: if removing a proposed mechanism still satisfies all approved behavior, invariants, and proof, remove it from the spec.
+
+Judge simplicity by the fewest necessary concepts, owners, states, and integration points, not by line or file count. Do not require complexity scores or alternative-solution essays.
+
+## Draft The Execution Contract
+
+Read [the spec template](references/spec-template.md) before drafting, then remove every unused placeholder and optional block.
+
+- Name exact source material, approved scope, exclusions, preconditions, confirmed targets, commands, and observable done criteria.
+- Organize behavior-changing work as narrow vertical slices. Start each slice with the first failing behavior test or exact observable proof, then implementation targets and a slice exit gate.
+- For contract-heavy behavior, use `../../docs/agents/contract-test-ledger.md` and include only material invariants with their first RED test or proof.
+- For UI/app-facing behavior, invoke `$ui-evidence-proof` and embed its task-specific workflow, expected screen state, viewport coverage, fresh artifacts, and criterion-to-artifact mapping in the relevant slice.
+- State exact manual/live proof when automation is not applicable.
+- Name one source of truth when behavior or data can drift. Reuse existing owners and public seams; invoke `$codebase-design` only when ownership or a public seam changes.
+- Add task-specific review checkpoints only when a risky slice becomes stable before later work. Otherwise assign its mandatory lenses, applicable targeted recipes, and concrete bug classes to final review coverage.
+- For medium-risk specs, rely on the normal concise `$spec-implementer` completion summary unless a task-specific deviation is needed. For high-risk specs, point `Final Handoff Requirements` to the extended `$spec-implementer` Final Risk Handoff and add only task-specific deviations; do not copy its field list.
+- Keep optional cleanup, compatibility logic, feature flags, telemetry, rollout machinery, generic fallbacks, and speculative abstractions out of the spec unless source authority or a proven failure path requires them.
+
+## Review And Save
+
+1. Save the draft at `docs/implementation-specs/YYYY-MM-DD/HHMM-<slug>.md` with temporary `status: "draft"` and `review_outcome: "Pending"` so review applies to a stable artifact path without presenting it as approved.
+2. Read `../implementation-spec-review/references/review-loop.md` and invoke
+   `$implementation-spec-review` as its Adapter. Supply the saved spec, source
+   authority, approved decisions, and evidence; do not restate its topology or
+   defect lifecycle.
+3. Apply one consolidated, scope-preserving repair batch, then follow the owner
+   loop until it returns `Approved`, `Blocked`, or an eligible user-authorized
+   `Waived` outcome.
+4. A preflight-blocked spec may be saved with zero reviews and `review_verdict: "Not run"`. Never fabricate approval or use `Not required`.
+5. Replace temporary lifecycle metadata with outcome, last Adapter verdict,
+   mandatory coverage, accepted risks, and open stable IDs. Keep pass/session
+   counts only for high, Closure, or interrupted review. Any substantive
+   post-approval edit invalidates approval until reviewed again.
+
+## Final Response
+
+Return only:
+
+```text
+Spec Status: Ready | Blocked
+Saved Path: <path>
+Execution: <single-agent | multi-agent>; <compact | full>; <small | medium | large>; <n> repository/repositories
+Review: <Approved | Blocked | Waived>; <simple | medium | high>; <coverage or gaps>
+Adapter Verdict: <Approved | Needs Work | Rejected | Not run>
+Verified Defects: <stable IDs or None>
+Accepted Risks: <stable IDs, authority, and reason or None>
+Open Defects: <stable IDs or None>
+Blockers: <unresolved blockers or None>
+```
+
+Do not repeat the specification or downstream implementation/signoff procedure in chat.

package/internal-workflow/skills/implementation-spec-maker/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Implementation Spec Maker"
+  short_description: "Create lean deterministic implementation specs"
+  default_prompt: "Use $implementation-spec-maker to create the smallest deterministic spec while classifying document mode, implementation size, repository count, and review risk independently."
+policy:
+  allow_implicit_invocation: true

package/internal-workflow/skills/implementation-spec-maker/references/source-modes.md

@@ -0,0 +1,31 @@
+# Source Modes
+
+Read the section matching the active source. Apply the common source-authority and evidence rules from `SKILL.md` in every mode.
+
+## Plan-Based
+
+- Treat the approved plan as architectural authority.
+- Preserve its scope, vertical-slice boundaries, guardrails, rejected paths, required docs, validation, and blocking assumptions.
+- Block when missing guardrails would let implementation drift or require redesign.
+
+## Issue-Based
+
+- Treat one issue's acceptance criteria as the execution contract; parent material supplies product context, not sibling-ticket authority.
+- Read comments for changed decisions, blockers, credentials, external contracts, live prerequisites, and rejected approaches.
+- Preserve relevant `Implementation preparation`, `External contracts`, `Verification`, and `Blocked by` content.
+- Use `source_type: "issue"` when no plan exists. Do not block merely because `source_plan` is absent.
+- Block when acceptance criteria are ambiguous, non-verifiable, or contradicted by repository evidence.
+
+## Contract Discovery
+
+- Specify discovery only: exact sources/tools to inspect, evidence to collect, decision record to update, and issue fields/comments to update.
+- Confirm the API surface, auth/secret source, license or terms constraints, acquisition path, deterministic fixture strategy, live-validation prerequisite, and rejected acquisition paths that matter to later implementation.
+- Do not include downstream implementation slices while material external behavior remains unconfirmed.
+
+## Revision
+
+- Reconcile the entire existing spec against new authority and current repository evidence.
+- Preserve still-valid completed `[x]` items exactly.
+- Reopen invalid completed items to `[ ]` and add a short `Revision Note:` with evidence.
+- Never silently delete progress or defect history.
+- Mark the spec blocked when completed history or its contract ledger cannot be trusted.

package/internal-workflow/skills/implementation-spec-maker/references/spec-template.md

@@ -0,0 +1,146 @@
+# Implementation Spec Template
+
+Use the base template for every spec. Add conditional blocks only when their trigger applies, and remove every instruction or placeholder before review.
+
+## Base Template
+
+```markdown
+---
+title: "<title>"
+created_at: "<ISO timestamp>"
+source_type: "plan | issue | contract-discovery | revised-spec"
+source_plan: "<absolute path or None>"
+source_issues:
+  - "<URL/reference or None>"
+status: "draft | ready | blocked"
+execution_model: "single-agent | multi-agent"
+spec_mode: "compact | full"
+implementation_size: "small | medium | large"
+expected_repositories: <positive integer>
+review_profile: "simple | medium | high"
+review_reasons:
+  - "<signal: evidence>"
+review_outcome: "Pending"
+review_verdict: "Not run"
+review_coverage: "Not reviewed"
+review_passes: "0"
+---
+
+## 1. Execution Context
+- **Goal:** <one observable outcome>
+- **Source Material:** <exact references>
+- **Approved Scope:** <strict allowed work>
+- **Out of Scope:** <explicit exclusions or None>
+- **Minimum Solution:** <direct path through existing owners and public seams>
+- **Added Complexity:** None | <repeat one entry per mechanism: `<mechanism>` — required for `<invariant or evidenced failure>`; without it `<concrete breakage>`>
+- **Primary Risk:** <main correctness or coordination risk>
+
+## 2. Preconditions And Evidence
+- **Required Services / Env / Fixtures:** <exact requirements or None>
+- **Blocking Unknowns:** <exact unknowns when blocked, otherwise None>
+- **Confirmed Targets:** <minimal evidence-backed paths and symbols>
+- **Confirmed Commands:** <exact commands>
+- **Protected Paths / Rejected Approaches:** <items or None>
+- **Source of Truth:** <existing owner whenever behavior/data can drift; otherwise omit>
+- **New Boundaries:** <only when ownership or a public seam changes; otherwise omit>
+
+## 3. Execution Slices
+
+### Slice 1 — <narrow end-to-end behavior>
+- [ ] **Test/Proof First:** <failing behavior test or exact observable proof>
+- [ ] **Target:** `<exact/path:symbol>` — <specific action>
+- [ ] **Validation:** <target-level check>
+- [ ] **Exit Gate:** <command or proof that the slice works end-to-end>
+
+<repeat only for independently verifiable behavior slices>
+
+## 4. Validation And Done Criteria
+- [ ] **Lint/Format:** <exact command or Not applicable with reason>
+- [ ] **Typecheck/Build:** <exact command or Not applicable with reason>
+- [ ] **Tests:** <exact command or Not applicable with reason>
+- [ ] **Architecture Check:** <exact command or Not applicable with reason>
+- [ ] **Live/Manual Proof:** <exact flow or Not applicable with reason>
+- [ ] **Behavior Proof:** <observable acceptance proof>
+- [ ] **Reconciliation:** every unchecked item is unfinished, blocked with evidence, or intentionally not applicable.
+- [ ] **Final Handoff Requirements:** <high only: extended `$spec-implementer` Final Risk Handoff plus task-specific deviations; omit for ordinary medium work>
+```
+
+## Conditional Blocks
+
+### Contract Test Ledger
+
+Add for contract-heavy behavior using the shared Contract Test Ledger referenced by `SKILL.md`. Keep one row per material invariant and place it before execution slices.
+
+### Review Checkpoint And Focus
+
+Add a checkpoint only when the risky target becomes stable before later slices. Otherwise put this compact block in final review coverage:
+
+```markdown
+## Review Focus
+- **Mandatory Lenses:** <applicable lenses>
+- **Targeted Recipes:** <applicable recipes or None>
+- **Bug Classes:** <concrete failures to hunt>
+```
+
+### Risk Controls
+
+Add in `full` mode only for applicable ambiguity:
+
+```markdown
+## Risk Controls
+- **Source of Truth:** <owner>
+- **Safety / Contract / State Constraints:** <only applicable constraints>
+- **Forbidden Scope:** <tempting but rejected paths>
+- **Review Timing:** <stable early checkpoint or concrete final-review focus>
+```
+
+### Write Scope Summary
+
+Add for multi-agent work, generated artifacts, broad runtime changes, or when phase targets do not make the write set auditable.
+
+```markdown
+## Write Scope Summary
+- `<path>` — <Create | Update | Delete>; <responsibility>
+```
+
+### Integrator Coordination Contract
+
+Require only when `execution_model: "multi-agent"`:
+
+```markdown
+## Integrator Coordination Contract
+| Agent | Exclusive Write Scope | Handoff | Merge Phase |
+| --- | --- | --- | --- |
+| <agent> | <disjoint paths> | <artifact> | <order> |
+
+- **Integrator Owner:** <owner>
+- **Forbidden Overlap:** <paths/contracts>
+- **Final Duties:** <integration, validation, reconciliation>
+```
+
+### Halt Conditions
+
+Add only when the common contradiction/guessing stop rule is insufficient. Use 3–6 task-specific conditions.
+
+### Defect Closure Notes
+
+Add only when review returns defects:
+
+```markdown
+## Defect Closure Notes
+- **Review Summary:** <pass counts and coverage>
+- **Verified Defects:** <stable IDs or None>
+- **Accepted Risks:** <stable IDs, authority, and reason or None>
+- **Open Defects:** <stable IDs or None>
+```
+
+## Terminal Review Metadata
+
+Replace the temporary frontmatter values after the owner review loop returns a real terminal outcome:
+
+```yaml
+review_outcome: "Approved | Blocked | Waived"
+review_verdict: "Approved | Needs Work | Rejected | Not run"
+review_coverage: "<covered lenses or Not reviewed>"
+review_passes: "<total; full/closure/fresh counts>"
+```

package/internal-workflow/skills/implementation-spec-review/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: "implementation-spec-review"
+description: "Review compact or full implementation specs for deterministic executability, proportional scope, validation coverage, safety, and zero-guess execution before coding starts."
+---
+
+# Implementation Spec Review
+
+Decide whether a saved implementation spec can be executed safely without
+guessing. Review execution quality, not the product idea. Do not rewrite the
+spec unless explicitly asked.
+
+Read:
+
+- `references/review-loop.md` when called by `$implementation-spec-maker`;
+- `../../docs/agents/confidence-rubric.md` for defect confidence;
+- `../../docs/agents/contract-test-ledger.md` only when the spec changes a
+  material behavior contract.
+
+## Independent Dimensions
+
+Keep these classifications independent:
+
+- `spec_mode: compact | full` — document/coordination density;
+- `implementation_size: small | medium | large` — delivery shape;
+- `review_profile: simple | medium | high` — consequence and uncertainty;
+- `expected_repositories` — approved repository count.
+
+Compact may describe broad or high-risk work when ownership, sequencing, and
+proof remain deterministic. Full is justified only when concrete coordination,
+contract, safety, ownership, or validation ambiguity cannot fit clearly in the
+compact form. Never request full-mode tables or ceremony merely from size or
+risk labels.
+
+## Adapter Contract
+
+When called by the maker, use the mode and lenses supplied by
+`references/review-loop.md`, reuse supplied defect IDs, and return actual
+coverage. A reviewer child executes this Adapter inline and never spawns a
+grandchild. If root receives a direct review request, it launches the
+profile-selected reviewer instead of self-reviewing.
+
+A standalone reviewer performs one bounded Full over all applicable lenses and
+returns only `Approved | Needs Work | Rejected`; it does not invent owner state
+or claim Closure.
+
+## Review Lenses
+
+Scale depth to the profile and inspect only applicable lenses:
+
+- **Determinism and evidence:** execution-critical paths, symbols, commands,
+  contracts, fixtures, and claims are confirmed rather than invented.
+- **Scope and minimum solution:** the spec preserves approved scope, uses
+  existing owners/seams, and ties every added mechanism to a requirement or
+  concrete failure path.
+- **Sequencing and ownership:** phases are safe, sources of truth are explicit
+  where drift is possible, and multi-agent write scopes are disjoint.
+- **Validation:** each behavior has an observable proof; contract-risk work maps
+  each material invariant to its first failing test or exact blocked proof.
+- **Preconditions and stop conditions:** required services, data, env, fixtures,
+  and destructive/sensitive constraints are explicit when applicable.
+- **Review focus:** ordinary work relies on one final review; only an explicit
+  stable high-risk slice gets an intermediate checkpoint.
+- **Revision integrity:** current content matches its authority and preserves
+  still-valid completed work.
+- **Completion:** another agent can tell what to do, what proves success, when
+  to stop, and what remains blocked.
+
+## Proportional Expectations
+
+Approve a compact spec when targets, ordered work, observable proof, and stop
+conditions are exact enough for the task. Do not require source-of-truth tables,
+file matrices, long halt lists, multi-agent contracts, or defect sections when
+no concrete ambiguity needs them.
+
+A lean full spec normally adds only applicable `Risk Controls`, exact phase
+targets/proof, and—when needed—write-scope or integrator coordination. Missing
+ownership, validation, safety, or handoff detail is a defect; missing formatting
+ceremony is not.
+
+Prefer deleting or narrowing an unsafe proposal before adding flags, telemetry,
+fallbacks, compatibility paths, or rollout machinery. Optional improvements
+remain optional unless source authority approves them.
+
+## Defects And Decision
+
+- **Blocker:** unsafe or impossible to execute as written.
+- **Execution risk:** executable but likely to drift or require rework.
+- **Improvement:** useful but not required for safe execution.
+
+Reject exact-looking but ungrounded paths/contracts, unresolved placeholders or
+alternative commands, validation that cannot prove the intended behavior,
+overlapping multi-agent ownership, missing material safety constraints, or any
+step that requires invention.
+
+Use:
+
+- `Approved` when the current spec is deterministic, bounded, proportional, and
+  executable without guessing;
+- `Needs Work` for repairable ambiguity, weak proof, or excess ceremony;
+- `Rejected` when execution would be unsafe or depend on invented decisions.
+
+## Output
+
+Answer in Russian and keep technical terms in English. Return:
+
+1. `Вердикт` and one-sentence reason.
+2. `Режим и покрытие` with Full/Closure and actual lenses.
+3. Short `Determinism / Evidence / Validation / Safety` scores from 0 to 2.
+4. Evidence-backed defects first, with supplied ID or `NEW-<LENS>-NN`, class,
+   confidence, failure, evidence, smallest repair, and affected section.
+5. Exact changes needed before execution, or `Ничего`.
+6. Only genuinely blocking questions, or `Нет`.
+
+Do not repeat the spec, propose broad redesign, or turn optional cleanup into a
+mandatory gate.

package/internal-workflow/skills/implementation-spec-review/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Implementation Spec Review"
+  short_description: "Review one implementation spec"
+  default_prompt: "Review the supplied spec through the assigned package-owned operation and return its exact JSON report."
+policy:
+  allow_implicit_invocation: false

package/internal-workflow/skills/implementation-spec-review/evals/evals.json

@@ -0,0 +1,24 @@
+{
+  "schema_version": 1,
+  "skill": "implementation-spec-review",
+  "cases": [
+    {
+      "id": "artifact-profile-by-consequence",
+      "prompt": "Review one broad but reversible spec and one narrow spec with irreversible data impact and unclear recovery ownership.",
+      "expected": ["broad reversible may remain medium", "narrow dangerous uncertain spec is high"],
+      "forbidden": ["classify from file count or spec mode"]
+    },
+    {
+      "id": "artifact-scope-conservation",
+      "prompt": "A review can repair the spec either by deleting an unnecessary mechanism or by adding flags, telemetry, and fallback infrastructure.",
+      "expected": ["prefer the smallest scope-preserving repair"],
+      "forbidden": ["add unapproved operational machinery"]
+    },
+    {
+      "id": "artifact-approval-invalidation",
+      "prompt": "An approved spec receives a substantive execution change after review.",
+      "expected": ["invalidate approval for the changed revision", "review only invalidated coverage"],
+      "forbidden": ["execute under stale approval", "restart unrelated coverage"]
+    }
+  ]
+}

package/internal-workflow/skills/implementation-spec-review/references/review-loop.md

@@ -0,0 +1,93 @@
+# Implementation Spec Review Loop
+
+This reference owns review orchestration for specs created by
+`implementation-spec-maker`. Read it when the maker requests artifact review.
+The reviewer skill remains the Adapter; the shared review mechanics live in
+`../../../docs/agents/review-protocol.md`.
+
+## Contract
+
+Input:
+
+- saved spec and pinned revision;
+- source authority and approved decisions;
+- evidence needed to verify execution claims;
+- optional user-raised review profile.
+
+Output:
+
+- `outcome: Approved | Blocked | Waived`;
+- `adapter_verdict: Approved | Needs Work | Rejected | Not run`;
+- `review_profile: simple | medium | high` and evidence-backed reasons;
+- mandatory-lens coverage and unresolved defects.
+
+The Adapter returns only its verdict. The root maps preflight, convergence, and
+waiver state to the artifact outcome.
+
+## Preflight And Profile
+
+Before launching a reviewer, confirm source authority, approved scope, current
+spec revision, and mandatory external evidence. Save a useful blocked spec when
+a product or contract decision is missing; do not launch review to discover a
+known authority gap.
+
+`medium` is the default. Use:
+
+- `simple` for one narrow owner with direct proof and no material uncertainty;
+- `medium` for all ordinary specs, including multi-file, API, persistence, or
+  stateful work with clear ownership and bounded proof;
+- `high` only when a sensitive mechanism has both a material failure
+  consequence and an uncertainty amplifier such as unclear ownership,
+  cross-trust effects, non-local recovery, or an unproven external contract.
+
+File count and implementation size never select `high`. The user may raise but
+not lower an evidence-backed profile.
+
+## Scope And Capsule
+
+Review the smallest approved solution. Risk may strengthen proof but does not
+authorize flags, telemetry, compatibility paths, generic fallbacks, or rollout
+machinery unless the source or a concrete failure requires them.
+
+Give each reviewer a bounded capsule containing the current spec, authority,
+approved scope, evidence, review question, assigned lenses, and current defect
+records. For Closure also include the repaired sections and affected contracts.
+Do not pass raw parent history or unrelated inventories.
+
+## Topology
+
+- `simple`: one `reviewer_fast`, one bounded Full.
+- `medium`: one `reviewer_standard`, one bounded Full.
+- `high`: two parallel `reviewer_deep` sessions with disjoint primary lenses:
+  Architecture/Execution and Failure/Contracts.
+
+Root launches and aggregates reviewers. A reviewer child runs the
+`implementation-spec-review` Adapter inline and never spawns another reviewer.
+Reuse valid coverage for the same revision and question.
+
+After one consolidated repair, coordinator verification is enough for ordinary
+medium/low findings. Use shared-protocol Closure only for critical/high defects,
+protected trust/data/concurrency/shared-contract impact, or invalidated
+mandatory coverage. A substantive rewrite gets a new Full only when it
+invalidates existing mandatory lenses.
+
+## Approval
+
+Return `Approved` only when the current saved revision matches source authority,
+mandatory lenses are covered, and every blocking defect is verified. Any
+substantive edit invalidates approval; lifecycle metadata alone does not.
+
+Return `Blocked` when authority/evidence is missing, repair needs a product or
+ownership decision, no substantive repair exists, or shared no-progress rules
+apply. Return `Waived` only after explicit user instruction and keep skipped
+coverage visible; an open blocker still maps the artifact to `Blocked`.
+
+Map outcomes to spec status:
+
+- `Approved` -> `ready`;
+- `Blocked` -> `blocked`;
+- eligible `Waived` -> `ready` with visible waiver metadata.
+
+Report profile, outcome, Adapter verdict, mandatory coverage, verified/open
+defects, and skipped checks. Do not report counters or session history for a
+normal one-review flow.