@izkac/forgekit 0.1.0

package/vendor/skills/thorough-code-review/reference/phase1c-coverage.md

@@ -0,0 +1,44 @@
+# Phase 1.5 — Coverage pass (recall)
+
+You are the **coverage critic**. The scout and skeptic together make confirmed findings trustworthy (precision); they do nothing about what the scout *missed* (recall). Your job is to close that gap.
+
+**This pass normally runs orchestrator-inline** — the orchestrator already holds the scope and the merged tentative list. Dispatch it as a subagent only when the scope was partitioned and the file list is too large to re-check in context.
+
+**You receive the scope, the active lenses, and the merged tentative-finding list.**
+
+## Inputs
+
+- **Scope:** {SCOPE_TYPE} — {SCOPE_DETAIL}
+- **Lenses:** {LENS_LIST}
+- **Tentative findings:** {FINDING_SUMMARY} (ids + locations + lenses)
+- **Signals:** {SIGNALS_SUMMARY} (which grounding tools ran and their status)
+
+## Checks
+
+1. **File coverage.** List every file in scope. For each that received **zero** tentative findings, decide: genuinely clean (state why — trivial, well-tested, unchanged logic) or **not actually reviewed**. Re-read the latter.
+2. **Lens coverage.** For each active lens that produced **zero** findings, decide: the code truly has no such issue, or the lens was not exercised on this scope. Re-inspect the latter against [lenses.md](lenses.md).
+3. **Blind spots.** Check the kinds of issue a single forward pass tends to miss:
+   - error/edge paths and early returns not on the happy path
+   - cross-file and cross-service interactions (callers of changed exports)
+   - what a change *removed* (deleted guard, dropped test, narrowed type)
+   - config, migrations, and generated artifacts in scope but easy to skim past
+4. **Signal gaps.** Any grounding tool `skipped` that should have run for this scope? Flag it.
+
+## Output
+
+```yaml
+coverage:
+  files_reviewed: [list]
+  files_skipped: [list]          # in scope but deliberately not deep-read (say why in notes)
+  lenses_without_findings:
+    - lens: performance
+      reason: no loops, queries, or allocations introduced
+new_findings: []                  # follow-up tentative findings (F-### / dup-###),
+                                  # full scout format; they go through Phase 2 like the rest
+```
+
+## Rules
+
+- A zero-finding lens or file is a claim that needs a one-line justification — not a silent gap.
+- New findings you raise are **tentative**; the skeptic still verifies them. Do not confirm anything here.
+- **Hard cap: 10 follow-up findings**, prioritized by severity. If you found more, keep the top 10 and note the overflow count in the coverage ledger notes.

package/vendor/skills/thorough-code-review/reference/phase2-skeptic.md

@@ -0,0 +1,105 @@
+# Phase 2 — Skeptic pass
+
+You are an **adversarial skeptic**. Your job is to **disprove** the scout's claim unless evidence confirms it.
+
+**You receive only this packet — no chat history.** It may contain **one finding** (critical, or an important finding alone in its file) or a **batch of findings sharing a file or module** (important: ≤4, minor: ≤6) — steelman and verdict each finding independently; never let one verdict color another.
+
+## Finding(s) under review
+
+One block per finding:
+
+```
+id: {FINDING_ID}
+lens: {LENS}
+location: {LOCATION}
+claim: {CLAIM}
+evidence: {EVIDENCE}
+context: {CONTEXT_EXCERPT}   # ±30 lines around the cited location, from the scout
+related: {RELATED}           # callers, test files, ADR paths
+tentative_severity: {SEVERITY}
+confidence: {CONFIDENCE}
+```
+
+Start from `context` and `related` — most verdicts need only 1–2 additional reads. Read more files only when the disproof checklist genuinely requires it.
+
+## Scope context
+
+- **Scope:** {SCOPE_DESCRIPTION}
+- **Mode:** {MODE}  <!-- `initial` or `reverify` -->
+- **Accepted risks:** {ACCEPTED_RISKS_DIGEST}  <!-- contents of reference/accepted-risks.md -->
+
+Check the digest **before** reading `docs/adr/` — if it covers the claim and no re-open trigger fired, the verdict is `false_positive` (cite the ADR id). Read full ADRs only when the digest is silent.
+
+## Steelman rule
+
+First, restate the **strongest** version of the claim — the worst reasonable interpretation an attacker or failure mode could exploit.
+
+## Disproof checklist
+
+Attempt each before concluding:
+
+1. **Call chain** — trace callers and callees; does the dangerous path actually execute?
+2. **Data flow** — is input attacker-controlled at the sink?
+3. **Tests** — read (or run if feasible) tests covering this path
+4. **Framework mitigations** — middleware, ORM parameterization, framework defaults
+5. **Deployment boundary** — internal-only API, LAN trust model, ADR-accepted risk
+6. **Project docs** — `docs/adr/`, `AGENTS.md`, prior security reviews
+7. **Intent** — comment, type guard, or early return that negates the claim
+
+## Verdict (initial review)
+
+| Verdict | When |
+| ------- | ---- |
+| `confirmed` | Issue is real at stated or higher severity |
+| `false_positive` | Claim does not hold after investigation |
+| `downgraded` | Real issue but lower severity — set `severity` and `original_severity` |
+| `needs_decision` | Architectural/policy choice; not a clear defect |
+
+**Requirements:**
+
+- `verdict_reason` must cite specific evidence (file:line, test name, ADR id).
+- "Looks fine" without evidence is invalid.
+- Upgrade severity only with **new** evidence not in the scout packet.
+
+## Risk-weighted second opinion
+
+A single skeptic returning `false_positive` is itself a single point of failure — it can quietly bury a real bug. The orchestrator dispatches a **second independent skeptic** (no history, blind to the first verdict) when the finding is in the **dangerous quadrant**:
+
+- `severity` is `critical`/`important` **and** the first verdict is `false_positive`, or
+- `phase1_confidence: high` **and** the first verdict is `false_positive` (scout/skeptic disagreement), or
+- `phase1_confidence: low` **and** `severity: critical` (high-stakes, low-certainty).
+
+If you are the second skeptic, verify independently and return your verdict in the `second_opinion` block. When the two skeptics disagree, the orchestrator keeps the higher-severity outcome or routes to `needs_decision` — a disagreement is never silently resolved in favour of dismissal.
+
+## Verdict (reverify mode)
+
+When `MODE` is `reverify`, the finding was previously `confirmed` or `downgraded`. Read **current** code at `location`.
+
+| Verdict | When |
+| ------- | ---- |
+| `resolved` | Fix fully addresses the issue |
+| `still_open` | Issue persists unchanged |
+| `partially_fixed` | Improved but incomplete |
+| `regressed` | Fix introduced new problem or made it worse |
+
+Include `verdict_reason` with before/after comparison.
+
+## Output
+
+Return one structured block **per finding** for synthesis:
+
+```yaml
+id: F-001
+lens: security
+location: path:line
+claim: ...
+severity: critical | important | minor
+original_severity: ...    # required if downgraded
+verdict: confirmed | false_positive | downgraded | needs_decision | resolved | still_open | partially_fixed | regressed
+verdict_reason: ...
+evidence: ...
+second_opinion:           # only for dangerous-quadrant findings
+  verdict: ...
+  verdict_reason: ...
+  agrees: true | false
+```

package/vendor/skills/thorough-code-review/reference/report-schema.json

