lgtm-specs 0.0.7 → 0.0.8

package/AGENTS.md

@@ -20,7 +20,7 @@ bun run check
 What this runs:
 
 ```bash
-# Validation (graph structure, indexing, capability registry, VERSION sync)
+# Validation (graph structure, indexing, role contracts, VERSION sync)
 bun run validate
 # or:
 python3 scripts/validate_specs.py
@@ -113,6 +113,8 @@ Tags and writing:
 Indexing:
 
 - Every directory with content MUST have a `README.md` indexing its files.
+- Exception: role prompt-chunk directories (`agents/roles/<role>/prompts/<profile>/`) may contain prompt templates
+  without a profile-local `README.md` when indexed by `agents/roles/<role>/README.md`.
 - Any new file must be added to the parent directory index `README.md`.
 
 ### 2.2 Agent Specs (`agents/**`)
@@ -120,12 +122,12 @@ Indexing:
 Contracts (external tools parse these; see `integrate/README.md`):
 
 - Do not remove placeholders like `{{injected_rules}}` / `{{indices}}`.
-- Modes require: `<Meta>`, `<Role>`, `<Workflow>`.
-- Roles require: `<Meta>`, `<Role>`, `<Input>`, `<Objective>`, `<OutputFormat>`, `<Workflow>`.
-- `<Meta>` key lines must start at column 1; role specs must include `Capability: <id>`.
-- `Capability` must exist as a key in `models/registry.yaml`.
-
-Valid capability IDs: `reasoning`, `coding`, `data`, `fast`, `security`, `docs`, `general`.
+- Modes are pure Markdown specs (no role prompt section tags) and compose flows via `{{flow_*}}`.
+- Roles are directory contracts: `agents/roles/<role>/role.yaml` + profile-scoped
+  `agents/roles/<role>/<profile>.md` (or `prompts/<profile>/*.md`) templates.
+- Prompt templates are plain Markdown (no role prompt section tags).
+- Role contracts must include `model_tier: critical|standard|economy`, profile `compose`/`allowed_injections`, and
+  optional profile `rule_render`/`rule_scope` per `integrate/agent_schema.yaml`.
 
 ### 2.3 Python Tooling (`scripts/**/*.py`)
 

package/README.md

@@ -31,7 +31,9 @@ Start here:
 ## Workflows
 
 LGTM runs as operating modes that orchestrate a specialist team (Lead, Explorer, Counsel, Planner, Implementer,
-Reviewers).
+Reviewer, Investigator).
+
+Modes are thin entrypoints composed from reusable flow contracts under `agents/flows/**`.
 
 Modes:
 
@@ -41,12 +43,17 @@ Modes:
 
 Core roles:
 
-- 🧠 [Lead](agents/roles/lead.md): orchestrates and arbitrates.
-- 🗺️ [Explorer](agents/roles/explorer.md): maps the target repo.
-- ⚖️ [Counsel](agents/roles/counsel.md): selects minimal relevant rule paths.
-- 📐 [Planner](agents/roles/planner.md): produces an execution/audit plan.
-- 🏗️ [Implementer](agents/roles/implementer.md): implements and produces proof.
-- 🔬 [Reviewers](agents/roles/reviewer/README.md): audit from specialized perspectives.
+- 🧠 [Lead (orchestrator profile)](agents/roles/lead/role.yaml): orchestrates workflows and synthesis.
+- 🧭 [Lead (arbitrator profile)](agents/roles/lead/role.yaml): arbitrates disputed findings.
+- 🗺️ [Explorer](agents/roles/explorer/role.yaml): maps the target repo.
+- ⚖️ [Counsel](agents/roles/counsel/role.yaml): selects minimal relevant rule paths.
+- 🗂️ [Planner](agents/roles/planner/role.yaml): owns plan-stage drafting, revisions, and planning decisions.
+- 🧱 [Implementer](agents/roles/implementer/role.yaml): owns build-stage implementation, remediation, and decisions.
+- 🛡️ [Reviewer (auditor + specialist lenses)](agents/roles/reviewer/README.md): runs panel gates,
+  report synthesis, and lens-based audits.
+- 🔎 [Investigator](agents/roles/investigator/role.yaml): owns investigation-stage decisions and fixed-slot worker
+  analysis.
+- 📚 [Librarian](agents/roles/librarian/role.yaml): optional external source lookup.
 
 Start here:
 
@@ -88,7 +95,11 @@ You are implementing integration for the LGTM specs repo (yyforyongyu/lgtm-specs
 Goal: wire this repo into a coding tool so it can run the LGTM agent workflows.
 
 Read and follow `integrate/README.md` exactly, including:
-- Parsing `agents/**/*.md` and honoring placeholders like `{{injected_rules}}`.
+- Parsing role contracts under `agents/roles/**/role.yaml` and composing role prompts from
+  profile-scoped templates under `agents/roles/**/<profile>.md` (or `agents/roles/**/prompts/<profile>/*.md`), plus
+  composing mode contracts from `agents/modes/*.md`:
+  - inject `Lead Stage Contract` to `lead/orchestrator`,
+  - compose `Workflow Contract (Runtime Reference)` from `agents/flows/**` for runtime routing/policy.
 - Running Counsel and enforcing its JSON output schema.
 - Hydrating rule paths into rule content and injecting role-appropriate subsets per reviewer.
 - Resolving models using `models/registry.yaml` in list order (preference order) with deterministic availability checks.

package/VERSION

@@ -1 +1 @@
-0.0.7
+0.0.8

package/agents/README.md

@@ -1,90 +1,16 @@
 # Agent Workforce
 
-This directory defines the LGTM agent contracts:
+This directory contains LGTM agent specifications: invocable role contracts plus non-invocable mode/flow orchestration
+specs. Treat this README as a top-level signpost and use subfolder indexes for details.
 
-- Modes (workflows): `@Build`, `@Hack`, `@Review`
-- Roles (workers): `@Lead`, `@Planner`, `@Counsel`, `@Implementer`, `@Explorer`, `@Librarian`, `@Reviewer*`
+Current architecture uses a stage-owner model: `lead/orchestrator` delegates to stage-owner profiles
+(`planner/init`, `implementer/init`, `reviewer/auditor`, `investigator/init`) while runtime owns transition mechanics.
+For implementation contracts and routing matrices, start at `integrate/README.md`.
 
-Files under `agents/` are runtime-consumed contracts optimized for parsing and prompt injection.
-For a human-facing overview, see [Agent Architecture](../docs/agent_architecture.md).
+## Index
 
-## Operating Modes
-
-- [@Build](modes/build.md): Production engineering; strict planning + verification + consensus gates.
-- [@Hack](modes/hack.md): Rapid prototyping; lighter gates; produce a draft branch/PR.
-- [@Review](modes/review.md): Read-only audit; produce an evidence-backed report.
-
-## Roles
-
-- [@Lead](roles/lead.md): Orchestrator and arbitrator.
-- [@Planner](roles/planner.md): Execution/audit plan author.
-- [@Counsel](roles/counsel.md): Rule/policy selection (paths + reasons).
-- [@Explorer](roles/explorer.md): Codebase mapping and policy discovery (Context Map).
-- [@Implementer](roles/implementer.md): Implementation + required proof (inner loop).
-- [@Librarian](roles/librarian.md): External documentation/spec research with citations.
-
-## Review Panel
-
-- [@Reviewer](roles/reviewer/README.md): Panel index (specialists).
-- [@Plan-Reviewer](roles/reviewer/plan.md): Plan critique (feasibility/alignment).
-- [@Reviewer-Lite](roles/reviewer/lite.md): Atomic diff sanity gate (fast).
-- [@Reviewer-Logic](roles/reviewer/logic.md): Correctness audit.
-- [@Reviewer-Quality](roles/reviewer/quality.md): Maintainability + docs audit.
-- [@Reviewer-Test](roles/reviewer/test.md): Test coverage + rigor audit.
-- [@Reviewer-Security](roles/reviewer/security.md): Trust boundary + safety audit.
-- [@Reviewer-Performance](roles/reviewer/performance.md): Efficiency + resource usage audit.
-
-## Templates (For Maintainers)
-
-- Role template: [templates/role.md](templates/role.md)
-- Mode template: [templates/mode.md](templates/mode.md)
-
-## Directory Structure
-
-```text
-agents/
-├── modes/
-│   ├── README.md
-│   ├── build.md
-│   ├── hack.md
-│   ├── review.md
-│   ├── build/
-│   │   ├── README.md
-│   │   ├── plan.md
-│   │   ├── code.md
-│   │   ├── panel.md
-│   │   ├── panel_consensus.md
-│   │   └── delivery.md
-│   ├── hack/
-│   │   ├── README.md
-│   │   ├── plan.md
-│   │   ├── code.md
-│   │   └── delivery.md
-│   └── review/
-│       ├── README.md
-│       ├── plan.md
-│       ├── audit.md
-│       └── synthesize.md
-├── templates/
-│   ├── README.md
-│   ├── role.md
-│   └── mode.md
-└── roles/
-    ├── lead.md
-    ├── planner.md
-    ├── counsel.md
-    ├── explorer.md
-    ├── implementer.md
-    ├── librarian.md
-    └── reviewer/
-        ├── BASE.md
-        ├── OUTPUT_FORMAT.md
-        ├── README.md
-        ├── plan.md
-        ├── lite.md
-        ├── logic.md
-        ├── quality.md
-        ├── security.md
-        ├── performance.md
-        └── test.md
-```
+- [modes/README.md](modes/README.md)
+- [flows/README.md](flows/README.md)
+- [roles/README.md](roles/README.md)
+- [templates/README.md](templates/README.md)
+- [../integrate/README.md](../integrate/README.md)

package/agents/flows/README.md

@@ -0,0 +1,19 @@
+# Reusable Flows
+
+Non-invocable orchestration contracts composed by mode specs.
+
+Flow contracts describe lead-visible stage transitions only (handoff -> expected outcome -> next decision).
+Role behavior details and runtime mechanics stay authoritative in `agents/roles/**` and `integrate/**`.
+
+Placeholder contract:
+
+- `{{flow_<family>_<variant>}}` -> `agents/flows/<family>/<variant>.md`
+- families: `plan`, `build`, `audit`, `investigate`
+
+## Index
+
+- [plan/README.md](plan/README.md): planning flow contracts
+- [build/README.md](build/README.md): implementation and delivery flow contracts
+- [audit/README.md](audit/README.md): review-panel and synthesis flow contracts
+- [investigate/README.md](investigate/README.md): shared investigation hook contracts
+- [../roles/README.md](../roles/README.md): role/profile contract index

package/agents/flows/audit/README.md

@@ -0,0 +1,16 @@
+# Audit Flow Contracts
+
+Panel/synthesis contracts keyed by `{{flow_audit_<variant>}}`.
+
+These flows define lead-visible audit-stage handoffs to [@Reviewer](/agents/roles/reviewer/role.yaml),
+plus synthesis/escalation decisions by [@Lead](/agents/roles/lead/role.yaml).
+
+## Index
+
+- [build_panel.md](build_panel.md): build-mode full panel barrier
+- [build_consensus.md](build_consensus.md): build-mode resolve/remediate consensus loop
+- [review_panel.md](review_panel.md): review-mode panel execution
+- [review_synthesize.md](review_synthesize.md): review-mode synthesis/reporting
+- [/agents/roles/reviewer/README.md](/agents/roles/reviewer/README.md): reviewer role profiles
+- [/agents/roles/implementer/README.md](/agents/roles/implementer/README.md): implementer role contract
+- [/agents/roles/planner/README.md](/agents/roles/planner/README.md): planner role contract

package/agents/flows/audit/build_consensus.md

@@ -0,0 +1,9 @@
+## Panel Consensus (Build)
+
+Runtime delta over mode `Lead Stage Contract`:
+
+1. Interpret each audit-stage outcome into remediation dispatch, arbitration dispatch, or gate-close action.
+2. On remediation action, route to [@Implementer](/agents/roles/implementer/role.yaml) (`init`) then schedule the next
+   panel-audit pass.
+3. On dispute action, route to [@Lead](/agents/roles/lead/role.yaml) (`arbitrator`) then return to panel audit.
+4. Close gate only on explicit approval, allowed override, or terminal abort outcome.

package/agents/flows/audit/build_panel.md

@@ -0,0 +1,7 @@
+## Panel Audit (Build)
+
+Runtime delta over mode `Lead Stage Contract`:
+
+1. Enforce panel round barrier before accepting audit-stage outcome payloads.
+2. Persist panel artifacts and accepted audit-stage decision payload for consensus routing.
+3. Carry scoped diff/context evidence refs forward for remediation and re-audit continuity.

package/agents/flows/audit/review_panel.md

@@ -0,0 +1,7 @@
+## Panel Audit (Review)
+
+Runtime delta over mode `Lead Stage Contract`:
+
+1. Include approved audit-plan refs in reviewer/auditor packets when present.
+2. Enforce audit round barrier and persist panel artifacts before synthesis transition.
+3. If stage outcome escalates disputed findings, schedule arbitration before final synthesis.

package/agents/flows/audit/review_synthesize.md

@@ -0,0 +1,8 @@
+## Synthesize & Report (Review)
+
+Runtime delta over mode `Lead Stage Contract`:
+
+1. Synthesis consumes persisted panel artifacts and finding-provenance mappings.
+2. Clarification pass is one bounded follow-up turn through [@Reviewer](/agents/roles/reviewer/role.yaml)
+   (`auditor`) before finalization.
+3. Final report output must include severity grouping, evidence references, and residual-risk notes.

package/agents/flows/build/README.md

@@ -0,0 +1,15 @@
+# Build Flow Contracts
+
+Implementation/delivery contracts keyed by `{{flow_build_<variant>}}`.
+
+These flows define lead-visible build-stage handoffs to [@Implementer](/agents/roles/implementer/role.yaml),
+escalation paths, and delivery closure expectations.
+
+## Index
+
+- [execute_high_assurance.md](execute_high_assurance.md): `@Build` execution loop
+- [execute_fast.md](execute_fast.md): `@Hack` fast execution loop
+- [delivery_production.md](delivery_production.md): production delivery closure
+- [delivery_prototype.md](delivery_prototype.md): prototype delivery closure
+- [/agents/roles/implementer/README.md](/agents/roles/implementer/README.md): implementer role contract
+- [/agents/roles/planner/README.md](/agents/roles/planner/README.md): planner role contract

package/agents/flows/build/delivery_production.md

@@ -0,0 +1,7 @@
+## Delivery
+
+Runtime delta over mode `Lead Stage Contract`:
+
+1. Assemble delivery evidence from final stage outcomes, verification results, and approved/overridden findings.
+2. Finalize output only when gate-approval/allowed-override conditions are satisfied.
+3. If unresolved required rejects remain without allowed override, emit blocked status (not success).

package/agents/flows/build/delivery_prototype.md

@@ -0,0 +1,7 @@
+## Delivery
+
+Runtime delta over mode `Lead Stage Contract`:
+
+1. Finalize as draft/experimental output and label it `Prototype / Not Production Ready`.
+2. Prefer explicit prototype signaling in branch/PR metadata (for example `[Hack]` / `[Prototype]`).
+3. Production graduation path requires rerun under `@Build` rather than silent direct merge.

package/agents/flows/build/execute_fast.md

@@ -0,0 +1,9 @@
+## Execute (Fast)
+
+Runtime delta over mode `Lead Stage Contract`:
+
+1. Execute as lightweight task loop with direct-task or planned-task entries.
+2. Permit immediate remediation chaining from accepted build-stage outcomes without planner re-entry,
+   unless scope repair is explicitly required.
+3. Persist each accepted build-stage outcome before next dispatch.
+4. Route escalations to [@Lead](/agents/roles/lead/role.yaml) (`arbitrator`) and stop on terminal outcomes.

package/agents/flows/build/execute_high_assurance.md

@@ -0,0 +1,9 @@
+## Execute (High Assurance)
+
+Runtime delta over mode `Lead Stage Contract`:
+
+1. Execute as per-task loop: one build-stage packet per approved plan step/remediation unit.
+2. Persist each accepted build-stage outcome before dispatching the next task/remediation unit.
+3. If escalation is emitted, route to [@Lead](/agents/roles/lead/role.yaml) (`arbitrator`) and block further dispatch
+   until arbitration outcome is recorded.
+4. Stop loop on terminal abort/escalation outcomes; otherwise continue until no open tasks remain.

package/agents/flows/investigate/README.md

@@ -0,0 +1,11 @@
+# Investigate Flow Contracts
+
+Shared investigation contracts keyed by `{{flow_investigate_<variant>}}`.
+
+Investigation stays stage-owner mediated: [@Investigator](/agents/roles/investigator/role.yaml) coordinates
+analysis runs and returns stage outcomes under runtime transition policy.
+
+## Index
+
+- [hooks.md](hooks.md): shared invocation/return constraints for investigation flow
+- [/agents/roles/investigator/README.md](/agents/roles/investigator/README.md): investigator role profiles

package/agents/flows/investigate/hooks.md

@@ -0,0 +1,10 @@
+## Investigation Hooks (Shared Contract)
+
+1. Treat investigation as analysis-only and stage-owner mediated.
+2. [@Investigator](/agents/roles/investigator/role.yaml) (`init`) owns worker dispatch, synthesis, and return/terminal
+   stage outcome decisions.
+3. [@Investigator](/agents/roles/investigator/role.yaml) (`worker`) outputs analysis only
+   (`findings/hypotheses/options`), never final compliance verdicts.
+4. Transition-edge IDs, worker-slot configuration, invocation-source policy, and auto-edge policy are runtime
+   contracts in
+   `/integrate/input_packets/README.md` and `/integrate/README.md`.

package/agents/flows/plan/README.md

@@ -0,0 +1,13 @@
+# Plan Flow Contracts
+
+Shared planning contracts keyed by `{{flow_plan_<variant>}}`.
+
+These flows keep [@Lead](/agents/roles/lead/role.yaml) at cross-stage control and define plan-stage
+handoff/outcome checkpoints via [@Planner](/agents/roles/planner/role.yaml).
+
+## Index
+
+- [build.md](build.md): high-assurance plan flow for `@Build`
+- [hack.md](hack.md): lightweight sketch flow for `@Hack`
+- [review.md](review.md): audit planning flow for `@Review`
+- [/agents/roles/planner/README.md](/agents/roles/planner/README.md): planner role contract

package/agents/flows/plan/build.md

@@ -0,0 +1,9 @@
+## Clarify & Plan (Build)
+
+Runtime delta over mode `Lead Stage Contract`:
+
+1. Plan sign-off gate is runtime-enforced before execution handoff.
+2. Waiver path requires persisted waiver rationale/residual-risk notes before routing to
+   [@Implementer](/agents/roles/implementer/role.yaml) (`init`).
+3. Planner outcomes map to transitions: `approve_plan -> execution`, `revise_plan -> planner continuation`,
+   `abort -> terminal`, escalation path -> [@Lead](/agents/roles/lead/role.yaml) (`arbitrator`).

package/agents/flows/plan/hack.md

@@ -0,0 +1,13 @@
+## Sketch (Hack)
+
+Runtime delta over mode `Lead Stage Contract`:
+
+1. If critical-path scope is detected and the user still keeps `@Hack`, persist explicit risk acknowledgement.
+2. Planning remains optional at runtime: trivial scope can route directly to
+   [@Implementer](/agents/roles/implementer/role.yaml) (`init`), planned scope routes to
+   [@Planner](/agents/roles/planner/role.yaml) (`init`).
+3. Planned-path outcomes map to transitions: `approve_plan -> implementer/init`,
+   `revise_plan -> planner continuation`, `abort -> terminal`, escalation path ->
+   [@Lead](/agents/roles/lead/role.yaml) (`arbitrator`).
+4. If stricter compliance was requested, persist selected [@Counsel](/agents/roles/counsel/role.yaml)
+   rule-set references in runtime artifacts.

package/agents/flows/plan/review.md

@@ -0,0 +1,10 @@
+## Map & Plan (Review)
+
+Runtime delta over mode `Lead Stage Contract`:
+
+1. Runtime triage gate decides trivial fast-path (direct audit) vs planned path.
+2. Planned-path outcomes map to transitions: `approve_plan -> reviewer/auditor`,
+   `revise_plan -> planner continuation`, `abort -> terminal`, escalation path ->
+   [@Lead](/agents/roles/lead/role.yaml) (`arbitrator`).
+3. When routing to [@Reviewer](/agents/roles/reviewer/role.yaml) (`auditor`), attach approved audit-plan
+   references when available.

package/agents/modes/README.md

@@ -2,7 +2,11 @@
 
 Mode specs define the canonical orchestration workflows for the LGTM workforce.
 
-Each mode may compose its `<Workflow>` from non-invocable fragments stored under `agents/modes/<mode>/`.
+Each mode defines:
+
+- `Lead Stage Contract`: compact lead-visible handoff/outcome map injected into `lead/orchestrator`.
+- `Workflow Contract (Runtime Reference)`: runtime sequencing reference composed from non-invocable
+  flow contracts under `agents/flows/**` using `{{flow_<family>_<variant>}}` placeholders.
 
 ## Index
 

package/agents/modes/build.md

@@ -1,10 +1,15 @@
 # Mode: @Build
 
-<Meta>
-Type: High-Assurance Engineering Workflow.
-Brain: Uses **[@Lead](../roles/lead.md)** for arbitration and orchestration decisions.
+## Type
 
-Trigger:
+High-Assurance Engineering Workflow.
+
+## Brain
+
+Uses **[@Lead](../roles/lead/role.yaml)** with profile `orchestrator` for orchestration and profile `arbitrator` for
+dispute rulings.
+
+## Trigger
 
 - New Feature implementation.
 - Refactoring critical paths (Auth, Payments, Cryptography).
@@ -13,52 +18,76 @@ Trigger:
 - "Production Ready" work.
 - (For rapid prototypes, use **[@Hack](hack.md)** instead).
 
-SafetyProfile:
+## Safety Profile
 
 - Strict gates (plan sign-off, verification, and panel review).
 - Overrides allowed only with explicit risk rationale.
 
-Team:
+## Coordination Model
+
+- `@Lead` (`orchestrator`) owns cross-stage decomposition, stage-owner handoff, and final synthesis.
+- Stage owners (`planner|implementer|reviewer/auditor|investigator`) own stage-local loops and decision payloads.
+- `@Lead` (`arbitrator`) handles disputed findings/plan decisions escalated from stage loops.
+
+## Delegation Boundary
+
+- `@Build` routes only across stage owners (`planner/init`, `implementer/init`, `reviewer/auditor`,
+  `investigator/init`).
+- Stage-owner internals (worker choice, panel composition, remediation loops) stay in role contracts and runtime
+  packet policy.
 
-- **Manager**: **[@Lead](../roles/lead.md)**.
-- **Planner**: **[@Planner](../roles/planner.md)**.
-- **Compliance**: **[@Counsel](../roles/counsel.md)**.
-- **Researcher**: **[@Librarian](../roles/librarian.md)** (Optional).
-- **Maker**: **[@Implementer](../roles/implementer.md)**.
-- **Cartographer**: **[@Explorer](../roles/explorer.md)**.
-- **Plan Reviewer**: **[@Plan-Reviewer](../roles/reviewer/plan.md)**.
-- **Micro-Critic**: **[@Reviewer-Lite](../roles/reviewer/lite.md)**.
-- **Critics**: **[@Reviewer](../roles/reviewer/README.md)** (Panel).
-</Meta>
+## Goal
 
-<Role>
-**Goal**: Ship Features, Refactors, and Production Code.
-</Role>
+Ship Features, Refactors, and Production Code.
+
+## Lead Stage Contract
+
+1. Scope with `@Explorer`; route rule selection/application through `@Counsel` when needed.
+2. Delegate planning to `planner/init`; expect `approve_plan|revise_plan|abort|escalate` stage outcomes.
+3. Require explicit user sign-off on approved plans unless the user explicitly waives review.
+4. Delegate each approved task/remediation unit to `implementer/init` and consume build-stage outcomes.
+5. Delegate the audit gate to `reviewer/auditor` and consume audit-stage outcomes.
+6. When audit returns actionable findings, route remediation to `implementer/init` and then re-enter audit.
+7. Route disputed findings/decisions to `lead/arbitrator` only when escalated by a stage outcome.
+8. Invoke `investigator/init` only when a stage outcome requests investigation under runtime transition policy.
+9. Finalize only on audit gate approval, explicit allowed override, or terminal abort.
+
+## Output Contract
 
-<OutputFormat>
 **Result**: Markdown with:
 
 - **PR/Commit**: PR URL or commit hash.
 - **Verification**: Commands run and outcomes.
 - **Notes**: Overrides/arbitrations (if any) and residual risk.
 
-</OutputFormat>
+## Workflow Contract (Runtime Reference)
+
+Runtime-owned sequencing reference for packet routing and transition policy.
+This section is not injected as lead model context.
+
+Follow these flow contracts in order; each role emits only role-local decisions/artifacts.
+
+{{flow_plan_build}}
+{{flow_build_execute_high_assurance}}
+{{flow_audit_build_panel}}
+{{flow_audit_build_consensus}}
+{{flow_investigate_hooks}}
+{{flow_build_delivery_production}}
 
-<Workflow>
-{{flow_build_plan}}
-{{flow_build_code}}
-{{flow_build_panel}}
-{{flow_build_panel_consensus}}
-{{flow_build_delivery}}
+## Constraints
 
-</Workflow>
+Mode-level constraints for lead and stage owners:
 
-<Constraints>
-**Hard Blocks**:
-- [ ] Do not proceed to Phase 2 until the Plan is explicitly approved by the user.
-- [ ] Every code-producing `@Implementer` task MUST include explicit `Files` and `Verification` (from the Plan step or
-      from `@Lead` when dispatching remediation tasks). If either is missing, route to `@Planner` to repair/derive.
-      - Assessment-only Tasks (triage/disposition only) may omit `Files`/`Verification`.
+- [ ] Do not proceed to Phase 2 until the Plan is explicitly approved, unless the user explicitly waives review;
+      record waiver rationale before proceeding.
+- [ ] Every code-producing implementer task MUST include explicit `Files` and `Verification`
+      (from the plan step or from `@Lead`/implementer remediation dispatch).
+      If either is missing, route to `planner/init` for repair/derivation.
+- [ ] Assessment/disposition routing is owned by `implementer/init`; it may dispatch remediation without re-entering
+      a separate assessment role.
 - [ ] Never skip required verification.
+- [ ] Reviewer packets SHOULD default to scoped `Diff`/`Context Snippets`; use `Diff Command` only as fallback.
 - [ ] Unanimous approval is required by default; any override MUST include an explicit risk rationale.
-</Constraints>
+- [ ] Investigation flow is analysis-only. Implementation remains `implementer/init`; certification remains
+      reviewer/audit gates.
+- [ ] Keep this mode contract stable; invocation-specific details belong in per-step context.