devlyn-cli 3.1.2 → 3.2.0

package/bin/instructions.js

@@ -0,0 +1,187 @@
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const legacyTemplates = require('./instruction-templates.json');
+
+const BEGIN = '<!-- devlyn:instructions:begin';
+const END = '<!-- devlyn:instructions:end -->';
+const LEGACY = /^devlyn-cli installs |^# Devlyn Agent Instructions\r?$|^This contract serves one goal: any capable engine|^Engine roles: orchestrator =/m;
+const normalize = (text) => text.replace(/\r\n/g, '\n');
+const digest = (text) => crypto.createHash('sha256').update(text).digest('hex');
+
+class InstructionError extends Error {}
+
+function managedBlock(template, eol) {
+  const body = 'Project-specific instructions outside this managed block take precedence over these defaults.\n\n'
+    + normalize(template).replace(/\n?$/, '\n');
+  return `${BEGIN} sha256=${digest(body)} -->\n${body}${END}\n`.replace(/\n/g, eol);
+}
+
+function matchedEnd(text, start, template) {
+  let end = start;
+  for (let n = 0; n < template.length && end < text.length; n++, end++) {
+    if (text[end] === '\r' && text[end + 1] === '\n') end++;
+  }
+  return digest(normalize(text.slice(start, end))) === template.sha256 ? end : null;
+}
+
+// A digest is ownership evidence; a familiar heading alone is not.
+function legacyRanges(text, templates) {
+  const starts = [...new Set([0, ...(text.startsWith('\uFEFF') ? [1] : []),
+    ...Array.from(text.matchAll(/^# (?:Codex )?Project Instructions\r?$/gm), (m) => m.index)])].sort((a, b) => a - b);
+  const ranges = [];
+  for (const start of starts) {
+    for (const template of templates) {
+      let end = matchedEnd(text, start, template);
+      let custom = '';
+      if (end === null && template.body) {
+        const prefix = text.slice(start, starts.find((offset) => offset > start));
+        const body = /^## North Star\r?$/m.exec(prefix);
+        const header = template.preamble.slice(0, template.preamble.indexOf('\n\n') + 2);
+        if (body && normalize(prefix).startsWith(header)) {
+          const bodyStart = start + body.index;
+          end = matchedEnd(text, bodyStart, template.body);
+          // Remove only an exact original preamble; preserve an edited one in full.
+          const preambleEnd = matchedEnd(text, start, { length: template.preamble.length, sha256: digest(template.preamble) });
+          custom = text.slice(preambleEnd ?? start, bodyStart);
+        }
+      }
+      if (end !== null) {
+        const existing = ranges.find((range) => range.start === start && range.end === end);
+        if (!existing) ranges.push({ start, end, custom });
+        // Releases may share a body. Prefer the exact owned preamble, if found.
+        else if (custom.length < existing.custom.length) existing.custom = custom;
+      }
+    }
+  }
+  return ranges;
+}
+
+function retainFile(file, bytes) {
+  for (const directory of [path.dirname(path.dirname(file)), path.dirname(file)]) {
+    const stat = fs.lstatSync(directory, { throwIfNoEntry: false });
+    if (stat && !stat.isDirectory()) {
+      throw new InstructionError(`Instruction recovery needs a real directory: ${directory}. Move it aside and rerun installation.`);
+    }
+    if (!stat) fs.mkdirSync(directory);
+  }
+  const ignore = path.join(path.dirname(file), '.gitignore');
+  if (!fs.existsSync(ignore)) fs.writeFileSync(ignore, '*\n', { flag: 'wx', mode: 0o600 });
+  if (fs.existsSync(file)) {
+    if (!fs.lstatSync(file).isFile() || !fs.readFileSync(file).equals(bytes)) {
+      throw new InstructionError(`Instruction recovery file differs; preserved it: ${file}. Move it aside before retrying.`);
+    }
+  } else {
+    fs.writeFileSync(file, bytes, { flag: 'wx', mode: 0o600 });
+  }
+}
+
+function updateInstructions(name) {
+  const templatePath = path.join(__dirname, '..', name);
+  const template = fs.readFileSync(templatePath, 'utf8');
+  if (template.includes(BEGIN) || template.includes(END)) {
+    throw new Error(`Packaged instruction template contains managed markers: ${templatePath}`);
+  }
+  const dest = path.join(process.cwd(), name);
+  const stat = fs.lstatSync(dest, { throwIfNoEntry: false });
+  const sourceStat = fs.statSync(templatePath);
+  if (stat?.isFile() && stat.dev === sourceStat.dev && stat.ino === sourceStat.ino) {
+    console.log(`  → Using source ${name}; packaged template left unchanged`);
+    return false;
+  }
+  const exists = Boolean(stat);
+  // Do not replace a shared instruction symlink or follow it outside the project.
+  if (stat && !stat.isFile()) {
+    throw new InstructionError(`Instruction file must be a regular file; preserved: ${dest}. Move it aside and rerun, then merge your shared rules outside the managed block.`);
+  }
+  const before = exists ? fs.readFileSync(dest) : Buffer.alloc(0);
+  let current;
+  try {
+    current = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(before);
+  } catch (cause) {
+    throw new InstructionError(`${name} must be UTF-8; original preserved. Convert its encoding and rerun installation.`, { cause });
+  }
+  const eol = current.match(/\r?\n/)?.[0] || '\n';
+  const block = managedBlock(template, eol);
+  const recovery = path.join(process.cwd(), '.devlyn', 'instructions');
+  const conflict = (reason) => {
+    const incoming = path.join(recovery, `${name}.${digest(block)}.incoming`);
+    const backup = path.join(recovery, `${name}.${digest(before)}.backup`);
+    const guide = path.join(recovery, `${name}.${digest(before)}.${digest(block)}.merge.md`);
+    retainFile(backup, before);
+    retainFile(incoming, Buffer.from(block));
+    retainFile(guide, Buffer.from(`# Merge ${name}\n\n`
+      + `Installation stopped: ${reason}. The original file is unchanged.\n\n`
+      + `- Backup before this install attempt: ${backup}\n- New Devlyn defaults: ${incoming}\n- File to update: ${dest}\n\n`
+      + `1. Compare the backup and new defaults side by side. Identify all project-specific additions and edits; do not discard them.\n`
+      + `2. Update ${name} with exactly one complete managed block from the new defaults. Keep project-specific rules outside that block; they take precedence. Resolve conflicting rules explicitly. Do not copy the new defaults over the whole file.\n`
+      + `3. Review the result, then rerun the same install command (for example, npx devlyn-cli). Other selected agents may still need installation.\n\n`
+      + `To undo this manual merge, restore that backup to ${dest}. Earlier backups are retained too.\n`));
+    throw new InstructionError(`${name} needs merge (${reason}).\n`
+      + `Original preserved: ${dest}\nBackup: ${backup}\nNew defaults: ${incoming}\n`
+      + `Merge instructions: ${guide}\n`
+      + `Keep custom rules outside the managed block, then rerun the same install command.\n`
+      + `Installation is incomplete; earlier selected agents may already have been updated.`);
+  };
+  let content;
+  if (current.includes(BEGIN) || current.includes(END)) {
+    const starts = [...current.matchAll(/^\uFEFF?<!-- devlyn:instructions:begin sha256=([a-f0-9]{64}) -->\r?\n/gm)];
+    const ends = [...current.matchAll(/^<!-- devlyn:instructions:end -->(?:\r?\n|$)/gm)];
+    if (starts.length !== 1 || ends.length !== 1
+        || current.split(BEGIN).length !== 2 || current.split(END).length !== 2) {
+      return conflict('ambiguous managed markers');
+    }
+    const start = starts[0];
+    const end = ends[0];
+    const bodyStart = start.index + start[0].length;
+    if (end.index < bodyStart || digest(normalize(current.slice(bodyStart, end.index))) !== start[1]) {
+      return conflict('managed defaults were edited');
+    }
+    content = current.slice(0, start.index + (start[0].startsWith('\uFEFF') ? 1 : 0)) + block + current.slice(end.index + end[0].length);
+  } else {
+    const normalized = normalize(template);
+    const bodyStart = normalized.indexOf('## North Star\n');
+    const preamble = normalized.slice(0, bodyStart);
+    const body = normalized.slice(bodyStart);
+    const ranges = legacyRanges(current, [
+      { length: normalized.length, sha256: digest(normalized),
+        ...(bodyStart > 0 ? { preamble, body: { length: body.length, sha256: digest(body) } } : {}) },
+      ...(legacyTemplates[name] || []),
+    ]);
+    if (ranges.length > 1) return conflict('multiple legacy templates');
+    if (ranges.length === 1) {
+      const { start, end, custom } = ranges[0];
+      if (LEGACY.test(current.slice(0, start) + custom + current.slice(end))) {
+        return conflict('edited legacy introduction or extra template text');
+      }
+      content = current.slice(0, start) + custom + block + current.slice(end);
+    } else {
+      if (LEGACY.test(current)) {
+        return conflict('unrecognized or edited legacy template');
+      }
+      content = current + (current ? eol + eol : '') + block;
+    }
+  }
+  const bytes = Buffer.from(content);
+  if (bytes.equals(before)) return false;
+  if (exists) {
+    const backup = path.join(recovery, `${name}.${digest(before)}.backup`);
+    retainFile(backup, before);
+    console.log(`  → Saved previous ${name}: ${backup}`);
+  }
+  const temp = `${dest}.${crypto.randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(temp, bytes, { flag: 'wx', mode: exists ? stat.mode & 0o777 : 0o644 });
+    if (exists) fs.chmodSync(temp, stat.mode & 0o777);
+    if (fs.existsSync(dest) !== exists || (exists && !fs.readFileSync(dest).equals(before))) {
+      throw new InstructionError(`${name} changed during installation; preserved it. Rerun installation.`);
+    }
+    fs.renameSync(temp, dest);
+  } finally {
+    if (fs.existsSync(temp)) fs.unlinkSync(temp);
+  }
+  console.log(`  → Updated Devlyn defaults in ${name}; project-specific instructions preserved`);
+  return true;
+}
+
+module.exports = { updateInstructions, InstructionError };

package/config/skills/_shared/adapters/claude.md

@@ -55,7 +55,7 @@ python3 "$DEVLYN_SHARED_DIR/run-bounded.py" 600 --stdin-file "<judge-prompt-file
 
 ## Identity
 
-You are Claude by Anthropic. Anthropic's prompt-engineering guide for this model governs your behavior on top of the canonical phase prompt below. When the canonical body and this header conflict on tactics, the canonical body wins on what to deliver; this header wins on how to deliver it.
+You are Claude by Anthropic. Anthropic's prompt-engineering guide for this model governs your behavior on top of the canonical phase prompt below.
 
 ## Output discipline
 
@@ -73,10 +73,6 @@ When the canonical body lists tools, use them when their result would change you
 
 For long-horizon coding, review, and agentic runs, assume the harness selected `high` or `xhigh` effort unless told otherwise. Spend that depth on upfront task/constraint understanding and end-state verification, not on verbose narration. If the user or orchestrator gives a complete task in one turn, proceed autonomously instead of requiring progressive clarification.
 
-## Validation pattern
-
-When the canonical body asks you to verify your output before declaring done ("self-check" instructions), execute that step literally — re-read the spec's acceptance criteria, run the listed verification commands if available, list any gap. This is not optional. Mechanical gates owned by the harness (spec-verify-check.py, build-gate.py) are the primary correctness guard; your self-check is the secondary layer that catches what regex cannot.
-
 ## Anti-patterns
 
 You interpret instructions literally and explicitly. The official guide is explicit about three failure modes:

package/config/skills/_shared/adapters/codex.md

@@ -4,7 +4,7 @@
 
 ## Identity
 
-You are OpenAI's Codex model. OpenAI's prompt-guidance for this model governs your behavior on top of the canonical phase prompt below. When the canonical body and this header conflict on tactics, the canonical body wins on what to deliver; this header wins on how to deliver it.
+You are OpenAI's Codex model. OpenAI's prompt-guidance for this model governs your behavior on top of the canonical phase prompt below.
 
 ## Output discipline
 
@@ -19,10 +19,6 @@ canonical file and its `.agents` mirror are byte-identical, inspect the
 canonical file only. Open self-test bodies or MECHANICAL raw streams only for a
 named clause that remains unresolved after the broad pass.
 
-## Validation pattern
-
-Validation is concrete commands and tools, not self-belief. When the canonical body lists verification commands, execute them and trust their output. Do not substitute your judgment for a deterministic check the harness has provided. When validation tools are available (test runners, lint, type-check, the harness's `spec-verify-check.py`), run them before declaring success. The minimum evidence sufficient to answer correctly, cited precisely — then stop.
-
 ## Anti-patterns
 
 The official guide warns explicitly about carrying over instructions from older prompt stacks — earlier models needed more help, and process-heavy directives now narrow GPT-5.5's search space.

package/config/skills/_shared/adapters/omp.md

@@ -8,10 +8,6 @@ You are the model running behind the `omp` CLI. Follow the canonical phase promp
 
 Keep phase output machine-consumable and concise. Write the artifacts the canonical body names, update `.devlyn/pipeline.state.json` only where that phase owns the state write, and avoid narrative outside the required phase result.
 
-## Validation Pattern
-
-When the canonical body names deterministic commands, run those commands and trust their exit codes. Do not replace BUILD_GATE, phase gates, or VERIFY mechanical checks with same-context judgment.
-
 ## Fresh Context
 
 Each native `task` tool invocation with a fresh `context` is a fresh phase worker. Do not call `/devlyn:resolve` recursively from inside a phase prompt; execute only the phase body you received.

package/config/skills/_shared/archive_run.py

@@ -464,7 +464,11 @@ def move_artifacts(devlyn: pathlib.Path, dest: pathlib.Path) -> int:
     try:
         for source, target in moves:
             target.parent.mkdir(parents=True, exist_ok=True)
-            shutil.move(str(source), str(target))
+            try:
+                shutil.move(str(source), str(target))
+            except OSError:
+                target.unlink(missing_ok=True)
+                raise
             completed.append((source, target))
     except BaseException:
         for source, target in reversed(completed):

package/config/skills/_shared/codex-config.md

@@ -22,7 +22,7 @@ if [ ! -f "$CODEX_MONITORED_PATH" ]; then
 fi
 ```
 
-**Read-only critique / adversarial review / debate** (`/devlyn:resolve` VERIFY pair-mode, plus any future ideate read-only critique). Security review stays native to Claude Code BUILD_GATE. Codex returns findings on stdout; the orchestrator writes files.
+**Read-only critique / adversarial review / debate** (`/devlyn:resolve` VERIFY pair-mode, plus any future ideate read-only critique). Codex returns findings on stdout; the orchestrator writes files.
 
 ```bash
 DEVLYN_CODEX_PROMPT_FILE="<prompt-file>" CODEX_MONITORED_ISOLATED=1 CODEX_MONITORED_TIMEOUT_SEC=600 bash "$CODEX_MONITORED_PATH" \
@@ -43,24 +43,13 @@ DEVLYN_CODEX_PROMPT_FILE="<prompt-file>" bash "$CODEX_MONITORED_PATH" \
   -
 ```
 
-**CI-equivalent BUILD_GATE** keeps the same write sandbox and enables general
-outbound network access inside that sandbox, including the loopback servers and
-network-backed test gates that CI may exercise:
-
-```bash
-DEVLYN_CODEX_PROMPT_FILE="<prompt-file>" bash "$CODEX_MONITORED_PATH" \
-  -C <project-root> \
-  -s workspace-write \
-  -c sandbox_workspace_write.network_access=true \
-  -c model_reasoning_effort=xhigh \
-  -
-```
+PLAN uses owner reasoning; BUILD_GATE/CLEANUP run owner commands, without separate Codex invocations. Code/doc cleanup runs inside the selected IMPLEMENT invocation. An already-open historical BUILD span without `execution_kind` keeps its receipt-bound workspace-write/network-true worker route; do not reinterpret or rewrite that evidence.
 
 Notes:
 - `DEVLYN_CODEX_PROMPT_FILE` — use the same file as `DEVLYN_INVOCATION_PROMPT_FILE` for receipt-bound calls. Retain the generated transport carrier with the prompt/session/argv evidence; a path or claimed environment value alone does not prove delivery. Do not use shell command substitution for prompt bytes.
 - `-C` — project root so Codex's working directory matches.
 - `-s read-only` / `-s workspace-write` — sandbox policy. Use workspace-write for implementation/probe phases that write tracked files or `.devlyn` artifacts.
-- `-c sandbox_workspace_write.network_access=<true|false>` — required and receipt-bound for mutation phases: `true` only for BUILD_GATE and, per call, PROBE-DERIVE when the probe's visible Verification command requires a localhost service; `false` for PLAN, IMPLEMENT, CLEANUP, and PROBE-DERIVE by default. This allows CI-equivalent loopback/network tests without widening to `danger-full-access` and prevents user configuration from silently changing other phases.
+- `-c sandbox_workspace_write.network_access=<true|false>` — required and receipt-bound for mutation phases: `true` only for historical receipt-bound BUILD_GATE and, per call, PROBE-DERIVE when the probe's visible Verification command requires a localhost service; `false` for IMPLEMENT, historical worker PLAN/CLEANUP, and PROBE-DERIVE by default. This allows CI-equivalent loopback/network tests without widening to `danger-full-access` and prevents user configuration from silently changing other phases.
 - `-c model_reasoning_effort=xhigh` — config override for reasoning depth. Required for deep critique; skills may choose `high` or `medium` when thoroughness doesn't warrant xhigh.
 - **For every receipt-bound Codex call, add `--json -m <model_requested>` to the recipes above**, matching the model recorded at spawn; keep the skill’s existing model-selection rules. Other routes keep their omission rules unless an explicit role profile supplies a model: normal workers may inherit user config, while unconfigured isolated VERIFY uses its CLI default. Explicit profiles use role-config.py options and the separate judge-role-evidence.py contract; they do not relax mutation receipts. Omission proves neither model identity nor role fitness. Re-certify seats after model/version changes before re-pinning them.
 - `CODEX_MONITORED_ISOLATED=1` — required for bounded read-only critique/probe/judge calls. The wrapper adds `--ignore-user-config --ignore-rules --ephemeral --disable codex_hooks --disable hooks` so user config, AGENTS.md, hooks, and project rules cannot add hidden context, tool calls, or transcript side effects. Do not set it for workspace-write implementation phases.

package/config/skills/_shared/engine-preflight.md

@@ -13,11 +13,11 @@ Engine requirements have two classes:
 
 ## Role resolution
 
-The orchestrator is the CLI the user opened. PLAN remains orchestrator-fixed. Resolve the legacy executor as explicit `--engine` > `cwd/.devlyn/engines.json` `executor` > the invoking skill's supported default. BUILD_GATE and risk-probe derivation keep their existing routes.
+The orchestrator is the CLI the user opened. PLAN remains orchestrator-fixed. Resolve the legacy executor as explicit `--engine` > `cwd/.devlyn/engines.json` `executor` > the invoking skill's supported default. BUILD_GATE runs commands in the orchestrator without a separate model; risk-probe derivation keeps its existing route.
 
 The role profiles and `--role-config` below apply only to `/devlyn:resolve`; `/devlyn:ideate` keeps its existing `--engine` / legacy executor selection and never inherits worker/judge profiles. `role-config.py` is resolve’s deterministic resolver. Optional project `roles.worker`, `roles.primary_judge`, and `roles.pair_judge` each require `engine` and accept exact `model`/`effort`; `/devlyn:resolve --role-config <path>` supplies the same `{"roles": {...}}` object for one run. Each entry replaces the entire lower entry. Worker/primary precedence is run role > `--engine` engine-only > project role > legacy executor. Pair precedence is run role > project role > existing `pair_judge_priority`/binary complement. An absent primary profile follows the legacy executor, not the worker profile. No parent/global devlyn config lookup.
 
-Worker controls IMPLEMENT/CLEANUP and their repair rounds only; primary/pair control VERIFY only. OTHER must differ from the resolved primary engine. Explicit same-engine pair is invalid; a legacy priority list skips the primary. `--no-pair` does not dispatch or check availability of an unused pair. Configured pins remain explicit promises, while an unconfigured unavailable automatic OTHER records its solo reason.
+Worker controls IMPLEMENT, its included code/doc cleanup, and their repair rounds only; owner CLEANUP performs artifact/invariant checks without a worker dispatch; primary/pair control VERIFY only. OTHER must differ from the resolved primary engine. Explicit same-engine pair is invalid; a legacy priority list skips the primary. `--no-pair` does not dispatch or check availability of an unused pair. Configured pins remain explicit promises, while an unconfigured unavailable automatic OTHER records its solo reason.
 
 Before the first phase, `/devlyn:resolve` freezes resolution with `state-phase-write.py --freeze-roles`; subsequent status/dispatch reads that state instead of mutable config. `state.engine` stays the legacy executor. The resolver rejects statically unsupported selected channel fields before PLAN, and validates adapter names and the existing ASCII `executor: yes|no` / `pair_judge: yes|no` eligibility markers; absent eligibility section means both. Malformed configuration fails with `BLOCKED:invalid-engine-config`.
 
@@ -33,7 +33,7 @@ When a run or phase requires engine `<name>` (claude, codex, omp, or any adapter
 
 Never prompt the user mid-pipeline. Missing engines for explicit routes are BLOCKED states, not silent fallbacks. Missing OTHER engines for automatic escalations are reported solo-skips, not fallbacks — the auto route was never selected.
 
-Per-skill defaults: `/devlyn:resolve` uses Claude for PLAN/IMPLEMENT when the orchestrator has Claude Code's native Agent primitive; Codex CLI and oh-my-pi orchestrators use their own fresh worker as the default route (Codex child process, omp native `task`) so the pipeline still has structural phase isolation. VERIFY invokes the OTHER engine by default when available unless `--no-pair` was passed. `/devlyn:ideate` defaults to Claude; `--engine` selects the elicitation/normalization adapter, not an automatic cross-model challenge phase. Any future ideate read-only critique must follow `_shared/codex-config.md` isolation rules. Each SKILL.md flag block is source of truth for that skill's default.
+Per-skill defaults: `/devlyn:resolve` uses Claude for IMPLEMENT when the orchestrator has Claude Code's native Agent primitive; Codex CLI and oh-my-pi orchestrators use their own fresh worker as the default route (Codex child process, omp native `task`) so implementation and independent verification retain structural isolation. PLAN uses the owner context; BUILD_GATE/CLEANUP use owner commands. VERIFY invokes the OTHER engine by default when available unless `--no-pair` was passed. `/devlyn:ideate` defaults to Claude; `--engine` selects the elicitation/normalization adapter, not an automatic cross-model challenge phase. Any future ideate read-only critique must follow `_shared/codex-config.md` isolation rules. Each SKILL.md flag block is source of truth for that skill's default.
 
 ## What a skill must report after a BLOCKED engine check
 

package/config/skills/_shared/expected.schema.json

@@ -147,13 +147,13 @@
     },
     "required_files": {
       "type": "array",
-      "description": "Files that must exist after the arm runs.",
+      "description": "Files specified by literal paths that must exist after the arm runs; globs are not expanded.",
       "items": { "type": "string", "minLength": 1 },
       "default": []
     },
     "forbidden_files": {
       "type": "array",
-      "description": "Files that must NOT appear in the arm's diff (e.g. tooling artifacts the spec didn't request).",
+      "description": "Exact Git-relative paths (forward slashes, no leading ./) that must NOT appear in the diff, including both rename names; globs and directory prefixes are not expanded.",
       "items": { "type": "string", "minLength": 1 },
       "default": []
     },

package/config/skills/_shared/platform-support.py

@@ -107,6 +107,7 @@ def system_exit_code(code):
 
 
 if os.name == "nt":
+    import _winapi
     import ctypes
     from ctypes import wintypes
     import msvcrt
@@ -226,7 +227,9 @@ if os.name == "nt":
                     try:
                         if self.child.poll() is None:
                             self.child.kill()
-                        self.child.wait(timeout=5)
+                        # kill() can cache an exit code before the native handle is signaled.
+                        if _winapi.WaitForSingleObject(self.child._handle, 5000) == _winapi.WAIT_TIMEOUT:
+                            raise subprocess.TimeoutExpired(self.child.args, 5)
                     finally:
                         self.child._handle.Close()
             finally:

package/config/skills/_shared/resolve-bootstrap.py

@@ -289,7 +289,7 @@ def init_spec_source(
             block("BLOCKED:invalid-flags", error or f"expected contract not found: {expected}")
     else:
         run_checked([sys.executable, str(helper), "--check", str(path)], cwd)
-        _staged, error = module.stage_from_source(path, staging_dir)
+        _found, _staged, error = module.stage_from_source(path, staging_dir)
         if error:
             block("BLOCKED:invalid-flags", error)
     staged_path = staging_dir / "spec-verify.json"
@@ -333,7 +333,7 @@ def capture_external_diff(cwd: pathlib.Path, ref: str) -> bytes:
     if source.is_file():
         raw = source.read_bytes()
     else:
-        proc = subprocess.run(["git", "diff", "--binary", ref], cwd=cwd, capture_output=True)
+        proc = subprocess.run(["git", "diff", "--binary", "--no-ext-diff", "--src-prefix=a/", "--dst-prefix=b/", ref], cwd=cwd, capture_output=True)
         if proc.returncode != 0:
             block("BLOCKED:invalid-flags", os.fsdecode(proc.stderr or proc.stdout).strip())
         raw = proc.stdout
@@ -1184,6 +1184,16 @@ def self_test() -> int:
         staged = strict_json((work / ".devlyn" / "spec-verify.json").read_text(encoding="utf-8"))
         assert staged["verification_commands"][0]["cmd"] == "printf ok"
         assert spec_result["source"]["spec_sha256"] == sha256(spec_raw)
+        pure_spec = spec_dir / "design.md"
+        pure_spec.write_text(
+            "# Design\n\n<!-- devlyn:verification -->\n## Verification\n\n"
+            '```json\n{"pure_design":true,"verification_commands":[]}\n```\n',
+            encoding="utf-8",
+        )
+        complete_prior(work)
+        pure_result = bootstrap(["--spec", str(pure_spec.relative_to(work))], work, script_shared)
+        assert pure_result["source"]["spec_sha256"] == sha256(pure_spec.read_bytes())
+        assert not (work / ".devlyn/spec-verify.json").exists()
         external_patch.write_bytes(b"stale free-form patch\n")
         complete_prior(work)
         bootstrap(["fresh", "goal"], work, script_shared)
@@ -1205,6 +1215,16 @@ def self_test() -> int:
         assert verify_result["mode"] == "verify-only"
         assert external_patch.read_bytes() == patch_raw
         subprocess.run(["git", "restore", "app.py"], cwd=work, check=True)
+        # Ambient no-prefix config must not change the reader's a/b contract.
+        (work / "app.py").write_text("print('prefix control')\n", encoding="utf-8")
+        settings = ["diff.noprefix"] + (["diff.external"] if os.name != "nt" else [])
+        for setting in settings:
+            subprocess.run(["git", "config", setting, "true"], cwd=work, check=True)
+            try:
+                assert b"diff --git a/app.py b/app.py\n" in capture_external_diff(work, "HEAD")
+            finally:
+                subprocess.run(["git", "config", "--unset", setting], cwd=work, check=True)
+        subprocess.run(["git", "restore", "app.py"], cwd=work, check=True)
         print("PASS bootstrap self-test patch lifecycle: full-mode removal + dirty verify-only exact capture")
 
         for valid_named in (True, False):

package/config/skills/_shared/role-config.py

@@ -10,6 +10,7 @@ import os
 from pathlib import Path
 import re
 import shutil
+import stat
 import subprocess
 import sys
 import tempfile
@@ -95,9 +96,20 @@ def validate(config, *, run=False, shared=SHARED):
 
 def read_config(path, *, run=False, optional=False, shared=SHARED):
     path = Path(path)
-    if optional and not path.exists():
-        return {}, {"path": str(path.absolute()), "sha256": None}
     try:
+        if optional:
+            try:
+                path.lstat()
+            except FileNotFoundError:
+                for parent in path.parents:
+                    try:
+                        mode = parent.stat().st_mode
+                    except FileNotFoundError:
+                        continue
+                    if not stat.S_ISDIR(mode):
+                        fail(f"cannot read role configuration {path}: {parent} is not a directory")
+                    return {}, {"path": str(path.absolute()), "sha256": None}
+                raise
         raw = path.read_bytes()
         value = validate(loads(raw), run=run, shared=shared)
     except (OSError, UnicodeError, json.JSONDecodeError) as exc: