devlyn-cli 4.2.24 → 4.2.26

package/bin/harness-status.js

@@ -0,0 +1,171 @@
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { Lexer } = require('marked');
+const { managedBody } = require('./instructions');
+const { ENGINE_IDS } = require('./engines');
+const templates = require('./instruction-templates.json');
+const history = require('./skill-history.json');
+const { fingerprint, gitEnvironment } = require('./skill-ownership');
+const { verifyRelease, sha256, physicalRoot, fail, options } = require('./release');
+
+function git(root, args, encoding = 'utf8') {
+  return spawnSync('git', ['-C', root, ...args], {
+    env: { ...gitEnvironment(), GIT_OPTIONAL_LOCKS: '0' }, encoding, maxBuffer: 8 * 1024 * 1024,
+  });
+}
+function gitOutput(root, args) {
+  const result = git(root, args);
+  if (result.error || result.status !== 0) fail('repository-unreadable', { detail: result.error?.message || result.stderr.trim() });
+  return result.stdout.trim();
+}
+function repositoryIdentity(project) {
+  const result = git(project, ['rev-parse', '--show-toplevel']);
+  if (result.error?.code === 'ENOENT' || (result.status === 128 && result.stderr.includes('not a git repository'))) return null;
+  if (result.error || result.status !== 0) fail('repository-unreadable', { detail: result.error?.message || result.stderr.trim() });
+  const root = fs.realpathSync(result.stdout.trim());
+  const commonGitDir = fs.realpathSync(gitOutput(root, ['rev-parse', '--path-format=absolute', '--git-common-dir']));
+  // Committed identity survives missing/edited files and linked worktrees.
+  const pkg = git(root, ['show', 'HEAD:package.json']);
+  const cli = git(root, ['cat-file', '-e', 'HEAD:bin/devlyn.js']);
+  let sourceRepository = false;
+  if (pkg.status === 0 && cli.status === 0) {
+    try { sourceRepository = JSON.parse(pkg.stdout).name === 'devlyn-cli'; }
+    catch (error) { fail('repository-unreadable', { detail: error.message }); }
+  }
+  return { root, commonGitDir, sourceRepository };
+}
+
+function inspectInstruction(text, template, name) {
+  const normalized = text.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
+  const body = managedBody(template);
+  const current = sha256(body);
+  const tokens = new Lexer({ gfm: false }).lex(normalized);
+  const hasMarkers = tokens.some((token) => token.type === 'html' && /^<!-- devlyn:instructions:(?:begin|end)/.test(token.raw));
+  const starts = [...normalized.matchAll(/^<!-- devlyn:instructions:begin sha256=([a-f0-9]{64}) -->\n/gm)];
+  const ends = [...normalized.matchAll(/^<!-- devlyn:instructions:end -->(?:\n|$)/gm)];
+  if (hasMarkers) {
+    if (starts.length !== 1 || ends.length !== 1 || ends[0].index < starts[0].index
+        || normalized.split('<!-- devlyn:instructions:begin').length !== 2
+        || normalized.split('<!-- devlyn:instructions:end').length !== 2) return { ownership: 'modified', blockSha256: null };
+    const previous = normalized.slice(starts[0].index + starts[0][0].length, ends[0].index);
+    const hash = sha256(previous);
+    if (hash !== starts[0][1]) return { ownership: 'modified', blockSha256: hash };
+    if (hash === current) return { ownership: 'current', blockSha256: hash };
+    const raw = previous.replace(/^Project-specific instructions outside this managed block take precedence over these defaults\.\n\n/, '');
+    const known = (templates[name] || []).some((entry) => entry.sha256 === sha256(raw));
+    return { ownership: known ? 'outdated' : 'modified', blockSha256: hash };
+  }
+  if (normalized === template.replace(/\r\n/g, '\n')) return { ownership: 'current', blockSha256: current };
+  const known = (templates[name] || []).some((entry) => entry.sha256 === sha256(normalized));
+  return { ownership: known ? 'outdated' : 'unowned', blockSha256: null };
+}
+
+function requirements() {
+  const [major, minor] = process.versions.node.split('.').map(Number);
+  const nodeSupported = (major === 20 && minor >= 17) || (major === 22 && minor >= 13)
+    || (major === 23 && minor >= 5) || major > 23;
+  const node = { name: 'node', required: true, available: nodeSupported, version: process.versions.node,
+    reasons: nodeSupported ? [] : [{ code: 'requirement-version', params: { name: 'node' } }] };
+  const probes = [
+    ['python', true, 'python3', ['-B', '--version']],
+    ['git', true, 'git', ['--version']],
+    ['git-bash', process.platform === 'win32', 'bash', ['--version']],
+    ['gh', false, 'gh', ['--version']],
+  ];
+  return [node, ...probes.map(([name, required, binary, argv]) => {
+    const result = spawnSync(binary, argv, { encoding: 'utf8', timeout: 5000, env: { ...process.env, PYTHONDONTWRITEBYTECODE: '1' } });
+    const output = (result.stdout || result.stderr || '').trim();
+    const match = output.match(/\b(\d+)\.(\d+)(?:\.\d+)?/);
+    let available = !result.error && result.status === 0 && Boolean(match);
+    if (name === 'python' && available) available = Number(match[1]) > 3 || (Number(match[1]) === 3 && Number(match[2]) >= 11);
+    if (name === 'git-bash' && required && available) available = /mingw|msys/i.test(output);
+    return { name, required, available, version: match?.[0] || null,
+      reasons: available ? [] : [{ code: 'requirement-unavailable', params: { name } }] };
+  })];
+}
+
+function harnessStatus(project, { releaseRoot = path.resolve(__dirname, '..') } = {}) {
+  const release = verifyRelease(releaseRoot, { npmInstall: true }).release;
+  project = physicalRoot(project);
+  const repository = repositoryIdentity(project);
+  const root = repository?.root || project;
+  const instructions = [];
+  const ownership = [];
+  for (const name of ['CLAUDE.md', 'AGENTS.md']) {
+    const file = path.join(root, name);
+    const stat = fs.lstatSync(file, { throwIfNoEntry: false });
+    if (!stat) continue;
+    let inspected = { ownership: 'unowned', blockSha256: null };
+    let committed = false;
+    const reasons = [];
+    if (stat.isFile() && stat.nlink === 1) {
+      const bytes = fs.readFileSync(file);
+      let text;
+      try { text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes); }
+      catch (error) {
+        if (!(error instanceof TypeError)) throw error;
+        reasons.push({ code: 'instruction-encoding', params: { path: file } });
+      }
+      if (text !== undefined) inspected = inspectInstruction(text, fs.readFileSync(path.join(release.root, name), 'utf8'), name);
+      if (repository) {
+        const head = git(root, ['show', `HEAD:${name}`], 'buffer');
+        committed = head.status === 0 && head.stdout.equals(bytes);
+      }
+    } else reasons.push({ code: 'outside-root-link-or-special-file', params: { path: file } });
+    // Native trust/config/loading is established by CLI-3. A familiar filename is insufficient.
+    instructions.push({ path: file, committed, ...inspected, applicableEngines: [], applicability: 'unknown' });
+    ownership.push({ path: file, kind: 'instructions', proof: inspected.ownership === 'current' ? 'current'
+      : inspected.ownership === 'outdated' ? 'historical' : 'none', reasons });
+  }
+  const current = new Map();
+  for (const agent of ['.agents', '.claude']) {
+    for (const name of ['devlyn-ideate', 'devlyn-engines', '_shared']) {
+      const file = path.join(root, agent, 'skills', name);
+      // Do not traverse an ancestor link just to discover an installation.
+      const ancestors = [path.join(root, agent), path.join(root, agent, 'skills')];
+      if (ancestors.some((dir) => {
+        const stat = fs.lstatSync(dir, { throwIfNoEntry: false });
+        return stat && !stat.isDirectory();
+      })) {
+        if (!ownership.some((entry) => entry.path === ancestors[0])) ownership.push({ path: ancestors[0], kind: 'core-skill',
+          proof: 'none', reasons: [{ code: 'outside-root-link-or-special-file', params: { path: ancestors[0] } }] });
+        continue;
+      }
+      if (!fs.lstatSync(file, { throwIfNoEntry: false })) continue;
+      let proof = 'none';
+      const reasons = [];
+      try {
+        const hash = fingerprint(file);
+        if (!current.has(name)) current.set(name, fingerprint(path.join(release.root, 'config/skills', name)));
+        if (hash === current.get(name)) proof = 'current';
+        else if ((history.skills[name] || []).includes(hash)) proof = 'historical';
+      } catch (error) {
+        reasons.push({ code: 'ownership-unverifiable', params: { path: file, detail: error.message } });
+      }
+      ownership.push({ path: file, kind: 'core-skill', proof, reasons });
+    }
+  }
+  // Pure queue inspection and effective engine configuration belong to CLI-2/CLI-3.
+  return { release, repository, instructions, requirements: requirements(), ownership };
+}
+
+function statusCommand(args) {
+  const opts = options(args, { project: { type: 'string' }, engine: { type: 'string' }, 'context-file': { type: 'string' } });
+  if (!opts.project) fail('invalid-arguments', { argument: '--project' }, 2);
+  if (opts.engine && !ENGINE_IDS.includes(opts.engine)) {
+    fail('invalid-arguments', { argument: '--engine' }, 2);
+  }
+  const status = harnessStatus(opts.project);
+  if (opts['context-file']) {
+    const { readContext, planActivation } = require('./harness-activation');
+    const context = readContext(opts['context-file']);
+    if ((opts.engine && opts.engine !== context.engine) || physicalRoot(context.cwd) !== physicalRoot(opts.project)) {
+      fail('invalid-arguments', { argument: 'status context must match project and engine' }, 2);
+    }
+    status.engines = [planActivation(status.release.root, context).channels];
+  }
+  return status;
+}
+
+module.exports = { harnessStatus, statusCommand, repositoryIdentity, inspectInstruction };

