devlyn-cli 4.3.25 → 4.3.28

package/bin/instructions.js

@@ -8,6 +8,7 @@ const cleanupHistory = require('./cleanup-history.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 VOID_ELEMENT = /^(?:area|base|br|col|embed|hr|img|input|link|meta|param|source|track|wbr)$/i;
 const normalize = (text) => text.replace(/\r\n/g, '\n');
 const digest = (text) => crypto.createHash('sha256').update(text).digest('hex');
 
@@ -39,33 +40,15 @@ 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] : []),
+  const starts = [...new Set([0, ...(bom ? [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);
+      .map((p) => p.start + bom)])];
   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 = 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 (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;
-      }
+      const end = matchedEnd(text, start, template);
+      if (end !== null && !ranges.some((range) => range.start === start && range.end === end)) ranges.push({ start, end });
     }
   }
   return ranges;
@@ -102,7 +85,7 @@ function instructionParagraphs(text) {
       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])) {
+          && !VOID_ELEMENT.test(opening[1])) {
         html = { tag: opening[1].toLowerCase(), depth: 0 };
       }
       if (html) {
@@ -130,42 +113,14 @@ function instructionParagraphs(text) {
   return paragraphs;
 }
 
-// Recognize direct adjacent imports in Markdown text, including inline imports.
-// Leaf tokens keep code, escapes and ordinary HTML from removing our only block.
-function importsAgentsMd(text) {
-  // Match the complete native path token before dropping its optional fragment.
-  const matchesImport = (value) => [...value.matchAll(/(?:^|\s)@((?:[^\s\\]|\\ )+)/g)].some((match) => {
-    const file = match[1].split('#', 1)[0];
-    return file === 'AGENTS.md' || file === './AGENTS.md';
-  });
-  const containsImport = (tokens) => tokens.some((token) => {
-    if (['code', 'codespan'].includes(token.type)) return false;
-    if (token.type === 'html') {
-      const raw = token.raw || '';
-      // Native Claude scans text left after complete comments in a comment-shaped HTML token.
-      return raw.trimStart().startsWith('<!--') && raw.includes('-->')
-        && matchesImport(raw.replace(/<!--[\s\S]*?-->/g, ''));
-    }
-    if (token.tokens) return containsImport(token.tokens);
-    if (token.items) return containsImport(token.items);
-    return token.type === 'text' && matchesImport(token.text);
-  });
-  // Claude strips this bounded frontmatter prefix before expanding imports.
-  const body = text.replace(/^\uFEFF/, '').replace(/^---\s*\n([\s\S]*?)---\s*\n?/, '');
-  return containsImport(new Lexer({ gfm: false }).lex(body));
-}
-
-function customInstructions(text, name, template, managed = false) {
-  const known = new Set([
-    ...(legacyTemplates.paragraphs[name] || []),
-    ...instructionParagraphs(template).map((p) => p.key),
-  ]);
+function customInstructions(text, name) {
+  const known = new Set(legacyTemplates.paragraphs[name] || []);
   const bom = text.startsWith('\uFEFF') ? '\uFEFF' : '';
   const paragraphs = instructionParagraphs(text.slice(bom.length));
   const keep = new Set();
-  let legacy = managed;
+  let legacy = false;
   for (const [index, paragraph] of paragraphs.entries()) {
-    if (!managed && paragraph.level === 1) {
+    if (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)
@@ -196,9 +151,42 @@ function removeEvaluatorBlocks(text) {
 }
 
 // Devlyn defaults in an instruction file: a managed block, or stock paragraphs of a template
-// that a release before managed blocks copied in whole (the evidence migration replaces).
+// that a release before managed blocks copied in whole.
 function holdsDevlynDefaults(name, text) {
-  return text.includes(BEGIN) || customInstructions(text, name, '') !== text;
+  return text.includes(BEGIN) || customInstructions(text, name) !== text;
+}
+
+// An example quotes a block: Markdown reads its marker as part of something else, or an element
+// opened before it is still open. An owner's stray tag can only keep a block, never lose text.
+function quoted(text) {
+  const open = new Map();
+  for (const token of new Lexer({ gfm: false }).lex(normalize(text.replace(/^\uFEFF/, '')))) {
+    if (token.type !== 'html') continue;
+    if (token.raw.startsWith(BEGIN)) return [...open.values()].some((depth) => depth > 0);
+    for (const [tag, close, element] of token.raw.replace(/<!--[\s\S]*?-->/g, '').matchAll(/<(\/?)([a-z][\w:-]*)\b[^>]*>/gi)) {
+      if (tag.endsWith('/>') || VOID_ELEMENT.test(element)) continue;
+      const name = element.toLowerCase();
+      open.set(name, (open.get(name) || 0) + (close ? -1 : 1));
+    }
+  }
+  return true;
+}
+
+// The range a release provably wrote, or null: one block whose bytes still match its own digest
+// and that no example quotes, or one whole template without markers. Anything else is the owner's.
+function devlynCopy(name, text, template) {
+  if (text.includes(BEGIN) || text.includes(END)) {
+    const starts = [...text.matchAll(/^(\uFEFF?)<!-- devlyn:instructions:begin sha256=([a-f0-9]{64}) -->\r?\n/gm)];
+    const ends = [...text.matchAll(/^<!-- devlyn:instructions:end -->(?:\r?\n|$)/gm)];
+    if (starts.length !== 1 || ends.length !== 1 || text.split(BEGIN).length !== 2 || text.split(END).length !== 2) return null;
+    const [start] = starts, [end] = ends;
+    const body = start.index + start[0].length;
+    if (end.index < body || digest(normalize(text.slice(body, end.index))) !== start[2] || quoted(text)) return null;
+    return { start: start.index + start[1].length, end: end.index + end[0].length };
+  }
+  const normalized = normalize(template);
+  const ranges = legacyRanges(text, [{ length: normalized.length, sha256: digest(normalized) }, ...(legacyTemplates[name] || [])]);
+  return ranges.length === 1 && !LEGACY.test(text.slice(0, ranges[0].start) + text.slice(ranges[0].end)) ? ranges[0] : null;
 }
 
 function retainFile(file, bytes) {
@@ -220,129 +208,53 @@ function retainFile(file, bytes) {
   }
 }
 
-// `withBlock` false removes the devlyn defaults the file holds, keeping everything else. `write` false writes nothing
-// and returns whether the file needs an update, a merge included.
-function updateInstructions(name, initial = '', withBlock = true, write = true, directory = process.cwd(), evaluatorOnly = false) {
-  const projectPackage = path.join(directory, 'package.json');
-  if (fs.existsSync(path.join(directory, 'bin', 'devlyn.js')) && fs.existsSync(projectPackage)
-      && JSON.parse(fs.readFileSync(projectPackage, 'utf8'))?.name === 'devlyn-cli') {
-    console.log(`  → Skipping ${name}; shipped instruction template in devlyn-cli source checkout`);
-    return false;
-  }
-  const templateName = path.basename(name);
-  const templatePath = path.join(__dirname, '..', templateName);
-  const template = ['CLAUDE.md', 'AGENTS.md'].includes(templateName) ? fs.readFileSync(templatePath, 'utf8') : '';
+// Removes the devlyn defaults the file holds, keeping everything else. `write` false writes nothing and returns
+// whether the file needs the removal. `evaluatorOnly` removes only appended evaluator blocks.
+function removeInstructions(name, write = true, directory = process.cwd()) {
+  const templatePath = path.join(__dirname, '..', name);
+  const template = ['CLAUDE.md', 'AGENTS.md'].includes(name) ? 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(directory, name);
   const stat = fs.lstatSync(dest, { throwIfNoEntry: false });
+  if (!stat) return false;
   const sourceStat = template ? fs.statSync(templatePath) : null;
-  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);
+  if (stat.isFile() && stat.dev === sourceStat?.dev && stat.ino === sourceStat?.ino) return false; // The shipped template itself.
   // 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 = initial;
+  if (!stat.isFile()) throw new InstructionError(`Instruction file must be a regular file; preserved: ${dest}.`);
+  const before = fs.readFileSync(dest);
+  let current;
   try {
-    if (exists) current = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(before);
+    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 });
-  }
-  current = removeEvaluatorBlocks(current);
-  const eol = current.match(/\r?\n/)?.[0] || '\n';
-  const block = managedBlock(template, eol);
-  const inserted = withBlock ? block : '';
-  const recovery = path.join(directory, '.devlyn', 'instructions');
-  const conflict = (reason) => {
-    if (!write) return true;
-    const incoming = path.join(recovery, `${encodeURIComponent(name)}.${digest(block)}.incoming`);
-    const backup = path.join(recovery, `${encodeURIComponent(name)}.${digest(before)}.backup`);
-    const guide = path.join(recovery, `${encodeURIComponent(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 (evaluatorOnly) {
-    content = current;
-  } else 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) return conflict('reversed managed markers');
-    const previous = current.slice(bodyStart, end.index);
-    const custom = digest(normalize(previous)) === start[1] ? ''
-      : customInstructions(previous, templateName,
-        'Project-specific instructions outside this managed block take precedence over these defaults.\n\n' + template, true);
-    const after = current.slice(end.index + end[0].length);
-    content = current.slice(0, start.index + (start[0].startsWith('\uFEFF') ? 1 : 0))
-      + custom + (custom ? eol : '') + inserted + after;
-  } 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, [
-      ...(normalized ? [{ length: normalized.length, sha256: digest(normalized),
-        ...(bodyStart > 0 ? { preamble, body: { length: body.length, sha256: digest(body) } } : {}) }] : []),
-      ...(legacyTemplates[templateName] || []),
-    ]);
-    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 + inserted + current.slice(end);
-    } else {
-      const custom = customInstructions(current, templateName, template);
-      content = custom + (custom && inserted ? eol + eol : '') + inserted;
-    }
+    throw new InstructionError(`${name} must be UTF-8; original preserved.`, { cause });
   }
+  let content = removeEvaluatorBlocks(current);
+  const copy = template ? devlynCopy(name, content, template) : null;
+  if (copy) content = content.slice(0, copy.start) + content.slice(copy.end);
   const bytes = Buffer.from(content);
   if (bytes.equals(before)) return false;
   if (!write) return true;
-  if (exists) {
-    const backup = path.join(recovery, `${encodeURIComponent(name)}.${digest(before)}.backup`);
-    retainFile(backup, before);
-    console.log(`  → Saved previous ${name}: ${backup}`);
-  }
+  const backup = path.join(directory, '.devlyn', 'instructions', `${encodeURIComponent(name)}.${digest(before)}.backup`);
+  retainFile(backup, before);
+  console.log(`  → Saved previous ${name}: ${backup}`);
+  const empty = content.replace(/^\uFEFF/, '') === '';
   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.writeFileSync(temp, bytes, { flag: 'wx', mode: stat.mode & 0o777 });
+    fs.chmodSync(temp, stat.mode & 0o777);
+    if (!fs.existsSync(dest) || !fs.readFileSync(dest).equals(before)) {
+      throw new InstructionError(`${name} changed during removal; preserved it.`);
     }
-    if (!withBlock && content === '') fs.unlinkSync(dest);
+    if (empty) fs.unlinkSync(dest);
     else fs.renameSync(temp, dest);
   } finally {
     if (fs.existsSync(temp)) fs.unlinkSync(temp);
   }
-  console.log(!withBlock && content === '' ? `  ✕ ${name} (removed)` : !exists ? `  → Created ${name}`
-    : `  → ${withBlock ? 'Updated Devlyn defaults in' : 'Removed Devlyn defaults from'} ${name}; project-specific instructions preserved`);
+  console.log(empty ? `  ✕ ${name} (removed)` : `  → Removed Devlyn defaults from ${name}; project-specific instructions preserved`);
   return true;
 }
 
-module.exports = { updateInstructions, InstructionError, instructionParagraphs, holdsDevlynDefaults, importsAgentsMd,
+module.exports = { removeInstructions, InstructionError, instructionParagraphs, holdsDevlynDefaults,
   managedBody, managedBlock, sessionDefaults };

package/bin/skill-history.json

@@ -90,6 +90,7 @@
       "6d1a5458b23196b6f6fde6b7e9dc097ed173cb5914de439e512a032ca1892812",
       "6e70044cab5a3fb1f78b7148c2111e4298ce8f5f8e902220430ca316bb61255d",
       "6fa2b5e089dcd00613c6e9800d2e763da9e5b2c80e6a7ef5d54d5ad7113e8399",
+      "701c6a010a526429642123a2be1a56d724cd47b7e5000f78c5bde7d66c3b133b",
       "713921f9a442770fc4de24b990dee6a4a5358a0d69bc26af80c33dc6f15a7274",
       "71fb125e20420d6f3fcd3396093fcdc8d552bab9626c3cbd962351e0d19adac8",
       "725395f70eec7e2ceae1f3aa122893433923b098a1e0d6202dd410979ef4eea0",
@@ -160,11 +161,13 @@
       "d201802016f06626bd9fa4074d61a54ab9f70b7febfccc0ea0c70605d1f1b811",
       "d2273f7404df92436c4c2ebcf38bdf1e5dbc65c5d1544f95dd1332c123ef17df",
       "d22bbe15dff66d4801320ea81d7952af50615a7ed57ffe7033545589b8d946bd",
+      "d243bff7bb0a780d933dc66ed5a899d0d4e2a00e9dcdde66beeb518247c859a6",
       "d3b40b9f0e15bf90ca557c0198a8fe5ff1d046b9aaa54b181c743d8e006f9c34",
       "d424feceffc005f220e33a19cac73f33bd40d120cc14da33725b8a990704bcf6",
       "d7388e36d76647a89ce52de615271928cf9fc78f980df399d2bc2e6d6675ec82",
       "d85fa24b9b2c439742c9a62d5d4e07a031a1cfe6024bbc06f98eff7063424179",
       "dac3da11ea5686382f5c9892a0b8e4ec25e625e5946283d8e2ad944aa84e1df2",
+      "db2a57a81fc9ffddb7f7f2b7a59ac4821563c345e2a47f825eade308f2707040",
       "db867d1fd98058bb20e41e942abd95f08fbaa9465928025f69f0a0308fa71514",
       "dd0bfdfd2db0b5f9ddef75d1b9ce3247698739fc551d292366dccd506fef6a36",
       "ddb0c8dac58e95298330ab54e4d1fe4a108c968d9af713f267b4f8f4c6808507",
@@ -358,6 +361,7 @@
       "5824f07e455fe1c3942bf595a12e935258d4c0a851ca1bf741db915603d1c4e0",
       "59261610d60ca0f94cc8fa33af61f8ddafd8e5616f9358591547dd23fcdc6328",
       "5954e371659ae1010757f0eec4b80dd65a899f9fcf76d4d84d9a75476a963218",
+      "6374290c74a8c17979e8c128905e106d38bd810c0451f0e9240c30e0f7ecabb0",
       "65770e3f20c3a3afd2822e9acdcfc80b827f84a7737010b79332da70d431b05d",
       "65c781764633b912e5947362eba0837c8027461a904975401d79ad4fe8714084",
       "694c8920e50d92cba46dbb27eb44dd88035a89ed625d3cbf9f2bce9366d44c96",
@@ -365,6 +369,7 @@
       "6b403afbf5a117cc08603d3648b9dded4f9ac4ca02fc1d8e1f0035615148bb5c",
       "6c3e2e4b84b0b4f81aed3759704da7c14f3cbabf3beeb0d1654feda3a15a8675",
       "6d9df58c117165e9d297aa6be0df8d076bac1ed49dc29ae93906af1969798ab1",
+      "6e2b54571bfbc1fab571b81564fb0625ed83333fc12277c473fdf5a231f7d40c",
       "6e7228610628fc4bca31dc0b0aaf5eb4445e1f123f2c54bd13921c5cd01129fe",
       "75cecbce4d1f4adbba608cef498ae7e421ea75512c6bf9282b66cd94d821f672",
       "7f451e48e391643b34f6249244bc47d93d6303875e7b092771e3af0718343bc1",
@@ -804,6 +809,9 @@
     "4.3.23",
     "4.3.24",
     "4.3.25",
+    "4.3.26",
+    "4.3.27",
+    "4.3.28",
     "4.3.3",
     "4.3.4",
     "4.3.5",

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

@@ -17,7 +17,7 @@ Seven rules govern every change. Cite them by name when a decision touches one.
 3. **No guesswork** — verify with the actual files, logs, diffs, and run output before forming conclusions. State the falsifiable prediction BEFORE the experiment; record raw results AFTER. Retroactive prediction edits are dishonest.
 4. **Worldclass** — zero CRITICAL, zero HIGH security/design findings on the shippable path. Any review is one pass in which every reviewer, including each one the user requires, reads the source the checks ran on; fix each finding or reject it with a reason, re-check the fixes and the invariants they touch, and repeat the full review only while a CRITICAL or HIGH finding remains.
 5. **Best practice** — idiomatic for the language and framework. Use standard primitives; do not hand-roll what the library already provides.
-6. **Optimized** — use efficient code and avoid unnecessary work without sacrificing correctness or the user's requirements.
+6. **Optimized** — efficient on the resource that matters (the user's time, tokens, attention, runtime) without weakening correctness or requirements. An extra check or process step must beat the simpler path.
 7. **Production ready** — error states are explicit and visible; behavior under failure is what the user expects, not silent corruption.
 
 Three discipline rules govern HOW the principles are applied:

package/config/skills/_shared/storage-checkout.py

@@ -52,6 +52,7 @@ def validate_closure(value):
     require(type(value) is dict, 'positive reservation closure missing')
     tag = value.get('established_by')
     shapes = {'released': {'established_by': ('released',), 'reservation': 'reservation'},
+              'authority_migrated': {'established_by': ('authority_migrated',), 'operation_id': 'str'},
               'authority_expired': {'established_by': ('authority_expired',), 'operation_id': 'str'},
               'never_admitted': {'established_by': ('never_admitted',), 'operation_id': 'str'},
               'legacy_unreserved': {'established_by': ('legacy_unreserved',), 'receipt_version': 'u32'}}