devlyn-cli 1.13.0 → 1.15.0

package/config/skills/devlyn:auto-resolve/references/phases/phase-3-critic.md

@@ -0,0 +1,84 @@
+# PHASE 3 — CRITIC (agent prompt body)
+
+Spawned when PHASE 3 runs. Engine: CRITIC row of `engine-routing.md` — design sub-pass always Claude; security sub-pass Dual on `--engine auto`, single on others.
+
+**Findings-only**: CRITIC does NOT write code. Orchestrator routes `NEEDS_WORK`/`BLOCKED` findings into PHASE 2.5 with `triggered_by: "critic"`. No bespoke mini-loop inside CRITIC.
+
+---
+
+<spec_integrity_check>
+Before reading anything: verify source hash per `references/phases/phase-1-build.md#spec_integrity_check`.
+</spec_integrity_check>
+
+<goal>
+One post-EVAL critic pass with two parallel sub-concerns. Produce a single `.devlyn/critic.findings.jsonl` tagged by rule_id prefix, plus a single `.devlyn/critic.log.md`.
+</goal>
+
+<input>
+- Change surface: `git diff <pipeline.state.json:base_ref.sha>`. Read every changed file in full, not just the hunks.
+- `package.json` / `requirements.txt` / lockfiles (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `Pipfile.lock`, `poetry.lock`, `Cargo.lock`, `go.sum`) — for dependency audit.
+</input>
+
+## Sub-pass 1: DESIGN (always Claude)
+
+<design_goal>
+Read the diff cold — no checklist, no prior-phase context. Find what a staff engineer would block before this PR ships. Any hesitation is a finding.
+</design_goal>
+
+<design_quality_bar>
+- Every finding anchored to `file:line` in code you have opened, with a concrete fix. Vague ≠ finding.
+- `fix_hint` is a specific change ("change X to Y because Z"), never "consider improving".
+- Interrogate: would this survive 10x traffic? A midnight oncall page? A junior dev in 6 months? Are baked-in assumptions stated out loud (hardcoded limits, implicit ordering, missed business-logic edges)? Is error handling actually helpful or does it prevent crashes while leaving users confused? Are there simpler idiomatic approaches — not "clever" but genuinely better?
+- Do not open with praise.
+- Rule_ids: `design.non-atomic-transaction`, `design.duplicate-pattern`, `design.hidden-assumption`, `design.unidiomatic-pattern`, `design.missing-integration`, etc.
+- Severities: CRITICAL / HIGH / MEDIUM — no LOW (design is ship/no-ship).
+
+**Design sub-verdict**: `PASS` only if zero design findings. Any open design finding → `NEEDS_WORK`.
+</design_quality_bar>
+
+## Sub-pass 2: SECURITY (Dual on `--engine auto`, single otherwise)
+
+<security_goal>
+Dedicated security audit of all recent changes. NOT a general code review — focus exclusively on security concerns. File:line evidence for every finding.
+</security_goal>
+
+<security_quality_bar>
+Check every changed file for:
+1. **Input validation**: trace every user input entry → storage/output. SQL injection, XSS, command injection, path traversal, SSRF.
+2. **Auth & authorization**: new endpoints protected? Auth checks consistent? Privilege escalation / BOLA paths?
+3. **Secrets & credentials**: grep for hardcoded API keys, tokens, passwords, private keys. Secrets from env vars. `.gitignore` covers sensitive files.
+4. **Data exposure**: error messages leaking internal details? Logs capturing sensitive data? API responses returning more than needed?
+5. **Dependencies** — **MANDATORY** when any dep manifest or lockfile changed (see `<input>` list above). Run the package manager's audit command:
+   - `npm audit --json` (Node/pnpm/yarn — all write to `npm audit`-compatible JSON)
+   - `pip-audit --format json`
+   - `cargo audit`
+   - `govulncheck ./...`
+   Report findings at CRITICAL/HIGH as blocking. Record the command run and its JSON output in `critic.log.md`.
+6. **CSRF/CORS**: new endpoints with side effects → CSRF protection. CORS not overly permissive.
+
+Rule_ids: `security.sql-injection`, `security.xss`, `security.path-traversal`, `security.ssrf`, `security.hardcoded-credential`, `security.missing-input-validation`, `security.missing-auth-check`, `security.privilege-escalation`, `security.data-exposure`, `security.insecure-dependency`, `security.missing-csrf`, `security.permissive-cors`.
+
+**Security sub-verdict** (stricter than general — same as v3.2 SECURITY):
+- `PASS` — zero findings
+- `PASS_WITH_ISSUES` — LOW only
+- `NEEDS_WORK` — HIGH or MEDIUM present (security MEDIUM is blocking by design)
+- `BLOCKED` — any CRITICAL
+
+**Dual merging** (when `--engine auto`): same finding from both models → keep more detailed wording, mark "confirmed by both". Codex-only → prefix message with `[codex]`. Conflicts → keep both. Take the MORE SEVERE severity between the two.
+</security_quality_bar>
+
+## Output contract
+
+- **`.devlyn/critic.findings.jsonl`** — one JSONL file containing BOTH sub-passes' findings. Every line carries `phase: "critic"`. Rule_id prefix (`design.*` vs `security.*`) distinguishes sub-pass. ID prefix: `CRIT-<4digit>` (single sequence shared by both sub-passes for simplicity).
+- **`.devlyn/critic.log.md`** — single prose summary: two sections ("Design" + "Security"). Each section: verdict + top 3 concerns framed actionably. Security section records the dep-audit command and its result.
+- **state.json phases.critic** — record both sub-verdicts AND the combined verdict. Combined verdict = WORSE of the two:
+  - Any `BLOCKED` → `BLOCKED`
+  - Any `NEEDS_WORK` → `NEEDS_WORK`
+  - Any `PASS_WITH_ISSUES` → `PASS_WITH_ISSUES`
+  - Both `PASS` → `PASS`
+
+## Principles
+
+- Cold eyes catch what structured reviews miss. For design: "would I ship this with my name on it?" is the only question.
+- For security: OWASP-anchored findings, file:line evidence. Speculative security concerns without a concrete attack vector are noise.
+- Do NOT write code changes. Do NOT commit. Orchestrator handles routing.

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

