devlyn-cli 3.1.3 → 3.2.1

package/bin/instructions.js

@@ -5,42 +5,157 @@ 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, ...Array.from(text.matchAll(/^# (?:Codex )?Project Instructions\r?$/gm), (m) => m.index)]);
-  if (text.startsWith('\uFEFF')) starts.add(1);
+  const bom = text.startsWith('\uFEFF') ? 1 : 0;
+  const starts = [...new Set([0, ...(text.startsWith('\uFEFF') ? [1] : []),
+    ...instructionParagraphs(text.slice(bom))
+      .filter((p) => p.level === 1 && /^# (?:Codex )?Project Instructions\r?\n/.test(p.text))
+      .map((p) => p.start + bom)])].sort((a, b) => a - b);
   const ranges = [];
   for (const start of starts) {
     for (const template of templates) {
-      let end = start;
-      for (let n = 0; n < template.length && end < text.length; n++, end++) {
-        if (text[end] === '\r' && text[end + 1] === '\n') end++;
+      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 = instructionParagraphs(prefix).find((p) => p.level === 2 && /^## North Star\r?\n/.test(p.text));
+        const header = template.preamble.slice(0, template.preamble.indexOf('\n\n') + 2);
+        if (body && normalize(prefix).startsWith(header)) {
+          const bodyStart = start + body.start;
+          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 (digest(normalize(text.slice(start, end))) === template.sha256
-          && !ranges.some((range) => range.start === start && range.end === end)) {
-        ranges.push({ start, end });
+      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;
 }
 
+// Keep complete paragraphs (including fenced examples and comments) intact.
+// Matching includes the heading path, so the same words in another section
+// are not evidence that Devlyn owns them.
+function instructionParagraphs(text) {
+  const paragraphs = [];
+  let pending = '', fence = null, comment = false, html = null, start = 0;
+  const flush = () => {
+    if (pending) paragraphs.push({ text: pending, start });
+    start += pending.length;
+    pending = '';
+  };
+  for (const line of text.match(/[^\n]*\n|[^\n]+$/g) || []) {
+    if (!fence && !comment && !html && (/^(?:#{1,6} |(?:[-*+]|\d+[.)]) )/.test(line)
+        || (/^#{1,6} [^\n]+\r?\n$/.test(pending) && !/^\r?\n$/.test(line)))) flush();
+    pending += line;
+    const marker = /^( {0,3})(`{3,}|~{3,})/.exec(line)?.[2];
+    if (!comment && marker) {
+      if (!fence) fence = marker;
+      else if (marker[0] === fence[0] && marker.length >= fence.length
+          && /^ {0,3}(?:`+|~+)\s*$/.test(line)) fence = null;
+    }
+    if (!fence) {
+      let markup = '', cursor = 0;
+      for (const marker of line.matchAll(/<!--|-->/g)) {
+        if (!comment) markup += line.slice(cursor, marker.index);
+        comment = marker[0] === '<!--';
+        cursor = marker.index + marker[0].length;
+      }
+      if (!comment) markup += line.slice(cursor);
+      const opening = /^ {0,3}<([a-z][\w:-]*)\b[^>]*>/i.exec(markup);
+      if (!html && opening && !/\/>$/.test(opening[0])
+          && !/^(?:area|base|br|col|embed|hr|img|input|link|meta|param|source|track|wbr)$/i.test(opening[1])) {
+        html = { tag: opening[1].toLowerCase(), depth: 0 };
+      }
+      if (html) {
+        for (const tag of markup.matchAll(/<(\/?)([a-z][\w:-]*)\b[^>]*>/gi)) {
+          if (tag[2].toLowerCase() === html.tag && !/\/>$/.test(tag[0])) html.depth += tag[1] ? -1 : 1;
+        }
+        if (html.depth <= 0) html = null;
+      }
+    }
+    if (!fence && !comment && !html && /^\r?\n$/.test(line)) flush();
+  }
+  flush();
+  const headings = [];
+  for (const [index, paragraph] of paragraphs.entries()) {
+    const value = normalize(paragraph.text).replace(/\n+$/, '');
+    const heading = /^(#{1,6}) ([^\n]+)$/.exec(value);
+    if (heading) {
+      paragraph.level = heading[1].length;
+      while (headings.length && headings.at(-1).level >= paragraph.level) headings.pop();
+    }
+    paragraph.parents = headings.map((h) => h.index);
+    paragraph.key = digest(JSON.stringify([headings.map((h) => h.title), value]));
+    if (heading) headings.push({ level: paragraph.level, title: value, index });
+  }
+  return paragraphs;
+}
+
+function customInstructions(text, name, template, managed = false) {
+  const known = new Set([
+    ...legacyTemplates.paragraphs[name],
+    ...instructionParagraphs(template).map((p) => p.key),
+  ]);
+  const bom = text.startsWith('\uFEFF') ? '\uFEFF' : '';
+  const paragraphs = instructionParagraphs(text.slice(bom.length));
+  const keep = new Set();
+  let legacy = managed;
+  for (const [index, paragraph] of paragraphs.entries()) {
+    if (!managed && paragraph.level === 1) {
+      const next = paragraphs.findIndex((p, i) => i > index && p.level === 1);
+      const section = paragraphs.slice(index, next < 0 ? undefined : next);
+      legacy = /^# (?:Codex )?Project Instructions\r?\n|^# Devlyn Agent Instructions\r?\n/.test(paragraph.text)
+        && section.some((p) => !/^\s*(?:`{3}|~{3}|<!--)/.test(p.text) && LEGACY.test(p.text));
+    }
+    if (!legacy || !known.has(paragraph.key)) {
+      keep.add(index);
+      for (const parent of paragraph.parents) keep.add(parent);
+    }
+  }
+  return bom + paragraphs.filter((_, index) => keep.has(index)).map((p) => p.text).join('');
+}
+
 function retainFile(file, bytes) {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
+  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 Error(`Instruction recovery file differs; preserved it: ${file}. Move it aside before retrying.`);
+      throw new InstructionError(`Instruction recovery file differs; preserved it: ${file}. Move it aside before retrying.`);
     }
   } else {
     fs.writeFileSync(file, bytes, { flag: 'wx', mode: 0o600 });
@@ -63,22 +178,36 @@ function updateInstructions(name) {
   const exists = Boolean(stat);
   // Do not replace a shared instruction symlink or follow it outside the project.
   if (stat && !stat.isFile()) {
-    throw new Error(`Instruction file must be a regular file; preserved: ${dest}. Move it aside and rerun, then merge your shared rules outside the managed block.`);
+    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 Error(`${name} must be UTF-8; original preserved. Convert its encoding and rerun installation.`, { 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));
-    throw new Error(`${name} needs merge (${reason}); original preserved. New defaults: ${incoming}. Keep custom rules outside the managed block, then rerun installation.`);
+    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)) {
@@ -91,25 +220,30 @@ function updateInstructions(name) {
     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);
+    if (end.index < bodyStart) return conflict('reversed managed markers');
+    const previous = current.slice(bodyStart, end.index);
+    const custom = digest(normalize(previous)) === start[1] ? ''
+      : customInstructions(previous, name,
+        'Project-specific instructions outside this managed block take precedence over these defaults.\n\n' + template, true);
+    content = current.slice(0, start.index + (start[0].startsWith('\uFEFF') ? 1 : 0))
+      + custom + (custom ? eol : '') + 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) },
+      { 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 } = ranges[0];
-      content = current.slice(0, start) + block + current.slice(end);
+    if (ranges.length === 1 && !LEGACY.test(current.slice(0, ranges[0].start)
+        + ranges[0].custom + current.slice(ranges[0].end))) {
+      const { start, end, custom } = ranges[0];
+      content = current.slice(0, start) + custom + block + current.slice(end);
     } else {
-      if (/^devlyn-cli installs |^# Devlyn Agent Instructions\r?$|^This contract serves one goal: any capable engine|^Engine roles: orchestrator =/m.test(current)) {
-        return conflict('unrecognized or edited legacy template');
-      }
-      content = current + (current ? eol + eol : '') + block;
+      const custom = customInstructions(current, name, template);
+      content = custom + (custom ? eol + eol : '') + block;
     }
   }
   const bytes = Buffer.from(content);
@@ -124,7 +258,7 @@ function updateInstructions(name) {
     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 Error(`${name} changed during installation; preserved it. Rerun installation.`);
+      throw new InstructionError(`${name} changed during installation; preserved it. Rerun installation.`);
     }
     fs.renameSync(temp, dest);
   } finally {
@@ -134,4 +268,4 @@ function updateInstructions(name) {
   return true;
 }
 
-module.exports = { updateInstructions };
+module.exports = { updateInstructions, InstructionError, instructionParagraphs };

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/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:

package/config/skills/_shared/spec-verify-check.py

@@ -1754,10 +1754,9 @@ def authorized_surface_findings(
     to catch. A persistent finding exhausts the existing BUILD_GATE
     fix-loop budget and halts for user/orchestrator review instead.
 
-    Not re-run at VERIFY MECHANICAL time (post-CLEANUP): CLEANUP's own
-    allowlist (tooling artifacts, dead code, doc-reference fixes) licenses
-    paths PLAN never declared, so re-checking there would false-positive on
-    CLEANUP's own sanctioned changes.
+    Not re-run at VERIFY MECHANICAL time: historical worker CLEANUP can
+    license paths outside PLAN. Owner CLEANUP instead enforces an unchanged
+    source checkpoint and the final untracked baseline before VERIFY.
     """
     surface, surface_error = load_authorized_surface(devlyn_dir)
     if surface_error is not None: