lgtm-specs 0.0.6 → 0.0.7

package/README.md

@@ -30,7 +30,8 @@ Start here:
 
 ## Workflows
 
-LGTM runs as operating modes that orchestrate a specialist team (Lead, Explorer, Counsel, Planner, Builder, Reviewers).
+LGTM runs as operating modes that orchestrate a specialist team (Lead, Explorer, Counsel, Planner, Implementer,
+Reviewers).
 
 Modes:
 
@@ -44,7 +45,7 @@ Core roles:
 - 🗺️ [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.
-- 🏗️ [Builder](agents/roles/builder.md): implements and produces proof.
+- 🏗️ [Implementer](agents/roles/implementer.md): implements and produces proof.
 - 🔬 [Reviewers](agents/roles/reviewer/README.md): audit from specialized perspectives.
 
 Start here:

package/VERSION

@@ -1 +1 @@
-0.0.6
+0.0.7

package/agents/README.md

@@ -3,7 +3,7 @@
 This directory defines the LGTM agent contracts:
 
 - Modes (workflows): `@Build`, `@Hack`, `@Review`
-- Roles (workers): `@Lead`, `@Planner`, `@Counsel`, `@Builder`, `@Explorer`, `@Librarian`, `@Reviewer*`
+- Roles (workers): `@Lead`, `@Planner`, `@Counsel`, `@Implementer`, `@Explorer`, `@Librarian`, `@Reviewer*`
 
 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).
