@martinffx/atelier 3.4.0 → 3.5.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@
 
 - **breaking:** rename the `recon` agent to `sentinel`. Existing Atelier configuration is migrated automatically and legacy generated files are removed during the next command.
 
+## [3.5.0](https://github.com/martinffx/atelier/compare/v3.4.0...v3.5.0) (2026-10-18)
+
+
+### Features
+
+* **code-review:** run rq as a critique, defense and ruling debate ([45ccfce](https://github.com/martinffx/atelier/commit/45ccfce6673f4eae8fc60dea5c5e0c61a28de510))
+* **code-review:** run simplicity on every review and consolidate reviewer prompts ([35b5927](https://github.com/martinffx/atelier/commit/35b59278eb6b690baa9cd95d68095e92e11d39e9))
+* **skills:** add spec-loop to run a Spec-backed Plan to a PR ([368afab](https://github.com/martinffx/atelier/commit/368afabe5e591e41bd7e0e05e118f35b775002c8))
+* **skills:** require explicit agent selection for subagents ([81dd276](https://github.com/martinffx/atelier/commit/81dd2764006b3af292cb7fb0893e091da81bba4e))
+
+
+### Bug Fixes
+
+* **code-review:** close debate protocol gaps from review ([a370713](https://github.com/martinffx/atelier/commit/a370713903f48b93ebb65f51d35001c9fecad5e5))
+* **code-review:** narrow when a finding counts as mechanical ([80551b7](https://github.com/martinffx/atelier/commit/80551b7002f6f1911f029e3710e6beb602abfa1a))
+* **spec-loop:** align Finish with the debate review ([ed671a9](https://github.com/martinffx/atelier/commit/ed671a9feb6cef7f7d2ae95bf15ff9a60622dfd8))
+* **spec-loop:** stop on blocking findings to match spec-finish ([7301061](https://github.com/martinffx/atelier/commit/7301061902d68c4a8db173fba2410986bafba414))
+
 ## [3.4.0](https://github.com/martinffx/atelier/compare/v3.3.0...v3.4.0) (2026-10-09)
 
 

package/README.md

@@ -63,6 +63,9 @@ flowchart TD
     SI --> CR[code-review]
     CR --> F[spec-finish]
     F --> PR[code-pull-request]
+    PS -->|Unattended run| SL[spec-loop]
+    SL -->|Per-batch review| SL
+    SL --> F
     SI -.->|Revise plan| P
     SI -.->|Revisit design| B
     F -.->|Issues found| SI
@@ -70,7 +73,7 @@ flowchart TD
 
 The workflow is deliberately harder to rush than an unstructured agent session. `spec-brainstorm` writes only `design.md`, and `spec-plan` writes only its selected plan output. Each skill then stops. The developer starts planning and implementation with separate requests. This records decisions when they need to survive the conversation, keeps implementation tied to an approved plan, and requires evidence before calling the work complete.
 
-Before a plan is presented, `spec-plan` runs a design review and a critical challenge as parallel subagents and notes what changed. During implementation, `spec-implement` hands tasks whose design is already settled to a subagent, keeping design-sensitive work in the main thread. Which agent handles each step is left to the harness.
+Before a plan is presented, `spec-plan` runs a design review and a critical challenge as parallel subagents and notes what changed. During implementation, `spec-implement` hands tasks whose design is already settled to a subagent, keeping design-sensitive work in the main thread. The main agent explicitly selects the agent for each step by the kind of work, per `atelier-orchestrator`.
 
 ## Grill the idea
 
@@ -84,7 +87,7 @@ Grill me on this migration plan
 
 ## Review the code
 
-[`code-review`](skills/code-review/SKILL.md) runs a multi-agent review rather than asking one agent for a general opinion. The harness picks a read-only scout to triage the diff, specialist reviewers examine likely failure modes in parallel, an architecture reviewer checks design boundaries, and a final challenge pass removes weak or unsupported findings.
+[`code-review`](skills/code-review/SKILL.md) runs a review as a debate rather than asking one agent for a general opinion. A read-only scout triages the diff, specialist Critics (always including a simplicity check) raise findings in parallel, an Author defends the change against each one, and Critics concede or maintain with evidence. A Judge rules only on what is still contested. Findings are labelled issue, suggestion, question, nitpick or praise, and as blocking or not; quotes are checked mechanically and the main agent audits what each turn did. See [the research notes](docs/research/multi-agent-debate.md).
 
 ```text
 rq             # Review the diff to main
@@ -113,7 +116,7 @@ The CLI also configures four specialist agents for Claude Code, OpenCode, Codex,
 | **Architect** | Domain modelling, system design, and architecture review |
 | **Keymaker** | Fast scaffolding of files and boilerplate from templates and existing patterns |
 
-The harness picks an agent by matching the task to its description, so workflows never name one. Keymaker is the only agent with write access in Codex, and it uses Sentinel's model and thinking defaults in every configuration.
+Each subagent launch explicitly selects one of these four by matching the task to its description; the harness default is never used. Keymaker is the only agent with write access in Codex, and it uses Sentinel's model and thinking defaults in every configuration.
 
 Run `npx @martinffx/atelier@latest --help` for CLI commands and options. Each skill contains its own operating instructions and loads when its context applies.
 
@@ -174,6 +177,7 @@ Some Atelier skills have more direct lineage:
 | [`spec-brainstorm`](skills/spec-brainstorm/SKILL.md) | Superpowers [`brainstorming`](https://github.com/obra/superpowers/tree/main/skills/brainstorming) | Adapted from its conversational discovery and section-by-section design approval. |
 | [`spec-plan`](skills/spec-plan/SKILL.md) | Superpowers [`writing-plans`](https://github.com/obra/superpowers/tree/main/skills/writing-plans) | Inspired by its explicit, verifiable implementation plans. |
 | [`spec-implement`](skills/spec-implement/SKILL.md) | Superpowers [`executing-plans`](https://github.com/obra/superpowers/tree/main/skills/executing-plans) and [`test-driven-development`](https://github.com/obra/superpowers/tree/main/skills/test-driven-development) | Inspired by plan-driven execution and test-first feedback loops. |
+| [`spec-loop`](skills/spec-loop/SKILL.md) | Superpowers [`subagent-driven-development`](https://github.com/obra/superpowers/tree/main/skills/subagent-driven-development) | Inspired by its fresh implementer per task, review after each unit, and final whole-branch review. Atelier reviews per batch. |
 | [`spec-finish`](skills/spec-finish/SKILL.md) | Superpowers [`finishing-a-development-branch`](https://github.com/obra/superpowers/tree/main/skills/finishing-a-development-branch) and [`verification-before-completion`](https://github.com/obra/superpowers/tree/main/skills/verification-before-completion) | Inspired by its validation and completion workflow. |
 | [`code-subagents`](skills/code-subagents/SKILL.md) | Superpowers [`subagent-driven-development`](https://github.com/obra/superpowers/tree/main/skills/subagent-driven-development) and [`dispatching-parallel-agents`](https://github.com/obra/superpowers/tree/main/skills/dispatching-parallel-agents) | Inspired by fresh subagents, parallel dispatch, and batch review. |
 | [`code-handoff`](skills/code-handoff/SKILL.md) | Matt Pocock's [`handoff`](https://github.com/mattpocock/skills/tree/main/skills/productivity/handoff) | Adapted from its context-preserving handoff format. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@martinffx/atelier",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "Personal development toolkit - spec-driven development, code quality, deep thinking, and ecosystem patterns",
   "type": "module",
   "bin": {

package/skills/atelier-orchestrator/SKILL.md

@@ -97,6 +97,7 @@ spec-brainstorm   → Spec-backed discovery + design → only design.md → stop
 spec-plan         → Inline conversation or only plan.json → stop
 spec-implement    → Execute approved Spec-backed Plans; track tasks
 spec-finish       → Post-implementation validation for Spec-backed Plans
+spec-loop         → Run an approved Spec-backed Plan unattended to a draft PR
 code-subagents    → Parallel dispatch for Spec-backed Plan tasks
 ```
 
@@ -124,10 +125,15 @@ choice to review. If any choice exists, use an Inline Plan.
 
 Delegate bounded, read-only work to a subagent when it would otherwise flood the main context:
 wide codebase research, finding comparable code, or independent review. Ask for a concise,
-file:line-cited summary, and read the key cited files yourself before deciding. Never name a
-specific agent; the harness chooses from agent descriptions. Do not delegate interviews or
-design dialogue with the human, lookups of a few files, or stateful debug and implementation
-loops.
+file:line-cited summary, and read the key cited files yourself before deciding. Do not delegate
+interviews or design dialogue with the human, lookups of a few files, or stateful debug and
+implementation loops.
+
+Every subagent launch must explicitly select an agent. Match the work to the descriptions of
+Atelier's agents (Sentinel, Oracle, Architect, Keymaker) and choose one. Never launch without a
+selection or rely on the harness default. Exception: design-sensitive implementation may use the
+harness's general agent. If Atelier's agents are not installed, explicitly choose the closest
+available agent by description and state the choice in the output.
 
 ## Hard Transitions
 
@@ -135,8 +141,9 @@ loops.
 |---------------------|-----------|
 | spec-brainstorm | Stop; wait for a separate spec-plan request |
 | approved Inline Plan | Stop; wait for a separate implementation request |
-| approved Spec-backed Plan | Stop; wait for a separate spec-implement request |
+| approved Spec-backed Plan | Stop; wait for a separate spec-implement or spec-loop request |
 | spec-implement | spec-finish |
+| spec-loop | spec-finish (run inside spec-loop under its unattended policy) |
 
 Do not begin implementation without an approved written plan. Spec-backed work must not
 jump from research to implementation.
@@ -195,7 +202,7 @@ If you loop 2+ times on the same issue, stop and ask the human:
 
 ## Skill Types
 
-**Process skills** (spec-brainstorm, spec-plan, spec-implement, spec-finish): Follow exactly.
+**Process skills** (spec-brainstorm, spec-plan, spec-implement, spec-loop, spec-finish): Follow exactly.
 Don't adapt away discipline.
 
 **Knowledge skills** (oracle-grill-me, oracle-domain-modelling, oracle-codebase-design): Adapt principles to

package/skills/code-review/SKILL.md

@@ -1,13 +1,21 @@
 ---
 name: code-review
-description: Multi-agent code review with parallel specialized reviewers, architecture validation, challenge validation, and durable handling of previously decided findings. Use `rq` to request a review of diffs (defaults to main branch), `rs` to respond to findings and record intentional non-fix decisions beside the relevant code. Triggers on "review this", "review my code", "code review", "check for bugs", "audit this", when examining PRs, pull requests, branches, or diffs. Always asks user before applying fixes or adding decision comments.
+description: Multi-agent code review run as a debate. Critics raise findings in parallel, an Author defends the change, Critics concede or maintain, and a Judge rules on what stays contested. Findings are classified by kind and blocking, and handled durably when previously decided. Use `rq` to request a review of diffs (defaults to main branch), `rs` to respond to findings and record intentional non-fix decisions beside the relevant code. Triggers on "review this", "review my code", "code review", "check for bugs", "audit this", when examining PRs, pull requests, branches, or diffs. Always asks user before applying fixes or adding decision comments.
 argument-hint: "rq [branch] | rs"
 user-invocable: true
 ---
 
 # Code Review Skill
 
-Multi-agent code analysis with a simplicity gate, focused reviewers, and challenge validation.
+A debate, not an opinion: Triage → Critique → Debate.
+
+- **Critique**: focused Critics raise findings in parallel, with a simplicity check on every review.
+- **Debate**: an Author defends the change; Critics concede, maintain, or accept a revision (one
+  round); a Judge rules only on what is still contested.
+- **Evidence** decides outcomes. Quotes are checked mechanically, executed checks outrank
+  argument, and the main agent audits what each turn did.
+
+Rationale and prior work: [docs/research/multi-agent-debate.md](../../docs/research/multi-agent-debate.md).
 
 Uses explicit subagent dispatch patterns from [code-subagents](../code-subagents/SKILL.md).
 
@@ -30,21 +38,21 @@ Uses explicit subagent dispatch patterns from [code-subagents](../code-subagents
 
 ## Agent Selection
 
-Dispatch each step as a subagent, but never name a specific agent. The harness chooses the
-available agent whose description best fits the step's task. Steps and the kind of work they
-need:
+Dispatch each step as a subagent and select the agent explicitly (see Delegation in `atelier-orchestrator`). Match the step's kind of work:
 
 | Step | Kind of work |
 |------|--------------|
-| Triage | Read-only recon: changed-file analysis, context retrieval, reviewer selection |
-| Reviewers | Critical analysis: evidence-based critique and failure-mode analysis |
-| Architect | Architecture, design-boundary, data-model, and API-contract review |
-| Challenge | Critical analysis: validate or reject findings |
+| Triage | Read-only recon: changed-file analysis, context retrieval, persona and check selection |
+| Critique and Rebuttal | Critical analysis: evidence-based critique and failure-mode analysis |
+| Defense | Architecture and design review: test each finding against the code and argue for the change |
+| Ruling | Critical analysis: impartial, evidence-ranked adjudication |
 
-Reviewer names such as `Security`, `Correctness`, `Maintainability`, and `PerformanceOperator` are prompt personas, not agent types.
+Critic, Author and Judge are prompt personas, not agent types. Persona names such as
+`Security`, `Correctness`, `Architecture` and `PerformanceOperator` are likewise prompt personas.
 
-`Simplicity` is a mandatory reviewer persona for migrations, refactors, and architectural
-changes. Run it before the other reviewers; do not include it in the parallel reviewer batch.
+`Simplicity` is a mandatory persona on every review. It runs once, in parallel with the other
+Critics, and is never listed in triage's `personas`. Triage picks the rest; `Architecture` is one
+of its options.
 
 ## Review Priority
 
@@ -60,16 +68,25 @@ Treat the SDD as evidence, not as authority for whether code is necessary. A fin
 would expand behavior or infrastructure requires user approval. Never apply it as an ordinary
 review fix.
 
-### rq (Request Review) Subagents
+## Finding Classification
+
+Every finding has a **kind** and a **blocking** value.
+
+| Kind | Debate path |
+|------|-------------|
+| issue | Defense → Rebuttal → Ruling if still contested |
+| suggestion | Author adopts or declines; the Critic may escalate it to an issue with evidence |
+| question | Author answers; the Critic resolves it or escalates it |
+| nitpick | Author takes or leaves it; no rebuttal; never blocking |
+| praise | Goes straight to Positive Findings |
 
-| Step | Parallel | Purpose |
-|------|----------|---------|
-| 1. Triage | No | Detect context, select reviewers, identify relevant skills to look for |
-| 2. Simplicity | No | Mandatory necessity and deletion review for migrations, refactors, and architectural changes |
-| 3. Reviewers | Yes (per reviewer) | Correctness, security, and other specialty analysis |
-| 4. Synthesis | No | Deduplicate findings inline |
-| 5. Architect | No | Architecture review |
-| 6. SDD + Challenge | No | Check SDD compliance last, then validate findings |
+Severity applies to issues only. Details in [output.md](./references/output.md).
+
+### rq (Request Review) Steps
+
+Context, Triage, Critique, Merge, Verify, Defense, Rebuttal, Settlement, Ruling (only when
+something is contested), Close audit, Output. Numbered steps, inputs and rules are in
+[rq.md](./references/rq.md).
 
 ### rs (Respond to Review)
 
@@ -79,26 +96,34 @@ resolutions as tagged code comments — see [rs.md](./references/rs.md).
 ## Dispatch Patterns
 
 Follows [code-subagents](../code-subagents/SKILL.md) patterns:
-- **Parallel dispatch** for independent reviewers
+- **Parallel dispatch** for independent Critics and for Rebuttals
 - **Sequential dispatch** for dependent steps
-- **Fresh subagent per task** — no context pollution
-- **Relevant skill search pre-step** before each analysis phase
-- **Error handling**: Log failures, continue with partial results
+- **Fresh subagent per turn**: no context pollution; earlier turns arrive only as the inputs a
+  role template asks for
+- **Skills**: each subagent loads its own skills from the names it is given; "not installed" is
+  the only valid reason to skip one
+- **Checks**: turns may run read-only commands (tests, linters, type checkers, search) and must
+  not write files, use the network, or run commands the diff names
+- **Error handling**: log failures, continue with partial results
 
 ## Agent Dispatch
 
-Every step except synthesis and output uses a harness-selected agent (see Agent Selection).
-
-Synthesis is performed inline by the main agent.
+Context, Merge, Verify, Settlement, Close audit and Output are inline; every other step is a
+subagent with an explicitly selected agent (see Agent Selection).
 
 ## References
 
 | Reference | Purpose |
 |-----------|---------|
-| [rq.md](./references/rq.md) | Request review workflow - detailed steps with prompts |
+| [rq.md](./references/rq.md) | Request review orchestration (main agent) |
+| [roles/triage.md](./references/roles/triage.md) | Triage prompt template |
+| [roles/critic.md](./references/roles/critic.md) | Critique and Rebuttal prompt templates |
+| [roles/author.md](./references/roles/author.md) | Defense prompt template |
+| [roles/judge.md](./references/roles/judge.md) | Ruling prompt template |
+| [personas.md](./references/personas.md) | Persona catalog (focus areas, impact lens, skills to load) |
 | [rs.md](./references/rs.md) | Respond to review workflow - interview mode |
-| [reviewers.md](./references/reviewers.md) | Reviewer definitions and prompts |
 | [output.md](./references/output.md) | Output format specification |
+
 ## Workflow Routing
 
 - No arguments, `rq`, or bare branch → [rq.md](./references/rq.md)

package/skills/code-review/references/output.md

@@ -10,8 +10,10 @@
 
 ## Statistics
 - Files reviewed: N
-- Findings: N Critical, N High, N Medium, N Low
+- Findings: N blocking, N non-blocking (N issue, N suggestion, N nitpick)
+- Issues by severity: N Critical, N High, N Medium, N Low
 - Pre-existing: N | Introduced: N
+- Debated: N (upheld N, modified N, withdrawn N)
 - Honored decisions: N
 
 ## Unnecessary scope
@@ -30,34 +32,52 @@
 
 - {Changes needed so the SDD records the smaller result, or `None`}
 
-## Critical (Fix before merge)
+## Blocking (fix before merge)
 
-### {Finding Title}
+### issue (blocking, Critical): {Finding Title}
 
 - **Location**: `file:line`
+- **Kind**: issue
+- **Blocking**: Yes
 - **Severity**: Critical
 - **Pre-existing**: No
 - **Issue**: {What's wrong}
 - **Impact**: {Why this matters}
+- **Debate**: {Author confirmed | Author disputed → Critic maintained → Judge upheld | …}
 - **Reasoning**:
   <details>
   <summary>Extended reasoning</summary>
-  {Detailed explanation of why this was flagged}
+  {Detailed explanation, including the exchange}
   </details>
 - **Suggestion**: {How to fix}
 - **Requires user approval**: {Yes when the suggestion expands behavior or infrastructure; otherwise No}
+- **Mechanical**: {Yes when the fix keeps behavior identical, stays local, and needs no judgment; otherwise No}
 - **Prior decision reopened**: {Why the recorded rationale no longer applies; omit when not applicable}
 
-## High Priority
+## Non-blocking
 
-### {Finding Title}
-{Same structure}
+Issues ordered by severity, then suggestions, then nitpicks.
 
-## Medium Priority
+### issue (High): {Finding Title}
 {Same structure}
 
-## Low Priority
-{Same structure}
+### suggestion: {Finding Title}
+{Same structure; no severity}
+
+### nitpick: {Finding Title}
+{Location, Issue, Suggestion only}
+
+## Follow-ups
+
+- {Valid findings outside this change: kind, location, one line}
+
+## Answered questions
+
+- `{file:line}` {Question} → {Answer}
+
+## Withdrawn in debate
+
+- `{id}` {Title} — {reason} (evidence: {code|test|sdd|intent|decision}; settled by {Critic concession | Judge})
 
 ## Positive Findings
 
@@ -68,33 +88,71 @@
 ## Honored Decisions
 
 - `{comment-file}:{line}` — {Concern}: {Short rationale and why it still applies}
+
+## Audit
+
+<details>
+<summary>Debate audit</summary>
+
+- Working tree: {unchanged | changed — all `test` evidence voided}
+- Turns: {per turn: commands run, re-runs matched / total, violations}
+- Evidence voided: {what and why, or none}
+- Unresolved: {ids of contested or unruled items, rendered in Blocking or Non-blocking, or none}
+</details>
 ```
 
-Omit the **Honored Decisions** section when there are no honored decisions. Keep each entry to
-one compact bullet; do not repeat the full finding, impact, reasoning, or suggestion.
-Severity and pre-existing/introduced statistics count active findings only.
-Always render the four simplicity sections, using `None` when no evidence supports an item.
+An unresolved item (Judge failed, or its decisive evidence was voided) renders in Blocking or
+Non-blocking by its `blocking` value, with `**Debate**: contested, unruled` and both positions in
+the reasoning. A nitpick's Debate field reads `Author took` or `Author left`.
+
+Omit **Follow-ups**, **Answered questions**, **Withdrawn in debate**, **Honored Decisions** and
+the nitpick group when they have no items. Keep **Audit** short: one line per turn.
+
+Honored decisions are a compact bullet each; do not repeat the full finding. Severity and
+pre-existing/introduced counts cover active findings only. Always render the four simplicity
+sections, using `None` when no evidence supports an item.
+
+`praise` findings appear only under Positive Findings.
 
 ---
 
 ## Inline Finding Format
 
-For each finding, provide inline comment style:
+For each finding, provide inline comment style, prefixed with its kind so it pastes into a
+PR comment:
 
 ```
-[{file}:{line}] {Finding Title}
-Severity: {Critical/High/Medium/Low}
+[{file}:{line}] {kind} ({blocking|non-blocking}, {severity}): {Finding Title}
 Pre-existing: {Yes/No}
 Issue: {Brief description}
 Reasoning: {Why this matters}
 Suggestion: {Fix}
+Debate: {outcome}
 Requires user approval: {Yes/No}
+Mechanical: {Yes/No}
 Prior decision reopened: {Why the recorded rationale no longer applies; omit when not applicable}
 ```
 
+Omit severity for anything that is not an issue.
+
 ---
 
-## Severity Definitions
+## Kinds
+
+| Kind | Meaning | Blocking? |
+|------|---------|-----------|
+| issue | Something is wrong or risky | Yes or no |
+| suggestion | A better approach; the code works as written | Yes or no |
+| question | The reviewer cannot tell; states what answer would make it an issue | Never until escalated |
+| nitpick | Style or convention, backed by a documented rule | Never |
+| praise | Worth keeping | Never |
+
+`follow_up` marks a valid finding that is outside this change; it is listed under Follow-ups and
+not fixed here.
+
+---
+
+## Severity Definitions (issues only)
 
 | Severity | When to use | Examples |
 |----------|------------|----------|
@@ -115,7 +173,7 @@ Prior decision reopened: {Why the recorded rationale no longer applies; omit whe
 **Marking pre-existing:**
 - Check if the line was modified in the current diff
 - If unchanged but flagged, mark as pre-existing
-- Pre-existing findings are informational, not blocking
+- Pre-existing findings are informational and non-blocking
 
 ---
 
@@ -124,9 +182,10 @@ Prior decision reopened: {Why the recorded rationale no longer applies; omit whe
 Each finding includes a collapsible section with:
 
 1. **Why flagged**: What triggered the finding (pattern, heuristic, context)
-2. **Verification**: How it was validated (static analysis, pattern match, context)
-3. **Evidence**: Code snippets, references, or examples
-4. **Alternative view**: If uncertain, what else to consider
+2. **Verification**: How it was validated (executed check, verified quote, static analysis)
+3. **Evidence**: Code snippets, check output, or references
+4. **Debate**: The Author's response, the Critic's rebuttal, and the Judge's ruling, when any
+5. **Alternative view**: If uncertain, what else to consider
 
 When a recorded decision is reopened, also identify the comment location and the evidence that
 invalidated its rationale or met its reconsideration condition.
@@ -138,13 +197,16 @@ Example:
 
 **Why flagged**: The `query` parameter is directly interpolated into SQL string without parameterization.
 
-**Verification**: Pattern match detected: `f"SELECT * FROM {table}"` - Python f-string in SQL context.
+**Verification**: Verified quote at `src/db.py:42`; no parameter binding on the path (checked with `grep -n "execute(" src/db.py`).
 
-**Evidence**: 
+**Evidence**:
 ```python
 query = f"SELECT * FROM users WHERE id = {user_id}"  # Line 42
 ```
 
+**Debate**: Author disputed (claimed upstream validation); Critic maintained — validation at
+`src/api.py:18` runs only on the legacy route. Judge upheld.
+
 **Alternative view**: If using a query builder or ORM, check if it handles escaping internally.
 </details>
 ```
@@ -161,8 +223,10 @@ Implements OAuth login flow with token refresh. Generally well-structured with p
 
 ## Statistics
 - Files reviewed: 1
-- Findings: 1 Critical, 1 High, 0 Medium, 2 Low
-- Pre-existing: 1 | Introduced: 3
+- Findings: 1 blocking, 2 non-blocking (2 issue, 0 suggestion, 1 nitpick)
+- Issues by severity: 1 Critical, 1 High, 0 Medium, 0 Low
+- Pre-existing: 1 | Introduced: 2
+- Debated: 2 (upheld 1, modified 0, withdrawn 1)
 - Honored decisions: 0
 
 ## Unnecessary scope
@@ -181,63 +245,80 @@ None
 
 - None
 
-## Critical (Fix before merge)
+## Blocking (fix before merge)
 
-### Token stored in localStorage
+### issue (blocking, Critical): Token stored in localStorage
 
 - **Location**: `src/auth/login.ts:45`
+- **Kind**: issue
+- **Blocking**: Yes
 - **Severity**: Critical
 - **Pre-existing**: No
 - **Issue**: Access token stored in localStorage, vulnerable to XSS
 - **Impact**: Any XSS vulnerability exposes user tokens
+- **Debate**: Author disputed → Critic maintained → Judge upheld
 - **Reasoning**:
   <details>
   <summary>Extended reasoning</summary>
-  
+
   **Why flagged**: localStorage is accessible to any JavaScript on the page.
-  
-  **Verification**: Direct localStorage API usage detected.
-  
+
+  **Verification**: Verified quote at `src/auth/login.ts:45`.
+
   **Evidence**:
   ```typescript
   localStorage.setItem('accessToken', token); // Line 45
   ```
-  
+
+  **Debate**: Author argued the CSP blocks inline scripts; Critic showed `script-src 'unsafe-inline'`
+  at `src/server.ts:9`. Judge upheld.
+
   **Alternative view**: If using httpOnly cookies is not possible, consider short-lived tokens with refresh rotation.
   </details>
 - **Suggestion**: Use httpOnly cookies or secure session storage
+- **Requires user approval**: No
+- **Mechanical**: No
 
-## High Priority
+## Non-blocking
 
-### Token validation on every request
+### issue (High): Token validation on every request
 
 - **Location**: `src/auth/middleware.ts:12`
 - **Severity**: High
 - **Pre-existing**: Yes
 - **Issue**: Token validated against auth server on every request
 - **Impact**: Adds 50-200ms latency per request
+- **Debate**: Author confirmed
 
-## Low Priority
-
-### Missing JSDoc on public function
+### nitpick: Missing JSDoc on public function
 
 - **Location**: `src/auth/login.ts:23`
-- **Severity**: Low
-- **Pre-existing**: No
-- **Issue**: `validateToken` lacks documentation
+- **Issue**: `validateToken` lacks documentation (repo rule: `docs/conventions.md` requires JSDoc on exports)
 
-### Inconsistent naming: userId vs user_id
+## Answered questions
 
-- **Location**: `src/auth/login.ts:67`
-- **Severity**: Low
-- **Pre-existing**: Yes
-- **Issue**: Mixed snake_case and camelCase in same file
+- `src/auth/login.ts:60` Why a 15-minute expiry? → `docs/auth.md:12` fixes it to match the refresh window.
+
+## Withdrawn in debate
+
+- `f4` Inconsistent naming: userId vs user_id — Critic conceded: `.eslintrc` allows both (evidence: code; settled by Critic concession).
 
 ## Positive Findings
 
 - Clean separation of OAuth flow into dedicated functions
 - Proper error handling with typed error classes
 - Token refresh logic handles edge cases well
+
+## Audit
+
+<details>
+<summary>Debate audit</summary>
+
+- Working tree: unchanged
+- Turns: Author 3 commands, 1 re-run matched 1/1; Security rebuttal 1 command; Judge 0 commands
+- Evidence voided: none
+- Unresolved: none
+</details>
 ```
 
 ---
@@ -250,3 +331,4 @@ None
 4. **Positive findings** help balance the review tone
 5. **Honored decisions** stay out of active severity counts and are summarized without restating the finding
 6. **Expansion findings** require user approval even when an SDD proposes the expansion
+7. **Blocking** means the change should not merge until resolved; spec-finish reads it directly