devlyn-cli 3.1.2 → 3.1.3

package/config/skills/_shared/state-phase-write.py

@@ -308,6 +308,36 @@ def bind_process_evidence(
                 raise runner.EvidenceError(
                     "spec-verify.results.json commands must be an array"
                 )
+            preflight_failure = "preflight_failure" in results
+            if preflight_failure:
+                failure = results["preflight_failure"]
+                if (
+                    not isinstance(failure, dict)
+                    or set(failure) != {"run_id", "phase", "round", "findings"}
+                    or failure["run_id"] != state.get("run_id")
+                    or failure["phase"] != phase
+                    or type(failure["round"]) is not int
+                    or failure["round"] != runner.phase_round(state, phase)
+                ):
+                    raise runner.EvidenceError("BUILD_GATE preflight failure identity is invalid")
+                record = failure["findings"]
+                if not isinstance(record, dict) or set(record) != {"path", "sha256"}:
+                    raise runner.EvidenceError("BUILD_GATE preflight failure findings binding is invalid")
+                path = runner._checked_file(work, record["path"], "preflight failure findings")
+                raw = path.read_bytes()
+                if hashlib.sha256(raw).hexdigest() != record["sha256"]:
+                    raise runner.EvidenceError("BUILD_GATE preflight failure findings digest mismatch")
+                findings = [loads_strict_json(line) for line in raw.decode("utf-8").splitlines() if line.strip()]
+                if len(findings) != 1 or not isinstance(findings[0], dict) or (
+                    findings[0].get("phase") != phase
+                    or findings[0].get("severity") != "CRITICAL"
+                    or findings[0].get("rule_id") not in {
+                        "correctness.spec-verify-malformed", "correctness.risk-probe-integrity",
+                    }
+                ):
+                    raise runner.EvidenceError("BUILD_GATE preflight failure requires its CRITICAL finding")
+                if verdict not in {"FAIL", "BLOCKED"}:
+                    raise runner.EvidenceError("BUILD_GATE preflight failure requires FAIL or BLOCKED verdict")
             carrier = results.get("process_evidence")
             if carrier is None:
                 if commands:
@@ -315,43 +345,42 @@ def bind_process_evidence(
                         "BUILD_GATE commands exist without a process-evidence carrier"
                     )
                 manifest_path = work / runner.manifest_relative_path(state, phase)
-                if manifest_path.exists():
+                if os.path.lexists(manifest_path):
                     raise runner.EvidenceError(
                         "BUILD_GATE manifest exists without a process-evidence carrier"
                     )
-                if runner.mechanical_evidence_required(work, state):
+                if not preflight_failure and runner.mechanical_evidence_required(work, state):
                     raise runner.EvidenceError(
                         "required BUILD_GATE evidence has no process-evidence carrier"
                     )
-                state.setdefault("process_evidence", None)
-                return
-            round_ = runner.phase_round(state, phase)
-            manifest = carrier.get("manifest") if isinstance(carrier, dict) else None
-            if (
-                not isinstance(carrier, dict)
-                or carrier.get("phase") != phase
-                or carrier.get("round") != round_
-                or not isinstance(manifest, dict)
-                or manifest.get("path") != runner.manifest_relative_path(state, phase)
-            ):
-                raise runner.EvidenceError(
-                    "BUILD_GATE process-evidence carrier does not match the active run/round"
-                )
-            outcome = runner.validate_summary_commands(work, commands, carrier)
-            if outcome["verdict"] == "BLOCKED" and verdict != "BLOCKED":
-                denial = outcome["capability_denials"][0]
-                raise runner.EvidenceError(
-                    "BUILD_GATE capability denial requires BLOCKED verdict: "
-                    f"{denial['id']}:{denial['operation']}"
-                )
-            if (
-                outcome["verdict"] == "NEEDS_WORK"
-                and verdict in {"PASS", "PASS_WITH_ISSUES"}
-            ):
-                raise runner.EvidenceError(
-                    "BUILD_GATE process evidence mismatch cannot complete as "
-                    f"{verdict}: {','.join(outcome['failed_ids'])}"
-                )
+            else:
+                round_ = runner.phase_round(state, phase)
+                manifest = carrier.get("manifest") if isinstance(carrier, dict) else None
+                if (
+                    not isinstance(carrier, dict)
+                    or carrier.get("phase") != phase
+                    or carrier.get("round") != round_
+                    or not isinstance(manifest, dict)
+                    or manifest.get("path") != runner.manifest_relative_path(state, phase)
+                ):
+                    raise runner.EvidenceError(
+                        "BUILD_GATE process-evidence carrier does not match the active run/round"
+                    )
+                outcome = runner.validate_summary_commands(work, commands, carrier)
+                if outcome["verdict"] == "BLOCKED" and verdict != "BLOCKED":
+                    denial = outcome["capability_denials"][0]
+                    raise runner.EvidenceError(
+                        "BUILD_GATE capability denial requires BLOCKED verdict: "
+                        f"{denial['id']}:{denial['operation']}"
+                    )
+                if (
+                    outcome["verdict"] == "NEEDS_WORK"
+                    and verdict in {"PASS", "PASS_WITH_ISSUES"}
+                ):
+                    raise runner.EvidenceError(
+                        "BUILD_GATE process evidence mismatch cannot complete as "
+                        f"{verdict}: {','.join(outcome['failed_ids'])}"
+                    )
     except (runner.EvidenceError, OSError, UnicodeError, ValueError) as exc:
         raise SystemExit(f"BLOCKED:process-evidence-invalid: {exc}") from exc
     existing = state.get("process_evidence")
@@ -362,8 +391,11 @@ def bind_process_evidence(
     try:
         for prior in existing:
             runner.validate_bound_carrier(work, prior)
-    except runner.EvidenceError as exc:
+    except (runner.EvidenceError, OSError, UnicodeError, ValueError) as exc:
         raise SystemExit(f"BLOCKED:process-evidence-invalid: {exc}") from exc
+    if carrier is None:
+        state.setdefault("process_evidence", None)
+        return
     if any(
         isinstance(item, dict)
         and item.get("phase") == carrier["phase"]
@@ -2996,6 +3028,144 @@ def self_test() -> int:
 
         test_interrupted_build_gate()
 
+        def test_preflight_build_gate() -> None:
+            work = (devlyn / "preflight-build-gate").resolve()
+            active = work / ".devlyn"
+            active.mkdir(parents=True)
+            state_file = active / "pipeline.state.json"
+            results_file = active / "spec-verify.results.json"
+            checker = pathlib.Path(__file__).with_name("spec-verify-check.py")
+            env = {key: value for key, value in os.environ.items() if key not in {
+                "BENCH_WORKDIR", "SPEC_VERIFY_PHASE", "SPEC_VERIFY_FINDINGS_FILE",
+                "SPEC_VERIFY_FINDING_PREFIX",
+            } and not key.startswith("DEVLYN_INVOCATION_")}
+            runner = process_evidence_module()
+
+            def complete(verdict: str) -> subprocess.CompletedProcess[str]:
+                return subprocess.run(
+                    [sys.executable, str(pathlib.Path(__file__).resolve()),
+                     "--devlyn-dir", ".devlyn", "--phase", "build_gate", "complete",
+                     "--verdict", verdict, "--findings-file", ".devlyn/spec-verify-findings.jsonl"],
+                    cwd=work, env=env, capture_output=True, text=True, encoding="utf-8",
+                )
+
+            history = []
+            for round_, scenario in enumerate(("fresh", "language", "stale", "denied")):
+                fixture = {
+                    "version": "3.0", "run_id": "rs-preflight-build-gate",
+                    "source": {"type": "generated", "criteria_path": ".devlyn/criteria.generated.md"},
+                    "phases": {"build_gate": None}, "process_evidence": copy.deepcopy(history) or None,
+                }
+                do_spawn(fixture, "build_gate", round_, None, None, "claude", None)
+                write_state(state_file, fixture)
+                original_state = state_file.read_bytes()
+                results_file.unlink(missing_ok=True)
+                relative = runner.manifest_relative_path(fixture, "build_gate")
+                manifest = work / relative
+                obligation = {"id": "type-check", "phase": "build_gate",
+                              "argv": [sys.executable, "-c", "raise SystemExit(7)"]}
+                if scenario == "language":
+                    runner.capture_process(work, manifest, fixture["run_id"], "build_gate", round_, obligation)
+                elif scenario == "denied":
+                    runner.record_capability_denial(
+                        work, manifest, fixture["run_id"], "build_gate", round_, obligation,
+                        "subprocess", b"route denied subprocess",
+                    )
+                elif scenario == "stale":
+                    results_file.write_bytes(prior_results)
+                observed = {path: path.read_bytes() for path in manifest.parent.iterdir()} if manifest.exists() else {}
+                rejected = subprocess.run(
+                    [sys.executable, str(checker), "--include-risk-probes"],
+                    cwd=work, env=env, capture_output=True, text=True, encoding="utf-8",
+                )
+                assert rejected.returncode == 1 and "source.criteria_path" in rejected.stderr, rejected.stderr
+                results = loads_strict_json(results_file.read_text(encoding="utf-8"))
+                assert results["preflight_failure"]["round"] == round_
+                prior_results = results_file.read_bytes()
+                finding = active / "spec-verify-findings.jsonl"
+                finding_bytes = finding.read_bytes()
+                for verdict in ("PASS", "PASS_WITH_ISSUES", "NEEDS_WORK"):
+                    denied = complete(verdict)
+                    assert denied.returncode != 0 and "preflight failure requires" in denied.stderr, denied.stderr
+                    assert state_file.read_bytes() == original_state
+                if scenario == "denied":
+                    denied = complete("FAIL")
+                    assert denied.returncode != 0 and "capability denial requires BLOCKED" in denied.stderr
+                    assert state_file.read_bytes() == original_state
+                completed = complete("BLOCKED" if scenario == "denied" else "FAIL")
+                assert completed.returncode == 0, completed.stderr
+                bound = read_state(state_file)
+                assert bound["phases"]["build_gate"]["verdict"] == ("BLOCKED" if scenario == "denied" else "FAIL")
+                assert finding.read_bytes() == finding_bytes and results_file.read_bytes() == prior_results
+                assert {path: path.read_bytes() for path in observed} == observed
+                if observed:
+                    assert bound["process_evidence"] == [*history, results["process_evidence"]]
+                else:
+                    assert bound["process_evidence"] == (history or None) and results["commands"] == []
+                history = bound["process_evidence"] or []
+                for mutation in ("run", "phase", "round", "bool-round", "digest", "escape", "finding", "null"):
+                    state_file.write_bytes(original_state)
+                    altered = copy.deepcopy(results)
+                    failure = altered["preflight_failure"]
+                    if mutation in {"run", "phase", "round", "bool-round"}:
+                        field, value = {"run": ("run_id", "rs-other"), "phase": ("phase", "verify"),
+                                        "round": ("round", round_ + 1), "bool-round": ("round", True)}[mutation]
+                        failure[field] = value
+                    elif mutation == "null":
+                        altered["preflight_failure"] = None
+                    elif mutation == "finding":
+                        finding.write_bytes(b"{}\n")
+                        failure["findings"]["sha256"] = hashlib.sha256(finding.read_bytes()).hexdigest()
+                    else:
+                        failure["findings"]["path" if mutation == "escape" else "sha256"] = (
+                            "../outside.jsonl" if mutation == "escape" else "0" * 64
+                        )
+                    results_file.write_text(json.dumps(altered), encoding="utf-8")
+                    result = complete("FAIL")
+                    assert result.returncode != 0 and "BLOCKED:process-evidence-invalid" in result.stderr, (mutation, result.stderr)
+                    assert state_file.read_bytes() == original_state
+                    finding.write_bytes(finding_bytes)
+                results_file.write_bytes(prior_results)
+                if scenario in {"fresh", "stale"}:
+                    state_file.write_bytes(original_state)
+                    malformed_prior = read_state(state_file)
+                    malformed_prior["process_evidence"] = {}
+                    write_state(state_file, malformed_prior)
+                    before = state_file.read_bytes()
+                    invalid = complete("FAIL")
+                    assert invalid.returncode != 0 and "null or an array" in invalid.stderr, invalid.stderr
+                    assert state_file.read_bytes() == before
+                    state_file.write_bytes(original_state)
+                if scenario == "stale":
+                    prior_stream = work / history[0]["streams"][0]["stdout"]["path"]
+                    saved = prior_stream.read_bytes()
+                    prior_stream.write_bytes(b"altered prior observation")
+                    invalid = complete("FAIL")
+                    assert invalid.returncode != 0 and "mismatch" in invalid.stderr, invalid.stderr
+                    assert state_file.read_bytes() == original_state
+                    prior_stream.write_bytes(saved)
+                    from unittest.mock import patch
+                    read_bytes = pathlib.Path.read_bytes
+
+                    def unreadable_prior(path):
+                        if path == prior_stream:
+                            raise PermissionError("prior stream unreadable")
+                        return read_bytes(path)
+
+                    fixture = read_state(state_file)
+                    unchanged = copy.deepcopy(fixture)
+                    with patch.object(pathlib.Path, "read_bytes", unreadable_prior):
+                        try:
+                            bind_process_evidence(fixture, "build_gate", "FAIL", active, work)
+                        except SystemExit as exc:
+                            assert str(exc) == "BLOCKED:process-evidence-invalid: prior stream unreadable", exc
+                        else:
+                            raise AssertionError("unreadable prior evidence completed")
+                    assert fixture == unchanged and state_file.read_bytes() == original_state
+            print("PASS preflight rejection: actual checker-to-completion, success floors, identity/digest controls")
+
+        test_preflight_build_gate()
+
         # complete() before spawn() must fail loudly, not silently invent data.
         write_state(state_path, {"phases": {}})
         state = read_state(state_path)

package/config/skills/_shared/task-complete.py

@@ -779,6 +779,14 @@ else:
     raise SystemExit('unexpected gh arguments: '+str(a))
 '''
 
+GIT_DISPATCH = r'''#!/bin/sh
+for arg do
+    case "$arg" in push|fetch|ls-remote|remove) exec python3 "$0.py" "$@";; esac
+done
+exec "$REAL_GIT" "$@"
+'''
+
+
 GIT_WRAPPER = r'''#!/usr/bin/env python3
 import json, os, pathlib, subprocess, sys
 a = sys.argv[1:]
@@ -822,7 +830,7 @@ class CompletionTests(unittest.TestCase):
         for key in list(self.env):
             if key in {"GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_COMMON_DIR"}:
                 del self.env[key]
-        for name, body in (("gh", FAKE_GH), ("git", GIT_WRAPPER)):
+        for name, body in (("gh", FAKE_GH), ("git.py", GIT_WRAPPER), ("git", GIT_DISPATCH)):
             path = self.bin / name
             path.write_text(body, encoding="utf-8")
             path.chmod(0o755)

package/config/skills/devlyn:ideate/SKILL.md

@@ -110,7 +110,7 @@ Structural lint (inline check, no script needed):
 After lint passes:
 1. Write `<spec-dir>/<id>-<slug>/spec.md` (the spec).
 2. Generate `<spec-dir>/<id>-<slug>/spec.expected.json` following `references/spec-template.md` § "Sibling file: `spec.expected.json`" for constraint coverage, diff scope and guard controls.
-3. Run `python3 "$DEVLYN_SHARED_DIR/spec-verify-check.py" --check <spec-path>` to validate the verification carrier shape, supported `complexity` frontmatter, and any present actionable solo-headroom hypothesis; if the spec uses a legacy inline `## Verification` JSON carrier, any solo-headroom hypothesis command must match that carrier's `verification_commands[].cmd`. If exit 2, fix the carrier/frontmatter/hypothesis and re-run.
+3. Run `python3 "$DEVLYN_SHARED_DIR/spec-verify-check.py" --check <spec-path>` to validate the actual spec's carrier shape and supported `complexity` frontmatter. Sibling `spec.expected.json` takes precedence over the legacy inline `## Verification` JSON carrier; any present actionable solo-headroom hypothesis command must match that carrier's `verification_commands[].cmd`. If exit 2, fix the file named in the error and re-run.
 4. Run `python3 "$DEVLYN_SHARED_DIR/spec-verify-check.py" --check-expected <expected-path>` to validate sibling `spec.expected.json` against `_shared/expected.schema.json` plus sibling spec `complexity` frontmatter and any present actionable solo-headroom hypothesis; if the spec has a solo-headroom hypothesis, its observable command must match `spec.expected.json.verification_commands[].cmd`. If exit 2, fix the JSON/frontmatter/hypothesis and re-run.
 5. Print: `spec ready — /devlyn:resolve --spec <spec-path>`.
 

package/config/skills/devlyn:ideate/references/from-spec-mode.md

@@ -37,7 +37,7 @@ You must NOT:
 3. For each missing/malformed piece: apply the smallest allowed fix.
 4. Write the normalized spec. Default location: `<spec-dir>/<id>-<slug>/spec.md`. With `--in-place` flag: write to `<path>` directly (overwrites the original).
 5. Generate or fix `spec.expected.json` per the rules above. Same dir as the spec.
-6. Run `python3 "$DEVLYN_SHARED_DIR/spec-verify-check.py" --check <spec-path>` to validate the spec carrier and supported `complexity` frontmatter; if the spec uses a legacy inline `## Verification` JSON carrier, any solo-headroom hypothesis command must match that carrier's `verification_commands[].cmd`.
+6. Run `python3 "$DEVLYN_SHARED_DIR/spec-verify-check.py" --check <spec-path>` to validate the actual spec's carrier shape and supported `complexity` frontmatter. Sibling `spec.expected.json` takes precedence over the legacy inline `## Verification` JSON carrier; any present actionable solo-headroom hypothesis command must match that carrier's `verification_commands[].cmd`. If exit 2, fix the file named in the error and re-run.
 7. Run `python3 "$DEVLYN_SHARED_DIR/spec-verify-check.py" --check-expected <expected-path>` to validate sibling `spec.expected.json` plus sibling spec `complexity` frontmatter and any present solo-headroom hypothesis command against `spec.expected.json.verification_commands[].cmd`.
 8. If lint still fails after allowed fixes (e.g. Requirements section is empty in the source), surface the issue and exit non-zero — do NOT invent Requirements.
 9. If the preserved Requirements combine state mutation with ordering/priority,

package/config/skills/devlyn:ideate/references/spec-template.md

@@ -95,10 +95,10 @@ Schema: `_shared/expected.schema.json`. Required when Requirements have observab
 python3 "$DEVLYN_SHARED_DIR/spec-verify-check.py" --check-expected <expected-path>
 ```
 
-Map mechanically decidable rules from both Requirements and Constraints into the existing carriers. Validate each new guard with a violating control that fails and an allowed control that passes, preserving permitted pre-existing occurrences:
+Map mechanically decidable rules from both Requirements and Constraints into the existing carriers. Preserve specific file constraints even when narrower than PLAN's scope. During BUILD_GATE, with `state.base_ref.sha` recorded, the existing `authorized_surface` check enforces PLAN's scope over the run diff and newly created untracked paths (`.devlyn/` exempt). Do not duplicate this general scope check with a whole-checkout scan in `verification_commands`. Validate each new guard with a violating control that fails and an allowed control that passes, preserving permitted pre-existing occurrences:
 - `verification_commands` ← `## Verification` + commands the conversation surfaced. While drafting both Verification and its carrier, omit a standalone check only when another command in that contract runs the same assertions under the required execution conditions and propagates failure; describe that shared coverage in Verification and keep both carriers aligned. Preserve distinct scenarios and required independent verification; execute approved commands unchanged without reusing results across phases. For semantic annotation or exception-handling rules, use a suitable syntax-aware/executable check, preferring existing checks; explicitly retain uncovered semantics as source-review obligations.
 - `forbidden_patterns` ← literal syntax constraints only; regex does not prove semantics. It scans the whole file-filtered diff, including context, deletions and headers; additions-only guards must exclude those lines.
-- `required_files` / `forbidden_files` ← file requirements and exclusions in Requirements, Constraints and Out of Scope.
+- `required_files` / `forbidden_files` ← literal file paths from Requirements, Constraints and Out of Scope; `forbidden_files` matches exact Git-relative paths (forward slashes, no leading `./`), including both names of a rename. Globs and directory-wide exclusions need a suitable `verification_commands` guard, not wildcard-looking entries in these lists.
 - `max_deps_added` ← dependency limits in Requirements or Constraints (default 0 unless the spec licenses a new dep).
 - `required_risk_probe_requirements` ← for specs where a Requirement combines ordering/priority, rollback, idempotency, auth/signature, concurrency, atomic-batch, or exact output shape, declare the risk categories PHASE 1.5 risk-probe derivation must cover directly, e.g. `[{"tag": "rollback_state", "derived_from": "<exact ## Verification bullet>"}]`. This replaces guessing the required categories from prose — declare them explicitly so the check works in any language. `tag` must be one of the risk-probe tags in `_shared/spec-verify-check.py:RISK_PROBE_TAGS`; `derived_from` must be an exact substring of `## Verification`. Omit entirely when the spec has no ordering/rollback/idempotency/auth/concurrency/atomic-batch/exact-shape risk.
 

package/config/skills/devlyn:resolve/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: devlyn:resolve
-description: Hands-free full pipeline for explicit resolve requests, formal specs, queue drains, material ambiguity, subsystem/design work, security/auth/payment/persistence/concurrency/public-API-contract changes, or no decisive acceptance check. Free-form goal or formal spec input. Plan → Implement → Build-gate → Cleanup → Verify (fresh subagent, findings-only). Mechanical-first verification; Verify dual-judge is default-when-available. Clear, local, reversible, low-risk conversational edits with decisive checks default to direct execution; explicit small resolve keeps the full workflow.
+description: Default to direct work after inspecting scope and verification, including bounded multi-file changes. Use full resolve for explicit resolve/spec-mode requests, queue drains, or concrete interacting requirements or verification too complex for the current context. Domain labels, file count, spec documents and quoted skill paths alone do not trigger it. Investigate or clarify missing intent/access first. Explicit small resolve retains all phases and independent verification. Verify dual-judge is default-when-available.
 ---
 
-Orchestrator for the 2-skill harness pipeline. One fresh worker per phase; file-based handoff via `.devlyn/pipeline.state.json`. VERIFY spawns a fresh-context worker so independence is structural — not advisory.
+The current CLI owns PHASE 0, state transitions, Git checkpoints and final report/archive. Spawn the canonical phase workers from this process; never delegate the whole run to another parent orchestrator. VERIFY uses a fresh, findings-only worker.
 
 <pipeline_config>
 $ARGUMENTS
@@ -297,7 +297,7 @@ the BUILD_GATE process-evidence manifest and complete the phase as
 `BLOCKED:build-env-underprovisioned`, not as a product finding or substitute
 command. The worker:
 1. Detects language/framework via project files (`package.json`, `pyproject.toml`, etc.).
-2. Runs language-specific gates (tsc / lint / test).
+2. Runs language-specific gates (tsc / lint / test), deferring exact literal overlaps under `references/phases/build-gate.md`'s current-contract/current-round rule; task-context prompts must preserve that rule.
 3. Always runs `python3 "$DEVLYN_SHARED_DIR/spec-verify-check.py" --include-risk-probes` (verification_commands literal-match plus `.devlyn/risk-probes.jsonl` when present). If `state.risk_profile.risk_probes_enabled == true`, the script requires `.devlyn/risk-probes.jsonl`; a missing file is a CRITICAL mechanical blocker, not a silent solo run. The script routes each command through `process-evidence.py`; preserve `.devlyn/spec-verify.results.json` and its validated BUILD_GATE carrier for the state-bound archive flow.
 4. If diff touches web-surface files: run the browser tier with the repo's available toolchain (for example Playwright or curl).
 5. Emits `.devlyn/build_gate.findings.jsonl` + `.devlyn/build_gate.log.md`.
@@ -306,7 +306,7 @@ State write: `phases.build_gate.{started_at, verdict, completed_at, duration_ms,
 
 Branch:
 - `PASS` → PHASE 4.
-- `FAIL` → fix loop. Spawn IMPLEMENT-engine agent with the build_gate findings as input, then run the common post-fix checkpoint with origin `build_gate`. On second FAIL with `state.rounds.global >= state.rounds.max_rounds` → halt with verdict `BLOCKED:build-gate-exhausted`.
+- `FAIL` → before product repair, halt with report-level `BLOCKED:required-tools-unavailable` only if a parent probe confirms the failed invocation's external gate tool is absent, unchanged `state.base_ref.sha` configuration requires it, and cited explicit task/spec constraints prohibit supplying it through any authorized route. Derive the tool from that configuration and invocation, never diagnostic text; bind the probe's interpreter, work root and normalized child environment to the runner call sites and actual gate invocation, not parent PATH or a manifest command string alone. An available authorized tool route, product-module/configuration failure, changed tool configuration, permitted or unspecified supply, or uncertain probe/identity/environment retains the fix loop. A confirmed prohibited-tool blocker wins even with other product findings: leave them unrepaired and preserve phase `FAIL`, findings, raw streams and sealed manifests unchanged. Record the probe and constraint citation separately in parent halt evidence; no repair means no round increment. Otherwise spawn IMPLEMENT-engine agent with the build_gate findings as input, then run the common post-fix checkpoint with origin `build_gate`. On second FAIL with `state.rounds.global >= state.rounds.max_rounds` → halt with verdict `BLOCKED:build-gate-exhausted`.
 - `BLOCKED:build-env-underprovisioned` → halt immediately with the denied operation, original command, and process-evidence manifest/id; do not enter the product fix loop.
 
 ## PHASE 4: CLEANUP

package/config/skills/devlyn:resolve/references/free-form-mode.md

@@ -75,8 +75,8 @@ When the rules are silent (rare — pathological goal text), default to `medium`
 The internal mini-spec written for trivial / medium / large-assumptions paths must satisfy:
 
 - `## Requirements` non-empty, each bullet testable (CLI command, test command, observable file change).
-- For executable generated verification, put one fenced `json` object with only `verification_commands` inside the sentinel-marked `## Verification` section. Generated mode reads this inline carrier, not a sibling file. Follow `../../devlyn:ideate/references/spec-template.md` § "Sibling file: `spec.expected.json`" for constraint coverage, diff scope and violating/allowed controls, but express those checks as executable `verification_commands`; sibling-only fields such as `required_files` and `forbidden_patterns` are rejected inline. Preserve uncovered semantics as source-review obligations.
-- `## Verification` is preceded by a `<!-- devlyn:verification -->` sentinel on its own line directly above the heading — the machine locator `spec-verify-check.py` uses; the heading text itself is decorative and may be any language. `## Verification` non-empty if the goal implies any runnable acceptance check. Empty Verification is allowed only when all Requirements are pure-design (e.g. "follow existing pattern X").
+- For executable generated verification, put one fenced `json` object with `verification_commands` inside the sentinel-marked `## Verification` section. Generated mode reads this inline carrier, not a sibling file. Follow `../../devlyn:ideate/references/spec-template.md` § "Sibling file: `spec.expected.json`" for constraint coverage, diff scope and violating/allowed controls, but express those checks as executable `verification_commands`; sibling-only fields such as `required_files` and `forbidden_patterns` are rejected inline. Preserve uncovered semantics as source-review obligations.
+- `## Verification` is preceded by a `<!-- devlyn:verification -->` sentinel on its own line directly above the heading — the machine locator `spec-verify-check.py` uses; the heading text itself is decorative and may be any language. When all Requirements are pure-design with no runnable acceptance check, put `{"pure_design": true, "verification_commands": []}` in the fenced `json` block and retain semantic source-review obligations. This explicit declaration is required; a missing block, an unmarked empty list, or `pure_design: true` with commands is invalid.
 - If a free-form goal includes pair-evidence intent and already includes an actionable solo-headroom hypothesis, preserve that literal hypothesis in `.devlyn/criteria.generated.md` unchanged enough for VERIFY to detect `solo-headroom hypothesis`, `solo_claude`, `miss`, and the backticked observable command line that itself contains `miss`, emit the canonical `spec.solo_headroom_hypothesis` pair trigger reason, and satisfy regenerated-evidence checks such as `benchmark audit --require-hypothesis-trigger`.
 - If a free-form goal includes unmeasured pair-candidate intent and already includes solo ceiling avoidance, preserve that literal note in `.devlyn/criteria.generated.md` unchanged enough for reviewers to see `solo ceiling avoidance`, `solo_claude`, and the concrete difference from rejected or solo-saturated controls such as `S2`-`S6`.
 - Free-form mode mini-specs are written to `.devlyn/criteria.generated.md` (not to a roadmap path) — this is run-scoped artifact, not a documented spec.

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

@@ -3,7 +3,7 @@
 Per-engine adapter header is prepended at runtime. BUILD_GATE is mechanical / deterministic — same commands CI / Docker / production run.
 
 <role>
-Run language-specific gates and the spec literal-match verification. Emit findings; the orchestrator's fix loop consumes them.
+Run language-specific gates and the spec literal-match verification. Emit findings; the orchestrator's fix loop consumes them. Git staging and commits belong to the parent IMPLEMENT checkpoint; verify any staging prerequisite with read-only Git inspection, never repeat `git add` or forward task staging instructions as worker actions.
 </role>
 
 <capability_contract>
@@ -46,7 +46,7 @@ Detect the project shape from files in `state.base_ref.sha`:
 </detection>
 
 <gates>
-Run in this order; each emits findings into `.devlyn/build_gate.findings.jsonl`:
+Resolve the concrete commands for steps 1–3; detection examples are not command identities. Run them in order unless step 4's current valid literal contract, using its source precedence and checker defaults, schedules the exact command with the same source/test inputs, working directory and effective environment. Establish the work root and normalized child environment from the checker/runner call sites and the current invocation; a manifest's command string alone does not establish them. The literal must expect exit 0, cover every gate assertion and use the same effective timeout as the planned gate invocation; uncertain matches run normally. Defer a matching gate to step 4 and derive its usual per-error findings and severity from that invocation's validated current BUILD_GATE run/round raw streams, citing the evidence id. A completed nonzero exit still supplies the gate's usual failure findings. If step 4 leaves no validated exit-kind result for a deferred gate, run that gate normally and append its findings, preserving step 4's failures; capability denials retain the stop contract above. Keep every literal invocation and independent post-CLEANUP VERIFY. Each gate emits findings into `.devlyn/build_gate.findings.jsonl`:
 
 1. **Type check** (TypeScript / mypy / etc.). Each error → one finding, severity `HIGH`, rule `correctness.type-check`.
 2. **Lint**. Run a recognized configured language linter (for example, ESLint with a config, `ruff`, or `clippy`) and/or the exact `package.json` `scripts.lint` command. A declared specialized `lint:*` script (for example, `lint:json`) is not the general language lint gate on the strength of its declaration alone. If the spec's verification commands explicitly name such a specialized command, step 4 executes it and preserves its real failure severity. If no linter is applicable, log an explicit SKIP in `.devlyn/build_gate.log.md` and emit zero lint findings. Each error → finding, severity `MEDIUM`, rule `quality.lint`. Warnings stay LOW unless the spec elevates them.
@@ -59,6 +59,7 @@ Append all findings; do not stop on the first failure.
 
 <output>
 - `.devlyn/build_gate.findings.jsonl` — JSONL stream, one finding per line. Schema: `{id, rule_id, severity, file, line, message, fix_hint, criterion_ref}`.
+- A completed checker preflight rejection writes `spec-verify.results.json` with `preflight_failure` and the original CRITICAL finding's path/digest. Retain that source (default `.devlyn/spec-verify-findings.jsonl`) and append its finding to `.devlyn/build_gate.findings.jsonl`. Earlier gate observations remain bound, but no spec command is claimed to have run. An absent results file still follows the interrupted-observation `BLOCKED` path.
 - `.devlyn/build_gate.log.md` — human-readable gate results with raw output or links to complete raw-output files, using sealed artifacts where available. Retain complete inventories/hash maps in `.devlyn/` files; report their paths, digests and relevant deltas instead of dumping them into the conversation.
 - Report `PASS` if zero CRITICAL/HIGH findings, `FAIL` for genuine product findings, or `BLOCKED:build-env-underprovisioned` only for the evidence-backed capability path above. A capability blocker leaves no product finding. Do not edit `pipeline.state.json` yourself — the orchestrator records it via `state-phase-write.py` from these artifacts.
 </output>

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

@@ -54,7 +54,7 @@ Single authoritative verdict source for `/devlyn:resolve`. The orchestrator bran
 - **engine** — any engine name with a shipped adapter (`_shared/adapters/<name>.md`); `"claude"` and `"codex"` today. A required unavailable engine stops the run with `BLOCKED:<engine>-unavailable`.
 - **engine_source** — `"flag" | "engines.json" | "default"` — provenance of the resolved executor engine (`_shared/engine-preflight.md#role-resolution`). Optional on archived pre-iter-0038 runs; absent means `default`.
 - **source** — downstream contract provenance. Spec/verify-only set `type: "spec"`, `spec_path`, and `spec_sha256`. Free-form sets `type: "generated"`, `goal_path: ".devlyn/goal.raw.txt"` + exact-byte `goal_sha256`, and `criteria_path: ".devlyn/criteria.generated.md"` + raw-byte `criteria_sha256`. VERIFY re-checks its contract hash.
-- **`.devlyn/external-diff.patch` artifact** — verify-only input; the verifier consumes it only when `mode` is `"verify-only"` and fails closed if it exists in any other mode.
+- **`.devlyn/external-diff.patch` artifact** — verify-only Git patch with `a/` and `b/` path prefixes (`git diff --binary --src-prefix=a/ --dst-prefix=b/`). A zero-byte file means no changes; file-path checks reject malformed or other-prefix input. File exclusions cover both names in rename/copy headers. The verifier fails closed if the artifact exists outside `"verify-only"` mode.
 - **risk_profile** — PHASE 0 routing state. `high_risk` controls automatic risk probes; `risk_probes_enabled` / `risk_probes_explicit` preserve their current semantics; `pair_default_enabled` is false only for explicit `--no-pair`. `risk_profile` must remain an object with boolean `high_risk`, `risk_probes_enabled`, `risk_probes_explicit`, and `pair_default_enabled` fields when present, plus `reasons` as a string list. Malformed state blocks VERIFY because it can hide required routes.
 - **risk_probes_digest** — top-level sha256 written by PHASE 1.5 after probe validation; BUILD_GATE/VERIFY replay semantics live in `phases/build-gate.md` step 4.
 - **process_evidence** — absent or JSON null for legacy runs and new runs with no captured obligation; otherwise an append-only array of `{phase, round, manifest: {path, sha256}, streams: [{id, stdout: {path, sha256}, stderr: {path, sha256}}]}` carriers. Paths are worktree-relative and live under `.devlyn/process-evidence/<run_id>/<phase>/round-<round>/`. A successful IMPLEMENT completion/transition validates every sibling `spec.expected.json.process_evidence[]` item declared for `phase: "implement"`, rehashes both raw streams (including zero-byte files), and appends the carrier before accepting the checkpoint. Missing, altered, escaping, duplicate-id, or expectation-mismatched evidence blocks without a state mutation. Later phases reuse the same carrier shape; no schema-major bump is required because readers must accept absent/null legacy state.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlyn-cli",
-  "version": "3.1.2",
+  "version": "3.1.3",
   "description": "Loop & harness engineering for AI coding agents (Claude Code, Codex, and any AGENTS.md-driven agent) — take intent to shipped, engineer-quality software hands-free with phase-gated pipelines and agent orchestration",
   "homepage": "https://github.com/fysoul17/devlyn-cli#readme",
   "bin": {

package/scripts/lint-skills.sh

@@ -356,7 +356,7 @@ PY
 
   incomplete="$tmp_install_marker/incomplete"
   mkdir -p "$incomplete/package" "$incomplete/home/.codex/skills" "$incomplete/claude/.claude/skills" "$incomplete/codex"
-  cp -R bin config package.json "$incomplete/package/"
+  cp -R bin config package.json AGENTS.md CLAUDE.md "$incomplete/package/"
   rm -rf "$incomplete/package/config/skills/devlyn:queue"
   printf '{"version":"stale"}\n' > "$incomplete/home/.codex/skills/.devlyn-install.json"
   printf '{"version":"stale"}\n' > "$incomplete/claude/.claude/skills/.devlyn-install.json"
@@ -1298,7 +1298,7 @@ done
 for pattern in \
   'def stage_from_expected' \
   'stage_from_expected(' \
-  'expected_found, expected_staged, expected_error, expected_path' \
+  'contract_found, _staged, expected_error, expected_path' \
   'def expected_contract_findings' \
   'correctness.forbidden-pattern' \
   'scope.max-deps-added-exceeded' \