@@ -20,7 +20,7 @@ For a human-facing overview, see [Agent Architecture](../docs/agent_architecture
 - [@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).
-- [@Builder](roles/builder.md): Implementation + required proof (inner loop).
+- [@Implementer](roles/implementer.md): Implementation + required proof (inner loop).
 - [@Librarian](roles/librarian.md): External documentation/spec research with citations.
 
 ## Review Panel
@@ -47,7 +47,24 @@ agents/
 │   ├── README.md
 │   ├── build.md
 │   ├── hack.md
-│   └── review.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
@@ -57,7 +74,7 @@ agents/
     ├── planner.md
     ├── counsel.md
     ├── explorer.md
-    ├── builder.md
+    ├── implementer.md
     ├── librarian.md
     └── reviewer/
         ├── BASE.md

package/agents/modes/README.md

@@ -2,6 +2,8 @@
 
 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>/`.
+
 ## Index
 
 - [@Build](build.md): High-assurance engineering workflow.

package/agents/modes/build/README.md

@@ -0,0 +1,11 @@
+# @Build Fragments
+
+Non-invocable workflow fragments composed by `agents/modes/build.md` via `{{flow_build_*}}` placeholders.
+
+## Index
+
+- [plan.md](plan.md): Phase 1 (clarify, plan, sign-off)
+- [code.md](code.md): Phase 2 (execute + lite gate)
+- [panel.md](panel.md): Phase 3 (full panel barrier)
+- [panel_consensus.md](panel_consensus.md): Phase 3 (resolve + remediate loop)
+- [delivery.md](delivery.md): Phase 4 (squash + PR hygiene)

package/agents/modes/build/code.md

@@ -0,0 +1,43 @@
+## Execute (The Heavy Loop)
+
+For each Task (Plan step or remediation task):
+
+- Unit of work:
+  - The runtime MUST dispatch exactly one Task at a time.
+  - `@Implementer` MUST produce exactly one primary atomic commit for that Task.
+  - Review remediation MAY add fixup commit(s) targeting that primary commit (no additional Tasks).
+
+- Optimization (optional): tools MAY reuse the same `@Implementer` session/thread across Tasks to reduce context cost.
+  This does not change the unit of work: one invocation = one Task = one primary atomic commit.
+
+1.  **Build**: Call `@Implementer` with `(Task, Files, Requirements, Verification)`.
+    - _Constraint_: `Files` MUST be explicit in the Task definition (from the Plan step, or from `@Lead` when
+      dispatching remediation tasks). If missing, `@Lead` routes back to `@Planner` to repair/derive the file list.
+    - _Constraint_: Verification is mandatory. The proof level is defined per step (tests and/or other evidence).
+    - _Timeout_: 20 minutes per attempt (default; runtime may override).
+    - _On Timeout_: Re-assign once; if it times out again, treat as a reject and re-plan or abort.
+2.  **Micro-Audit**: Call `@Reviewer-Lite` on the diff.
+    - _Scope_: Fast sanity gate (obvious correctness breakage + basic style/tooling + commit message). Deep specialist
+      review happens in Phase 3.
+    - _Input_: Provide `User Request` + (`Diff` or `Diff Command`).
+      Include `Base Ref` whenever the runtime has git metadata (e.g., PR merge target).
+      Include `Head Ref` when available.
+      Include the atomic `Commit Message` when available.
+    - _Gate_: One Lite decision per primary atomic commit.
+      - No Lite roundtrip.
+      - Fixup remediation does not trigger a new Lite decision.
+    - _Timeout_: 5 minutes per attempt.
+    - _On Timeout_: Re-assign once. If it still times out, `@Lead` must either abort or proceed with an explicit risk
+      rationale (record in artifacts).
+    - _On Reject_: The runtime records the Lite artifact and the commit SHA. `@Implementer` MUST respond with a
+      disposition for every finding in that Lite artifact (single assessment packet) using `finding_id` (`1..N` in the
+      injected findings packet) and a short rationale for any dispute.
+      - If all findings are `accept`: `@Implementer` fixes using fixup commits (target the original commit):
+        `git commit --fixup <sha>`.
+      - If any finding is `dispute`: `@Lead` arbitrates at that commit (no Lite roundtrip).
+        - The runtime MUST batch all disputed findings for the commit into the minimum number of arbitration packets to
+          `@Lead`, subject to context limits.
+        - `@Lead` returns a decision per `finding_id` (`uphold` -> Implementer fixes using fixup commits; `override` ->
+          explicit risk rationale).
+      - After all findings are resolved (fixed or overridden), proceed after required verification passes (no Lite
+        re-review).

package/agents/modes/build/delivery.md

@@ -0,0 +1,9 @@
+## Delivery
+
+1.  **Squash (Runtime)**: `@Lead` instructs the runtime to consolidate history.
+    - Squash "fixup", "wip", or "address comments" commits into the relevant atomic feature commits.
+    - Ensure the final history reflects the _story_ of the change, not the _process_ of the review.
+2.  **Finalize**: Produce the Production-Ready PR.
+    - **PR Hygiene**: Title/body explain intent, risks, and verification evidence; mark Draft vs Ready explicitly.
+    - **Merge Plan**: State merge strategy expectations (squash vs merge-commit vs rebase) per repo policy.
+    - **Last Check**: Re-run required verification before marking ready.

package/agents/modes/build/panel.md

@@ -0,0 +1,30 @@
+## Panel Audit (The Jury)
+
+1.  **Verify**: Ensure required verification passes (including integration tests when required).
+2.  **Audit (Round 1: Full Panel)**: Call the **Full Review Panel** in parallel.
+    - Mandatory: [Logic](../../roles/reviewer/logic.md), [Quality](../../roles/reviewer/quality.md),
+      [Test](../../roles/reviewer/test.md).
+    - Conditional: [Security](../../roles/reviewer/security.md) when `@Lead` marks the work security-sensitive (or
+      `@Counsel` selected `#security` rules).
+    - Conditional: [Performance](../../roles/reviewer/performance.md) when `@Lead` marks the work perf-sensitive (or
+      `@Counsel` selected `#efficiency` rules).
+    - **Redundancy**: Run **N** independent invocations per Specialist role (default: 2; configurable).
+      - _Goal_: Reduce false negatives by auditing the same area multiple times.
+      - _Provider Diversity_: The runtime MUST attempt provider-first diversity across the redundant invocations.
+        - Provider is derived from the `model_id` prefix before `/`.
+        - For invocation 2+: exclude previously used providers; if not possible, exclude previously used `model_id`
+          values.
+        - If diversification is not possible, it MAY reuse the same model but MUST record this in artifacts.
+      - _Configuration (Optional)_: Tools MAY allow users to configure redundancy per role (e.g., `logic=2`,
+        `security=3`) and provider allow/deny lists.
+      - _Runtime Limits_: If the runtime cannot run the configured redundancy (resource/budget constraints), it MAY run
+        a single invocation per role but MUST:
+        - record `redundancy_mode=reduced` in artifacts, and
+        - surface the reduced-redundancy state in the final report.
+      - _Artifacts_: When any Specialist role is invoked redundantly (per-role invocation count > 1), the runtime MUST
+        record `redundancy_mode` and `diversity_result` on the panel timeline entry.
+    - _Input (each invocation)_: Provide `User Request` + (`Diff` or `Diff Command`).
+      Include `Base Ref` whenever the runtime has git metadata (e.g., PR merge target).
+      Include `Head Ref` when available.
+    - _Barrier_: The runtime MUST wait for all invoked reviewers to return (`lgtm` | `reject` | `timeout` | `error`) and
+      persist the round artifacts before any remediation begins.

package/agents/modes/build/panel_consensus.md

@@ -0,0 +1,71 @@
+## Panel Consensus (Resolve + Remediate)
+
+This flow assumes the panel audit barrier has completed (all invoked reviewers returned and round artifacts are
+persisted).
+
+1.  **Assess (After Barrier)**: If any reviewer status is not `lgtm`, call `@Implementer` to
+    produce a per-finding assessment.
+    - _Routing_: The runtime injects a **single consolidated** findings packet into `@Implementer` once per round.
+      `@Lead` is not in the high-bandwidth reviewer<->implementer loop except for arbitration and remediation dispatch.
+    - _Dedup (Recommended)_: Before invoking `@Implementer`, the runtime SHOULD deduplicate equivalent findings across
+      redundant invocations of the same Specialist role.
+      - Preserve provenance by retaining the underlying `finding_id` values.
+      - `@Implementer` MAY apply one disposition to a deduplicated group by using `finding_ids` in the assessment artifact.
+    - _Output_: Provide dispositions that cover every finding in the injected packet.
+      - Cite either `finding_id` (`1..N`) or a `finding_ids` group for a deduplicated set.
+    - The runtime MUST persist this assessment and use it to route disputes.
+2.  **Dispute Routing (Targeted)**: For disputed findings, the runtime sends the finding(s) + Implementer rationale back
+    to the originating reviewer for one-step reassessment and records the outcome.
+    - _Batching (Required)_: The runtime MUST batch all disputed findings for the same originating reviewer invocation
+      into a single reassessment call.
+    - _Reviewer Response Contract_: The reviewer responds using the standard reviewer output format:
+      - `LGTM` withdraws all disputed findings in the reassessment packet.
+      - Otherwise, the reviewer outputs a top-level bullet list where each bullet starts with `<finding_id>:` and then
+        either `LGTM` (withdraw) or the maintained/revised finding text.
+    - If the reviewer does not withdraw and Implementer still disputes, the runtime MUST batch all still-contested
+      `finding_id` values for the round into the minimum number of arbitration packets to `@Lead`, subject to context
+      limits.
+      - Prefer a single packet when feasible.
+      - Use stable ordering by ascending `finding_id`.
+      - `@Lead` returns a decision per `finding_id`; the ruling is final for that finding and recorded.
+3.  **Remediate**: `@Lead` converts accepted findings (and upheld disputes) into remediation Tasks.
+    - _Planner (Conditional)_: If remediation requires multi-step coordination or re-architecture, `@Lead` calls
+      `@Planner`; otherwise `@Lead` may dispatch Tasks directly to `@Implementer`.
+    - _Task Shape_: Every remediation Task MUST include explicit `Files` and `Verification`.
+      - If either is missing, `@Lead` MUST route to `@Planner` to repair/derive.
+    - Each remediation Task MUST complete Phase 2 (Build + Micro-Audit) before re-entering the panel. Micro-Audit is
+      complete only when: the Lite decision is recorded; any reject is resolved (fixed or arbitrated); and required
+      verification passes.
+4.  **Re-Audit (Selective Rounds)**: Re-run only Specialist roles that still have open issues (most recent status !=
+    `lgtm`) and any newly-required specialists.
+    - _Role Status_: When a role has multiple reviewer invocations in the most recent round, treat the role as closed
+      only if **all** invocations for that role returned status `lgtm`.
+      - If any invocation is `reject|timeout|error`, treat the role as still open and re-run it.
+    - _Diff Scope_: Prefer incremental diffs since the previous panel round for selective rounds.
+      - _prev_head_: Use the `Head Ref` recorded in the previous panel timeline entry.
+    - _Redundancy_: When a Specialist role is re-run, apply the configured per-role redundancy count
+      (e.g., `logic=2`, `security=3`) unless the runtime is explicitly running in reduced-redundancy mode.
+      - If reduced redundancy is used, the runtime MUST record `redundancy_mode=reduced`.
+5.  **Final Consensus (Full Panel)**: Once all selective reviewers have status `lgtm` and disputes are resolved, run a
+    final full panel round including every Specialist role invoked in any prior Phase 3 round
+    (Round 1 + any newly-added specialists).
+    - _Diff Scope_: Use the cumulative diff (`Base Ref...Head Ref`).
+    - If any reviewer rejects, repeat steps 1-5.
+    - _Invariant_: Phase 3 may only conclude immediately after a successful final full-panel round
+      (do not conclude after a selective round).
+6.  **Gate**: Unanimous Approval Required.
+    - _Loop_: Max 10 panel rounds (selective + final both count).
+    - _Timeout_: 10 minutes per reviewer invocation per attempt.
+    - _On Timeout_: Re-assign each timed-out reviewer once. If it still times out, treat as a reject for that round.
+    - _Compress_: After each round, keep a compact "Resolved / Remaining" summary; do not carry full prior transcripts.
+    - _Deadlock Escape_:
+      - If the disputed finding-signature set is unchanged across 2 consecutive rounds, `@Lead` must either trigger
+        arbitration or abort.
+      - **Majority Consensus (Non-Critical)**: If the change is clearly non-critical-path (no Auth, Payments,
+        Cryptography/Secrets, DB schema, or Public API touch points per `@Explorer`), `@Lead` may accept majority
+        approval of the invoked panel, overriding strict unanimity with a risk rationale.
+    - _Override_: If needed, `@Lead` may override with an explicit risk rationale.
+      - _Guardrail_: If overriding a security- or test-related rejection, `@Lead` must surface the residual risk and get
+        explicit user acknowledgement.
+    - _After Max_: If still not unanimous after 10 panel rounds, `@Lead` must either abort (recommended)
+      or override with an explicit risk rationale.

package/agents/modes/build/plan.md

@@ -0,0 +1,28 @@
+## Clarify & Plan (The Blueprint)
+
+1.  **Orchestrate**: `@Lead` assesses the request and engages `@Explorer` to map the codebase.
+2.  **Compliance**: `@Lead` consults `@Counsel` for Rules and Policies.
+    - **Policy (Always)**: The runtime resolves the active Policy (local policy if present; otherwise default) and
+      injects it into downstream agents. Policy rules are always active.
+    - **Inject (Dynamic)**: `@Lead` instructs the Runtime to load/hydrate rule content and inject
+      `{{injected_rules}}`.
+      - `@Planner`: plan-level rules/policies.
+      - `@Implementer`: step-scoped rules per Task (always include the active Policy rules).
+      - Reviewers: review-scope rules/policies for `@Plan-Reviewer`, `@Reviewer-Lite`, and the specialist panel.
+3.  **Draft**: `@Planner` creates the **Execution Plan**.
+    - _Input_: User Request + Map + Rules.
+    - _Constraint_: The plan phase is task planning only.
+      - If an architecture decision is required, it MUST appear as an explicit Task (often an ADR update) to be executed
+        by `@Implementer` under the normal build loop.
+4.  **Plan Review**: Call **two** independent `@Plan-Reviewer` instances.
+    - _Gate_: Must have unanimous approval to proceed.
+    - _Loop_: Max 3 revision cycles.
+    - _Timeout_: 5 minutes per reviewer per attempt (default; runtime may override).
+    - _On Timeout_: Re-assign each timed-out reviewer once. If it still times out, treat as a reject for that cycle.
+    - _On Reject_: `@Lead` digests reviewer feedback, decides legitimacy, and asks `@Planner` to revise the plan.
+      - Planner revisions SHOULD include a "Plan Review Response" with `accept|dispute` per finding.
+      - Plan review does not have dispute routing; disputed plan findings are resolved by `@Lead` arbitration/override.
+    - _After Max_: If still not unanimously approved after 3 cycles, `@Lead` must either abort (recommended) or
+      arbitrate/override by authoring a revised plan with an explicit risk rationale.
+5.  **Gate**: Present Plan to User. **WAIT for Sign-off**.
+    - _Constraint_: Do not proceed to Build until Plan is explicitly approved.

package/agents/modes/build.md

@@ -21,10 +21,10 @@ SafetyProfile:
 Team:
 
 - **Manager**: **[@Lead](../roles/lead.md)**.
-- **Architect**: **[@Planner](../roles/planner.md)**.
+- **Planner**: **[@Planner](../roles/planner.md)**.
 - **Compliance**: **[@Counsel](../roles/counsel.md)**.
 - **Researcher**: **[@Librarian](../roles/librarian.md)** (Optional).
-- **Maker**: **[@Builder](../roles/builder.md)**.
+- **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)**.
@@ -45,133 +45,20 @@ Team:
 </OutputFormat>
 
 <Workflow>
-## Phase 1: Clarify & Design (The Blueprint)
-1.  **Orchestrate**: `@Lead` assesses the request and engages `@Explorer` to map the codebase.
-2.  **Compliance**: `@Lead` consults `@Counsel` for Rules and Policies.
-    *   **Policy (Always)**: The runtime resolves the active Policy (local policy if present; otherwise default) and
-        injects it into downstream agents. Policy rules are always active.
-    *   **Inject (Dynamic)**: `@Lead` instructs the Runtime to load/hydrate rule content and inject
-        `{{injected_rules}}`.
-        - `@Planner`: plan-level rules/policies.
-        - `@Builder`: step-scoped rules per Task (always include the active Policy rules).
-        - Reviewers: review-scope rules/policies for `@Plan-Reviewer`, `@Reviewer-Lite`, and the specialist panel.
-3.  **Draft**: `@Planner` creates the **Execution Plan**.
-    *   *Input*: User Request + Map + Rules.
-4.  **Plan Review**: Call **two** independent `@Plan-Reviewer` instances.
-    *   *Gate*: Must have unanimous approval to proceed.
-    *   *Loop*: Max 3 revision cycles.
-    *   *Timeout*: 5 minutes per reviewer per attempt (default; runtime may override).
-    *   *On Timeout*: Re-assign each timed-out reviewer once. If it still times out, treat as a reject for that cycle.
-    *   *On Reject*: `@Lead` digests reviewer feedback, decides legitimacy, and asks `@Planner` to revise the plan.
-    *   *After Max*: If still not unanimously approved after 3 cycles, `@Lead` must either abort (recommended) or
-        arbitrate/override by authoring a revised plan with an explicit risk rationale.
-5.  **Gate**: Present Plan to User. **WAIT for Sign-off**.
-    *   *Constraint*: Do not proceed to Build until Plan is explicitly approved.
-
-## Phase 2: Execute (The Heavy Loop)
-
-For each Task in the Plan:
-
-1.  **Build**: Call `@Builder` with `(Task, Files, Requirements, Verification)`.
-    - _Constraint_: `Files` MUST come from the Plan step. If missing, `@Lead` routes back to `@Planner` to repair the
-      plan.
-    - _Constraint_: Verification is mandatory. The proof level is defined per step (tests and/or other evidence).
-    - _Timeout_: 20 minutes per attempt (default; runtime may override).
-    - _On Timeout_: Re-assign once; if it times out again, treat as a reject and re-plan or abort.
-2.  **Micro-Audit**: Call `@Reviewer-Lite` on the diff.
-    - _Scope_: Fast sanity gate (obvious correctness breakage + basic style/tooling + commit message). Deep specialist
-      review happens in Phase 3.
-    - _Input_: Provide `User Request` + (`Diff` or `Diff Command`).
-      Include `Base Ref` whenever the runtime has git metadata (e.g., PR merge target).
-      Include `Head Ref` when available.
-      Include the atomic `Commit Message` when available.
-    - _Gate_: One Lite decision per atomic commit (no Lite roundtrip).
-    - _Timeout_: 5 minutes per attempt.
-    - _On Timeout_: Re-assign once. If it still times out, `@Lead` must either abort or proceed with an explicit risk
-      rationale (record in artifacts).
-    - _On Reject_: The runtime records the Lite artifact and the commit SHA. `@Builder` MUST respond with a disposition
-      per finding using `finding_id` (`<invocation_id>:<bullet_index>`) and a short rationale for any dispute.
-      - `bullet_index` is the 1-based index of the top-level bullet in the stored reviewer artifact.
-      - If all findings are `accept`: `@Builder` fixes by amending the same commit (`git commit --amend`) when the commit
-        is not pushed/shared. If the commit is already pushed/shared, use fixup commits and squash later.
-      - If any finding is `dispute`: `@Lead` arbitrates at that commit (no Lite roundtrip). `@Lead` either upholds the
-        finding (Builder must fix using the same commit strategy: amend when not pushed/shared; otherwise fixup + squash)
-        or overrides with an explicit risk rationale.
-      - After all findings are resolved (fixed or overridden), proceed after required verification passes (no Lite
-        re-review).
-
-## Phase 3: Consensus (The Jury)
-
-1.  **Verify**: Ensure required verification passes (including integration tests when required).
-2.  **Audit (Round 1: Full Panel)**: Call the **Full Review Panel** in parallel.
-    - Mandatory: [Logic](../roles/reviewer/logic.md), [Quality](../roles/reviewer/quality.md),
-      [Test](../roles/reviewer/test.md).
-    - Conditional: [Security](../roles/reviewer/security.md) when `@Lead` marks the work security-sensitive (or
-      `@Counsel` selected `#security` rules).
-    - Conditional: [Performance](../roles/reviewer/performance.md) when `@Lead` marks the work perf-sensitive (or
-      `@Counsel` selected `#efficiency` rules).
-    - _Input (each)_: Provide `User Request` + (`Diff` or `Diff Command`).
-      Include `Base Ref` whenever the runtime has git metadata (e.g., PR merge target).
-      Include `Head Ref` when available.
-    - _Barrier_: The runtime MUST wait for all invoked reviewers to return (`LGTM` | `reject` | `timeout` | `error`) and
-      persist the round artifacts before any remediation begins.
-3.  **Assess (After Barrier)**: After the barrier in Step 2, if any reviewer is not `LGTM`, call `@Builder` to produce a
-    per-finding assessment.
-    - _Output_: For each finding bullet, mark `accept` or `dispute`, citing `finding_id`
-      (`<invocation_id>:<bullet_index>`).
-      - `bullet_index` is the 1-based index of the top-level bullet in the stored reviewer artifact.
-    - The runtime MUST persist this assessment and use it to route disputes.
-4.  **Dispute Routing (Targeted)**: For each disputed finding, the runtime sends the finding + Builder rationale back to
-    the originating reviewer for one-step reassessment (`withdraw` | `maintain` | `revise`) and records the outcome.
-    - If the reviewer maintains and Builder still disputes, `@Lead` arbitrates once; the ruling is final and recorded.
-5.  **Remediate**: `@Lead` converts accepted findings (and upheld disputes) into remediation Tasks.
-    - _Planner (Conditional)_: If remediation requires multi-step coordination or re-architecture, `@Lead` calls
-      `@Planner`; otherwise `@Lead` may dispatch Tasks directly to `@Builder`.
-    - Each remediation Task MUST complete Phase 2 (Build + Micro-Audit) before re-entering the panel. Micro-Audit is
-      complete only when: the Lite decision is recorded; any reject is resolved (fixed or arbitrated); and required
-      verification passes.
-6.  **Re-Audit (Selective Rounds)**: Re-run only reviewers who still have open issues (most recent status != `LGTM`) and
-    any newly-required specialists.
-    - _Diff Scope_: Prefer incremental diffs since the previous panel round for selective rounds.
-      - _prev_head_: Use the `Head Ref` recorded in the previous panel timeline entry.
-7.  **Final Consensus (Full Panel)**: Once all selective reviewers are `LGTM` and disputes are resolved, run a final full
-    panel round including every reviewer invoked in any prior Phase 3 round (Round 1 + any newly-added specialists).
-    - _Diff Scope_: Use the cumulative diff (`Base Ref...Head Ref`).
-    - If any reviewer rejects, repeat steps 3-7.
-    - _Invariant_: Phase 3 may only conclude immediately after a successful final full-panel round (do not conclude after
-      a selective round).
-8.  **Gate**: Unanimous Approval Required.
-    - _Loop_: Max 10 panel rounds (selective + final both count).
-    - _Timeout_: 10 minutes per reviewer per attempt.
-    - _On Timeout_: Re-assign each timed-out reviewer once. If it still times out, treat as a reject for that round.
-    - _Compress_: After each round, keep a compact "Resolved / Remaining" summary; do not carry full prior transcripts.
-    - _Deadlock Escape_:
-      - If the panel stalls for 2 consecutive rounds, `@Lead` must either trigger arbitration or abort.
-      - **Majority Consensus (Non-Critical)**: If the change is clearly non-critical-path (no Auth, Payments,
-        Cryptography/Secrets, DB schema, or Public API touch points per `@Explorer`), `@Lead` may accept majority
-        approval of the invoked panel, overriding strict unanimity with a risk rationale.
-    - _Override_: If needed, `@Lead` may override with an explicit risk rationale.
-      - _Guardrail_: If overriding a security- or test-related rejection, `@Lead` must surface the residual risk and get
-        explicit user acknowledgement.
-    - _After Max_: If still not unanimous after 10 panel rounds, `@Lead` must either abort (recommended) or override with
-      an explicit risk rationale.
-
-## Phase 4: Delivery
-
-1.  **Squash (Runtime)**: `@Lead` instructs the runtime to consolidate history.
-    - Squash "fixup", "wip", or "address comments" commits into the relevant atomic feature commits.
-    - Ensure the final history reflects the _story_ of the change, not the _process_ of the review.
-2.  **Finalize**: Produce the Production-Ready PR.
-    - **PR Hygiene**: Title/body explain intent, risks, and verification evidence; mark Draft vs Ready explicitly.
-    - **Merge Plan**: State merge strategy expectations (squash vs merge-commit vs rebase) per repo policy.
-    - **Last Check**: Re-run required verification before marking ready.
+{{flow_build_plan}}
+{{flow_build_code}}
+{{flow_build_panel}}
+{{flow_build_panel_consensus}}
+{{flow_build_delivery}}
 
 </Workflow>
 
 <Constraints>
 **Hard Blocks**:
 - [ ] Do not proceed to Phase 2 until the Plan is explicitly approved by the user.
