@izkac/forgekit 0.3.12 → 0.3.14

package/vendor/skills/thorough-code-review/examples.md

@@ -1,133 +1,133 @@
-# Thorough code review — examples
-
-## 1. Full review (all lenses, branch diff)
-
-**User:** "Review my branch before I open a PR."
-
-**Agent:**
-
-1. Ask scope → user picks "Branch vs main".
-2. Scaffold: `review new mercury-vat --type branch` (captures id, timestamp, base/head SHAs).
-3. Signals pre-flight: `review signals --type branch` → run the listed typecheck/test commands; 1 grounded finding from a failing test.
-4. All lenses active; dedupe pre-flight (smells).
-5. Scout → 8 tentative findings (small scope, single pass).
-6. Coverage pass → confirms `performance` lens clean (no loops/queries added); records ledger.
-7. Eight parallel skeptic subagents; one Critical `false_positive` triggers a second skeptic (agrees).
-8. Fill JSON → `review render` → `review export`.
-
-**Excerpt — executive summary (`summary.headline`):**
-
-```markdown
-Reviewed 4 files on `feature/vat` vs `main`. 8 tentative → 3 confirmed, 2 downgraded,
-3 false positives. No open critical. Top action: add test for zero-rate edge case.
-```
-
-## 2. Security-only narrow review
-
-**User:** "Run a security review on `services/persona/src/routes/profile.ts` --security"
-
-**Agent:**
-
-1. Scope: single path (no ask needed — explicit).
-2. Lenses: `security` only — skip dedupe pre-flight.
-3. Scout with security checklist + project accepted-risks digest (if any).
-4. Severity-routed skeptic dispatch (dedicated for critical, batched/inline otherwise; within budget).
-5. Report: `.reviews/20260605T162000Z-persona-profile-security-review.json`
-
-## 3. Fix verification after patches
-
-**User:** "I fixed the findings — re-verify."
-
-**Agent:**
-
-1. Load `.reviews/20260605T161200Z-mercury-vat-review.json`.
-2. Three findings were `confirmed` or `downgraded`.
-3. `--verify-fixes` flow: skeptics with `MODE=reverify`, severity-routed and batched like initial mode.
-4. Write `.reviews/20260605T170000Z-mercury-vat-reverify.json`:
-
-```json
-{
-  "review_id": "20260605T170000Z-mercury-vat-reverify",
-  "kind": "reverify",
-  "parent_report": "20260605T161200Z-mercury-vat-review",
-  "findings": [
-    {
-      "id": "F-002",
-      "verdict": "resolved",
-      "verdict_reason": "Guard added at line 88; test added in vat-verify.test.ts"
-    },
-    {
-      "id": "F-005",
-      "verdict": "still_open",
-      "verdict_reason": "Error path still swallows exception at line 102"
-    }
-  ]
-}
-```
-
-## 4. CI usage
-
-After a review completes:
-
-```bash
-# Validate latest report
-review export
-
-# Pin specific report in CI
-review export --file .reviews/20260605T161200Z-mercury-vat-review.json
-
-# Fail pipeline on open critical
-review export --file .reviews/20260605T161200Z-mercury-vat-review.json --fail-on critical
-
-# Copy artefacts for upload
-review export --out ./ci-artifacts/review
-```
-
-**GitHub Actions sketch:**
-
-```yaml
-- name: Validate code review report
-  run: review export --file .reviews/pr-review.json --fail-on critical
-```
-
-## 5. Skeptic false-positive example
-
-**Scout F-003:** "Race condition in idempotency check-then-act."
-
-**Skeptic verdict:** `false_positive`
-
-**Reason:** "Handler uses unique index `create` collision path; integration test `idempotency.test.ts` asserts single side effect under concurrent requests. Non-atomic window exists but duplicate work is prevented at persistence layer."
-
-→ Appears in Appendix A, not main findings.
-
-## 6. Dedupe pre-flight example
-
-**Scope:** `services/*/src/middleware/idempotency.ts` (smells in "all" review)
-
-**Pre-flight dup-001:** Same idempotency middleware copied in cdp, mercury, persona.
-
-→ Merged as tentative `dup-001` / smells / Important → skeptic confirms → main report suggests shared package extraction.
-
-## 7. Signals pre-flight grounds the scout
-
-**User:** "Review `services/persona` --tests --contracts"
-
-**Agent:**
-
-```bash
-review signals --paths services/persona
-#   Workspaces: your-workspace
-#   npm run typecheck --workspace=your-workspace
-#   npm run test --workspace=your-workspace
-#   Notes: Contract/route files touched — verify OpenAPI route-parity (contracts lens).
-```
-
-`npm run test --workspace=your-workspace` fails one route-parity case → grounded `F-001` / contracts / Important, `confidence: high`, tool output as evidence. Recorded in JSON `signals.tools`.
-
-## 8. Risk-weighted second skeptic
-
-**Scout F-002:** "IDOR on `GET /profile/:id`" — `severity: critical`, `phase1_confidence: high`.
-
-**Skeptic 1 verdict:** `false_positive` ("CLM binds actor server-side").
-
-→ Dangerous quadrant (critical + high-confidence dismissed). A **second independent skeptic** is dispatched blind. It also returns `false_positive`, citing ADR-0048 and the signed-JWT actor binding. `second_opinion.agrees: true` → finding stays in Appendix A, now with two concurring dismissals. Had they disagreed, it would route to `needs_decision`.
+# Thorough code review — examples
+
+## 1. Full review (all lenses, branch diff)
+
+**User:** "Review my branch before I open a PR."
+
+**Agent:**
+
+1. Ask scope → user picks "Branch vs main".
+2. Scaffold: `review new mercury-vat --type branch` (captures id, timestamp, base/head SHAs).
+3. Signals pre-flight: `review signals --type branch` → run the listed typecheck/test commands; 1 grounded finding from a failing test.
+4. All lenses active; dedupe pre-flight (smells).
+5. Scout → 8 tentative findings (small scope, single pass).
+6. Coverage pass → confirms `performance` lens clean (no loops/queries added); records ledger.
+7. Eight parallel skeptic subagents; one Critical `false_positive` triggers a second skeptic (agrees).
+8. Fill JSON → `review render` → `review export`.
+
+**Excerpt — executive summary (`summary.headline`):**
+
+```markdown
+Reviewed 4 files on `feature/vat` vs `main`. 8 tentative → 3 confirmed, 2 downgraded,
+3 false positives. No open critical. Top action: add test for zero-rate edge case.
+```
+
+## 2. Security-only narrow review
+
+**User:** "Run a security review on `services/persona/src/routes/profile.ts` --security"
+
+**Agent:**
+
+1. Scope: single path (no ask needed — explicit).
+2. Lenses: `security` only — skip dedupe pre-flight.
+3. Scout with security checklist + project accepted-risks digest (if any).
+4. Severity-routed skeptic dispatch (dedicated for critical, batched/inline otherwise; within budget).
+5. Report: `.reviews/20260605T162000Z-persona-profile-security-review.json`
+
+## 3. Fix verification after patches
+
+**User:** "I fixed the findings — re-verify."
+
+**Agent:**
+
+1. Load `.reviews/20260605T161200Z-mercury-vat-review.json`.
+2. Three findings were `confirmed` or `downgraded`.
+3. `--verify-fixes` flow: skeptics with `MODE=reverify`, severity-routed and batched like initial mode.
+4. Write `.reviews/20260605T170000Z-mercury-vat-reverify.json`:
+
+```json
+{
+  "review_id": "20260605T170000Z-mercury-vat-reverify",
+  "kind": "reverify",
+  "parent_report": "20260605T161200Z-mercury-vat-review",
+  "findings": [
+    {
+      "id": "F-002",
+      "verdict": "resolved",
+      "verdict_reason": "Guard added at line 88; test added in vat-verify.test.ts"
+    },
+    {
+      "id": "F-005",
+      "verdict": "still_open",
+      "verdict_reason": "Error path still swallows exception at line 102"
+    }
+  ]
+}
+```
+
+## 4. CI usage
+
+After a review completes:
+
+```bash
+# Validate latest report
+review export
+
+# Pin specific report in CI
+review export --file .reviews/20260605T161200Z-mercury-vat-review.json
+
+# Fail pipeline on open critical
+review export --file .reviews/20260605T161200Z-mercury-vat-review.json --fail-on critical
+
+# Copy artefacts for upload
+review export --out ./ci-artifacts/review
+```
+
+**GitHub Actions sketch:**
+
+```yaml
+- name: Validate code review report
+  run: review export --file .reviews/pr-review.json --fail-on critical
+```
+
+## 5. Skeptic false-positive example
+
+**Scout F-003:** "Race condition in idempotency check-then-act."
+
+**Skeptic verdict:** `false_positive`
+
+**Reason:** "Handler uses unique index `create` collision path; integration test `idempotency.test.ts` asserts single side effect under concurrent requests. Non-atomic window exists but duplicate work is prevented at persistence layer."
+
+→ Appears in Appendix A, not main findings.
+
+## 6. Dedupe pre-flight example
+
+**Scope:** `services/*/src/middleware/idempotency.ts` (smells in "all" review)
+
+**Pre-flight dup-001:** Same idempotency middleware copied in cdp, mercury, persona.
+
+→ Merged as tentative `dup-001` / smells / Important → skeptic confirms → main report suggests shared package extraction.
+
+## 7. Signals pre-flight grounds the scout
+
+**User:** "Review `services/persona` --tests --contracts"
+
+**Agent:**
+
+```bash
+review signals --paths services/persona
+#   Workspaces: your-workspace
+#   npm run typecheck --workspace=your-workspace
+#   npm run test --workspace=your-workspace
+#   Notes: Contract/route files touched — verify OpenAPI route-parity (contracts lens).
+```
+
+`npm run test --workspace=your-workspace` fails one route-parity case → grounded `F-001` / contracts / Important, `confidence: high`, tool output as evidence. Recorded in JSON `signals.tools`.
+
+## 8. Risk-weighted second skeptic
+
+**Scout F-002:** "IDOR on `GET /profile/:id`" — `severity: critical`, `phase1_confidence: high`.
+
+**Skeptic 1 verdict:** `false_positive` ("CLM binds actor server-side").
+
+→ Dangerous quadrant (critical + high-confidence dismissed). A **second independent skeptic** is dispatched blind. It also returns `false_positive`, citing ADR-0048 and the signed-JWT actor binding. `second_opinion.agrees: true` → finding stays in Appendix A, now with two concurring dismissals. Had they disagreed, it would route to `needs_decision`.

package/vendor/skills/thorough-code-review/reference/accepted-risks.md

@@ -1,26 +1,26 @@
-# Accepted risks digest (inject into every scout & skeptic packet)
-
-Project-specific list of risks that ADRs (or equivalent) have **formally accepted**. Inject into every scout and skeptic packet so subagents do not re-escalate them.
-
-**Do not flag these as findings** unless a listed re-open trigger has fired; cite the decision record instead. If a claim is not covered here, check the project's ADR / decision docs before confirming a security finding.
-
-**Maintenance:** update whenever a decision that accepts, changes, or re-opens a risk is recorded.
-
-## Template
-
-```markdown
-## DEC-NNNN — short title
-
-Accepted, NOT findings:
-- …
-
-**Re-open triggers:** …
-```
-
-## Cross-cutting patterns to check (not accepted risks)
-
-List project invariants that *are* fair game for findings (idempotency, route-parity tests, index rules, etc.).
-
----
-
-See [examples/accepted-risks-janus.md](../examples/accepted-risks-janus.md) for a filled-in digest from the originating monorepo.
+# Accepted risks digest (inject into every scout & skeptic packet)
+
+Project-specific list of risks that ADRs (or equivalent) have **formally accepted**. Inject into every scout and skeptic packet so subagents do not re-escalate them.
+
+**Do not flag these as findings** unless a listed re-open trigger has fired; cite the decision record instead. If a claim is not covered here, check the project's ADR / decision docs before confirming a security finding.
+
+**Maintenance:** update whenever a decision that accepts, changes, or re-opens a risk is recorded.
+
+## Template
+
+```markdown
+## DEC-NNNN — short title
+
+Accepted, NOT findings:
+- …
+
+**Re-open triggers:** …
+```
+
+## Cross-cutting patterns to check (not accepted risks)
+
+List project invariants that *are* fair game for findings (idempotency, route-parity tests, index rules, etc.).
+
+---
+
+See [examples/accepted-risks-janus.md](../examples/accepted-risks-janus.md) for a filled-in digest from the originating monorepo.