package/bin/instructions.js

@@ -13,12 +13,21 @@ 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'
+function managedBody(template) {
+  return 'Project-specific instructions outside this managed block take precedence over these defaults.\n\n'
     + normalize(template).replace(/\n?$/, '\n');
+}
+
+function managedBlock(template, eol = '\n') {
+  const body = managedBody(template);
   return `${BEGIN} sha256=${digest(body)} -->\n${body}${END}\n`.replace(/\n/g, eol);
 }
 
+function sessionDefaults(template) {
+  return 'The following Devlyn instructions are defaults for this session. Applicable explicit user instructions and native owner/project instructions take precedence over these defaults. This delegation applies only to the Devlyn defaults below; it does not change other engine instructions or permissions.\n\n'
+    + normalize(template);
+}
+
 function matchedEnd(text, start, template) {
   let end = start;
   for (let n = 0; n < template.length && end < text.length; n++, end++) {
@@ -335,4 +344,5 @@ function updateInstructions(name, initial = '', withBlock = true, write = true,
   return true;
 }
 
-module.exports = { updateInstructions, InstructionError, instructionParagraphs, holdsDevlynDefaults, importsAgentsMd };
+module.exports = { updateInstructions, InstructionError, instructionParagraphs, holdsDevlynDefaults, importsAgentsMd,
+  managedBody, managedBlock, sessionDefaults };

package/bin/release.js

@@ -0,0 +1,368 @@
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+const { parseArgs } = require('util');
+const { managedBody, managedBlock, sessionDefaults } = require('./instructions');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const CORE = ['devlyn-ideate', 'devlyn-engines', '_shared'];
+const DEFAULTS = 'config/skills/_shared/runtime-principles.md';
+const SHA256 = /^[a-f0-9]{64}$/;
+const VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+
+class HarnessError extends Error {
+  constructor(code, params = {}, exitCode = 1) {
+    super(`${code}: ${JSON.stringify(params)}`);
+    this.reason = { code, params };
+    this.exitCode = exitCode;
+  }
+}
+function fail(code, params, exitCode) { throw new HarnessError(code, params, exitCode); }
+const sha256 = (bytes) => crypto.createHash('sha256').update(bytes).digest('hex');
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+function manifestDigest(manifest) {
+  const { digest, ...body } = manifest;
+  return sha256(canonical(body));
+}
+const jsonBytes = (value) => Buffer.from(JSON.stringify(value, null, 2) + '\n');
+
+// POSIX manifest names must also be unambiguous on Windows and macOS volumes.
+function validatePath(name) {
+  if (typeof name !== 'string' || !name || /[\\\x00-\x1f\x7f:<>"|?*]/.test(name)
+      || path.posix.isAbsolute(name) || path.win32.isAbsolute(name)
+      || name.split('/').some((part) => !part || part === '.' || part === '..' || /[. ]$/.test(part)
+        || /^(?:con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³])(?:\.|$)/i.test(part))) {
+    fail('release-unsafe-path', { path: String(name) });
+  }
+}
+function validatePaths(names) {
+  const seen = new Map();
+  const files = new Set();
+  for (const name of names) {
+    validatePath(name);
+    if (files.has(name)) fail('release-duplicate-path', { path: name });
+    files.add(name);
+    const parts = name.split('/');
+    for (let i = 1; i <= parts.length; i++) {
+      const prefix = parts.slice(0, i).join('/');
+      const folded = prefix.normalize('NFC').toUpperCase().toLowerCase().toUpperCase();
+      if (seen.has(folded) && seen.get(folded) !== prefix) fail('release-case-collision', { path: name });
+      seen.set(folded, prefix);
+    }
+  }
+  for (const name of names) {
+    const parts = name.split('/');
+    for (let i = 1; i < parts.length; i++) {
+      if (files.has(parts.slice(0, i).join('/'))) fail('release-path-conflict', { path: name });
+    }
+  }
+}
+function regular(file, directory = false) {
+  const stat = fs.lstatSync(file);
+  if (directory ? !stat.isDirectory() : !stat.isFile() || stat.nlink !== 1) {
+    fail('release-unsafe-entry', { path: file });
+  }
+  return stat;
+}
+function physicalRoot(root) {
+  if (typeof root !== 'string' || !path.isAbsolute(root)) fail('invalid-arguments', { argument: 'absolute path required' }, 2);
+  regular(root, true);
+  return fs.realpathSync(root);
+}
+function safeFile(root, relative) {
+  validatePath(relative);
+  const parts = relative.split('/');
+  for (let i = 1; i < parts.length; i++) regular(path.join(root, ...parts.slice(0, i)), true);
+  const file = path.join(root, ...parts);
+  regular(file);
+  return file;
+}
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (error) {
+    if (error instanceof SyntaxError) fail('invalid-json', { path: file });
+    throw error;
+  }
+}
+function treeFiles(root, relative = '', npmInstall = false) {
+  regular(path.join(root, relative), true);
+  const files = [];
+  for (const name of fs.readdirSync(path.join(root, relative)).sort()) {
+    const rel = relative ? `${relative}/${name}` : name;
+    validatePath(rel);
+    const stat = fs.lstatSync(path.join(root, rel));
+    if (stat.isDirectory()) {
+      // npm generates these launch shims after unpacking. Mutable install sources
+      // may contain them; immutable releases never do, and capture never copies them.
+      if (npmInstall && rel === 'node_modules/.bin') continue;
+      files.push(...treeFiles(root, rel, npmInstall));
+    }
+    else { regular(path.join(root, rel)); files.push(rel); }
+  }
+  validatePaths(files);
+  return files.sort();
+}
+function packageMetadata(root) {
+  const pkg = readJson(safeFile(root, 'package.json'));
+  if (pkg.name !== 'devlyn-cli' || !VERSION.test(pkg.version) || typeof pkg.engines?.node !== 'string') {
+    fail('release-schema', { field: 'package.json' }, 3);
+  }
+  return pkg;
+}
+
+function generatedArtifacts(root) {
+  const pkg = packageMetadata(root);
+  const template = fs.readFileSync(safeFile(root, 'CLAUDE.md'), 'utf8').replace(/\r\n/g, '\n');
+  const agents = fs.readFileSync(safeFile(root, 'AGENTS.md'), 'utf8').replace(/\r\n/g, '\n');
+  if (template !== agents || /<!-- devlyn:instructions:(?:begin|end)/.test(template)) {
+    fail('release-template-mismatch', {});
+  }
+  const outputs = new Map();
+  const put = (name, bytes, executable = false) => outputs.set(name, { bytes: Buffer.from(bytes), executable });
+  put(DEFAULTS, sessionDefaults(template));
+  put('harness/CLAUDE.md', managedBlock(template));
+  put('harness/AGENTS.md', managedBlock(template));
+  const plugin = { name: 'devlyn', version: pkg.version, description: 'Devlyn harness skills', skills: './skills/' };
+  put('native/claude/.claude-plugin/plugin.json', jsonBytes(plugin));
+  put('native/codex/plugins/devlyn/.codex-plugin/plugin.json', jsonBytes(plugin));
+  put('native/codex/.agents/plugins/marketplace.json', jsonBytes({
+    name: `devlyn-harness-v${pkg.version.replace(/\./g, '-')}`,
+    plugins: [{ name: 'devlyn', source: { source: 'local', path: './plugins/devlyn' } }],
+  }));
+  for (const skill of CORE) {
+    const source = `config/skills/${skill}`;
+    for (const relative of treeFiles(path.join(root, source))) {
+      // Python bytecode and OS metadata are not release inputs.
+      if (relative.split('/').includes('__pycache__') || /(?:^|\/)(?:\.DS_Store|Thumbs\.db)$|\.pyc$/.test(relative)) continue;
+      const name = `${source}/${relative}`;
+      const file = safeFile(root, name);
+      const bytes = outputs.get(name)?.bytes || fs.readFileSync(file);
+      const executable = name === DEFAULTS ? false : Boolean(fs.statSync(file).mode & 0o111);
+      for (const mirror of ['native/claude', 'native/codex/plugins/devlyn']) put(`${mirror}/skills/${skill}/${relative}`, bytes, executable);
+    }
+  }
+  return outputs;
+}
+
+function checkGenerated(root) {
+  const expected = generatedArtifacts(root);
+  for (const [name, { bytes, executable }] of expected) {
+    const file = safeFile(root, name);
+    if (!fs.readFileSync(file).equals(bytes) || (process.platform !== 'win32' && Boolean(fs.statSync(file).mode & 0o111) !== executable)) {
+      fail('release-generated-mismatch', { path: name });
+    }
+  }
+  const actual = ['harness', 'native'].flatMap((dir) => treeFiles(path.join(root, dir)).map((name) => `${dir}/${name}`));
+  if (actual.some((name) => !expected.has(name))) fail('release-generated-mismatch', { path: 'unlisted generated file' });
+  return expected.size;
+}
+
+function metadata(root) {
+  const pkg = packageMetadata(root);
+  return {
+    schemaVersion: 1, package: 'devlyn-cli', version: pkg.version,
+    principles: { defaults: DEFAULTS, memory: { claude: 'harness/CLAUDE.md', agents: 'harness/AGENTS.md' },
+      sourceBlockSha256: sha256(managedBody(fs.readFileSync(safeFile(root, 'CLAUDE.md'), 'utf8'))) },
+    skills: { root: 'config/skills', names: CORE.slice(0, 2), support: '_shared',
+      claudePlugin: 'native/claude', codexMarketplace: 'native/codex' },
+    stateCompat: {
+      loopManifest: { read: [1, 1], write: 1 }, addRecord: { read: [1, 1], write: 1 },
+      // CLI-2 introduces packet v2 and queueBinding together with their implementations.
+      taskPacket: { inspect: [1, 1], execute: [1, 1], write: 1 },
+      submission: { read: [1, 1], write: 1 }, review: { read: [1, 1], write: 1 },
+      acceptanceResult: { read: [1, 1], write: 1 }, invocationReceipt: { read: [1, 1], write: 1 },
+      legacyFormats: ['completion-receipt-unversioned', 'direct-acceptance-unversioned',
+        'expected-contract-unversioned', 'engines-config-unversioned', 'queue-markdown-inspect-only'],
+    },
+    requires: { node: pkg.engines.node, python: '>=3.11', git: true, windowsGitBash: true, githubDelivery: 'gh' },
+  };
+}
+
+function writeArtifact(root, name, bytes, executable) {
+  const parts = name.split('/');
+  for (let i = 1; i < parts.length; i++) {
+    const dir = path.join(root, ...parts.slice(0, i));
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir);
+    regular(dir, true);
+  }
+  const file = path.join(root, name);
+  if (fs.lstatSync(file, { throwIfNoEntry: false })) regular(file);
+  fs.writeFileSync(file, bytes);
+  fs.chmodSync(file, executable ? 0o755 : 0o644);
+}
+
+function buildRelease(root = PACKAGE_ROOT) {
+  root = physicalRoot(root);
+  // npm omits links from its inventory; reject them before that omission can hide an input.
+  for (const dir of ['bin', 'config', 'optional-skills']) treeFiles(path.join(root, dir));
+  const outputs = generatedArtifacts(root);
+  // Generated roots are package-owned. Validate before removing stale mirror files.
+  for (const dir of ['harness', 'native']) {
+    if (fs.lstatSync(path.join(root, dir), { throwIfNoEntry: false })) {
+      treeFiles(path.join(root, dir));
+      fs.rmSync(path.join(root, dir), { recursive: true });
+    }
+  }
+  for (const [name, { bytes, executable }] of outputs) writeArtifact(root, name, bytes, executable);
+  // npm's own inventory includes the exact bundled dependency closure and pack exclusions.
+  const npmCli = process.env.npm_execpath || (process.platform === 'win32'
+    ? path.join(path.dirname(process.execPath), 'node_modules/npm/bin/npm-cli.js') : null);
+  const result = spawnSync(npmCli ? process.execPath : 'npm', [
+    ...(npmCli ? [npmCli] : []), 'pack', '--dry-run', '--ignore-scripts', '--json',
+  ], { cwd: root, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
+  if (result.error || result.status !== 0) fail('release-pack-failed', { detail: result.error?.message || result.stderr.trim() });
+  const packed = JSON.parse(result.stdout)[0];
+  const names = packed.files.map((file) => file.path).filter((name) => name !== 'release.json').sort();
+  validatePaths(names);
+  const pkg = packageMetadata(root);
+  for (const dependency of pkg.bundleDependencies) {
+    if (!names.includes(`node_modules/${dependency}/package.json`)) fail('release-missing-dependency', { dependency });
+  }
+  const modes = new Map(packed.files.map((file) => [file.path, Boolean(file.mode & 0o111)]));
+  const manifest = { ...metadata(root), files: names.map((name) => ({
+    path: name, sha256: sha256(fs.readFileSync(safeFile(root, name))), executable: modes.get(name),
+  })) };
+  manifest.digest = { algorithm: 'sha256', value: manifestDigest(manifest) };
+  writeArtifact(root, 'release.json', jsonBytes(manifest), false);
+  return { manifestPath: path.join(root, 'release.json'), version: manifest.version,
+    digest: manifest.digest.value, fileCount: manifest.files.length };
+}
+
+function checkNpmShims(root, files) {
+  const dir = path.join(root, 'node_modules/.bin');
+  if (!fs.lstatSync(dir, { throwIfNoEntry: false })) return;
+  regular(dir, true);
+  const names = new Set(files.map((file) => file.path));
+  const targets = new Map();
+  for (const file of files) {
+    if (!/^node_modules\/(?:@[^/]+\/)?[^/]+\/package\.json$/.test(file.path)) continue;
+    const pkg = readJson(safeFile(root, file.path));
+    const bins = typeof pkg.bin === 'string' ? { [pkg.name.split('/').at(-1)]: pkg.bin } : pkg.bin || {};
+    for (const [name, relative] of Object.entries(bins)) {
+      validatePath(name);
+      if (name.includes('/') || typeof relative !== 'string') fail('release-schema', { field: 'dependency bin' }, 3);
+      const target = path.posix.normalize(`${path.posix.dirname(file.path)}/${relative}`);
+      validatePath(target);
+      if (!names.has(target)) fail('release-file-list-mismatch', { path: target });
+      for (const shim of [name, `${name}.cmd`, `${name}.ps1`]) {
+        if (!targets.has(shim)) targets.set(shim, new Set());
+        targets.get(shim).add(path.join(root, target));
+      }
+    }
+  }
+  for (const name of fs.readdirSync(dir)) {
+    const file = path.join(dir, name);
+    const stat = fs.lstatSync(file);
+    if (!targets.has(name)) fail('release-file-list-mismatch', { path: `node_modules/.bin/${name}` });
+    if (stat.isSymbolicLink()) {
+      if (!targets.get(name).has(path.resolve(dir, fs.readlinkSync(file)))) fail('release-unsafe-entry', { path: file });
+    } else regular(file); // Windows shims are regular files; never execute or copy them.
+  }
+}
+
+function verifyRelease(root, { npmInstall = false } = {}) {
+  root = physicalRoot(root);
+  const manifest = readJson(safeFile(root, 'release.json'));
+  if (!manifest || manifest.schemaVersion !== 1 || manifest.package !== 'devlyn-cli'
+      || !VERSION.test(manifest.version) || manifest.digest?.algorithm !== 'sha256'
+      || !SHA256.test(manifest.digest?.value) || !Array.isArray(manifest.files)
+      || !manifest.files.every((f) => f && typeof f.path === 'string' && SHA256.test(f.sha256) && typeof f.executable === 'boolean')) {
+    fail('release-schema', { path: 'release.json' }, 3);
+  }
+  const names = manifest.files.map((file) => file.path);
+  validatePaths([...names, 'release.json']);
+  if (canonical(names) !== canonical([...names].sort())) fail('release-schema', { field: 'files order' }, 3);
+  if (manifestDigest(manifest) !== manifest.digest.value) fail('release-digest-mismatch', { path: 'release.json' });
+  const actual = treeFiles(root, '', npmInstall).filter((name) => name !== 'release.json');
+  if (canonical(actual) !== canonical(names)) fail('release-file-list-mismatch', {});
+  for (const file of manifest.files) {
+    const full = safeFile(root, file.path);
+    if (sha256(fs.readFileSync(full)) !== file.sha256) fail('release-file-digest-mismatch', { path: file.path });
+    // Windows has no POSIX execute bit; its declared mode is retained in the digest.
+    if (process.platform !== 'win32' && Boolean(fs.statSync(full).mode & 0o111) !== file.executable) {
+      fail('release-mode-mismatch', { path: file.path });
+    }
+  }
+  if (npmInstall) checkNpmShims(root, manifest.files);
+  const { files, digest, ...declared } = manifest;
+  if (canonical(declared) !== canonical(metadata(root))) fail('release-schema', { field: 'metadata' }, 3);
+  checkGenerated(root);
+  return { release: { package: 'devlyn-cli', version: manifest.version, digest: digest.value, root }, valid: true };
+}
+
+function materializeRelease(source, store) {
+  const verified = verifyRelease(source, { npmInstall: true }).release;
+  if (!path.isAbsolute(store)) fail('invalid-arguments', { argument: 'absolute store required' }, 2);
+  // Check every existing store component before mkdir; never write through a store link.
+  const missing = [];
+  let parent = path.resolve(store);
+  while (!fs.lstatSync(parent, { throwIfNoEntry: false })) { missing.push(parent); parent = path.dirname(parent); }
+  regular(parent, true);
+  for (let dir = parent; dir !== path.dirname(dir); dir = path.dirname(dir)) regular(dir, true);
+  for (const dir of missing.reverse()) { fs.mkdirSync(dir, { recursive: true }); regular(dir, true); }
+  store = physicalRoot(store);
+  const packageDir = path.join(store, 'devlyn-cli');
+  fs.mkdirSync(packageDir, { recursive: true });
+  regular(packageDir, true);
+  const target = path.join(packageDir, verified.version);
+  const existing = () => {
+    const release = verifyRelease(target).release;
+    if (release.digest !== verified.digest) fail('release-version-conflict', { version: release.version }, 3);
+    return { release, created: false };
+  };
+  if (fs.lstatSync(target, { throwIfNoEntry: false })) return existing();
+  const temp = fs.mkdtempSync(path.join(packageDir, `.${verified.version}-`));
+  try {
+    const manifest = readJson(safeFile(verified.root, 'release.json'));
+    for (const file of [...manifest.files, { path: 'release.json', executable: false }]) {
+      writeArtifact(temp, file.path, fs.readFileSync(safeFile(verified.root, file.path)), file.executable);
+    }
+    const captured = verifyRelease(temp).release;
+    if (captured.digest !== verified.digest) fail('release-source-changed', {}, 3);
+    try { fs.renameSync(temp, target); }
+    catch (error) {
+      if (['EEXIST', 'ENOTEMPTY', 'EPERM', 'EACCES'].includes(error.code) && fs.existsSync(target)) return existing();
+      throw error;
+    }
+    return { release: { ...captured, root: target }, created: true };
+  } finally {
+    fs.rmSync(temp, { recursive: true, force: true });
+  }
+}
+
+function options(args, definitions) {
+  try { return parseArgs({ args, options: { json: { type: 'boolean' }, ...definitions }, strict: true }).values; }
+  catch (error) { fail('invalid-arguments', { detail: error.message }, 2); }
+}
+function releaseCommand(args) {
+  const opts = options(args, Object.fromEntries(['build', 'verify', 'materialize', 'root', 'source', 'store']
+    .map((key) => [key, { type: ['build', 'verify', 'materialize'].includes(key) ? 'boolean' : 'string' }])));
+  const actions = ['build', 'verify', 'materialize'].filter((key) => opts[key]);
+  const allowed = { build: ['build', 'json'], verify: ['verify', 'root', 'json'], materialize: ['materialize', 'source', 'store', 'json'] };
+  if (actions.length !== 1 || Object.keys(opts).some((key) => !allowed[actions[0]].includes(key))
+      || (opts.verify && !opts.root) || (opts.materialize && (!opts.source || !opts.store))) fail('invalid-arguments', {}, 2);
+  if (opts.build) return buildRelease();
+  if (opts.verify) return verifyRelease(opts.root);
+  return materializeRelease(opts.source, opts.store);
+}
+function runJson(action) {
+  try { process.stdout.write(JSON.stringify({ schemaVersion: 1, ok: true, data: action() }) + '\n'); }
+  catch (error) {
+    const reason = error instanceof HarnessError ? error.reason
+      : { code: 'operation-failed', params: { detail: error.message, ...(error.code ? { systemCode: error.code } : {}) } };
+    process.stderr.write(`${reason.code}: ${JSON.stringify(reason.params)}\n`);
+    process.stdout.write(JSON.stringify({ schemaVersion: 1, ok: false, error: reason }) + '\n');
+    process.exitCode = error instanceof HarnessError ? error.exitCode : 1;
+  }
+}
+
+module.exports = { buildRelease, verifyRelease, materializeRelease, checkGenerated,
+  sha256, manifestDigest, physicalRoot, HarnessError, fail,
+  options, releaseCommand, runJson };

package/bin/skill-history.json

@@ -18,11 +18,13 @@
       "161cb4f1b27a9f81ae1e96af6ff596399c8936578a11d601108a89cbdeea241d",
       "196afa14871099a9afc4e484b00e8d8ccd928dba79db95a6a8776f58c8e78c39",
       "1c1e5e44ff704b1b8791fabcad79a4158d8cd2f024569c1685ec3b185a98fbcc",
+      "20ac702b463f3eaa07fd6686d5209aed7993773504e35896fc732f7e653ec6cd",
       "20bfec10dcec9a06701827a6a39faf3495f970f659f1e941cbfb62e880a0649c",
       "20e11efa7b27dcd30b5550ba5e0e2e07df9ac522a76445a594803a0e29b2e13d",
       "21723943c52573124ce3c74e9090a8ae7d7c9ecdeb78fdfa52b89c45ff1b3374",
       "247904cad29c1c3ed810f848e66f982e8765e5c627ef3a18a876fd95eed9c29c",
       "24f73bd06d359296088e43ce2e7bf5178e3f69752b559639585563ec35fc33f5",
+      "2692865ee864aebedb2b385384b2a8220bc780bd92310bc1cf2f56927de1e0b8",
       "27d4da7863ed4652187f6a101da0e56b1d3d18e4565c720d5f8150ad0a193402",
       "2a4361bca0a9fadc4a8e5e4578c383171cd64c65296fe882990502250df44d53",
       "2bcac1ab5995e474c7dd46705413982876384d8b4da704126a66c10770a1a4d2",
@@ -33,6 +35,7 @@
       "353b483942a62b79d1c5bf31e30060ef7ed9a67ae2d8b27450a53acb98e4e23c",
       "3554398c2be144938e4837d9b60c0976f685cfc2c0dd0451cda714fd053f3c7d",
       "35c7e6c069c847ff147f2bf4f3b67a296652c122aa91a3966457a00dd0597b78",
+      "364aa97ec4065d8b78188f40281dfa575120a8fb91089120363e532566ef0dcb",
       "37acccbdc76aee15311b5f47fd26c50b1652dbe7cbcbacfc37774841ab464028",
       "393ad728eb0906ae61110fde3820c4fce015d8f94643a2877372b74a6b6eeb02",
       "3b6193eabc83d815804533010ca7bff1f240286e7898380a5fc2adac71dcb513",
@@ -88,6 +91,7 @@
       "7a0f6c692bd1f74759d44f1a145899c157e1787635db546ea8a192461421e353",
       "7ca704d818bf9c044fed59fdd4107bd0463f9b0514d44729003e3e52aa796353",
       "7e915cc7307af694e326c7f75cf831d187edd965f38d870323cd50f0f01a564b",
+      "7f5f9f318f465b01c573fa521922a218e0973056a53053d262ca6ffb84dda145",
       "800543bb9d1f8b90a7c077f072aa45364a0136d3c4e9b7acddcdbc30d63eb0c8",
       "823e497e01870123d4e73c8dac7472e161b5ffa2f6181ddcba71fcb829096948",
       "83b6d37fcacc086a09b9c3eddfff2263bfef23f8fabf8d8833a7c9f9fb6186c5",
@@ -100,6 +104,7 @@
       "9162fc2fed6f4a611d299485be3a397080beb3304865ce59b95576ba7d00650e",
       "94a14a1b87df1d7297d12949a24e47a0d6c16a8fe30495ee759fcabb2e1aa398",
       "978e4210e49b42827c98cf6e40c868c87dc6e3533a2b779ca2fa05abfc16ad0f",
+      "97e7ad89c74c609b15dfbf6f9f7ac61df8b50e97e4bc318f72922e058ecffba4",
       "9815b6e6963e068872a6dbeae24068143bf92042bb035f67bafd1a224d65bcb0",
       "998343c148618b937556b58b83749c05d5aa3283280d751c118da6a542fb87f2",
       "9dd3ec225818efe0ad3726192db94ff129154e995617a9d3c150fc58ad0f9f2c",
@@ -144,6 +149,7 @@
       "db867d1fd98058bb20e41e942abd95f08fbaa9465928025f69f0a0308fa71514",
       "dd0bfdfd2db0b5f9ddef75d1b9ce3247698739fc551d292366dccd506fef6a36",
       "ddb0c8dac58e95298330ab54e4d1fe4a108c968d9af713f267b4f8f4c6808507",
+      "de4f504265e960cb8d81752e9ae922f664790ee026b4454f1b07252d1a6282a4",
       "e0a305cf3bf47c8bc357195d4d50b0f6177069e870c33040c258c93edae68646",
       "e115205a744fef918a59d1b3a601df09a8b6df1d3e60613b9e8b87240929f8d8",
       "e41013abf5e17445ef83a86974ac1de77beaa61e484e1916577ecc64bb34c220",
@@ -343,6 +349,7 @@
       "a7d7d65fd5f672cb404e6069fdc42ad7077deaa80ed8500cfa8b382dab2e3e29",
       "aba66b674683935e4c28c93333896dc116ffe67e7a35fe30b3599a8be507e94e",
       "b2e4437fa981317362d03ee032e1cfd8b686316e966c6ba12ecd619a009c80a6",
+      "bdd0751eea04532c050334fda3bc5c61c6b429e485d97e0b8ebb4fae154da2c7",
       "c1b8e3ebf38e2be8972aa003e9614a782cb4f195c69d20b95a475ebf9aaaab9e",
       "c8e375aab574148542f392b093cbbf3f2e8dc623826b45e35df0a1a2c3862226",
       "ce282a55328c2d071cacc377670fbebea4da4b9a7fee81b25293fb26763f17c9",

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

@@ -1,3 +1,6 @@
 # oh-my-pi adapter
 
+executor: no
+
 Engine `omp`, the oh-my-pi CLI.
+Stub: model-call execution and failure handling have not been qualified.

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

@@ -1,6 +1,8 @@
-# Runtime principles
+The following Devlyn instructions are defaults for this session. Applicable explicit user instructions and native owner/project instructions take precedence over these defaults. This delegation applies only to the Devlyn defaults below; it does not change other engine instructions or permissions.
 
-The North Star and core principles of the installed CLAUDE.md/AGENTS.md block, for a context without that block. These sections stay byte-identical to the templates (lint Check 12).
+# Project Instructions
+
+devlyn-cli installs the `devlyn-ideate` and `devlyn-engines` skills alongside the principles below, which are non-negotiable on every change — yours and any sub-agent's.
 
 ## North Star
 
@@ -23,3 +25,11 @@ Three discipline rules govern HOW the principles are applied:
 - **Root cause via flexible why-chain.** Keep asking "why?" until you find the violated invariant. **If the answer surfaces in 2 questions, stop.** If it takes 5 or 7, keep going. Strict counts are wrong; until-found is right.
 - **First-principles thinking.** Challenge the requirement before optimizing the answer. Surface unstated assumptions, ambiguities, tradeoffs, and simpler alternatives BEFORE implementing — do not silently pick one interpretation when multiple exist, do not hide confusion, push back when a simpler path is genuinely better. Most "we have to do X" assumptions are habit, not necessity. Reduce the problem to its irreducible truths and rebuild from there.
 - **Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away.** — Saint-Exupéry. This is the operating definition of "done." A change is finished when no further line, branch, flag, or doc paragraph can be removed without breaking a learned failure mode. Not before.
+
+## Quick Start
+
+- `devlyn-ideate` — loop designer and intent queue: `plan <intent or document>` writes a validated loop package, `add` queues its tasks, `status` (or no arguments) reports the queue, `drain` executes it serially.
+- Delivery — direct work edits the current checkout; deliver completed, verified requests with changes by project policy (default PR and merge), following `_shared/task-completion.md` in `.claude/skills/` or `.agents/skills/` (project, else `~`). With known concurrent writers, isolate before editing; on unexplained changes, pause writes until safe or isolated. An ideate drain delivers every task. Explicit limits win; commit alone stays local.
+- Executor — `devlyn-engines` shows it and pins it in `.devlyn/engines.json`. A pinned executor does the implementation work, direct or drained: when it is not you, delegate to it, and when it is unavailable stop with `BLOCKED:<engine>-unavailable`. Without a pin, you are the executor.
+
+Each skill's `SKILL.md` is the source of truth for its flags and workflow.