-- [ ] Every `@Builder` task MUST include `Files` and `Verification` from the Plan (repair the plan if missing).
+- [ ] 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`.
 - [ ] Never skip required verification.
 - [ ] Unanimous approval is required by default; any override MUST include an explicit risk rationale.
 </Constraints>

package/agents/modes/hack/README.md

@@ -0,0 +1,9 @@
+# @Hack Fragments
+
+Non-invocable workflow fragments composed by `agents/modes/hack.md` via `{{flow_hack_*}}` placeholders.
+
+## Index
+
+- [plan.md](plan.md): Phase 1 (sketch)
+- [code.md](code.md): Phase 2 (fast loop + lite gate)
+- [delivery.md](delivery.md): Phase 3 (draft PR/branch)

package/agents/modes/hack/code.md

@@ -0,0 +1,42 @@
+## Code (The Fast Loop)
+
+For each Task (plan step or a single task when planning is skipped):
+
+- Unit of work:
+  - The runtime MUST dispatch exactly one Task at a time.
+  - `@Implementer` MUST produce exactly one primary atomic commit for that Task.
+  - Review remediation MAY add fixup commit(s) targeting that primary commit (no additional Tasks).
+
+- Optimization (optional): tools MAY reuse the same `@Implementer` session/thread across Tasks to reduce context cost.
+  This does not change the unit of work: one invocation = one Task = one primary atomic commit.
+
+1.  **Build**: Call `@Implementer` with `(Task, Files, Requirements, Verification)`.
+    - _Constraint_: No mandatory TDD or Unit Tests in `@Hack`.
+    - _Note_: If the user requests tests, include them in the plan.
+    - _Timeout_: 15 minutes.
+    - _On Timeout_: Re-assign once; if it times out again, abort or invoke `@Planner` to split the task and retry.
+2.  **Check**: Call `@Reviewer-Lite`.
+    - _Scope_: Release blockers only (obvious correctness breakage, basic style/tooling, commit message, docs/index).
+    - _Input_: Provide `User Request` + (`Diff` or `Diff Command`).
+      Include `Base Ref` whenever the runtime has git metadata (e.g., PR merge target).
+      Include `Head Ref` when available.
+      Include the atomic `Commit Message` when available.
+    - _Gate_: One Lite decision per primary atomic commit.
+      - No Lite roundtrip.
+      - Fixup remediation does not trigger a new Lite decision.
+    - _Timeout_: 5 minutes per attempt.
+    - _On Timeout_: Re-assign once. If it still times out, proceed as prototype or abort.
+    - _On Reject_: The runtime records the Lite artifact and the commit SHA. `@Implementer` MUST respond with a
+      disposition for every finding in that Lite artifact (single assessment packet) using `finding_id` (`1..N` in the
+      injected findings packet) and a short rationale for any dispute.
+      - If all findings are `accept`: `@Implementer` fixes using fixup commits (target the original commit):
+        `git commit --fixup <sha>`.
+      - If any finding is `dispute`: `@Lead` arbitrates immediately for that commit (no Lite roundtrip, no debate).
+        - The runtime MUST batch all disputed findings for the commit into the minimum number of arbitration packets to
+          `@Lead`, subject to context limits.
+        - `@Lead` returns a decision per `finding_id` (`uphold` -> fix; `override` -> proceed).
+        - If fix: Implementer uses fixup commits targeting that commit.
+      - After all findings are resolved (fixed or arbitrated), proceed.
+    - _Fail_: If still rejected, `@Lead` may proceed only when the remaining findings are strictly non-runtime-impacting
+      hygiene (commit message wording, docs/index, formatting) and the user explicitly accepts the residual risk (record
+      in artifacts). Otherwise abort or invoke `@Planner` to re-scope.

package/agents/modes/hack/delivery.md

@@ -0,0 +1,6 @@
+## Delivery
+
+- **Finalize**: Produce a Draft PR or Experimental Branch.
+- **Note**: Explicitly label as "Prototype / Not Production Ready".
+  - Prefer a Draft PR and a title prefix like `[Hack]` or `[Prototype]`.
+- **Graduation**: To ship as production code, rerun the work under `@Build` (do not merge a Hack prototype silently).

package/agents/modes/hack/plan.md

@@ -0,0 +1,29 @@
+## Sketch
+
+1.  **Map**: `@Lead` engages `@Explorer` to identify likely touched files and risks.
+2.  **Risk Gate (Advisory)**: If `@Explorer` indicates critical-path scope (Auth, Payments, Cryptography/Secrets, DB
+    schema, Public API), `@Lead` warns the user and recommends switching to `@Build`.
+    - _Constraint_: Do not auto-escalate or switch modes; run `@Hack` as selected.
+3.  **Policy (Always)**: `@Lead` instructs the Runtime to resolve the active Policy (local policy if present; otherwise
+    default) and inject it into downstream agents.
+4.  **Rules (Optional)**: If the user requests stricter compliance, `@Lead` consults `@Counsel` and instructs the Runtime
+    to load/hydrate selected rule content and inject `{{injected_rules}}`.
+    - `@Planner`: plan-level rules/policies.
+    - `@Plan-Reviewer`: review-scope rules/policies (when invoked).
+    - `@Implementer`: step-scoped rules per Task (always include the active Policy rules).
+    - `@Reviewer-Lite`: review-scope rules/policies.
+5.  **Plan (Optional)**: `@Planner` creates a short "Sketch Plan" (atomic steps).
+    - Each step MUST include: Action, Files, Verification, and Requirements as rule IDs (may be empty).
+    - For trivial changes (single-file, low-risk), `@Lead` may skip `@Planner` and proceed with a single Implementer task.
+      - If skipping `@Planner`, `@Lead` MUST still provide `@Implementer` with `(Task, Files, Requirements, Verification)`.
+      - If `@Counsel` ran, `@Lead` MUST include all Counsel-selected rule IDs in `Requirements` for the single task.
+      - If the user requests plan review, do not skip `@Planner`.
+6.  **Plan Review**: Optional (only when a Plan exists). `@Lead` may call `@Plan-Reviewer` (0-1) based on scope
+    (e.g., multi-step/multi-file) or if the user requests it.
+    - _Timeout (Default)_: 5 minutes per attempt (if called).
+    - _On Timeout_: Proceed without plan review.
+    - _On Reject_: `@Lead` digests feedback and asks `@Planner` to revise once.
+      - Planner revisions SHOULD include a "Plan Review Response" with `accept|dispute` per finding.
+      - Plan review does not have dispute routing; disputed plan findings are resolved by `@Lead` arbitration/override.
+      - Re-review: re-invoke the same `@Plan-Reviewer` once on the revised plan.
+      - If it still rejects, proceed as a prototype or abort.

package/agents/modes/hack.md

@@ -29,8 +29,8 @@ Team:
 - **Cartographer**: **[@Explorer](../roles/explorer.md)**.
 - **Compliance**: **[@Counsel](../roles/counsel.md)** (Optional).
 - **Researcher**: **[@Librarian](../roles/librarian.md)** (Optional).
-- **Architect**: **[@Planner](../roles/planner.md)** (Optional; Sketch/Plan).
-- **Maker**: **[@Builder](../roles/builder.md)** (Fast Mode).
+- **Planner**: **[@Planner](../roles/planner.md)** (Optional; Sketch/Plan).
+- **Maker**: **[@Implementer](../roles/implementer.md)** (Fast Mode).
 - **Plan Reviewer**: **[@Plan-Reviewer](../roles/reviewer/plan.md)** (Optional).
 - **Critic**: **[@Reviewer-Lite](../roles/reviewer/lite.md)**.
 </Meta>
@@ -49,67 +49,9 @@ Team:
 </OutputFormat>
 
 <Workflow>
-## Phase 1: Sketch
-1.  **Map**: `@Lead` engages `@Explorer` to identify likely touched files and risks.
-2.  **Risk Gate (Advisory)**: If `@Explorer` indicates critical-path scope (Auth, Payments, Cryptography/Secrets, DB
-    schema, Public API), `@Lead` warns the user and recommends switching to `@Build`.
-    - _Constraint_: Do not auto-escalate or switch modes; run `@Hack` as selected.
-3.  **Policy (Always)**: `@Lead` instructs the Runtime to resolve the active Policy (local policy if present; otherwise
-    default) and inject it into downstream agents.
-4.  **Rules (Optional)**: If the user requests stricter compliance, `@Lead` consults `@Counsel` and instructs the Runtime
-    to load/hydrate selected rule content and inject `{{injected_rules}}`.
-    - `@Planner`: plan-level rules/policies.
-    - `@Plan-Reviewer`: review-scope rules/policies (when invoked).
-    - `@Builder`: step-scoped rules per Task (always include the active Policy rules).
-    - `@Reviewer-Lite`: review-scope rules/policies.
-5.  **Plan (Optional)**: `@Planner` creates a short "Sketch Plan" (atomic steps).
-    - Each step MUST include: Action, Files, Verification, and Requirements as rule IDs (may be empty).
-    - For trivial changes (single-file, low-risk), `@Lead` may skip `@Planner` and proceed with a single Builder task.
-      - If skipping `@Planner`, `@Lead` MUST still provide `@Builder` with `(Task, Files, Requirements, Verification)`.
-      - If `@Counsel` ran, `@Lead` MUST include all Counsel-selected rule IDs in `Requirements` for the single task.
-      - If the user requests plan review, do not skip `@Planner`.
-6.  **Plan Review**: Optional (only when a Plan exists). `@Lead` may call `@Plan-Reviewer` (0-1) based on scope
-    (e.g., multi-step/multi-file) or if the user requests it.
-    *   *Timeout (Default)*: 5 minutes per attempt (if called).
-    *   *On Timeout*: Proceed without plan review.
-    *   *On Reject*: `@Lead` digests feedback and asks `@Planner` to revise once. If it still rejects, proceed as a
-        prototype or abort.
-
-## Phase 2: Code (The Fast Loop)
-
-1.  **Build**: Call `@Builder` with `(Task, Files, Requirements, Verification)`.
-    - _Constraint_: No mandatory TDD or Unit Tests in `@Hack`.
-    - _Note_: If the user requests tests, include them in the plan.
-    - _Timeout_: 15 minutes.
-    - _On Timeout_: Re-assign once; if it times out again, abort or invoke `@Planner` to split the task and retry.
-2.  **Check**: Call `@Reviewer-Lite`.
-    - _Scope_: Release blockers only (obvious correctness breakage, basic style/tooling, commit message, docs/index).
-    - _Input_: Provide `User Request` + (`Diff` or `Diff Command`).
-      Include `Base Ref` whenever the runtime has git metadata (e.g., PR merge target).
-      Include `Head Ref` when available.
-      Include the atomic `Commit Message` when available.
-    - _Gate_: One Lite decision per atomic commit (no Lite roundtrip).
-    - _Timeout_: 5 minutes per attempt.
-    - _On Timeout_: Re-assign once. If it still times out, proceed as prototype or abort.
-    - _On Reject_: The runtime records the Lite artifact and the commit SHA. `@Builder` MUST respond with a disposition
-      per finding using `finding_id` (`<invocation_id>:<bullet_index>`) and a short rationale for any dispute.
-      - `bullet_index` is the 1-based index of the top-level bullet in the stored reviewer artifact.
-      - If all findings are `accept`: `@Builder` fixes by amending the same commit (`git commit --amend`) when the commit
-        is not pushed/shared. If the commit is already pushed/shared, use fixup commits and squash later.
-      - If any finding is `dispute`: `@Lead` arbitrates immediately for that commit (no Lite roundtrip, no debate) and
-        decides fix vs proceed.
-        - If fix: Builder uses the same commit strategy (amend when not pushed/shared; otherwise fixup + squash later).
-      - After all findings are resolved (fixed or arbitrated), proceed.
-    - _Fail_: If still rejected, `@Lead` may proceed only when the remaining findings are strictly non-runtime-impacting
-      hygiene (commit message wording, docs/index, formatting) and the user explicitly accepts the residual risk (record
-      in artifacts). Otherwise abort or invoke `@Planner` to re-scope.
-
-## Phase 3: Delivery
-
-- **Finalize**: Produce a Draft PR or Experimental Branch.
-- **Note**: Explicitly label as "Prototype / Not Production Ready".
-  - Prefer a Draft PR and a title prefix like `[Hack]` or `[Prototype]`.
-- **Graduation**: To ship as production code, rerun the work under `@Build` (do not merge a Hack prototype silently).
+{{flow_hack_plan}}
+{{flow_hack_code}}
+{{flow_hack_delivery}}
 
 </Workflow>
 

package/agents/modes/review/README.md

@@ -0,0 +1,9 @@
+# @Review Fragments
+
+Non-invocable workflow fragments composed by `agents/modes/review.md` via `{{flow_review_*}}` placeholders.
+
+## Index
+
+- [plan.md](plan.md): Phases 1-2 (map + optional audit plan)
+- [audit.md](audit.md): Phase 3 (panel audit barrier)
+- [synthesize.md](synthesize.md): Phase 4 (synthesize + report)