package/vendor/skills/thorough-code-review/reference/lenses.md

@@ -1,96 +1,96 @@
-# Review lenses
-
-Load **only** the sections matching active lenses. Default invocation uses all sections.
-
-**Ground first.** Before hand-reading for any lens, ingest the [signals pre-flight](signals-preflight.md) — typecheck, lint, and test output convert directly into grounded findings (especially for smells, contracts, tests, and errors).
-
-## security
-
-- AuthN/AuthZ: who can call this? Is identity bound to the credential?
-- Injection: SQL, NoSQL, command, path, template, XSS (if user-facing output)
-- Secrets: hardcoded keys, logs, error messages, env leakage
-- Crypto: constant-time compare, algorithm choice, key rotation surface
-- Input validation at trust boundaries
-- SSRF, open redirects, CORS misconfiguration
-- Dependency vulnerabilities in changed manifests (note only; do not auto-audit whole tree unless scope includes lockfiles)
-- Example (HMAC): body-only signatures without method/path binding? Idempotency caches errors? Headers outside signed envelope?
-
-
-## correctness
-
-- Logic errors, off-by-one, wrong operator, inverted conditions
-- Null/undefined/empty handling
-- Race conditions, check-then-act, missing transactions
-- Idempotency and retry semantics
-- Money: integer cents, rounding, currency conversion
-- Date/time/timezone handling
-- Error paths that leave inconsistent state
-
-## smells
-
-**Pre-flight (before this checklist):** the dedupe scan is the smells-lens arm of the [signals pre-flight](signals-preflight.md). Read the project `dedupe` skill and run a **read-only** duplicate scan scoped to the review target. Emit `dup-###` tentative findings; include summary in report appendix. Do not edit code.
-
-Then apply:
-
-- Copy-paste blocks (rule of three)
-- Near-identical functions differing only by parameter
-- Magic numbers/strings repeated across files
-- Dead code, unused exports, unreachable branches
-- Overly long functions/files **introduced or grown by this change**
-- Parallel switch/if chains that could share structure
-
-## architecture
-
-- Single responsibility per module
-- Layer violations (domain importing transport, etc.)
-- Coupling across service boundaries
-- Hidden dependencies, global mutable state
-- Does design match existing patterns in the repo?
-- Scope creep beyond stated goal
-
-## performance
-
-- N+1 queries or sequential remote calls in loops
-- Unbounded memory (loading full collections)
-- Missing indexes for new query patterns
-- Hot-path allocations or sync I/O
-- Missing pagination on list endpoints
-
-## tests
-
-- Do tests assert behaviour, not implementation details?
-- Mock-heavy tests that don't catch real regressions
-- Missing cases for new branches or error paths
-- Flaky patterns (timing, ordering assumptions)
-- Integration coverage where unit tests insufficient
-- Tests excluded from runner (wrong vitest `include` path)
-
-## contracts
-
-- OpenAPI/registry drift vs mounted routes
-- Breaking API or shared package export changes
-- Versioning and migration notes
-- Client packages updated when server contract changes
-
-## errors
-
-- Swallowed errors (empty catch, ignored return)
-- Wrong error type or status code mapping
-- Leaking internal details to clients
-- Missing error logging with correlation context
-
-## maintainability
-
-- Naming clarity and consistency with codebase
-- Comment quality (why, not what)
-- File organization and import hygiene
-- Type safety gaps (if typed language)
-- Documentation for non-obvious public behaviour
-
-## Project hooks (all lenses)
-
-When reviewing a project with agent docs / ADRs:
-
-1. Read project agent instructions (`AGENTS.md` or equivalent) for coding guidelines
-2. Check ADRs / [accepted-risks.md](accepted-risks.md) before confirming security findings
-3. Note cross-package impact if shared libraries change
+# Review lenses
+
+Load **only** the sections matching active lenses. Default invocation uses all sections.
+
+**Ground first.** Before hand-reading for any lens, ingest the [signals pre-flight](signals-preflight.md) — typecheck, lint, and test output convert directly into grounded findings (especially for smells, contracts, tests, and errors).
+
+## security
+
+- AuthN/AuthZ: who can call this? Is identity bound to the credential?
+- Injection: SQL, NoSQL, command, path, template, XSS (if user-facing output)
+- Secrets: hardcoded keys, logs, error messages, env leakage
+- Crypto: constant-time compare, algorithm choice, key rotation surface
+- Input validation at trust boundaries
+- SSRF, open redirects, CORS misconfiguration
+- Dependency vulnerabilities in changed manifests (note only; do not auto-audit whole tree unless scope includes lockfiles)
+- Example (HMAC): body-only signatures without method/path binding? Idempotency caches errors? Headers outside signed envelope?
+
+
+## correctness
+
+- Logic errors, off-by-one, wrong operator, inverted conditions
+- Null/undefined/empty handling
+- Race conditions, check-then-act, missing transactions
+- Idempotency and retry semantics
+- Money: integer cents, rounding, currency conversion
+- Date/time/timezone handling
+- Error paths that leave inconsistent state
+
+## smells
+
+**Pre-flight (before this checklist):** the dedupe scan is the smells-lens arm of the [signals pre-flight](signals-preflight.md). Read the project `dedupe` skill and run a **read-only** duplicate scan scoped to the review target. Emit `dup-###` tentative findings; include summary in report appendix. Do not edit code.
+
+Then apply:
+
+- Copy-paste blocks (rule of three)
+- Near-identical functions differing only by parameter
+- Magic numbers/strings repeated across files
+- Dead code, unused exports, unreachable branches
+- Overly long functions/files **introduced or grown by this change**
+- Parallel switch/if chains that could share structure
+
+## architecture
+
+- Single responsibility per module
+- Layer violations (domain importing transport, etc.)
+- Coupling across service boundaries
+- Hidden dependencies, global mutable state
+- Does design match existing patterns in the repo?
+- Scope creep beyond stated goal
+
+## performance
+
+- N+1 queries or sequential remote calls in loops
+- Unbounded memory (loading full collections)
+- Missing indexes for new query patterns
+- Hot-path allocations or sync I/O
+- Missing pagination on list endpoints
+
+## tests
+
+- Do tests assert behaviour, not implementation details?
+- Mock-heavy tests that don't catch real regressions
+- Missing cases for new branches or error paths
+- Flaky patterns (timing, ordering assumptions)
+- Integration coverage where unit tests insufficient
+- Tests excluded from runner (wrong vitest `include` path)
+
+## contracts
+
+- OpenAPI/registry drift vs mounted routes
+- Breaking API or shared package export changes
+- Versioning and migration notes
+- Client packages updated when server contract changes
+
+## errors
+
+- Swallowed errors (empty catch, ignored return)
+- Wrong error type or status code mapping
+- Leaking internal details to clients
+- Missing error logging with correlation context
+
+## maintainability
+
+- Naming clarity and consistency with codebase
+- Comment quality (why, not what)
+- File organization and import hygiene
+- Type safety gaps (if typed language)
+- Documentation for non-obvious public behaviour
+
+## Project hooks (all lenses)
+
+When reviewing a project with agent docs / ADRs:
+
+1. Read project agent instructions (`AGENTS.md` or equivalent) for coding guidelines
+2. Check ADRs / [accepted-risks.md](accepted-risks.md) before confirming security findings
+3. Note cross-package impact if shared libraries change

