devlyn-cli 1.14.0 → 1.15.0

package/config/skills/devlyn:auto-resolve/evals/evals.json

@@ -0,0 +1,21 @@
+{
+  "skill_name": "devlyn:auto-resolve",
+  "note": "Real regression fixtures from measured A/B runs. Each eval is a task we have actually driven through the pipeline and scored blind against a bare-prompt baseline. Expand only with real runs, not synthesized prompts.",
+  "evals": [
+    {
+      "id": 1,
+      "name": "doctor-subcommand",
+      "route": "standard",
+      "complexity": "medium",
+      "prompt": "Implement per spec at evals/task-doctor-subcommand.md",
+      "spec": "evals/task-doctor-subcommand.md",
+      "expected_output": "Single-file CLI change adding a `doctor` subcommand to bin/devlyn.js with node-version, HOME/.claude, plugins, and skills checks, TTY-gated color, exit-code semantics, help integration. Zero new npm dependencies. No silent error catches.",
+      "baseline_source": "bare prompt (no skill pipeline) — see benchmark history commit 2d9a5f0..51a8aeb",
+      "historical_scores": {
+        "v3.4":   { "skill": 57, "bare": 45, "margin": 12, "judge": "codex gpt-5.3-codex blind" },
+        "v3.4.1": { "skill": 59, "bare": 43, "margin": 16, "judge": "codex gpt-5.3-codex blind" }
+      },
+      "files": []
+    }
+  ]
+}

package/config/skills/devlyn:auto-resolve/evals/task-doctor-subcommand.md

