lgtm-specs 0.0.4 → 0.0.6

package/AGENTS.md

@@ -1,7 +1,7 @@
 # Agent Instructions (lgtm-specs)
 
-This repository (`lgtm-specs`) is a versioned **Knowledge Graph** of specs (rules + agent prompts). Treat changes as spec
-edits, not application code.
+This repository (`lgtm-specs`) is a versioned **Knowledge Graph** of specs (rules + agent prompts).
+Treat changes as spec edits, not application code.
 
 Repo-local assistant instructions:
 
@@ -25,6 +25,9 @@ bun run validate
 # or:
 python3 scripts/validate_specs.py
 
+# Unit tests (validator self-tests)
+bun run test
+
 # Formatting (Prettier)
 bun run format
 bun run format:check
@@ -97,7 +100,8 @@ Atomic rule requirements (see `rules/RULE-00000-EXAMPLE.md`):
 Citations and links:
 
 - Source-of-truth material lives in `docs/meta/**`; do not invent citations.
-- Use repo-root-relative links (`/rules/...`, `/docs/...`) and ensure targets exist.
+- Links: prefer repo-root-relative links (`/rules/...`, `/docs/...`) for stability.
+  Relative links are acceptable; follow the local directory convention.
 - `**Source**` links into `docs/meta/**` should include an anchor (`#...`).
 
 Tags and writing:

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yyforyongyu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,8 +1,19 @@
 # LGTM Specifications
 
