devlyn-cli 3.2.0 → 3.3.0

package/bin/instructions.js

@@ -27,8 +27,11 @@ function matchedEnd(text, start, template) {
 
 // A digest is ownership evidence; a familiar heading alone is not.
 function legacyRanges(text, templates) {
+  const bom = text.startsWith('\uFEFF') ? 1 : 0;
   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);
+    ...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) {
@@ -36,10 +39,10 @@ function legacyRanges(text, templates) {
       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 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.index;
+          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) });
@@ -57,6 +60,89 @@ function legacyRanges(text, templates) {
   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) {
   for (const directory of [path.dirname(path.dirname(file)), path.dirname(file)]) {
     const stat = fs.lstatSync(directory, { throwIfNoEntry: false });
@@ -134,10 +220,13 @@ 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');
@@ -148,18 +237,13 @@ function updateInstructions(name) {
         ...(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) {
+    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];
-      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 custom = customInstructions(current, name, template);
+      content = custom + (custom ? eol + eol : '') + block;
     }
   }
   const bytes = Buffer.from(content);
@@ -184,4 +268,4 @@ function updateInstructions(name) {
   return true;
 }
 
-module.exports = { updateInstructions, InstructionError };
+module.exports = { updateInstructions, InstructionError, instructionParagraphs };

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

@@ -67,8 +67,7 @@ tool-use loop (2/3 made zero tool calls and fabricated findings), and a
 
 The judge prompt must name the exact permitted command(s). Derive the prompt
 anchor and allow-list string identically from one source, in this precedence:
-the solo-headroom hypothesis's backticked observable command when present;
-otherwise the backticked commands in the spec's `## Verification` bullets;
+the backticked commands in the spec's `## Verification` bullets;
 otherwise the repo's existing test/CLI runner. If none exists, the probe
 obligation does not arise and a static review is correct for that spec.
 The documented `Bash(<command>)` form matches the exact command or its prefix;

package/config/skills/_shared/archive_run.py

@@ -110,6 +110,9 @@ BOOTSTRAP_TEMP_PATTERNS = tuple(
 PER_RUN_PATTERNS += BOOTSTRAP_TEMP_PATTERNS
 
 SAFE_RUN_ID_RE = re.compile(r"^[A-Za-z0-9_.-]+$")
+valid_final_verdict = runpy.run_path(
+    pathlib.Path(__file__).with_name("terminal-claim-check.py")
+)["valid_final_verdict"]
 
 
 class ArchiveError(Exception):
@@ -173,9 +176,7 @@ def read_run_id(devlyn: pathlib.Path) -> str:
 def is_completed(state: object) -> bool:
     phases = state.get("phases") if isinstance(state, dict) else None
     final = phases.get("final_report") if isinstance(phases, dict) else None
-    if not isinstance(final, dict) or final.get("verdict") not in (
-        "PASS", "PASS_WITH_ISSUES", "NEEDS_WORK", "BLOCKED",
-    ):
+    if not isinstance(final, dict) or not valid_final_verdict(final.get("verdict")):
         return False
     timestamp = final.get("completed_at")
     if not isinstance(timestamp, str) or not re.fullmatch(
@@ -566,6 +567,16 @@ def completion_self_test() -> None:
     print("PASS archive completion: 8 terminal forms; malformed/unfinished/residue retained beyond keep-10")
 
 
+def full_terminal_verdict_completion_self_test() -> None:
+    timestamp = "2026-09-06T00:00:00Z"
+    assert is_completed({"phases": {"final_report": {
+        "verdict": "BLOCKED:repair-budget-exhausted", "completed_at": timestamp,
+    }}})
+    assert not is_completed({"phases": {"final_report": {
+        "verdict": "BLOCKED:", "completed_at": timestamp,
+    }}})
+
+
 def self_test() -> int:
     assert dynamic_judge_role_artifacts(pathlib.Path(".devlyn"), {"phases": {"verify": None}}) == []
     assert dynamic_judge_role_artifacts(pathlib.Path(".devlyn"), {"phases": {}}) == []
@@ -921,6 +932,7 @@ def self_test() -> int:
         else:
             raise AssertionError("NaN archive run_id was accepted")
     completion_self_test()
+    full_terminal_verdict_completion_self_test()
     return 0
 
 

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

@@ -100,7 +100,7 @@ def describe(devlyn, state, role, exit_code):
             index = next((i for i, arg in enumerate(argv) if Path(arg).name == "run-bounded.py"), -1)
             require(index >= 0 and argv[index + 1:index + 3] == ["600", "--stdin-file"]
                     and len(argv) > index + 6 and argv[index + 4:index + 6] == ["--record-transport", "--"], "invalid bounded file transport")
-            require(Path(argv[index + 3]).resolve() == devlyn / (stem + ".prompt"), "bounded prompt path mismatch")
+            require(Path(argv[index + 3]).resolve() == (devlyn / (stem + ".prompt")).resolve(), "bounded prompt path mismatch")
             require(transport["command"] == argv[index + 6:] and prompt not in transport["command"], "bounded actual argv mismatch")
             require("-p" in transport["command"] or "--print" in transport["command"], "Claude print mode missing")
         else:
@@ -199,6 +199,26 @@ def self_test():
         (devlyn / "claude-judge.r0.stdout").write_bytes(text)
         (devlyn / "claude-judge.r0.role-evidence.json").write_bytes(encoded(receipt))
         authenticate(devlyn, state, "primary_judge")
+        file_command = [argv[4], argv[5], *argv[7:]]
+        file_argv = ["python3", "run-bounded.py", "600", "--stdin-file",
+                     str(devlyn / "claude-judge.r0.prompt"), "--record-transport", "--", *file_command]
+        (devlyn / "claude-judge.r0.argv.json").write_bytes(encoded(file_argv))
+        carrier = devlyn / "claude-judge.r0.prompt.transport.json"
+        carrier.write_bytes(encoded({"schema_version": 1, "transport": "stdin-file",
+            "prompt": {"path": str(devlyn / "claude-judge.r0.prompt"), "sha256": digest(b"review"), "bytes": 6},
+            "command": file_command, "argv": file_command, "timeout_sec": 600,
+            "isolated": False, "status": "completed", "exit_code": 0}))
+        describe(devlyn, state, "primary_judge", 0)
+        file_argv[4] = str(work / "wrong.prompt")
+        (devlyn / "claude-judge.r0.argv.json").write_bytes(encoded(file_argv))
+        try:
+            describe(devlyn, state, "primary_judge", 0)
+        except ValueError as exc:
+            assert "bounded prompt path mismatch" in str(exc)
+        else:
+            raise AssertionError("wrong file-transport prompt accepted")
+        carrier.unlink()
+        (devlyn / "claude-judge.r0.argv.json").write_bytes(encoded(argv))
         for field, value in (("subtype", "error_max_turns"), ("stop_reason", "tool_use"), ("is_error", True), ("session_id", ""), ("result", None)):
             bad = {**envelope, field: value}
             try:

package/config/skills/_shared/runtime-principles.md

@@ -94,7 +94,7 @@ A finding without one of these forms is excluded. Vague findings produce vague f
 ## Consumption
 
 **Consumers**:
-- `devlyn:resolve/SKILL.md` `<harness_principles>` points here as the contract source. Phase prompt bodies inline or reference the operational excerpt needed for each phase.
+- `devlyn:resolve/SKILL.md` `<harness_principles>` points here as the contract source. Phase prompt bodies inline the operational excerpt needed for each phase.
 - `devlyn:ideate/SKILL.md` consumes this file for spec-shaping and conversation discipline through its own `<harness_principles>` block.
 
 **Codex routing**: Codex-routed phases must inline the contract excerpt directly into the prompt body. Bounded read-only Codex critique, probe, or judge calls must also follow `_shared/codex-config.md` isolation rules.