@@ -0,0 +1,222 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://forgekit.local/schemas/code-review-report.json",
+  "title": "ThoroughCodeReviewReport",
+  "type": "object",
+  "required": ["review_id", "kind", "created_at", "scope", "lenses", "summary", "findings"],
+  "additionalProperties": false,
+  "properties": {
+    "review_id": { "type": "string", "minLength": 1 },
+    "kind": { "type": "string", "enum": ["review", "reverify"] },
+    "created_at": { "type": "string", "format": "date-time" },
+    "scope": {
+      "type": "object",
+      "required": ["type", "description"],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["uncommitted", "branch", "paths", "commit_range", "file"]
+        },
+        "description": { "type": "string", "minLength": 1 },
+        "base_sha": { "type": "string" },
+        "head_sha": { "type": "string" },
+        "paths": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "lenses": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "enum": [
+          "security",
+          "correctness",
+          "smells",
+          "architecture",
+          "performance",
+          "tests",
+          "contracts",
+          "errors",
+          "maintainability"
+        ]
+      }
+    },
+    "parent_report": { "type": "string" },
+    "summary": {
+      "type": "object",
+      "required": ["tentative_count"],
+      "additionalProperties": true,
+      "properties": {
+        "tentative_count": { "type": "integer", "minimum": 0 },
+        "headline": { "type": "string" },
+        "top_actions": { "type": "array", "items": { "type": "string" } },
+        "confirmed": { "type": "integer", "minimum": 0 },
+        "downgraded": { "type": "integer", "minimum": 0 },
+        "false_positive": { "type": "integer", "minimum": 0 },
+        "needs_decision": { "type": "integer", "minimum": 0 },
+        "resolved": { "type": "integer", "minimum": 0 },
+        "still_open": { "type": "integer", "minimum": 0 },
+        "partially_fixed": { "type": "integer", "minimum": 0 },
+        "regressed": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/finding" }
+    },
+    "dedupe_preflight": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "count": { "type": "integer", "minimum": 0 },
+        "items": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "location", "claim"],
+            "properties": {
+              "id": { "type": "string" },
+              "location": { "type": "string" },
+              "claim": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "coverage": {
+      "type": "object",
+      "description": "Recall / completeness pass ledger.",
+      "additionalProperties": true,
+      "properties": {
+        "files_reviewed": { "type": "array", "items": { "type": "string" } },
+        "files_skipped": { "type": "array", "items": { "type": "string" } },
+        "lenses_without_findings": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["lens", "reason"],
+            "properties": {
+              "lens": {
+                "type": "string",
+                "enum": [
+                  "security",
+                  "correctness",
+                  "smells",
+                  "architecture",
+                  "performance",
+                  "tests",
+                  "contracts",
+                  "errors",
+                  "maintainability"
+                ]
+              },
+              "reason": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    },
+    "signals": {
+      "type": "object",
+      "description": "Signals pre-flight: deterministic tools run before the scout.",
+      "additionalProperties": true,
+      "properties": {
+        "tools": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name"],
+            "properties": {
+              "name": { "type": "string", "minLength": 1 },
+              "status": { "type": "string", "enum": ["pass", "fail", "skipped"] },
+              "summary": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "stats": {
+      "type": "object",
+      "description": "Pipeline stats: subagent counts and shortcut tallies for the run.",
+      "additionalProperties": false,
+      "properties": {
+        "scouts": { "type": "integer", "minimum": 0 },
+        "skeptics_dedicated": { "type": "integer", "minimum": 0 },
+        "skeptics_batched": { "type": "integer", "minimum": 0 },
+        "inline_verdicts": { "type": "integer", "minimum": 0 },
+        "grounded_skips": { "type": "integer", "minimum": 0 },
+        "carried_forward": { "type": "integer", "minimum": 0 },
+        "second_opinions": { "type": "integer", "minimum": 0 }
+      }
+    }
+  },
+  "$defs": {
+    "finding": {
+      "type": "object",
+      "required": ["id", "lens", "location", "claim", "severity", "verdict", "verdict_reason"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^(F|dup)-[0-9]{3}$" },
+        "title": { "type": "string", "minLength": 1 },
+        "lens": {
+          "type": "string",
+          "enum": [
+            "security",
+            "correctness",
+            "smells",
+            "architecture",
+            "performance",
+            "tests",
+            "contracts",
+            "errors",
+            "maintainability"
+          ]
+        },
+        "location": { "type": "string", "minLength": 1 },
+        "claim": { "type": "string", "minLength": 1 },
+        "evidence": { "type": "string" },
+        "severity": { "type": "string", "enum": ["critical", "important", "minor"] },
+        "phase1_confidence": { "type": "string", "enum": ["low", "medium", "high"] },
+        "original_severity": { "type": "string", "enum": ["critical", "important", "minor"] },
+        "verdict": {
+          "type": "string",
+          "enum": [
+            "confirmed",
+            "false_positive",
+            "downgraded",
+            "needs_decision",
+            "resolved",
+            "still_open",
+            "partially_fixed",
+            "regressed"
+          ]
+        },
+        "verdict_reason": { "type": "string", "minLength": 1 },
+        "second_opinion": {
+          "type": "object",
+          "description": "Independent second skeptic for dangerous-quadrant findings.",
+          "required": ["verdict", "verdict_reason"],
+          "additionalProperties": false,
+          "properties": {
+            "verdict": {
+              "type": "string",
+              "enum": [
+                "confirmed",
+                "false_positive",
+                "downgraded",
+                "needs_decision",
+                "resolved",
+                "still_open",
+                "partially_fixed",
+                "regressed"
+              ]
+            },
+            "verdict_reason": { "type": "string", "minLength": 1 },
+            "agrees": { "type": "boolean" }
+          }
+        }
+      }
+    }
+  }
+}

package/vendor/skills/thorough-code-review/reference/report-template.md

@@ -0,0 +1,115 @@
+# Code review report template
+
+**Generated, not hand-authored.** The JSON sidecar is the single source of truth; the paired markdown is produced from it by `review render --file <json>`. This file documents the structure the renderer emits — edit the JSON (and the renderer in the review CLI `lib.mjs`), never the `.md` directly.
+
+Path: `.reviews/<timestamp>-<scope-slug>-review.md` (or `-reverify.md` for fix verification), per [report-schema.json](report-schema.json).
+
+---
+
+```markdown
+# Code review — {SCOPE_DESCRIPTION}
+
+**Review ID:** {REVIEW_ID}
+**Kind:** review | reverify
+**Created:** {ISO_TIMESTAMP}
+**Scope:** {SCOPE_TYPE} — {SCOPE_DETAIL}
+**Lenses:** {LENS_LIST}
+**Parent report:** {PARENT_REVIEW_ID or —}
+
+## Executive summary
+
+{TWO_TO_FOUR_SENTENCES: what was reviewed, verdict counts, overall risk posture.}
+
+### Verdict counts
+
+| Verdict | Count |
+| ------- | ----- |
+| Confirmed | |
+| Downgraded | |
+| False positive | |
+| Needs decision | |
+| Resolved | |
+| Still open | |
+| Partially fixed | |
+| Regressed | |
+
+### Top actions
+
+1. {Highest priority confirmed/critical item}
+2. {Second}
+3. {Third}
+
+---
+
+## Critical
+
+### {F-001}: {Short title}
+
+- **Lens:** security
+- **Location:** `path:line`
+- **Severity:** critical {or `minor (was important)` when downgraded}
+- **Verdict:** confirmed
+- **Claim:** ...
+- **Reason:** ...
+- **Second skeptic:** {only for dangerous-quadrant findings} verdict — reason
+
+{Repeat per finding}
+
+---
+
+## Important
+
+{Same structure}
+
+---
+
+## Minor
+
+{Same structure}
+
+---
+
+## Needs decision
+
+{Architectural items with `needs_decision` verdict — link ADRs if applicable}
+
+---
+
+## Coverage ledger
+
+{From the recall pass — files reviewed/skipped and active lenses that produced
+no findings, each with a one-line reason. Omitted when no `coverage` object.}
+
+---
+
+## Appendix A — Rejected findings (false positives)
+
+### {F-00X}: {Short title}
+
+- **Claim:** ...
+- **Why rejected:** ...
+
+---
+
+## Appendix B — Dedupe pre-flight
+
+{If smells lens ran; else omit section}
+
+| ID | Location | Claim |
+| -- | -------- | ----- |
+| dup-001 | ... | ... |
+
+---
+
+## Appendix C — Method
+
+- Phase 1: Scout pass ({N} tentative findings)
+- Phase 2: Adversarial skeptic verification (severity-routed, budgeted)
+- {If reverify: Re-verification against parent report {PARENT_ID}}
+```
+
+## JSON sidecar
+
+Author the `.json` (the source of truth), then `review render` to (re)generate this markdown and `review export` to validate before handing off in CI contexts.
+
+Main report body includes only `confirmed` and `downgraded` findings (initial review) or `still_open`, `partially_fixed`, `regressed` (reverify). Render places `false_positive` in Appendix A automatically.

package/vendor/skills/thorough-code-review/reference/severity-rubric.md

@@ -0,0 +1,49 @@
+# Severity rubric
+
+Calibrate severity before Phase 2. Skeptics may **downgrade** with evidence; upgrade only with new evidence.
+
+## Critical
+
+Must fix before merge or production. Examples:
+
+- Exploitable auth bypass or IDOR on production path
+- SQL/command injection with attacker-controlled input reaching sink
+- Secret or credential committed or logged
+- Data loss, corruption, or double-charge on money paths
+- Broken idempotency causing duplicate financial side effects
+
+## Important
+
+Should fix soon; real defect or serious debt with plausible trigger. Examples:
+
+- Logic bug on common edge case (empty input, race under concurrency)
+- Missing authorization on sensitive internal endpoint (if not ADR-accepted)
+- Error responses cached by idempotency middleware
+- Test gap on behaviour-critical path
+- Significant duplication that must stay in sync (rule of three)
+
+## Minor
+
+Nice to have; low likelihood or defense-in-depth. Examples:
+
+- Naming inconsistency
+- Missing progress indicator
+- Unlikely edge case with graceful degradation
+- Style nits not affecting behaviour
+- Pre-existing file size (only flag growth **this change** introduced)
+
+## Needs decision (not a severity)
+
+Architectural or policy trade-off — route to `NEEDS_DECISION` verdict, not Critical by default.
+
+Examples: accepted inter-service trust model per ADR, intentional public surface, documented technical debt.
+
+## Project-specific downgrades
+
+Before marking Critical/Important on themes covered by the project's accepted-risk digest, read that digest (and ADRs):
+
+- Formally accepted trust boundaries (e.g. LAN-only HMAC)
+- Documented intentional broad access patterns
+- Actor/header trust models bound by an upstream session
+
+Re-flag only if a listed re-open trigger has fired. See [accepted-risks.md](accepted-risks.md) and [examples/accepted-risks-janus.md](../examples/accepted-risks-janus.md).

package/vendor/skills/thorough-code-review/reference/signals-preflight.md

@@ -0,0 +1,55 @@
+# Signals pre-flight
+
+Ground the scout in real tool output **before** reading code by hand. Tool-confirmed problems are facts, not guesses — they raise recall on the smells / contracts / tests / errors lenses and cut hallucinated findings.
+
+## Steps
+
+1. **Plan the commands.** Run the planner for the review scope:
+
+   ```bash
+   review signals --type branch          # detect changed files vs main
+   review signals --type uncommitted      # working tree + untracked
+   review signals --paths services/persona,services/mercury
+   review signals --json                  # machine-readable
+   ```
+
+   It maps the scope to the **workspaces that own it** and prints the exact per-workspace grounding commands (this monorepo has no root typecheck — each package owns its scripts).
+
+2. **Run the grounding commands** it lists, e.g.:
+
+   ```bash
+   npm run typecheck --workspace=your-workspace
+   npm run test --workspace=your-workspace
+   npm run lint --workspace=your-workspace
+   ```
+
+   Add, when available and relevant to the scope:
+
+   - `npx knip` (or the repo's dead-code script) — unused exports / dead code → **smells**
+   - the service's OpenAPI **route-parity** test — mounted routes vs registry → **contracts**
+
+3. **Convert real failures to grounded tentative findings.** A type error, failing test, lint error, or dead export becomes an `F-###` (or `dup-###`) tentative finding with `confidence: high` and the tool output as `evidence`. Do **not** invent findings the tools did not support.
+
+4. **Record what ran** in the report JSON `signals` object so the grounding is auditable:
+
+   ```json
+   "signals": {
+     "tools": [
+       { "name": "typecheck your-workspace", "status": "pass" },
+       { "name": "test your-workspace", "status": "fail", "summary": "1 failing: consent.test.ts" },
+       { "name": "knip", "status": "skipped", "summary": "not in scope" }
+     ]
+   }
+   ```
+
+## Rules
+
+- Read-only. The pre-flight never edits code.
+- Scope-bound. Run tools for the **workspaces in scope**, not the whole repo, unless the scope is repo-wide.
+- A passing tool is signal too — it lets the coverage pass mark a lens genuinely exercised.
+- If a tool can't run (missing script, environment), record it `skipped` with a reason rather than omitting it.
+
+## Notes
+
+- The **dedupe pre-flight** (smells lens) is the same pattern with the `dedupe` skill as the tool; keep emitting `dup-###` findings and the `dedupe_preflight` summary.
+- Grounded findings at `critical`/`important` still go through Phase 2 — a failing test might be an intentional WIP. Below `important`, skip the skeptic: the tool output is the proof; the orchestrator just checks for intentional-WIP signals (commit message, TODO, user context) and records the verdict directly.

package/vendor/templates/adr/README.md

@@ -0,0 +1,7 @@
+# Architecture Decision Records
+
+Canonical index of ADRs for this project. See [decisions.md]({{DECISIONS_REL}}) for the full convention (when to write, template, cross-links with OpenSpec).
+
+| #     | Title | Status | Date |
+| ----- | ----- | ------ | ---- |
+| <!-- add rows as ADRs are written: | NNNN | Title | Status | YYYY-MM-DD | --> |