package/vendor/skills/thorough-code-review/reference/phase1-scout.md

@@ -1,62 +1,62 @@
-# Phase 1 — Scout pass
-
-You are the **scout** for a thorough code review. Discovery only — no fix suggestions yet.
-
-## Input packet
-
-- **Scope:** {SCOPE_TYPE} — {SCOPE_DESCRIPTION}
-- **Lenses:** {LENS_LIST}
-- **Git range / paths:** {SCOPE_DETAIL}
-- **Accepted risks:** {ACCEPTED_RISKS_DIGEST}  <!-- contents of reference/accepted-risks.md — do not raise findings it covers unless a re-open trigger fired -->
-
-## Steps
-
-1. Ingest the **signals pre-flight** results ([signals-preflight.md](signals-preflight.md)) — tool-confirmed failures are grounded findings; start from them.
-2. Read the files in scope (`git diff`, paths, or commits as applicable). **Partition large scopes** — see below.
-3. If **smells** lens is active: run dedupe pre-flight (read `dedupe` skill; report-only scan on scope).
-4. For each active lens, read the checklist from [lenses.md](lenses.md) and inspect code.
-5. Emit **tentative findings** — de-duplicate overlapping claims before handing off.
-6. Do **not** assign final verdicts; Phase 2 skeptics do that. The coverage pass ([phase1c-coverage.md](phase1c-coverage.md)) runs after you to catch misses.
-
-## Scaling — partition large scopes
-
-A single scout reading every file degrades once the scope is large (context pressure → shallow reads → missed findings).
-
-- **Small scope** (≲10 files / ≲800 changed lines): one scout pass.
-- **Large scope:** split into reviewable **units** — by module/directory, or by lens — and run one scout subagent per unit **in parallel**, capped at **4 scouts** (grow the unit size, not the scout count). Each unit owns a slice; none needs the whole tree in context. Each scout writes its findings to `.reviews/<id>-tentative/<scout-name>.json` (`{ "findings": [...] }`).
-- **Merge:** `review merge --dir .reviews/<id>-tentative` — dedupes overlapping claims (same file, line ±5, same lens; keeps the stronger finding, records merged ids in `related`) and renumbers `F-###` deterministically into `merged.json`.
-
-## Tentative finding format
-
-Each finding MUST include all fields:
-
-```
-id: F-001          # or dup-001 from pre-flight
-lens: security
-location: services/foo/src/bar.ts:42
-claim: One-sentence description of the suspected issue
-evidence: |
-  ```42:48:services/foo/src/bar.ts
-  // cited lines
-  ```
-context: |         # ±30 lines around the citation — lets the skeptic verdict without re-discovering the file
-  ...
-related: []        # callers, test files, ADR paths — you already found these; hand them over
-tentative_severity: critical | important | minor
-confidence: low | medium | high
-```
-
-The `context` and `related` fields are what keep Phase 2 cheap: you already read this code — package it so the skeptic doesn't have to rediscover it.
-
-## Rules
-
-- Every finding needs `file:line` (or line range) and a code citation.
-- Prefer fewer, higher-quality findings over laundry lists.
-- "Might be wrong" is fine — skeptics verify. Mark `confidence: low` when unsure.
-- Check ADRs for accepted-risk patterns before claiming security issues.
-- Record scope and lens list for the synthesis report header.
-
-## Handoff
-
-1. Run the **coverage pass** ([phase1c-coverage.md](phase1c-coverage.md)) on the merged tentative list — it may add follow-up findings and records the `coverage` ledger.
-2. Pass the full tentative list (scout + coverage) to Phase 2. Skeptic dispatch is severity-routed and budgeted (see SKILL.md) using [phase2-skeptic.md](phase2-skeptic.md) — not one subagent per finding.
+# Phase 1 — Scout pass
+
+You are the **scout** for a thorough code review. Discovery only — no fix suggestions yet.
+
+## Input packet
+
+- **Scope:** {SCOPE_TYPE} — {SCOPE_DESCRIPTION}
+- **Lenses:** {LENS_LIST}
+- **Git range / paths:** {SCOPE_DETAIL}
+- **Accepted risks:** {ACCEPTED_RISKS_DIGEST}  <!-- contents of reference/accepted-risks.md — do not raise findings it covers unless a re-open trigger fired -->
+
+## Steps
+
+1. Ingest the **signals pre-flight** results ([signals-preflight.md](signals-preflight.md)) — tool-confirmed failures are grounded findings; start from them.
+2. Read the files in scope (`git diff`, paths, or commits as applicable). **Partition large scopes** — see below.
+3. If **smells** lens is active: run dedupe pre-flight (read `dedupe` skill; report-only scan on scope).
+4. For each active lens, read the checklist from [lenses.md](lenses.md) and inspect code.
+5. Emit **tentative findings** — de-duplicate overlapping claims before handing off.
+6. Do **not** assign final verdicts; Phase 2 skeptics do that. The coverage pass ([phase1c-coverage.md](phase1c-coverage.md)) runs after you to catch misses.
+
+## Scaling — partition large scopes
+
+A single scout reading every file degrades once the scope is large (context pressure → shallow reads → missed findings).
+
+- **Small scope** (≲10 files / ≲800 changed lines): one scout pass.
+- **Large scope:** split into reviewable **units** — by module/directory, or by lens — and run one scout subagent per unit **in parallel**, capped at **4 scouts** (grow the unit size, not the scout count). Each unit owns a slice; none needs the whole tree in context. Each scout writes its findings to `.reviews/<id>-tentative/<scout-name>.json` (`{ "findings": [...] }`).
+- **Merge:** `review merge --dir .reviews/<id>-tentative` — dedupes overlapping claims (same file, line ±5, same lens; keeps the stronger finding, records merged ids in `related`) and renumbers `F-###` deterministically into `merged.json`.
+
+## Tentative finding format
+
+Each finding MUST include all fields:
+
+```
+id: F-001          # or dup-001 from pre-flight
+lens: security
+location: services/foo/src/bar.ts:42
+claim: One-sentence description of the suspected issue
+evidence: |
+  ```42:48:services/foo/src/bar.ts
+  // cited lines
+  ```
+context: |         # ±30 lines around the citation — lets the skeptic verdict without re-discovering the file
+  ...
+related: []        # callers, test files, ADR paths — you already found these; hand them over
+tentative_severity: critical | important | minor
+confidence: low | medium | high
+```
+
+The `context` and `related` fields are what keep Phase 2 cheap: you already read this code — package it so the skeptic doesn't have to rediscover it.
+
+## Rules
+
+- Every finding needs `file:line` (or line range) and a code citation.
+- Prefer fewer, higher-quality findings over laundry lists.
+- "Might be wrong" is fine — skeptics verify. Mark `confidence: low` when unsure.
+- Check ADRs for accepted-risk patterns before claiming security issues.
+- Record scope and lens list for the synthesis report header.
+
+## Handoff
+
+1. Run the **coverage pass** ([phase1c-coverage.md](phase1c-coverage.md)) on the merged tentative list — it may add follow-up findings and records the `coverage` ledger.
+2. Pass the full tentative list (scout + coverage) to Phase 2. Skeptic dispatch is severity-routed and budgeted (see SKILL.md) using [phase2-skeptic.md](phase2-skeptic.md) — not one subagent per finding.