@@ -0,0 +1,42 @@
+# Task: `devlyn doctor` subcommand
+
+Add a new `doctor` subcommand to `bin/devlyn.js`. When the user runs `npx devlyn-cli doctor` (or `node bin/devlyn.js doctor`), it diagnoses the local devlyn-cli installation and prints a status report.
+
+## Requirements
+
+1. **Node version check** — `process.version >= v18.0.0`. Emit a status line. If below, mark FAIL.
+2. **`$HOME/.claude/` check** — exists as directory AND is writable. Missing → FAIL. Exists but not writable (EACCES) → FAIL with a distinct "permission" message.
+3. **Installed plugins scan** — read subdirectories of `$HOME/.claude/plugins/cache/` and print a summary line with the count. `--verbose` lists names.
+4. **Installed skills scan** — count files matching `$HOME/.claude/skills/**/SKILL.md`. Print count; `--verbose` lists relative paths.
+5. **Colored output** — each line prefixed with `[OK]` (green), `[WARN]` (yellow), `[FAIL]` (red) using ANSI escape codes, **only when `process.stdout.isTTY` is true**. Non-TTY → no color codes.
+6. **Summary line** — e.g., `doctor: 3 ok, 1 warn, 0 fail`.
+7. **Exit code** — `0` if zero fails, `1` if any fail.
+8. **`--verbose` flag** — expands details for plugins/skills scans.
+9. **Help integration** —
+   - `node bin/devlyn.js doctor --help` prints a short help block and exits 0.
+   - `node bin/devlyn.js --help` / `node bin/devlyn.js help` lists `doctor` as an available subcommand.
+
+## Constraints
+
+- **Zero new dependencies.** Use only Node.js built-ins (`fs`, `path`, `os`, `process`).
+- **No silent error catches.** Per project CLAUDE.md error-handling philosophy, do not wrap operations in `try { … } catch { return fallbackValue }`. All errors visible to the user with actionable messages.
+- **HOME guard.** If `process.env.HOME` is undefined or empty, emit a clear FAIL line ("HOME environment variable is not set") and exit 1. Do not attempt to read arbitrary paths.
+- **EACCES handling.** If `readdirSync` fails with EACCES, emit a permission-specific message quoting the offending path. Do not silently return an empty list.
+
+## Acceptance verification
+
+Run each of these and they must behave as described:
+
+- `node bin/devlyn.js doctor` — produces the status report, exits 0 on a clean machine.
+- `HOME=/nonexistent node bin/devlyn.js doctor` — prints a FAIL line clearly referencing the missing `/nonexistent/.claude`, exits 1.
+- `node bin/devlyn.js doctor | cat` — piped output contains no ANSI escape codes (`\x1b[`).
+- `node bin/devlyn.js doctor --help` — prints help, exits 0.
+- `node bin/devlyn.js --help` — mentions `doctor` in the list of subcommands.
+- `git diff -- package.json` — no new entries under `dependencies`.
+- `node bin/devlyn.js doctor --verbose` — lists each plugin directory and each skill path.
+
+## Out of Scope
+
+- Auto-repair (don't offer to fix detected problems; just report).
+- Checking remote/registry state (npm, GitHub).
+- Any feature requiring a new npm dependency.

package/config/skills/devlyn:auto-resolve/references/build-gate.md

@@ -82,35 +82,49 @@ Use `--build-gate no-docker` to skip Docker builds for faster iteration during d
 
 ## Output Format
 
-Write results to `.devlyn/BUILD-GATE.md`:
+Emit two files plus one state update (schemas: `references/findings-schema.md`, `references/pipeline-state.md`).
+
+### 1. `.devlyn/build_gate.findings.jsonl`
+
+One JSON line per failing command's extracted root cause. Do NOT emit findings for PASSING commands. Each line follows the canonical findings schema:
+
+```jsonl
+{"id":"BGATE-0001","rule_id":"build.type-error","level":"error","severity":"HIGH","confidence":0.99,"message":"Property 'config' does not exist on type 'SettingsTabsProps'","file":"dashboard/app/(dashboard)/settings/page.tsx","line":90,"phase":"build_gate","criterion_ref":null,"fix_hint":"Read dashboard/app/(dashboard)/settings/page.tsx:88-93 and dashboard/components/settings/SettingsTabs.tsx (the SettingsTabsProps type definition). Either add 'config' to SettingsTabsProps or remove the prop from the parent.","blocking":true,"status":"open"}
+```
+
+Dedup key is `(rule_id, file, line)` per `findings-schema.md` — no fingerprint bookkeeping (removed in v3.4).
+
+Suggested `rule_id` values: `build.type-error`, `build.lint-violation`, `build.dep-missing`, `build.docker-copy-mismatch`, `build.module-not-found`, `build.compile-error`.
+
+### 2. `.devlyn/build_gate.log.md`
+
+Human-readable run log. This is where the FULL raw stderr/stdout lives — not in the JSONL `message`. Structure:
 
 ```markdown
-# Build Gate Results
-## Verdict: [PASS / FAIL]
+# Build Gate Run Log
 ## Detected Project Types
 - [type] ([path/])
-## Gate Commands Run
-| # | Command | Dir | Exit | Status | Time |
-|---|---|---|---|---|---|
-| 1 | `npx tsc --noEmit` | dashboard/ | 0 | PASS | 4.2s |
-| 2 | `npx next build` | dashboard/ | 1 | FAIL | 9.8s |
-| 3 | `cargo check --all-targets` | services/indexer/ | 0 | PASS | 12.1s |
 
-## Failures
+## Commands
+| # | Command | Dir | Exit | Time |
+|---|---|---|---|---|
+| 1 | `npx tsc --noEmit` | dashboard/ | 0 | 4.2s |
+| 2 | `npx next build` | dashboard/ | 1 | 9.8s |
 
-### Command #2: `npx next build` (dashboard/, exit 1)
-```
-[full error output — do NOT truncate. Build errors reference files from earlier in output.]
+## Raw Output — failing commands only
+
+### #2: `npx next build` (dashboard/, exit 1)
+\`\`\`
+[full raw output — keep for debugging]
+\`\`\`
 ```
 
-**Root file:line(s)**:
-- `dashboard/app/(dashboard)/settings/page.tsx:90` — Type error: Property 'config' does not exist on type 'SettingsTabsProps'
+### 3. Update `pipeline.state.json`
 
-**Fix guidance**:
-Read `dashboard/app/(dashboard)/settings/page.tsx:88-93` and `dashboard/components/settings/SettingsTabs.tsx` (the SettingsTabsProps type definition). Either add `config` to SettingsTabsProps or remove the prop from the parent. Then re-run `npx next build` from `dashboard/` to verify.
-```
+Set `phases.build_gate`:
+- `verdict`: `PASS` if all exit codes == 0, else `FAIL`. If no gates detected, `PASS` with a note in log.md ("No build gate detected — project type unknown; consider adding `--build-gate deploy` if Dockerfiles are present.")
+- `engine: "bash"`, `model: null`
+- `started_at`, `completed_at`, `duration_ms`, `round`
+- `artifacts.findings_file: ".devlyn/build_gate.findings.jsonl"`, `artifacts.log_file: ".devlyn/build_gate.log.md"`
 
-Verdict rules:
-- Any exit code != 0 → **FAIL**
-- All exit codes == 0 → **PASS**
-- No gates detected → **PASS** with note "No build gate detected — project type unknown. Consider adding `--build-gate deploy` if Dockerfiles are present."
+The orchestrator branches on `phases.build_gate.verdict` — it does NOT re-read the findings or log file for routing decisions.

package/config/skills/devlyn:auto-resolve/references/engine-routing.md

@@ -1,204 +1,82 @@
 # Engine Routing: Intelligent Model Selection
 
-Instructions for routing work to the optimal model (Claude or Codex) per role and phase. Only read this file when `--engine` is set to `auto` or `codex`.
+Routing rules for Claude / Codex / Dual per role and phase. Only read when `--engine` is `auto` or `codex`.
 
-The routing table below is derived from published benchmarks (April 2026) comparing Claude Opus 4.6 and GPT-5.4 across task-relevant dimensions. The principle: each role's work goes to the model that objectively performs better at that task type.
-
----
-
-## Benchmark Basis
-
-| Dimension | Claude Opus 4.6 | GPT-5.4 | Gap | Source |
-|-----------|-----------------|---------|-----|--------|
-| Long-context retrieval (256k) | 92% | ~64% | Claude +28pp | MRCR v2 |
-| Graduate-level reasoning | 87.4% | 83.9% | Claude +3.5pp | GPQA Diamond |
-| Hard coding problems | ~46% | 57.7% | Codex +11.7pp | SWE-bench Pro |
-| Function-level code gen | 90.4% | 93.1% | Codex +2.7pp | HumanEval |
-| Terminal/CLI tasks | 65.4% | 75.1% | Codex +9.7pp | Terminal-Bench 2.0 |
-| Real-world issue resolution | ~80% | ~80% | Tied | SWE-bench Verified |
-| Security vulnerability detection | — | — | Tied | Semgrep 2025 study |
-| Agentic computer use | 72.7% | 75.0% | Codex +2.3pp | OSWorld |
-| Ambiguous intent handling | Preferred by 70% devs | — | Claude | Developer surveys |
-
----
-
-## Codex Call Defaults
-
-Every Codex call in this file uses these defaults unless stated otherwise:
-
-```
-model: "gpt-5.4"
-reasoningEffort: "xhigh"
-sandbox: varies per role (see table)
-workingDirectory: project root
-```
-
-The `model` field accepts any string — pass `"gpt-5.4"` even if the MCP schema lists older defaults. The Codex CLI resolves it.
-
----
-
-## Role Routing Table
-
-### team-resolve roles
-
-| Role | Engine | Sandbox | Rationale |
-|------|--------|---------|-----------|
-| root-cause-analyst | **Claude** | — | A/B test: Claude traced git history (15 tool calls) finding exact commit + unchecked migration plan. Codex analyzed structure well but lacked git history depth. Tool access > SWE-bench Pro advantage for this role. |
-| test-engineer | **Codex** | workspace-write | Test code generation = HumanEval (+2.7pp), needs file write |
-| security-auditor | **Dual** | read-only | Semgrep: both find unique vulns; GAN > single model |
-| implementation-planner | **Codex** | read-only | Implementation planning = SWE-bench Pro (+11.7pp) |
-| product-designer | **Claude** | — | Ambiguous requirements, user intent = Claude strength |
-| ui-designer | **Claude** | — | Visual spec, design reasoning = non-coding task |
-| ux-designer | **Claude** | — | User flow analysis = ambiguous intent handling |
-| accessibility-auditor | **Claude** | — | A/B test: Claude found 12 issues (1 CRITICAL) vs Codex 4. WCAG auditing requires thoroughness and domain knowledge depth, not code generation speed. Claude 3x coverage. |
-| product-analyst | **Claude** | — | Requirements clarity, scope judgment = ambiguity handling |
-| architecture-reviewer | **Claude** | — | Codebase-wide pattern review = MRCR long-context (+28pp) |
-| performance-engineer | **Codex** | read-only | Terminal tasks + algorithm analysis = Terminal-Bench (+9.7pp) |
-| api-designer | **Dual** | read-only | A/B test: Claude found 9 issues, Codex found 6, with unique findings on both sides (Claude: --version, exit codes; Codex: YAML folded scalar parsing bug). Dual maximizes coverage for API surface review. |
-
-### team-review roles
-
-| Role | Engine | Sandbox | Rationale |
-|------|--------|---------|-----------|
-| security-reviewer | **Dual** | read-only | Same as team-resolve security-auditor |
-| quality-reviewer | **Dual** | read-only | A/B test: Claude found 14 issues (2 HIGH), Codex found 11 (3 HIGH), only ~6 overlap. Dual yields ~19 unique findings (+36-73% coverage). Both models find HIGH-severity issues the other misses. |
-| test-analyst | **Codex** | workspace-write | Test gap analysis + test code suggestions |
-| ux-reviewer | **Claude** | — | UX flow assessment = ambiguity handling |
-| ui-reviewer | **Claude** | — | Design token consistency = non-coding task |
-| accessibility-reviewer | **Claude** | — | Same rationale as team-resolve accessibility-auditor: Claude 3x finding coverage on WCAG audits |
-| product-validator | **Claude** | — | Business logic intent = ambiguity handling |
-| api-reviewer | **Dual** | read-only | Same rationale as team-resolve api-designer: both models find unique API issues |
-| performance-reviewer | **Codex** | read-only | Algorithm complexity = Terminal-Bench (+9.7pp) |
-
-### Summary distribution
-
-| Engine | team-resolve (12) | team-review (9) | Total |
-|--------|-------------------|-----------------|-------|
-| Claude | 7 | 4 | 11 |
-| Codex | 2 | 2 | 4 |
-| Dual | 3 | 3 | 6 |
+Codex call defaults: `model: "gpt-5.4"`, `reasoningEffort: "xhigh"`, `sandbox` per role (below), `workingDirectory: <project root>`.
 
 ---
 
 ## Pipeline Phase Routing (auto-resolve)
 
-| Phase | --engine auto | --engine codex | --engine claude |
+| Phase | `--engine auto` | `--engine codex` | `--engine claude` |
 |-------|--------------|----------------|-----------------|
-| BUILD (implementation) | **Codex** | Codex | Claude |
-| BUILD GATE | bash (model-agnostic) | bash | bash |
-| BROWSER VALIDATE | Claude (Chrome MCP only) | Claude | Claude |
+| BUILD | **Codex** | Codex | Claude |
+| BUILD GATE | bash | bash | bash |
+| BROWSER VALIDATE | Claude (Chrome MCP) | Claude | Claude |
 | EVALUATE | **Claude** | Claude | Claude |
 | FIX LOOP | **Codex** | Codex | Claude |
-| SIMPLIFY | Claude | Codex | Claude |
-| REVIEW (team) | **Mixed per table** | Codex all | Claude all |
-| CHALLENGE | **Claude** | Claude | Claude |
-| SECURITY REVIEW | **Dual** | Codex | Claude |
-| CLEAN | Claude | Codex | Claude |
+| CRITIC (design sub-pass) | Claude | Claude | Claude |
+| CRITIC (security sub-pass) | **Dual** | Codex | Claude |
 | DOCS | Claude | Codex | Claude |
 
-Rationale for `--engine auto` choices:
-- BUILD/FIX: Codex — SWE-bench Pro 57.7% vs 46%. The biggest model gap is in hard coding tasks.
-- EVALUATE/CHALLENGE: Claude — evaluating a full diff requires long-context retrieval (MRCR +28pp) and skeptical reasoning (GPQA +3.5pp). Different model family from builder creates GAN dynamic.
-- BROWSER: Claude — Chrome MCP tools are Claude Code session-bound.
-- SECURITY: Dual — Semgrep study shows both models find unique vulnerabilities.
+Rationale:
+- BUILD/FIX: Codex — SWE-bench Pro advantage on hard coding.
+- EVALUATE/CRITIC design sub-pass: Claude — long-context retrieval + skeptical reasoning; different model family from builder for GAN dynamic.
+- BROWSER: Claude — Chrome MCP tools session-bound.
+- CRITIC security: Dual on `auto` — Semgrep study shows each model finds unique vulnerabilities; for security, coverage trumps cost.
 
 ---
 
 ## Pipeline Phase Routing (ideate)
 
-| Phase | --engine auto | --engine codex | --engine claude |
+| Phase | `--engine auto` | `--engine codex` | `--engine claude` |
 |-------|--------------|----------------|-----------------|
-| FRAME | **Claude** | Codex | Claude |
-| EXPLORE | **Claude** | Codex | Claude |
-| CONVERGE | **Claude** | Codex | Claude |
+| FRAME | Claude | Codex | Claude |
+| EXPLORE | Claude | Codex | Claude |
+| CONVERGE | Claude | Codex | Claude |
 | CHALLENGE | **Codex** (rubric critic) | Claude (role reversal) | Claude |
-| DOCUMENT | **Claude** | Codex | Claude |
+| DOCUMENT | Claude | Codex | Claude |
 
-Rationale:
-- FRAME/EXPLORE/CONVERGE: Claude — ambiguous intent handling, multi-perspective reasoning.
-- CHALLENGE: When `--engine auto`, Codex runs the rubric pass as critic — automatic on every run. When `--engine codex`, Claude runs the challenge (role reversal — builder and critic are always different models).
-- DOCUMENT: Claude — writing quality for spec generation.
+CHALLENGE: when `--engine auto`, Codex runs the rubric as critic (builder and critic always different models).
 
 ---
 
 ## Pipeline Phase Routing (preflight)
 
-| Phase | --engine auto | --engine codex | --engine claude |
+| Phase | `--engine auto` | `--engine codex` | `--engine claude` |
 |-------|--------------|----------------|-----------------|
-| EXTRACT COMMITMENTS | Claude | Codex | Claude |
-| CODE AUDIT | **Codex** | Codex | Claude |
-| DOCS AUDIT | **Claude** | **Claude** | Claude |
-| BROWSER AUDIT | Claude (Chrome MCP) | Claude | Claude |
+| EXTRACT | Claude | Codex | Claude |
+| AUDIT (code) | **Codex** | Codex | Claude |
+| AUDIT (docs) | **Claude** | Claude | Claude |
+| AUDIT (browser) | Claude | Claude | Claude |
 | SYNTHESIZE | Claude | Claude | Claude |
 
-DOCS AUDIT is always Claude regardless of `--engine` — writing-quality strength on documentation drift detection (READMEs, VISION.md prose, spec status accuracy) is the deciding factor, not code analysis. BROWSER AUDIT is always Claude because Chrome MCP tools are session-bound to Claude Code.
+Docs auditor is always Claude (writing-quality strength for prose-drift detection). Browser is always Claude (Chrome MCP session-bound).
 
 ---
 
-## How to Spawn a Codex Role
-
-For roles marked **Codex** in the routing table, call `mcp__codex-cli__codex` instead of spawning a Claude Agent subagent. Package the role's full prompt (from the skill's teammate prompt section) into the Codex call.
-
-Template:
-
-```
-mcp__codex-cli__codex({
-  prompt: "[full role prompt with issue context, file paths, and deliverable format]",
-  model: "gpt-5.4",
-  reasoningEffort: "xhigh",
-  sandbox: "[read-only or workspace-write per table]",
-  workingDirectory: "[project root]"
-})
-```
-
-**Important**: Codex has no access to team infrastructure (TeamCreate, SendMessage, TaskCreate). For Codex roles:
-- Include ALL context inline in the prompt (issue description, file paths from investigation, deliverable format)
-- The orchestrator collects Codex's response and routes it where it would have gone via SendMessage
-- Codex roles cannot communicate with other teammates directly — the orchestrator relays findings
-
-For roles marked **Claude**, spawn a normal Agent subagent as before.
-
----
+## Team-role routing (when `--team` is on OR route == strict in auto-resolve, OR team-review in standalone)
 
-## How to Spawn a Dual Role
-
-For roles marked **Dual**, run BOTH models in parallel and merge findings:
-
-1. Spawn a Claude Agent subagent with the role's prompt
-2. Call `mcp__codex-cli__codex` with the same role's prompt (sandbox: "read-only")
-3. Wait for both to complete
-4. Merge findings:
-   - Same finding from both → keep more detailed description, mark "confirmed by both models"
-   - Claude-only → keep as-is
-   - Codex-only → prefix with `[codex]`
-   - Conflicting findings → keep both, note the disagreement
-   - Take the MORE SEVERE verdict between the two
-
----
-
-## How to Spawn a Codex BUILD/FIX Agent
-
-For BUILD and FIX LOOP phases when engine routes to Codex:
-
-```
-mcp__codex-cli__codex({
-  prompt: "[full build/fix prompt with task description, done criteria, and implementation instructions]",
-  model: "gpt-5.4",
-  reasoningEffort: "xhigh",
-  sandbox: "workspace-write",
-  fullAuto: true,
-  workingDirectory: "[project root]"
-})
-```
+| Role | Engine | Sandbox | Rationale |
+|------|--------|---------|-----------|
+| root-cause-analyst | Claude | — | Git-history traversal + tool access beats SWE-bench Pro for this role |
+| test-engineer | Codex | workspace-write | HumanEval edge, needs file write |
+| security-auditor | Dual | read-only | Semgrep: each finds unique vulns |
+| implementation-planner | Codex | read-only | SWE-bench Pro +11.7pp |
+| architecture-reviewer | Claude | — | Codebase-wide pattern review = MRCR strength |
+| performance-engineer | Codex | read-only | Terminal-Bench edge |
+| api-designer / api-reviewer | Dual | read-only | Both find unique API issues |
+| quality-reviewer | Dual | read-only | Measured ~36–73% coverage gain from dual |
+| ux/ui/accessibility-* | Claude | — | Ambiguity handling + WCAG domain depth |
 
-**After Codex completes**: verify changes were made (`git diff --stat`), then proceed to the next phase as normal. The file-based handoff (`.devlyn/done-criteria.md`, `.devlyn/EVAL-FINDINGS.md`, etc.) works identically — Codex writes the same files Claude would.
+For Codex roles: `mcp__codex-cli__codex` with `model: "gpt-5.4"`, `reasoningEffort: "xhigh"`, sandbox per table. Include full role prompt inline; Codex has no access to TeamCreate/SendMessage/TaskCreate.
 
-**Session management**: For FIX LOOP iterations, use a fresh call each time (no `sessionId` reuse) because sandbox/fullAuto parameters only apply on the first call of a session.
+For Dual roles: run both in parallel, merge findings. Same finding from both → keep more detailed wording, mark "confirmed by both". Codex-only → prefix `[codex]`. Conflicts → keep both.
 
 ---
 
-## Override Behavior
+## Override behavior
 
-- `--engine claude` → all roles and phases use Claude (no Codex calls)
-- `--engine codex` → all phases use Codex for implementation/analysis, Claude only for orchestration and Chrome MCP
-- `--engine auto` (default) → each role and phase routes to the optimal model per this table
+- `--engine claude` → all roles/phases use Claude (no Codex calls).
+- `--engine codex` → all phases use Codex for implementation/analysis, Claude only for orchestration/Chrome MCP.
+- `--engine auto` (default) → each role/phase routes per this table.

package/config/skills/devlyn:auto-resolve/references/findings-schema.md

@@ -0,0 +1,103 @@
+# Findings Schema — `.devlyn/<phase>.findings.jsonl`
+
+Structured findings format for phase outputs. One JSON object per line (JSONL). Written by Evaluate, Build Gate, Browser Validate, Critic, and any other phase that emits structured findings.
+
+## Purpose
+
+Separate structured findings from prose summaries. The orchestrator and fix-loop need machine-readable data for:
+- Filtering by severity / blocking / status.
+- Cross-round dedup (single primary key — see below).
+- Packing into fix-batch packets for the fix-loop subagent.
+- Final report aggregation.
+
+## Canonical schema (per line)
+
+```json
+{
+  "id": "<PHASE>-<4digit>",
+  "rule_id": "<category>.<kebab-name>",
+  "level": "note" | "warning" | "error",
+  "severity": "LOW" | "MEDIUM" | "HIGH" | "CRITICAL",
+  "confidence": <float 0.0..1.0>,
+  "message": "<one-line human description>",
+  "file": "<path relative to repo root>",
+  "line": <int, 1-based>,
+  "phase": "<phase name, e.g. 'evaluate'>",
+  "criterion_ref": "<anchor, e.g. 'spec://requirements/2'>" | null,
+  "fix_hint": "<concrete action quoting file:line to change>",
+  "blocking": true | false,
+  "status": "open" | "resolved" | "suppressed"
+}
+```
+
+## Field semantics
+
+### Identity
+
+- `id` — stable within a single run. Format: `<PHASE>-<4digit>` zero-padded. Examples: `EVAL-0007`, `BUILD-0001`, `CRIT-0003`, `BGATE-0004`.
+- `rule_id` — stable across runs. Format: `<category>.<kebab-case-name>`. Use existing rule_ids before inventing new ones — keeps dedup working. Common categories:
+  - `correctness.*` — logic errors, silent failures, null access, wrong API contracts
+  - `design.*` — staff-engineer ship/no-ship concerns (non-atomic transactions, hidden assumptions, unidiomatic patterns)
+  - `security.*` — OWASP-anchored (sql-injection, xss, hardcoded-credential, missing-input-validation, missing-auth-check, insecure-dependency, permissive-cors, missing-csrf, privilege-escalation, data-exposure, path-traversal, ssrf)
+  - `ux.*` — missing error/loading/empty states
+  - `architecture.*` — pattern violations, duplication, missing integration
+  - `hygiene.*` — unused imports, dead code, unused deps (typically LOW)
+  - `types.*` — any-cast escapes, unsafe casts
+  - `scope.*` — out-of-scope violations (e.g. `scope.out-of-scope-violation`)
+  - `performance.*`, `style.*` — typically LOW
+
+### Severity and level
+
+- `level` — SARIF-style coarse bucket: `error` blocks ship, `warning` should fix, `note` informational.
+- `severity` — finer granularity for pipeline logic.
+
+  | severity | level | blocking default |
+  |----------|-------|------------------|
+  | `CRITICAL` | `error` | always true |
+  | `HIGH` | `error` | usually true |
+  | `MEDIUM` | `warning` | true (stricter for `security.*` — see pipeline-routing terminal state) |
+  | `LOW` | `note` | false |
+
+- `confidence` — reporter's self-rating, `0.0`–`1.0`. Fix-loop prioritizes high-confidence HIGH findings first.
+
+### Message and location
+
+- `message` — one line. NAME the issue, not the symptom. Good: `"Token validated on read path but not write path"`. Bad: `"Potential security issue"`.
+- `file` — repo-relative path. No leading `./`, no absolute paths. Forward slashes.
+- `line` — 1-based line number. Multi-line spans → primary (first) line.
+
+### Dedup primary key
+
+The primary key is `(rule_id, file, line)`. Two findings with identical coordinates are the same issue. If EVAL runs again after a fix and the finding re-appears at the same spot, it's still unresolved. If the line shifted after a fix, the next EVAL regenerates the finding with the new line — cross-round drift heals naturally via re-evaluation, no hash-normalization bookkeeping.
+
+### Pipeline linkage
+
+- `phase` — the phase that produced this finding (redundant with filename but keeps records self-describing when concatenated for fix-batch packets).
+- `criterion_ref` — anchor to the criterion this finding affects, or `null` if cross-cutting.
+- `fix_hint` — concrete action with file:line. Not "improve error handling" — e.g. `"Wrap read+write in db.transaction() at src/auth/session.ts:84-92; re-check order.status === 'pending' inside transaction before updating"`.
+
+### Lifecycle
+
+- `blocking` — does this block ship?
+- `status`:
+  - `open` — reported, awaiting action
+  - `resolved` — a fix-loop round applied a fix AND subsequent evaluation confirms the finding is gone (via `(rule_id, file, line)` absence in the new EVAL run)
+  - `suppressed` — intentionally not fixed with justification in the phase's `log.md`; requires user override or Out-of-Scope mapping in the spec
+
+## Dedup and round handling
+
+Each phase writes a fresh `.findings.jsonl` on each execution. Fix rounds re-run EVAL, which produces a new file.
+
+**Cross-round reconciliation** (fix-loop rounds only):
+1. Read prior round's `<phase>.findings.jsonl` (if any).
+2. For each finding in the new file: if prior open finding has same `(rule_id, file, line)` → reuse the prior `id`, keep `status: open`. Otherwise → new `id`.
+3. For each prior open finding not matched by the new file → set `status: resolved` in the prior file.
+
+Fix-batch packet: orchestrator concatenates all phases' `.findings.jsonl`, filters `status == "open"`, drops `blocking == false` when round budget is tight, writes to `.devlyn/fix-batch.round-<N>.json`.
+
+## Non-goals
+
+- Full SARIF 2.1.0 export (can derive later by mapping our fields to SARIF).
+- Cross-project aggregation.
+- Rule metadata catalogs.
+- Code fix patches — `fix_hint` is prose; fix-loop subagent writes the patch.

package/config/skills/devlyn:auto-resolve/references/phases/phase-1-build.md

@@ -0,0 +1,54 @@
+# PHASE 1 — BUILD (agent prompt body)
+
+Spawned when PHASE 1 runs. Engine: BUILD row of `engine-routing.md`.
+
+Orchestrator passes the task description as the final section, and sets the team flag (`team: true|false`) per orchestrator rule: team only when `--team` flag OR `state.route.selected == "strict"`.
+
+---
+
+<spec_integrity_check>
+Before reading anything else:
+- If `pipeline.state.json:source.type == "spec"`, compute `sha256(state.source.spec_path)`. If it differs from `state.source.spec_sha256`, write `phases.build.verdict: "BLOCKED"` with reason `"spec_sha256 mismatch"` and return. The spec changed mid-run — invariant violation per `references/pipeline-state.md`.
+- If `source.type == "generated"` and `state.source.criteria_sha256` exists, verify the same way.
+- If the hash field is absent (first phase to populate the file), skip this check this one time only.
+</spec_integrity_check>
+
+<goal>
+Implement code changes that satisfy every pending criterion in `pipeline.state.json:criteria[]` without violating anything declared Out of Scope or Constraints. Make the source's intent run in the code.
+</goal>
+
+<input>
+- Canonical criteria: `pipeline.state.json:source`. Follow `source.spec_path` (read directly, do not copy) or `source.criteria_path` (`.devlyn/criteria.generated.md` — may not yet exist; see OUTPUT CONTRACT).
+- Codebase at `pipeline.state.json:base_ref.sha`.
+- Task statement appended at the bottom of this prompt.
+</input>
+
+<output_contract>
+- **Code changes** implementing every `pending` criterion. Verify with `git diff`.
+- **state.json criteria updates**: for each criterion satisfied, set `status: "implemented"` and append an `evidence` record `{"file": "...", "line": N, "note": "brief"}`.
+- **If `source.type == "generated"` and `.devlyn/criteria.generated.md` does not exist**: create it once with `## Requirements` (each `- [ ]` testable in under 30 seconds, specific, scoped), `## Out of Scope`, `## Verification`. Populate `state.criteria[]` with `{"id": "C<N>", "ref": "criteria.generated://requirements/<N-1>", "status": "pending", "evidence": [], "failed_by_finding_ids": []}`. Classify task complexity into `low` / `medium` / `high` and write to `phases.build.complexity`. Compute `criteria_sha256 = sha256(criteria.generated.md)` and store in `state.source.criteria_sha256`.
+- **No pending criterion remains**: every `criteria[]` entry must transition to `status: "implemented"` with an `evidence` record before you exit. If a criterion genuinely cannot be satisfied (missing external dep, blocking ambiguity), set `phases.build.verdict: "BLOCKED"` and report. Never exit with a criterion still `pending`. BUILD must not mark any criterion `failed` — that's EVAL-only. Legal transitions: `pending → implemented`, or halt via `verdict: "BLOCKED"`.
+- **Tests** added or updated for changed behavior. Run the full test suite before stopping.
+- **Team** (only if orchestrator set `team: true`): use `TeamCreate` per the role table below; collect findings; shut down the team before exiting. Otherwise implement directly — the default.
+</output_contract>
+
+<quality_bar>
+- Criteria and Out-of-Scope are the contract — never weaken, reword, or delete them.
+- Read only files the source implicates (Architecture Notes + Dependencies + touched patterns), not the whole codebase.
+- Bugs: failing test first, then fix. Features: follow existing patterns, then write tests. Refactors: tests pass before and after.
+- Fix root causes only — no `any`, `@ts-ignore`, silent `catch`, or hardcoded values.
+</quality_bar>
+
+<principle>
+The source is the contract. Your output is evidence that the contract now runs in code.
+</principle>
+
+<team_role_selection>
+When `team: true`, select teammates by task type (per-role engine routing per `references/engine-routing.md`):
+- Bug fix: root-cause-analyst + test-engineer (+ security-auditor / performance-engineer as needed)
+- Feature: implementation-planner + test-engineer (+ ux-designer / architecture-reviewer / api-designer as needed)
+- Refactor: architecture-reviewer + test-engineer
+- UI/UX: product-designer + ux-designer + ui-designer (+ accessibility-auditor as needed)
+</team_role_selection>
+
+The task is: [orchestrator pastes the task description here]

package/config/skills/devlyn:auto-resolve/references/phases/phase-2-evaluate.md

@@ -0,0 +1,45 @@
+# PHASE 2 — EVALUATE (agent prompt body)
+
+Spawned when PHASE 2 runs. Engine: Claude (cross-model critic when builder was Codex).
+
+---
+
+<spec_integrity_check>
+Before reading anything: verify source hash per `references/phases/phase-1-build.md#spec_integrity_check`. Apply the same rule (spec_sha256 for spec runs, criteria_sha256 for generated).
+</spec_integrity_check>
+
+<goal>
+Independently verify whether every criterion in `pipeline.state.json:criteria[]` is satisfied by the current code. Surface every defect with file:line evidence. You are a skeptic, not a cheerleader — praise is not your job.
+</goal>
+
+<input>
+- Canonical rubric: `pipeline.state.json:source`. Follow `source.spec_path` or `source.criteria_path` and read Requirements + Out of Scope + Verification directly.
+- Change surface: `git diff <pipeline.state.json:base_ref.sha>` + `git status`. Read every changed/new file in full — not just the hunks.
+- Prior browser findings at `.devlyn/browser_validate.findings.jsonl` (if that phase ran).
+</input>
+
+<output_contract>
+- **`.devlyn/evaluate.findings.jsonl`** — one JSON per line (schema: `references/findings-schema.md`). Per finding:
+  `id` (`EVAL-<4digit>`), `rule_id` (stable kebab-case, e.g. `correctness.silent-error`, `ux.missing-error-state`, `architecture.duplication`, `security.missing-validation`, `types.any-cast-escape`, `style.let-vs-const`, `scope.out-of-scope-violation`, `hygiene.unused-import`), `level` (`error`/`warning`/`note` — map from severity: CRITICAL/HIGH → error, MEDIUM → warning, LOW → note), `severity` (`CRITICAL`/`HIGH`/`MEDIUM`/`LOW`), `confidence` (0.0–1.0), `message` (one line naming the issue, not symptoms), `file`, `line` (1-based primary location), `phase: "evaluate"`, `criterion_ref` (exact `ref` string from a `criteria[]` entry — e.g. `"spec://requirements/2"` — when the finding fails a specific criterion; or a section anchor from `state.source.criteria_anchors` such as `"spec://constraints"` / `"spec://out-of-scope"` when cross-cutting; `null` when scope-broader than any anchor), `fix_hint` (concrete action quoting file:line), `blocking` (CRITICAL/HIGH/MEDIUM default true, LOW false), `status: "open"`. Dedup key is `(rule_id, file, line)` — no fingerprint bookkeeping.
+- **`.devlyn/evaluate.log.md`** — 3–5 line human summary: verdict + criteria pass/fail counts + top 3 risks + cross-cutting patterns if any. Prose here; structured data in the JSONL.
+- **state.json criteria updates** — every `criteria[]` entry leaves Evaluate in a terminal state. Incoming status from BUILD is normally `implemented`; transition each to `status: "verified"` (append `evidence` record confirming satisfaction) OR `status: "failed"` (set `failed_by_finding_ids` to the IDs you emitted). If a criterion is still `pending` (BUILD did not satisfy it), mark it `failed` with a finding whose `rule_id` is `correctness.criterion-unimplemented`. No `criteria[]` entry may remain `pending` or `implemented` after Evaluate.
+- **state.json phases.evaluate** — `verdict` per taxonomy, `engine: "claude"`, `model`, timing, `round`, `artifacts.{findings_file, log_file}`.
+
+Verdict taxonomy: `BLOCKED` (any CRITICAL) / `NEEDS_WORK` (HIGH or MEDIUM present) / `PASS_WITH_ISSUES` (LOW only) / `PASS` (clean).
+</output_contract>
+
+<quality_bar>
+- Every finding points at a file:line you have opened and read. No real anchor = speculation; exclude it.
+- Every failed criterion maps to ≥1 finding `id`.
+- **Coverage over comfort**: report uncertain and LOW findings too; downstream filters rank them. Missing a real defect ships broken code — the asymmetry is decisive.
+- Audit each changed file for: correctness (logic errors, silent failures, null access, wrong API contracts), architecture (pattern violations, duplication, missing integration), security (if auth/secrets/user-data touched: injection, hardcoded credentials, missing validation), frontend (if UI changed: missing error/loading/empty states, React anti-patterns, server/client boundaries), test coverage (untested modules, missing edge cases), hygiene (unused imports, dead code, unused deps — `hygiene.*` at LOW), defensive programming (recursion depth/cycle guards, boundary conditions, missing null checks — severity per blast radius: `correctness.*` when it can crash or corrupt, `hygiene.*` when cosmetic).
+- Calibration: a catch block that logs but doesn't surface the error to the user → HIGH, not MEDIUM (logging ≠ error handling). A `let` that could be `const` → LOW (linters catch it). "Error handling is generally quite good" is not a finding — count instances, name files.
+- "Pre-existing" findings still count if they relate to the criteria. Working software, not blame attribution.
+- **Out-of-Scope violations are findings**: if BUILD added behavior the source's `## Out of Scope` excludes, emit `rule_id: "scope.out-of-scope-violation"`, `severity: HIGH`, `criterion_ref: "spec://out-of-scope"` (or `"criteria.generated://out-of-scope"`), `fix_hint` naming what to remove.
+</quality_bar>
+
+<principle>
+Missing a real defect is worse than reporting an extra one. Asymmetric cost demands bias toward reporting.
+</principle>
+
+Do not delete `pipeline.state.json` or the JSONL/log files.