@@ -0,0 +1,114 @@
+# Pipeline Routing — 3 Routes + Stage A + Stage B LITE
+
+Auto-resolve adapts its pipeline shape to each task. Single source of truth for route selection; the orchestrator reads it, SKILL.md does not restate the rules.
+
+## The 3 routes
+
+| Route | Intended for | Phases that run |
+|-------|-------------|-----------------|
+| `fast` | Trivial / low-complexity, zero risk signals | PARSE → BUILD → BUILD GATE → [BROWSER if web] → EVAL → [FIX if findings] → FINAL REPORT |
+| `standard` | Default for medium work | `fast` + CRITIC (findings-only) + DOCS |
+| `strict` | High-complexity OR risk signals present OR escalated | `standard` + team-assembled BUILD + BUILD GATE strict mode |
+
+Every route runs PARSE, BUILD, BUILD GATE, EVAL, and FINAL REPORT. Routes differ in whether CRITIC/DOCS run and whether BUILD assembles a team.
+
+**Findings-only** (CRITIC) means the phase emits a `.findings.jsonl` + `.log.md` but does not write code. The orchestrator routes any NEEDS_WORK/BLOCKED findings through the unified fix loop (see SKILL.md `PHASE 2.5`), which re-runs EVAL. This enforces the post-EVAL invariant: all semantic changes go through EVAL.
+
+## Default guardrails (route-invariant under `auto`)
+
+These hold across all three routes with no `--bypass`:
+
+1. **BUILD GATE PASS** — `fast` runs the gate too.
+2. **Independent EVAL PASS** — file:line evidence required.
+3. **Every criterion terminal** (`verified` or `failed`).
+4. **Zero open HIGH/CRITICAL findings** at pipeline exit (subject to `--max-rounds` — see exhaustion table).
+5. **Web file changes force BROWSER VALIDATE** (`.tsx/.jsx/.vue/.svelte/.css/.html`, `page.*/layout.*/route.*`).
+6. **Post-BUILD risk detection auto-escalates** via Stage B LITE.
+
+## The `--bypass` flag
+
+Semantics: `--bypass <phase>[,<phase>...]`. Bypassable phases: `build-gate`, `browser`, `critic`, `docs`.
+
+Every bypass is recorded in `state.route.bypasses` and surfaced in the final report's `Guardrails bypassed:` line.
+
+**Deprecated aliases** (still accepted, log warning once): `--skip-build-gate`, `--skip-browser`, `--skip-review`, `--skip-clean`, `--skip-docs`, `--security-review skip`, `--bypass simplify|review|clean|security|challenge` all map to `--bypass critic` for the post-EVAL group or the appropriate phase otherwise. Removed next minor version.
+
+## `--max-rounds` exhaustion
+
+When the fix loop exhausts `max_rounds` with findings still open:
+
+| `triggered_by` | exhaustion behavior |
+|---|---|
+| `build_gate` | **halt** — skip to FINAL REPORT with `BUILD GATE EXHAUSTED` banner |
+| `browser_validate` | **halt** — skip to FINAL REPORT with `BROWSER EXHAUSTED` banner |
+| `evaluate` | **proceed_with_warning** — FINAL REPORT shows `EVAL EXHAUSTED` banner + open findings |
+| `critic` | **proceed_with_warning** — FINAL REPORT shows `CRITIC EXHAUSTED` banner + open findings |
+
+Guardrail #4 is suspended under `_with_warning` exhaustion: report banner shows what's unresolved.
+
+## Stage A — Pre-build (PHASE 0)
+
+Decision order (first match wins):
+
+1. **User override** (`--route fast|standard|strict`): set `route.selected`, `route.user_override: true`. Stage B LITE will not run.
+2. **Hard blocker**: missing spec or unmet internal deps → halt BLOCKED.
+3. **Risk keywords in source**: grep source body (spec body for spec-driven, task description for generated) for `auth, login, session, token, secret, password, crypto, api, env, permission, access, database, migration, payment`. Any hit → `strict`. Record matched keywords.
+4. **Complexity-based** (spec-driven only):
+   - `spec.frontmatter.complexity == "high"` → `strict`
+   - `spec.frontmatter.complexity == "medium"` → `standard`
+   - `spec.frontmatter.complexity == "low"` → `fast`
+5. **Generated tasks**: default to `standard`, Stage B LITE may escalate after BUILD.
+
+Stage A writes to `state.route.stage_a.{at, reasons}`.
+
+## Stage B LITE — Post-BUILD-GATE (PHASE 1.4)
+
+**One rule** (simplified from v3.2's multi-heuristic machinery). Does not run if `route.user_override == true`. Only escalates, never de-escalates.
+
+**Rule**: escalate to `strict` if `git diff <state.base_ref.sha>` meets ANY of:
+
+- **Risk keyword in diff content** — matches any of the 14 Stage A risk keywords.
+- **API surface** — changed files include paths under `src/api/`, `routes/`, `handlers/`, `app/api/`.
+- **Dependency change** — any of: `package.json`, `requirements.txt`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `Pipfile.lock`, `poetry.lock`, `Cargo.toml`, `Cargo.lock`, `go.mod`, `go.sum`.
+
+Stage B LITE writes to `state.route.stage_b.{at, escalated_from, reasons}`. No escalation → `stage_b.at` remains `null`.
+
+## Phase inclusion matrix
+
+| Phase | `fast` | `standard` | `strict` |
+|-------|--------|-----------|----------|
+| 0 PARSE + PREFLIGHT + ROUTE | ✓ | ✓ | ✓ |
+| 1 BUILD (solo) | ✓ | ✓ | — (team) |
+| 1 BUILD (team) | `--team` | `--team` | ✓ |
+| 1.4 BUILD GATE (auto) | ✓ | ✓ | — (strict+docker) |
+| 1.4 BUILD GATE (strict+docker) | — | — | ✓ |
+| 1.5 BROWSER VALIDATE | ✓ (web) | ✓ (web) | ✓ (web) |
+| 2 EVALUATE | ✓ | ✓ | ✓ |
+| 2.5 UNIFIED FIX LOOP | ✓ (if findings) | ✓ (if findings) | ✓ (if findings) |
+| 3 CRITIC (findings-only) | — | ✓ | ✓ (Dual security sub-pass) |
+| 4 DOCS (doc-files only) | — | ✓ | ✓ |
+| 5 FINAL REPORT + ARCHIVE | ✓ | ✓ | ✓ |
+
+Legend: ✓ runs, — skipped by route. `--bypass <phase>` forces skip on any route. `fast` skips CRITIC and DOCS.
+
+## Terminal-state algorithm (PHASE 5)
+
+Final verdict computed across all findings files in precedence order:
+
+1. **BUILD GATE FAIL** at exhaustion → `BLOCKED` with `BUILD GATE EXHAUSTED`.
+2. **BROWSER VALIDATE BLOCKED** at exhaustion → `BLOCKED`.
+3. **Any unresolved CRITICAL** in any `<phase>.findings.jsonl` → `BLOCKED`.
+4. **Any unresolved HIGH** with `rule_id` prefix `correctness.*` / `security.*` / `design.*` → `NEEDS_WORK`.
+5. **Any unresolved HIGH** (other categories) → `NEEDS_WORK`.
+6. **Any unresolved MEDIUM security.***  → `NEEDS_WORK` (security stricter than general by design).
+7. **Any unresolved MEDIUM** (other categories) → `PASS_WITH_ISSUES`.
+8. **Only LOW / none** → `PASS`.
+
+"Unresolved" means `status == "open"` in the latest round's file.
+
+## Non-goals
+
+- Per-criterion routing (every phase sees every criterion).
+- Route re-evaluation mid-round.
+- De-escalation.
+- Replacing `--bypass` (bypass is an orthogonal opt-out).

package/config/skills/devlyn:auto-resolve/references/pipeline-state.md

@@ -0,0 +1,201 @@
+# Pipeline State — `.devlyn/pipeline.state.json`
+
+Control plane for a single auto-resolve run. Contains pointers and state only — never copied content from the spec or findings files.
+
+## Purpose
+
+Every phase reads `pipeline.state.json` to answer:
+- What base git SHA am I diffing against? (prevents diff-scope drift across phases)
+- Where is the canonical criteria source? (spec file path or generated file path)
+- What route was selected and why?
+- Which criteria are verified / failed and with what evidence?
+- What is the current fix-loop round and max?
+- Where are the artifacts from phases that already ran?
+- What SHA did EVALUATE first pass at? (post-EVAL invariant check)
+
+State.json is the only cross-phase mutable state. Spec files and `<phase>.findings.jsonl` are immutable within a run.
+
+## File location
+
+`.devlyn/pipeline.state.json` during a run; moved to `.devlyn/runs/<run_id>/pipeline.state.json` at PHASE 5 (archive).
+
+Created by PHASE 0 on run start. At PHASE 5, the entire `.devlyn/` run artifact set is **moved** (not deleted) into `.devlyn/runs/<run_id>/`. See `## Archive contract` below.
+
+## Canonical schema (v1.2)
+
+```json
+{
+  "version": "1.2",
+  "run_id": "ar-<ISO8601-compact>-<uuidv7-short>",
+  "started_at": "<ISO-8601 UTC>",
+  "engine": "auto" | "codex" | "claude",
+  "base_ref": {
+    "branch": "<string, e.g. 'main'>",
+    "sha": "<full 40-char git sha captured at Phase 0 start>"
+  },
+  "eval_passed_sha": "<git sha recorded when PHASE 2 first returns PASS or PASS_WITH_ISSUES>" | null,
+  "route": {
+    "selected": "fast" | "standard" | "strict" | null,
+    "user_override": true | false,
+    "bypasses": ["<phase-name>", "..."],
+    "stage_a": {
+      "at": "<ISO-8601 UTC>" | null,
+      "reasons": ["<string>", "..."]
+    },
+    "stage_b": {
+      "at": "<ISO-8601 UTC>" | null,
+      "escalated_from": "fast" | "standard" | null,
+      "reasons": ["<string>", "..."]
+    }
+  },
+  "source": {
+    "type": "spec" | "generated",
+    "spec_path": "<string path>" | null,
+    "spec_sha256": "<hex>" | null,
+    "criteria_path": "<string path>" | null,
+    "criteria_sha256": "<hex>" | null,
+    "criteria_anchors": ["spec://requirements", "..."]
+  },
+  "criteria": [
+    {
+      "id": "C1",
+      "ref": "<anchor>",
+      "status": "pending" | "implemented" | "verified" | "failed",
+      "evidence": [
+        {"file": "<string>", "line": <int>, "note": "<string>"}
+      ],
+      "failed_by_finding_ids": ["<string>"]
+    }
+  ],
+  "phases": {
+    "<phase_name>": {
+      "verdict": "PASS" | "PASS_WITH_ISSUES" | "NEEDS_WORK" | "FAIL" | "BLOCKED" | null,
+      "engine": "codex" | "claude" | "bash" | "dual" | null,
+      "model": "<string>" | null,
+      "started_at": "<ISO-8601 UTC>" | null,
+      "completed_at": "<ISO-8601 UTC>" | null,
+      "duration_ms": <int> | null,
+      "round": <int>,
+      "triggered_by": "<phase-name>" | null,
+      "pre_sha": "<git sha captured before this phase spawned; used for per-phase diff invariant>" | null,
+      "artifacts": {
+        "findings_file": "<path>" | null,
+        "log_file": "<path>" | null
+      }
+    }
+  },
+  "rounds": {
+    "global": <int>,
+    "max_rounds": <int>
+  },
+  "perf": {  // OPTIONAL — present only when --perf flag is passed (v3.4 demoted from mandatory)
+    "wall_ms": <int>,
+    "tokens_total": <int>,
+    "per_phase": [
+      {"phase": "<name>", "engine": "codex" | "claude" | "bash" | "dual", "wall_ms": <int>, "tokens": <int>, "round": <int>, "triggered_by": "<phase>" | null}
+    ]
+  }
+}
+```
+
+## Field semantics
+
+### Top-level
+
+- `version` — schema version; current value `1.2`. Orchestrators must refuse incompatible versions.
+- `run_id` — unique, time-sortable run identifier in format `ar-<UTC-compact>-<12 hex>`. Example: `ar-20260423T163044Z-018f4c2a1b9c`.
+- `started_at` — Phase 0 start, ISO-8601 UTC.
+- `engine` — user-provided `--engine` flag value, or `auto` default.
+- `base_ref` — git state captured at Phase 0. **All subsequent `git diff` commands use this SHA**, not `HEAD~1` or `main`. This eliminates diff-scope drift.
+- `eval_passed_sha` — `null` until PHASE 2 first returns `PASS` or `PASS_WITH_ISSUES`. At that moment the orchestrator records `git rev-parse HEAD` here. After this field is populated, the **post-EVAL findings-only invariant** applies: PHASE 3 (CRITIC) must not write any non-doc files (reverted on violation), and PHASE 4 (DOCS) may only touch doc-allowlist paths. See `invariants` section of the skill.
+
+### Route
+
+- `selected` — `fast` / `standard` / `strict`, or `null` before Phase 0 decides.
+- `user_override` — `true` if user passed `--route <value>`.
+- `bypasses` — list of phase names the user explicitly bypassed via `--bypass <phase>`. Surfaced in the final report's `Guardrails bypassed` line. Empty list if no bypass.
+- `stage_a` — initial routing at Phase 0, based on spec frontmatter + content scan.
+- `stage_b` — post-BUILD checkpoint at Phase 1.4 completion. **Can only escalate** (fast → standard → strict), never de-escalate. `at` is `null` if no escalation.
+- `reasons` — human-readable decision rationale, surfaced in final report.
+
+### Source
+
+- `type` — `spec` (roadmap spec file) or `generated` (ad-hoc task).
+- `spec_path` + `spec_sha256` — canonical spec pointer + integrity hash for spec runs. Each phase re-computes and compares before reading. Mismatch → phase writes `verdict: "BLOCKED"` with reason `spec_sha256 mismatch`.
+- `criteria_path` + `criteria_sha256` — same pair for generated runs. `criteria_sha256` is populated by PHASE 1 BUILD after it creates `criteria.generated.md`. Subsequent phases verify it the same way.
+- `criteria_anchors` — enumerated anchors downstream phases may reference.
+
+### Criteria
+
+One entry per testable criterion extracted from the source. State machine: `pending → implemented → verified | failed`.
+
+### Phases
+
+Key is phase name (v3.4 set): `build`, `build_gate`, `browser_validate`, `evaluate`, `fix_loop`, `critic`, `docs`, `final_report`.
+
+- `verdict` — `PASS` / `PASS_WITH_ISSUES` / `NEEDS_WORK` / `FAIL` / `BLOCKED` / `null`. **Single canonical verdict source** — orchestrator branches on this, never by parsing artifact files.
+- `engine` / `model` — which model ran this phase. `bash` for build-gate. `dual` for `critic` security sub-pass on `--engine auto`.
+- `round` — which fix-loop round this execution belongs to. Phases that run once: `1`. `build_gate`, `browser_validate`, `evaluate`, `critic` increment with fix-loop iterations.
+- `triggered_by` — for phases re-run via the unified fix loop (PHASE 2.5), records the triggering phase name (`build_gate` / `browser_validate` / `evaluate` / `critic`). Also written on fix-loop entries themselves. `null` for the first run.
+- `pre_sha` — captured by the orchestrator immediately before spawning a post-EVAL phase (`git rev-parse HEAD`). Used by the post-EVAL invariant to diff **only what this phase touched**. Applies to `critic` and `docs`. `null` for PARSE/BUILD/BUILD_GATE/BROWSER/EVAL (those use `base_ref.sha`).
+- `artifacts` — pointers to phase output files. Phases that emit structured findings write both `findings_file` and `log_file`. `critic` writes a single `.devlyn/critic.findings.jsonl` carrying both design and security rule_id prefixes. DOCS leaves both `null` (its output is git commits).
+- `sub_verdicts` (only on `critic`) — `{"design": <verdict>, "security": <verdict>}`; overall `verdict` = WORSE of the two per `references/phases/phase-3-critic.md`.
+- `dep_audit` (only on `critic`) — `{"ran": bool, "command": "<cmd>", "high": N, "critical": N}` populated when critic's security sub-pass ran `npm audit` / `pip-audit` / equivalent.
+
+### Rounds
+
+- `global` — shared round counter across all fix-loop invocations regardless of trigger. Increments once per fix-loop iteration.
+- `max_rounds` — cap from `--max-rounds` flag (default 4).
+
+### Perf (opt-in via `--perf`, v3.4)
+
+When `--perf` is passed, the orchestrator records wall-time and token consumption per phase for retrospective benchmarking. When the flag is omitted (the default), the `perf` block is absent from state.json and the orchestrator skips timing/token bookkeeping — Karpathy P2 (Simplicity First) applied: no mandatory meta-measurement.
+
+When enabled:
+- `wall_ms` — total wall-clock from PHASE 0 start to PHASE 5 end, in milliseconds.
+- `tokens_total` — sum of `per_phase[].tokens`.
+- `per_phase` — one entry per phase execution. Fields: `phase`, `engine`, `wall_ms`, `tokens` (from subagent `total_tokens` or Codex usage; `bash` reports 0), `round`, `triggered_by`.
+
+Written at phase completion; totals roll up at PHASE 5.
+
+## Anchor syntax
+
+Format: `<scheme>://<section>[/<index>]`. `scheme` is `spec` or `criteria.generated`. `section` is slug-lowercased H2. `index` is optional 0-based position.
+
+## Write protocol
+
+- **Phase 0 (PARSE + PREFLIGHT + ROUTE)** — creates state.json with `version`, `run_id`, `started_at`, `engine`, `base_ref`, `rounds.max_rounds`, empty `phases`, and (after preflight step) populates `source`, `criteria[]` with `status: pending`, `route.selected`, `route.stage_a`, `route.bypasses`. `eval_passed_sha` remains `null`.
+- **Each phase start** — orchestrator writes `phases.<name>.started_at`, `round`, `triggered_by` (if re-run).
+- **Each phase end** — phase writes `phases.<name>.{verdict, completed_at, duration_ms, artifacts}`. Build and Evaluate additionally update `criteria[]` state. **When EVALUATE first returns PASS/PASS_WITH_ISSUES**, orchestrator sets `state.eval_passed_sha = git rev-parse HEAD` — this is the reference point for the post-EVAL invariant.
+- **Phase 1.4 completion checkpoint** — orchestrator runs Stage B LITE routing check; writes `route.stage_b` on escalation.
+- **Phase 5 (FINAL REPORT + ARCHIVE)** — reads state.json for the report, renders the report, then archives (see below).
+
+## Archive contract (PHASE 5)
+
+Best-effort move-and-prune. Replaces the previous "delete `.devlyn/`" behavior.
+
+1. Create `.devlyn/runs/<run_id>/` with `mkdir -p`.
+2. Move `.devlyn/pipeline.state.json`, every `.devlyn/<phase>.findings.jsonl`, every `.devlyn/<phase>.log.md`, every `.devlyn/fix-batch.round-*.json`, and `.devlyn/criteria.generated.md` (if exists) into that directory. Use `mv` (atomic within a filesystem).
+3. Prune to the last 10 completed runs. List `.devlyn/runs/*/pipeline.state.json`, sort by enclosing `run_id` (lexicographic = chronological because run_ids start with a compact ISO8601 timestamp), and delete the oldest directories until at most 10 remain. **Never delete a directory whose `pipeline.state.json` has `phases.final_report.verdict == null`** — those are still in flight.
+4. Kill any dev-server process spawned by PHASE 1.5 (BROWSER VALIDATE).
+
+Best-effort; no cross-process lock. Pruning is idempotent on sorted run_id list, so concurrent runs at worst delete a run already slated for pruning.
+
+## Integrity invariants
+
+The orchestrator enforces:
+
+1. `base_ref.sha` never changes after Phase 0.
+2. `source.spec_sha256` (or `source.criteria_sha256` for generated runs) is re-verified at every phase start. Mismatch → the phase writes `verdict: "BLOCKED"` with reason. Missing hash is allowed ONLY on the phase that first populates it (PHASE 0 for spec; PHASE 1 for generated).
+3. `route.selected` can only escalate via `stage_b`. No de-escalation.
+4. `rounds.global` never exceeds `rounds.max_rounds`.
+5. `criteria[].status` progression is monotonic per round: `pending → implemented → verified | failed`. A `failed` criterion can return to `implemented` via a subsequent fix-loop round, then be re-evaluated.
+6. **Post-EVAL findings-only** (per-phase diff, not cumulative): once `eval_passed_sha` is non-null, each post-EVAL phase (CRITIC, DOCS) records `phases.<phase>.pre_sha = git rev-parse HEAD` at spawn time. After completion, the orchestrator runs `git diff --name-only <phases.<phase>.pre_sha> -- ':!.devlyn/**'`. For CRITIC (findings-only), any non-empty diff triggers `git reset --hard <pre_sha>` + `invariant.post-eval-code-mutation` finding + fix-loop entry. For DOCS, only doc-file-allowlist paths are legal; everything else triggers the same flow. `pre_sha` (not cumulative `eval_passed_sha`) is the correct baseline because fix-loop commits between EVAL and CRITIC are legitimate — they were re-EVALed. The `:!.devlyn/**` pathspec excludes orchestrator bookkeeping writes.
+
+Violations indicate a bug in the orchestrator. Do not attempt silent recovery.
+
+## Non-goals
+
+- Crash-resume / workflow-engine semantics. State.json enables audit and orchestrator branching, not resume-from-crash.
+- Full SARIF export from state.json. `<phase>.findings.jsonl` is the SARIF-aligned surface; state.json is internal.
+- Per-finding history across runs. Current run's findings live in its `runs/<run_id>/` directory; cross-run comparison is manual.

package/config/skills/devlyn:auto-resolve/scripts/archive_run.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""Archive auto-resolve run artifacts per references/pipeline-state.md#archive-contract.
+
+Usage:
+    python3 scripts/archive_run.py [--devlyn-dir .devlyn]
+
+Reads run_id from .devlyn/pipeline.state.json, moves per-run artifacts into
+.devlyn/runs/<run_id>/, then best-effort prunes to last 10 completed runs
+(in-flight runs — phases.final_report.verdict == null — are never deleted).
+
+The contract lives in pipeline-state.md. This script implements it so that
+archive behavior is identical across every invocation.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import shutil
+import sys
+
+
+PER_RUN_PATTERNS = (
+    "pipeline.state.json",
+    "*.findings.jsonl",
+    "*.log.md",
+    "fix-batch.round-*.json",
+    "criteria.generated.md",
+)
+
+
+def read_run_id(devlyn: pathlib.Path) -> str:
+    state_path = devlyn / "pipeline.state.json"
+    if not state_path.is_file():
+        raise SystemExit(f"error: {state_path} not found")
+    try:
+        state = json.loads(state_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        raise SystemExit(f"error: {state_path} is not valid JSON: {e}")
+    run_id = state.get("run_id")
+    if not run_id:
+        raise SystemExit(f"error: {state_path} has no run_id")
+    return run_id
+
+
+def move_artifacts(devlyn: pathlib.Path, dest: pathlib.Path) -> int:
+    dest.mkdir(parents=True, exist_ok=True)
+    moved = 0
+    for pat in PER_RUN_PATTERNS:
+        for src in devlyn.glob(pat):
+            if src.is_file():
+                shutil.move(str(src), str(dest / src.name))
+                moved += 1
+    return moved
+
+
+def prune(runs_dir: pathlib.Path, keep: int = 10) -> int:
+    """Delete oldest completed runs beyond `keep`. In-flight runs never removed."""
+    candidates = []
+    for d in sorted(runs_dir.glob("*/"), key=lambda p: p.name):
+        state_file = d / "pipeline.state.json"
+        if not state_file.is_file():
+            continue
+        try:
+            s = json.loads(state_file.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            # Can't decide flight-state safely; skip (never prune)
+            continue
+        verdict = s.get("phases", {}).get("final_report", {}).get("verdict")
+        if verdict is None:
+            continue  # in-flight
+        candidates.append(d)
+    over = len(candidates) - keep
+    if over <= 0:
+        return 0
+    pruned = 0
+    for d in candidates[:over]:  # oldest first (lex sort = chronological)
+        shutil.rmtree(d, ignore_errors=False)
+        pruned += 1
+    return pruned
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--devlyn-dir", default=".devlyn")
+    ap.add_argument("--keep", type=int, default=10, help="keep N most recent completed runs")
+    args = ap.parse_args()
+
+    devlyn = pathlib.Path(args.devlyn_dir)
+    if not devlyn.is_dir():
+        sys.stderr.write(f"error: {devlyn} is not a directory\n")
+        return 1
+
+    run_id = read_run_id(devlyn)
+    dest = devlyn / "runs" / run_id
+    moved = move_artifacts(devlyn, dest)
+    pruned = prune(devlyn / "runs", keep=args.keep)
+
+    sys.stdout.write(f"archived run_id={run_id} files={moved} pruned={pruned}\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/config/skills/devlyn:auto-resolve/scripts/terminal_verdict.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""Compute auto-resolve terminal verdict per references/pipeline-routing.md#terminal-state-algorithm.
+
+Usage:
+    python3 scripts/terminal_verdict.py [--devlyn-dir .devlyn] [--json]
+
+Reads every `.devlyn/<phase>.findings.jsonl`, filters `status == "open"`, applies the
+precedence list, and prints the verdict (stdout) and exit code.
+
+Exit codes: 0 = PASS | 1 = PASS_WITH_ISSUES | 2 = NEEDS_WORK | 3 = BLOCKED
+
+The pipeline routing file defines the authoritative precedence. This script implements
+it deterministically so the orchestrator does not re-reason through the rule set per run.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import sys
+from collections import Counter
+
+
+PRECEDENCE = [
+    # (label, predicate on finding list) — first True wins
+    ("BLOCKED", lambda fs: any(f["severity"] == "CRITICAL" for f in fs)),
+    ("NEEDS_WORK", lambda fs: any(
+        f["severity"] == "HIGH"
+        and any(f.get("rule_id", "").startswith(p) for p in ("correctness.", "security.", "design."))
+        for f in fs
+    )),
+    ("NEEDS_WORK", lambda fs: any(f["severity"] == "HIGH" for f in fs)),
+    ("NEEDS_WORK", lambda fs: any(
+        f["severity"] == "MEDIUM" and f.get("rule_id", "").startswith("security.")
+        for f in fs
+    )),
+    ("PASS_WITH_ISSUES", lambda fs: any(f["severity"] == "MEDIUM" for f in fs)),
+    ("PASS_WITH_ISSUES", lambda fs: any(f["severity"] == "LOW" for f in fs)),
+    ("PASS", lambda fs: True),  # fallthrough
+]
+
+EXIT = {"PASS": 0, "PASS_WITH_ISSUES": 1, "NEEDS_WORK": 2, "BLOCKED": 3}
+
+
+def collect_open(devlyn: pathlib.Path) -> list[dict]:
+    open_findings: list[dict] = []
+    for jsonl in devlyn.glob("*.findings.jsonl"):
+        for line in jsonl.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                f = json.loads(line)
+            except json.JSONDecodeError:
+                # Malformed line surfaces explicitly rather than silently dropping.
+                sys.stderr.write(f"warn: malformed finding in {jsonl}: {line[:80]}\n")
+                continue
+            if f.get("status") == "open":
+                open_findings.append(f)
+    return open_findings
+
+
+def compute(findings: list[dict]) -> str:
+    for label, pred in PRECEDENCE:
+        if pred(findings):
+            return label
+    return "PASS"
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    p.add_argument("--devlyn-dir", default=".devlyn", help="path to .devlyn/ (default: ./.devlyn)")
+    p.add_argument("--json", action="store_true", help="emit JSON summary to stdout")
+    args = p.parse_args()
+
+    devlyn = pathlib.Path(args.devlyn_dir)
+    if not devlyn.is_dir():
+        sys.stderr.write(f"error: {devlyn} is not a directory\n")
+        return 3
+
+    findings = collect_open(devlyn)
+    verdict = compute(findings)
+    by_sev = Counter(f["severity"] for f in findings)
+
+    if args.json:
+        json.dump({"verdict": verdict, "open": len(findings), "by_severity": dict(by_sev)}, sys.stdout)
+        sys.stdout.write("\n")
+    else:
+        sys.stdout.write(f"{verdict}\n")
+        sys.stdout.write(f"open: {len(findings)} ({' '.join(f'{k}={v}' for k, v in sorted(by_sev.items()))})\n")
+
+    return EXIT[verdict]
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())