-[![Validate Specs](https://github.com/yyforyongyu/lgtm-specs/actions/workflows/validate.yml/badge.svg?branch=main)](https://github.com/yyforyongyu/lgtm-specs/actions/workflows/validate.yml?query=branch%3Amain) [![Version](https://img.shields.io/github/v/tag/yyforyongyu/lgtm-specs?sort=semver)](https://github.com/yyforyongyu/lgtm-specs/releases)
+[![CI](https://github.com/yyforyongyu/lgtm-specs/actions/workflows/validate.yml/badge.svg?branch=main)](https://github.com/yyforyongyu/lgtm-specs/actions/workflows/validate.yml?query=branch%3Amain)
+[![version](https://img.shields.io/npm/v/lgtm-specs?label=version)](https://www.npmjs.com/package/lgtm-specs)
+[![downloads](https://img.shields.io/npm/dm/lgtm-specs?label=downloads)](https://www.npmjs.com/package/lgtm-specs)
 
-LGTM Specifications is a versioned knowledge graph of engineering standards (Rules) and an autonomous workforce (Agents) used by tools to plan, build, and audit changes with high assurance.
+LGTM Specifications is a versioned knowledge graph of engineering standards (Rules) and an agent workforce (Modes/Roles)
+that tools can run to plan, build, and audit changes with high assurance.
+
+## Quick Links
+
+- Rules: `rules/README.md`
+- Agents: `agents/README.md`
+- Integration protocol: `integrate/README.md`
+- Docs: `docs/README.md`
+- Contributing: `docs/CONTRIBUTING.md`
 
 ## Knowledge
 
@@ -19,7 +30,7 @@ Start here:
 
 ## Workflows
 
-LGTM runs as a set of operating modes that orchestrate a specialist team (Lead, Explorer, Counsel, Planner, Builder, Reviewer panel).
+LGTM runs as operating modes that orchestrate a specialist team (Lead, Explorer, Counsel, Planner, Builder, Reviewers).
 
 Modes:
 
@@ -29,27 +40,46 @@ Modes:
 
 Core roles:
 
-- Lead orchestrates and arbitrates.
-- Explorer maps the target repo.
-- Counsel selects minimal relevant rule paths.
-- Planner produces an execution/audit plan.
-- Builder implements and produces proof.
-- Reviewers audit from specialized perspectives.
+- 🧠 [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.
+- 🏗️ [Builder](agents/roles/builder.md): implements and produces proof.
+- 🔬 [Reviewers](agents/roles/reviewer/README.md): audit from specialized perspectives.
 
 Start here:
 
 - [Agent Architecture](docs/agent_architecture.md)
 - [Agents Index](agents/README.md)
 
-## Integrating
+## Consume
 
 Tools consume this repo as a read-only spec database.
 
+Install via npm (recommended):
+
+```bash
+npm install --save-dev lgtm-specs
+
+# or:
+bun add -d lgtm-specs
+```
+
+The specs live at `node_modules/lgtm-specs/`.
+
+Versioning:
+
+- `VERSION` matches `integrate/README.md` `**Spec Version**:`
+- See `integrate/versioning.md` for consumption options (tags, submodules, npm)
+
+## Integrating
+
 Start here:
 
 - [Integration Protocol](integrate/README.md)
 
-Copy/paste prompt for a tool/LLM implementing the integration:
+<details>
+<summary>Prompt starter (tools/LLMs implementing the integration)</summary>
 
 ```text
 You are implementing integration for the LGTM specs repo (yyforyongyu/lgtm-specs).
@@ -68,22 +98,25 @@ Output:
 3) pseudocode for: index loading -> counsel -> rule hydration -> per-agent injection -> execution.
 ```
 
+</details>
+
 ## Contributing
 
 Contributions should preserve atomicity, indexing, and link integrity.
 
 Start here:
 
-- [Contribution Guide](contribute/README.md)
-- [Definition of Done Checklist](contribute/checklist.md)
+- [Contribution SOPs](docs/contribute/README.md)
+- [Definition of Done Checklist](docs/contribute/checklist.md)
 - Local checks: `bun run check` (runs spec validation + `prettier --check`).
 
-Copy/paste prompt for an LLM starting a contribution:
+<details>
+<summary>Prompt starter (LLMs starting a contribution)</summary>
 
 ```text
 You are contributing to the LGTM specs repo (yyforyongyu/lgtm-specs).
 
-Read `contribute/README.md` and `contribute/checklist.md` and follow them strictly.
+Read `docs/contribute/README.md` and `docs/contribute/checklist.md` and follow them strictly.
 Run `bun run check` before finalizing your changes.
 
 Constraints:
@@ -96,3 +129,5 @@ Task:
 2) propose exact file edits,
 3) run `python3 scripts/validate_specs.py` and report any failures.
 ```
+
+</details>

package/VERSION

@@ -1 +1 @@
-0.0.4
+0.0.6

package/agents/modes/build.md

@@ -11,6 +11,12 @@ Trigger:
 - Public API changes.
 - Database Schema migrations.
 - "Production Ready" work.
+- (For rapid prototypes, use **[@Hack](hack.md)** instead).
+
+SafetyProfile:
+
+- Strict gates (plan sign-off, verification, and panel review).
+- Overrides allowed only with explicit risk rationale.
 
 Team:
 
@@ -29,18 +35,32 @@ Team:
 **Goal**: Ship Features, Refactors, and Production Code.
 </Role>
 
+<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>
 ## 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.
-    *   **Inject**: `@Lead` instructs the Runtime to load/hydrate rule content and inject `{{injected_rules}}` into
-        `@Planner` and all reviewers used in this mode (`@Plan-Reviewer`, `@Reviewer-Lite`, Panel).
+    *   **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 cycle (default; runtime may override).
+    *   *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
@@ -52,37 +72,106 @@ Team:
 
 For each Task in the Plan:
 
-1.  **Build**: Call `@Builder` with `(Task, Rules, Verification)`.
+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_: Include the PR merge target as `Base Ref` and the atomic `Commit Message` when available.
-    - _Retry_: Max 3 attempts.
+    - _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_: Treat as a reject and retry.
-    - _On Reject_: `@Lead` digests feedback, decides legitimacy, and asks `@Builder` to address it.
-    - _Fail_: If 3 retries fail, `@Lead` calls `@Planner` to re-plan or overrides with rationale.
+    - _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**: Call the **Full Review Panel**.
-    - Mandatory: `Logic`, `Quality`, `Test`.
-    - Conditional: `Security` (if tagged), `Performance` (if tagged).
-3.  **Gate**: Unanimous Approval Required.
-    - _Loop_: Max 10 review->fix cycles.
-    - _Timeout_: 10 minutes per reviewer per cycle.
-    - _On Timeout_: Re-assign each timed-out reviewer once. If it still times out, treat as a reject for that cycle.
-    - _Clarify_: If a finding is contested or unclear, `@Lead` asks the specific reviewer to justify or withdraw it (one round-trip max) before planning fixes.
-    - _Cycle_: On each rejection, `@Lead` digests the panel feedback and calls `@Planner` to produce a remediation todo list. `@Builder` executes tasks one at a time, then the panel re-reviews.
-    - _Compress_: After each cycle, keep a compact "Resolved / Remaining" summary; do not carry full prior transcripts into later cycles.
-    - _Arbitration (Conditional)_: If reviewers deadlock/contradict, runtime injects the minimum Tier 2 contested diff and
-      full contested rules into `@Lead`; `@Lead` judges citing rule IDs and diff evidence.
+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.
-    - _After Max_: If still not unanimous after 10 cycles, `@Lead` must either abort (recommended) or 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
 
-- **Finalize**: Produce the Production-Ready PR.
+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.
 
 </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).
+- [ ] Never skip required verification.
+- [ ] Unanimous approval is required by default; any override MUST include an explicit risk rationale.
+</Constraints>

package/agents/modes/hack.md

@@ -29,7 +29,7 @@ Team:
 - **Cartographer**: **[@Explorer](../roles/explorer.md)**.
 - **Compliance**: **[@Counsel](../roles/counsel.md)** (Optional).
 - **Researcher**: **[@Librarian](../roles/librarian.md)** (Optional).
-- **Architect**: **[@Planner](../roles/planner.md)** (Sketch/Plan).
+- **Architect**: **[@Planner](../roles/planner.md)** (Optional; Sketch/Plan).
 - **Maker**: **[@Builder](../roles/builder.md)** (Fast Mode).
 - **Plan Reviewer**: **[@Plan-Reviewer](../roles/reviewer/plan.md)** (Optional).
 - **Critic**: **[@Reviewer-Lite](../roles/reviewer/lite.md)**.
@@ -39,38 +39,83 @@ Team:
 **Goal**: PoCs, Experiments, Non-Critical Fixes.
 </Role>
 
+<OutputFormat>
+**Result**: Markdown with:
+
+- **PR/Branch**: URL or branch name.
+- **Status**: "Prototype / Not Production Ready".
+- **Notes**: Known issues, skipped verification, or follow-ups.
+
+</OutputFormat>
+
 <Workflow>
 ## Phase 1: Sketch
 1.  **Map**: `@Lead` engages `@Explorer` to identify likely touched files and risks.
-2.  **Plan**: `@Planner` creates a short "Sketch Plan" (atomic steps + files).
-3.  **Rules (Optional)**: If the user requests stricter compliance, `@Lead` consults `@Counsel` and instructs the Runtime
-    to hydrate and inject `{{injected_rules}}`.
-4.  **Plan Review**: Optional. `@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 if called.
+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`.
+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.
-2.  **Check**: Call `@Reviewer-Lite` (Format + Basic Logic).
-    - _Scope_: Sanity checks only (no deep architecture review).
-    - _Input_: Pass the PR merge target as `Base Ref` and the atomic `Commit Message` when available.
-    - _If REJECT_: `@Lead` digests feedback and asks `@Builder` to address it.
-    - _Retry_: Max 3 attempts.
+    - _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.
-    - _Fail_: If 3 retries fail, `@Lead` decides to proceed (as a prototype) or abort.
+    - _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).
 
 </Workflow>
 
 <Constraints>
 **Hard Blocks**:
 - [ ] Do not auto-escalate or switch modes; run `@Hack` as selected.
+- [ ] Always provide `@Reviewer-Lite` with `Diff` or a runnable `Diff Command`.
+- [ ] Never proceed if `@Reviewer-Lite` flags an obvious security issue; fix it or abort (recommend `@Build`).
 </Constraints>

package/agents/modes/review.md

@@ -41,9 +41,11 @@ Only when Phase 1 Triage deems the scope non-trivial:
 
 1.  **Plan**: `@Planner` produces an **Audit Plan** (scope, files, risk areas, and which Reviewers to invoke).
 2.  **Plan Review**: Call **at least one** `@Plan-Reviewer` instance.
-    - _Gate_: Must be approved before proceeding to Phase 3.
-    - _Timeout (Default)_: 5 minutes. Runtime may override.
+    - _Gate_: Must be approved before proceeding to Phase 3. If more than one `@Plan-Reviewer` is invoked, require
+      unanimous approval.
+    - _Timeout (Default)_: 5 minutes per attempt. Runtime may override.
     - _On Timeout_: Re-assign a fresh `@Plan-Reviewer` once. If it still times out, abort the audit.
+    - _On Reject_: `@Lead` digests feedback and asks `@Planner` to revise once. If it still rejects, abort the audit.
 
 ## Phase 3: Audit
 
@@ -56,7 +58,7 @@ Only when Phase 1 Triage deems the scope non-trivial:
     - `Base Ref` / `Head Ref` (when available)
     - either an inline `Diff` or a ready-to-run `Diff Command` (filtered; excludes generated files)
     - injected Requirements (`{{injected_rules}}`)
-    - _Timeout (Default)_: 10 minutes per reviewer. Runtime may override.
+    - _Timeout (Default)_: 10 minutes per reviewer per attempt. Runtime may override.
     - _On Timeout_: Re-assign the timed-out reviewer once. If it still times out, continue and explicitly mark the finding set as incomplete.
 3.  **Clarify (Optional)**: If reviewers contradict each other or a finding seems unsupported, `@Lead` requests a one-round clarification from the specific reviewer.
 4.  **Synthesize**: `@Lead` aggregates findings into categories (Critical, Major, Minor, Info).

package/agents/roles/builder.md

@@ -15,7 +15,8 @@ RuleScope: step
 <Input>
 **Task**: Specific step from the Plan.
 **Files**: Target files.
-**Requirements**: Step-scoped injected rules + constraints.
+**Requirements**: Rule IDs for this step (plus any additional constraints); full rule bodies are injected via
+`{{injected_rules}}`.
 **Verification**: Required proof level from the Plan (e.g., unit tests required vs. none).
 </Input>
 
@@ -30,6 +31,8 @@ Implement the task. Produce the required proof (tests and/or other evidence) tha
 <OutputFormat>
 **Result**: Markdown with:
 
+- **Assessment (Conditional)**: If the Task is to address reviewer feedback, list each `finding_id` and mark `accept` or
+  `dispute` (with a short rationale).
 - **Changes**: What was changed (1-3 bullets).
 - **Evidence**: Commands run and their outcomes (tests/build/lint).
 - **Notes**: Any risks, follow-ups, or constraints.
@@ -43,6 +46,19 @@ Implement the task. Produce the required proof (tests and/or other evidence) tha
 3.  **Confirm Proof Level**: Follow the Task's verification requirements.
     *   If Unit Tests are required, write them first.
 
+## Phase 1.5: Review Remediation (Conditional)
+
+If the runtime provides reviewer findings for this Task (Lite or Panel):
+
+1.  **Assess First**: Before coding, produce an explicit disposition per finding (`accept` | `dispute`) using the
+    provided `finding_id` values.
+2.  **Assessment-Only Invocations**: If the Task is to _assess/triage_ findings, do not change code.
+    - Output the assessment and return.
+    - The runtime orchestrates dispute routing/arbitration and then re-invokes `@Builder` with a concrete remediation
+      Task.
+3.  **Disputes**: Do not implement disputed changes until `@Lead` (or the originating reviewer, when routed) resolves the
+    dispute.
+
 ## Phase 2: Implementation
 
 1.  **Write Code**: Implement logic.
@@ -60,7 +76,11 @@ Implement the task. Produce the required proof (tests and/or other evidence) tha
     - **Check**: Are there unrelated changes? (Reformatting, whitespace).
     - **Check**: Does it match the Task scope?
 2.  **Prepare Commit**: Follow the injected Git rules and project policy for commit scope/message/signing.
-3.  **Commit**: Submit the **Atomic Diff** with the validated commit message.
+3.  **Commit Strategy (Conditional)**:
+    - If you are addressing `@Reviewer-Lite` feedback on the same atomic commit and the commit is not pushed/shared,
+      update it via `git commit --amend`.
+    - If the commit is already pushed/shared, use fixup commits and rely on the mode's squash policy.
+4.  **Commit**: Submit the Atomic Diff with the validated commit message.
 
 </Workflow>
 

package/agents/roles/lead.md

@@ -50,19 +50,38 @@ Deliver the User Request by coordinating the Engineering Team.
 
 <Workflow>
 1.  **Clarify**: If ambiguous, ask targeted questions.
-    *   **Research Trigger**: If the request depends on external truth (official docs/specs/API details), invoke `@Librarian`.
-2.  **Assemble Team**: If `<InjectedSubAgents>` contains entries (non-empty), treat it as the allowed subagent set for this run.
+    *   **Research Trigger**: If the request depends on external truth (official docs/specs/API details),
+        invoke `@Librarian`.
+2.  **Assemble Team**: If `<InjectedSubAgents>` contains entries (non-empty), treat it as the allowed subagent set for
+    this run.
 3.  **Execute Mode**: Follow the selected mode workflow contract (provided by the Runtime) as the canonical workflow:
     *   `@Build`
     *   `@Hack`
     *   `@Review`
-    *   **Rule Pipeline**: When `@Counsel` returns rule paths, instruct the Runtime to load/hydrate rule content and inject `{{injected_rules}}` into `@Planner` and any reviewers used.
-        - Inject a **role-appropriate subset** of rules per reviewer (Logic vs Test vs Security vs Performance vs Quality); do not inject all rules into every reviewer.
+    *   **Rule Pipeline**: When `@Counsel` returns rule paths, instruct the Runtime to load/hydrate rule content and
+        inject `{{injected_rules}}` into `@Planner`, `@Builder` (step-scoped per plan step; always include active Policy
+        rules), and any reviewers used.
+        - Inject a **role-appropriate subset** of rules per reviewer (Logic vs Test vs Security vs Performance vs
+          Quality); do not inject all rules into every reviewer.
 4.  **Track Provenance**: Track which reviewer produced which finding so follow-up questions can be routed correctly.
-5.  **Clarify Findings (Optional)**: For contested/unclear findings, request one-round clarification from the original reviewer (justify or withdraw).
-6.  **Arbitrate (Conditional)**: If reviewers deadlock, contradict each other, or repeatedly reject, request the Runtime to inject full contested rules into `<InjectedRules>` and provide minimal Tier 2 diff context for tie-breaking.
+    - When the runtime provides `finding_id` values (e.g., `invocation_id:bullet_index`), use them in responses and
+      arbitration decisions.
+5.  **Clarify Findings (Optional)**: For contested/unclear findings, request one-round clarification from the original
+    reviewer (justify or withdraw).
+6.  **Arbitrate (Conditional)**: If reviewers deadlock, contradict each other, or repeatedly reject, request the Runtime
+    to inject full contested rules into `<InjectedRules>` and provide minimal Tier 2 diff context for tie-breaking.
     *   *Precedence*: The selected mode spec defines which gates are overridable.
-7.  **Compress Loops**: In multi-cycle review loops, keep a compact "Resolved / Remaining" summary; do not carry full prior transcripts.
+    *   **Lite Dispute Arbitration (Commit-Level)**:
+        - Trigger: Builder disputes one or more `@Reviewer-Lite` findings.
+        - Runtime provides: `finding_id` + verbatim finding bullet + Builder dispute rationale + commit SHA.
+          Provide a minimal diff snippet only when needed for tie-breaking.
+        - Lead outputs: uphold (must fix) OR override (explicit risk rationale).
+        - Runtime records the decision in review/dispute artifacts.
+    *   **Panel Dispute Arbitration (Finding-Level)**:
+        - Trigger: A reviewer maintains a finding after Builder disputes and Builder still disagrees.
+        - Lead arbitrates once per finding; the ruling is final for that finding (recorded in artifacts).
+7.  **Compress Loops**: In multi-cycle review loops, keep a compact "Resolved / Remaining" summary; do not carry full
+    prior transcripts.
 </Workflow>
 
 <Constraints>

package/agents/roles/reviewer/BASE.md

@@ -1,6 +1,7 @@
 **Hard Blocks**:
 
 - [ ] **Evidence**: Cite file paths + line numbers (or plan step numbers) for every finding.
+- [ ] **Commit Message Evidence**: For commit-message findings, cite the commit SHA and/or subject (from `Commit Message`).
 - [ ] **One Finding Per Bullet**: Each bullet is one sentence with evidence and a short fix hint.
 - [ ] **Negative Reporting**: Only list violations. Do not include praise or "looks good" notes.
 - [ ] Never fix the artifact yourself.

package/agents/roles/reviewer/OUTPUT_FORMAT.md

@@ -1,4 +1,7 @@
-**Result**: Markdown bullet list only (no paragraphs).
+**Result**: Markdown top-level bullet list only (no paragraphs).
 
-- If there are no violations, output "LGTM".
-- Never output "Approve" (or "Approved").
+- Output MUST be a top-level bullet list only (no nested bullets, no paragraphs).
+- Each top-level bullet = one finding.
+- If there are no violations, output exactly `LGTM`.
+- Never output `Approve` (or `Approved`).
+- Note: The runtime may assign `finding_id` values based on top-level bullet position.