devlyn-cli 3.1.3 → 3.2.0

package/README.md

@@ -27,7 +27,7 @@ If devlyn-cli saved you time, [give it a star](https://github.com/fysoul17/devly
 npx devlyn-cli
 ```
 
-That's it. The installer opens with a single **agent selector** — pick any combination of **Claude Code**, **Codex CLI**, **oh-my-pi (omp)**, **Pi**, or **Grok Build CLI**, and devlyn installs into every one you choose in a single pass. Claude Code and any agent already present on your machine are pre-checked, so the common case is just Enter. Skill-capable agents receive the `devlyn:resolve`, `devlyn:ideate`, and `devlyn:design-ui` skills — plus the `devlyn:engines` and `devlyn:queue` utilities — in the directory each one loads from: Codex → `~/.codex/skills/`, Grok → `~/.grok/skills/`, while **omp and Pi share `~/.agents/skills/`** — the cross-agent standard both read — so the bundle is written there once, not duplicated per agent. In Codex / omp / Pi, invoke them as skills (`$devlyn:resolve`, `$devlyn:ideate`, `$devlyn:design-ui`); in Claude Code and Grok Build CLI they're slash commands (`/devlyn:resolve`). Rerunning refreshes skills for selected agents, preserves existing AGENTS.md without legacy managed markers (legacy appended blocks are still cleaned up), and replaces CLAUDE.md when Claude Code is selected. Use the bundled AGENTS.md template path printed by the installer to compare and merge relevant shared runtime instructions into your preserved AGENTS.md, retaining your content and keeping engine-specific instructions distinct. (`npx devlyn-cli -y` installs the Claude core non-interactively; `npx devlyn-cli agents <cli>` adds one agent later.)
+That's it. The installer opens with a single **agent selector** — pick any combination of **Claude Code**, **Codex CLI**, **oh-my-pi (omp)**, **Pi**, or **Grok Build CLI**, and devlyn installs into every one you choose in a single pass. Claude Code and any agent already present on your machine are pre-checked, so the common case is just Enter. Skill-capable agents receive the `devlyn:resolve`, `devlyn:ideate`, and `devlyn:design-ui` skills — plus the `devlyn:engines` and `devlyn:queue` utilities — in the directory each one loads from: Codex → `~/.codex/skills/`, Grok → `~/.grok/skills/`, while **omp and Pi share `~/.agents/skills/`** — the cross-agent standard both read — so the bundle is written there once, not duplicated per agent. In Codex / omp / Pi, invoke them as skills (`$devlyn:resolve`, `$devlyn:ideate`, `$devlyn:design-ui`); in Claude Code and Grok Build CLI they're slash commands (`/devlyn:resolve`). Rerunning refreshes skills and the managed instruction block for selected agents while preserving project rules outside it. See [Migration from earlier versions](#migration-from-earlier-versions) for legacy migration and merge recovery. (`npx devlyn-cli -y` installs the Claude core non-interactively; `npx devlyn-cli agents <cli>` adds one agent later.)
 
 ---
 
@@ -76,10 +76,10 @@ Internal phases run sequentially with file-based handoff via `.devlyn/pipeline.s
 PLAN  →  IMPLEMENT  →  BUILD_GATE  →  CLEANUP  →  VERIFY (fresh subagent, findings-only)
 ```
 
-- **PLAN** is the heaviest phase by design — formalizes invariants from the spec/goal and the file list to touch.
-- **BUILD_GATE** runs your project's real compilers, typecheckers, linters, and `python3 .claude/skills/_shared/spec-verify-check.py` (verification commands literal-match). Auto-detects Next.js, Rust, Go, Solidity, Expo, Swift, and Dockerfiles. Browser flows route through Chrome MCP → Playwright → curl tier.
+- **PLAN** runs in the owner context and freezes requirements, verification and the authorized file surface before implementation.
+- **BUILD_GATE** runs commands in the owner context without another model invocation, using your project's real compilers, typecheckers, linters, and `python3 .claude/skills/_shared/spec-verify-check.py` (verification commands literal-match). Auto-detects Next.js, Rust, Go, Solidity, Expo, Swift, and Dockerfiles. Browser flows route through Chrome MCP → Playwright → curl tier.
 - **VERIFY** runs in a fresh subagent context with no code-mutation tools — findings only, structurally independent.
-- Git checkpoints at every phase for safe rollback. Fix-loop budget shared across BUILD_GATE and VERIFY (`--max-rounds N`, default 4).
+- Git checkpoints at every phase for safe rollback. Fix-loop budget shared across BUILD_GATE, CLEANUP and VERIFY (`--max-rounds N`, default 4).
 
 Common flags: `--engine claude|codex|omp` (default: the orchestrator-supported default), `--role-config <path>` (one-run worker/judge profiles, see below), `--bypass build-gate,cleanup`, `--pair-verify` (force pair-mode JUDGE in VERIFY), `--no-pair` (intentional solo VERIFY), `--risk-probes` / `--no-risk-probes`, `--perf` (per-phase timing).
 `--pair-verify` and `--no-pair` are mutually exclusive; using both stops with `BLOCKED:invalid-flags`.
@@ -118,10 +118,10 @@ Stack tasks to run back-to-back without supervision. `/devlyn:queue add "<intent
 devlyn separates three engine roles:
 
 - **Orchestrator** — the CLI you opened (Claude Code, Codex, or omp) that drives the conversation and loop. The contract is symmetric (`CLAUDE.md` ↔ `AGENTS.md`), so the same phase-gated pipeline runs whichever you launch; the file artifacts (spec, queue, state) carry over if you switch.
-- **Executor** (legacy) — the worker for IMPLEMENT / CLEANUP and their repair rounds, and the primary VERIFY judge, unless either is separately profiled (below). Defaults to the orchestrator-supported default. PLAN is orchestrator-fixed and never inherits `--engine` or an executor pin. An absent primary profile follows the legacy executor, not an opt-in worker profile.
+- **Executor** (legacy) — the worker for IMPLEMENT, its included code/doc cleanup, and their repair rounds, and the primary VERIFY judge, unless either is separately profiled (below). Defaults to the orchestrator-supported default. PLAN is orchestrator-fixed and never inherits `--engine` or an executor pin. An absent primary profile follows the legacy executor, not an opt-in worker profile.
 - **Pair judge** — the first available *other* engine, default for VERIFY and conditional for risk probes.
 
-`--engine <name>` sets the legacy executor for one run as an engine-only entry (it clears any lower-precedence profile's model/effort). BUILD_GATE and risk-probe derivation keep their existing routes; PLAN always runs on the orchestrator's native worker. VERIFY/JUDGE runs pair mode by default when the OTHER engine is available.
+`--engine <name>` sets the legacy executor for one run as an engine-only entry (it clears any lower-precedence profile's model/effort). PLAN stays in the owner context; BUILD_GATE/CLEANUP run owner commands; risk-probe derivation keeps its existing route. VERIFY/JUDGE runs pair mode by default when the OTHER engine is available.
 
 Pin roles durably with `/devlyn:engines` (no args shows the role table + detected engines; `executor <name>` / `pair <name>,...` / `role <worker|primary_judge|pair_judge> <JSON object>` / `role <name> clear` manage the pins, stored machine-local in `.devlyn/engines.json`; `clear` removes all legacy and role pins, preserves unrelated keys, and deletes an empty file). Pins fail closed: an unavailable pinned engine stops with `BLOCKED:<engine>-unavailable`, and a name with no `_shared/adapters/<name>.md` adapter stops with `BLOCKED:invalid-engine-config`. New engines plug in by shipping an adapter file — no skill changes.
 
@@ -144,12 +144,12 @@ Pin roles durably with `/devlyn:engines` (no args shows the role table + detecte
 `--role-config <path>` supplies the same `{"roles": {...}}` object for one run only, with no other top-level keys; the flag may appear once.
 
 - **Precedence** — an entry replaces the lower one as a whole; model/effort never merge across engines. Worker and primary judge: run `--role-config` entry > `--engine` (engine-only) > project role entry > legacy executor/default. Pair judge: run entry > project entry > `pair_judge_priority` / the OTHER-engine complement. A missing `model`/`effort` keeps that route's current default and is shown as inherited/unresolved.
-- **Boundaries** — `worker` covers IMPLEMENT / CLEANUP and their repair rounds; `primary_judge` and `pair_judge` cover VERIFY only. PLAN stays orchestrator-fixed, BUILD_GATE keeps its existing route, and risk-probe derivation stays outside these controls. OTHER must differ from the primary by engine: an explicit same-engine pair is `BLOCKED:invalid-engine-config`. `--no-pair` is unchanged — explicit solo VERIFY; an unused pair entry is neither dispatched nor availability-checked.
+- **Boundaries** — `worker` covers IMPLEMENT, its included code/doc cleanup, and their repair rounds; `primary_judge` and `pair_judge` cover VERIFY only. PLAN stays orchestrator-fixed, BUILD_GATE/CLEANUP run owner commands, and risk-probe derivation stays outside these controls. OTHER must differ from the primary by engine: an explicit same-engine pair is `BLOCKED:invalid-engine-config`. `--no-pair` is unchanged — explicit solo VERIFY; an unused pair entry is neither dispatched nor availability-checked.
 - **Initial explicit routes** — Codex worker/primary/pair accept exact `model` + `effort` (dispatched as `-m` / `-c model_reasoning_effort=`, validated against the installed Codex CLI's native model metadata for its version). Claude primary/pair judges pass an exact `model` as `--model` and validate native result identity; model-only selection needs no source update for a new ID. Explicit `effort` separately requires the adapter's version/model support declaration. The Claude worker stays the native `Agent` route and is engine-only: explicit `model`/`effort` on a Claude worker is `BLOCKED:unsupported-role-option` — a supported-route boundary, not a claim that Claude cannot implement. Other adapters (omp, grok) are engine-only for their eligible roles.
 - **Errors** — `BLOCKED:unsupported-role-option` names the role, engine and field with guidance; there is no clamp, fallback, substituted model, or weaker retry. An explicitly selected engine (flag, pin, or profile) that is unavailable stops with `BLOCKED:<engine>-unavailable`. A native warning that a requested option was ignored is a failed promise even at exit 0.
 - **Requested vs observed** — `/devlyn:engines` status prints each role's requested engine/model/effort, source and dispatch channel before dispatch; it describes a request and does not prove a native invocation happened. Effective model is reported only with native evidence; a Codex worker receipt binds requested dispatch and leaves effective model unknown. A reported worker model reroute blocks completion even at exit 0. SURFACE_CLOSE inherits native Claude model settings and records the model from its required JSON result. Effective effort stays unknown unless native evidence establishes it — invocation arguments prove dispatch, not provider-internal reasoning.
 
-`--engine codex` routes IMPLEMENT / CLEANUP to Codex as a supported engine-only route (exact model/effort via the profiles above). Historical record: iter-0020 closed Codex BUILD/IMPLEMENT below the quality floor on the 9-fixture suite (L2 vs L1 = −3.6, 3/8 gated fixtures cleared the +5 margin floor — release-readiness FAIL). Separately, PLAN-pair remains research-only: iter-0033g + iter-0034 closed it with explicit unblock conditions (container/sandbox infra OR production telemetry capturing positive evidence of subagent introspection). Install the Codex CLI (https://platform.openai.com/docs/codex) and pass the flag explicitly to opt in:
+`--engine codex` routes IMPLEMENT and its included code/doc cleanup to Codex as a supported engine-only route (exact model/effort via the profiles above). Historical record: iter-0020 closed Codex BUILD/IMPLEMENT below the quality floor on the 9-fixture suite (L2 vs L1 = −3.6, 3/8 gated fixtures cleared the +5 margin floor — release-readiness FAIL). Separately, PLAN-pair remains research-only: iter-0033g + iter-0034 closed it with explicit unblock conditions (container/sandbox infra OR production telemetry capturing positive evidence of subagent introspection). Install the Codex CLI (https://platform.openai.com/docs/codex) and pass the flag explicitly to opt in:
 
 ```
 /devlyn:resolve "fix the auth bug" --engine codex
@@ -232,13 +232,19 @@ CLIs. Claude uses `CLAUDE.md`; Codex, Grok, omp and Pi share `AGENTS.md`.
 Devlyn updates its checksum-marked instruction block and preserves project-specific
 rules outside it. Keep custom rules outside the block; they take precedence over
 its defaults. Exact pre-update backups are saved in `.devlyn/instructions/`.
-
-Unmodified templates from versions 3.0.0–3.1.2 migrate automatically, including
-custom text before or after the template. Edited or unrecognized older Devlyn
-templates with recognizable Devlyn contract text, changed managed blocks and
-ambiguous markers stop installation without replacing the original.
-The error names an `.incoming` file with current defaults:
-merge it, move custom rules outside its managed block, and rerun installation.
+When recovery is needed, pre-existing symlinks or non-directory entries at `.devlyn/` or
+`.devlyn/instructions/` stop installation without replacing the instruction file.
+
+Templates from versions 3.0.0–3.1.2 migrate automatically, including custom
+text before or after the template. Replaced or extended introductions under the
+original project heading also migrate when the entire body from `## North Star`
+onward matches a known template hash. Replacement project rules are preserved
+outside the managed block; only an exact original introduction is removed.
+Recognizable leftover Devlyn text, changed bodies and ambiguous templates stop
+with a concise recovery message and leave the original unchanged. The message
+links an exact `.backup`, new defaults in `.incoming`, and a `.merge.md` guide.
+Compare the two files, preserve all project rules outside one new managed block,
+and rerun the same install command. Earlier selected agents may already be updated.
 Plain custom instruction files retain their contents and gain a managed block.
 Use 3.1.3 or newer consistently: older installers still overwrite `CLAUDE.md`.
 

package/bin/devlyn.js

@@ -9,7 +9,7 @@ const { execSync } = require('child_process');
 const CONFIG_SOURCE = path.join(__dirname, '..', 'config');
 const OPTIONAL_SKILLS_SOURCE = path.join(__dirname, '..', 'optional-skills');
 const PKG = require('../package.json');
-const { updateInstructions } = require('./instructions');
+const { updateInstructions, InstructionError } = require('./instructions');
 
 // The devlyn skill bundle installed into every skill-capable agent's loader
 // directory. Single source of truth so codex/omp/pi stay in lockstep — adding a
@@ -765,8 +765,30 @@ function installAgentsForAllDetected() {
 // Install the Claude Code core config: project .claude/ (skills, templates,
 // settings, CLAUDE.md, .gitignore) plus global ~/.claude/settings.json tweaks.
 // Extracted so the unified target selector installs it only when "Claude Code"
-// is chosen. Check instruction conflicts before changing settings or skills.
+// is chosen. Check global settings and instruction conflicts before writes.
 function installClaudeCore() {
+  const globalClaudeDir = path.join(os.homedir(), '.claude');
+  const globalSettingsPath = path.join(globalClaudeDir, 'settings.json');
+  function readGlobalSettings() {
+    let settings = {};
+    try {
+      if (fs.lstatSync(globalSettingsPath, { throwIfNoEntry: false })) {
+        settings = JSON.parse(fs.readFileSync(globalSettingsPath, 'utf8'));
+      }
+    } catch (error) {
+      const reason = error instanceof SyntaxError ? 'invalid JSON' : error.message;
+      throw new Error(`Cannot merge ${globalSettingsPath}: ${reason}. Original preserved; correct the file or its access and rerun installation.`);
+    }
+    if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
+      throw new Error(`Cannot merge ${globalSettingsPath}: root must be a JSON object. Original preserved; correct it and rerun installation.`);
+    }
+    if (!Object.prototype.hasOwnProperty.call(settings, 'env')) settings.env = {};
+    if (!settings.env || typeof settings.env !== 'object' || Array.isArray(settings.env)) {
+      throw new Error(`Cannot merge ${globalSettingsPath}: env must be a JSON object. Original preserved; correct it and rerun installation.`);
+    }
+    return settings;
+  }
+  readGlobalSettings();
   updateInstructions('CLAUDE.md');
   const targetDir = getTargetDir();
   const skillsDir = path.join(targetDir, 'skills');
@@ -904,17 +926,8 @@ function installClaudeCore() {
   }
 
   // Configure global Claude Code settings (~/.claude/settings.json)
-  const globalClaudeDir = path.join(os.homedir(), '.claude');
-  const globalSettingsPath = path.join(globalClaudeDir, 'settings.json');
-  let globalSettings = {};
-  if (fs.existsSync(globalSettingsPath)) {
-    try {
-      globalSettings = JSON.parse(fs.readFileSync(globalSettingsPath, 'utf8'));
-    } catch {
-      globalSettings = {};
-    }
-  }
-  if (!globalSettings.env) globalSettings.env = {};
+  // Project settings may refer to this same file; merge the latest bytes.
+  const globalSettings = readGlobalSettings();
   let globalSettingsChanged = false;
   if (!globalSettings.env.CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING) {
     globalSettings.env.CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING = '1';
@@ -1204,6 +1217,8 @@ function showBenchmarkModeHelp(mode) {
 
 // Main
 const args = process.argv.slice(2);
+
+async function main() {
 const command = args[0];
 
 switch (command) {
@@ -1213,7 +1228,7 @@ switch (command) {
     break;
   case '-y':
   case '--yes':
-    init(true);
+    await init(true);
     break;
   case 'list':
   case 'ls':
@@ -1294,10 +1309,16 @@ switch (command) {
   }
   case 'init':
   case undefined:
-    init(false);
+    await init(false);
     break;
   default:
     log(`Unknown command: ${command}`, 'yellow');
     showHelp();
     process.exit(1);
 }
+}
+
+main().catch((error) => {
+  console.error(error instanceof InstructionError ? `\n${error.message}` : error);
+  process.exitCode = 1;
+});

package/bin/instruction-templates.json

@@ -5,14 +5,24 @@
         "3.0.0"
       ],
       "length": 11091,
-      "sha256": "099e68f3e203fa735bb1ebcd780a0e18bde462ea7de5f74fb3d17cee5e64b63a"
+      "sha256": "099e68f3e203fa735bb1ebcd780a0e18bde462ea7de5f74fb3d17cee5e64b63a",
+      "preamble": "# Codex Project Instructions\n\ndevlyn-cli installs `/devlyn:ideate` (optional) and `/devlyn:resolve` (required) into Claude Code, plus the contract below. Codex CLI reads this file when invoked inside a project that has it. The principles are non-negotiable on every change.\n\n",
+      "body": {
+        "length": 10816,
+        "sha256": "8b972c2c379e5ff8411bf1214f926a3b9904bdf857ac6b30a8c79ce0e32182e3"
+      }
     },
     {
       "versions": [
         "3.0.1"
       ],
       "length": 12166,
-      "sha256": "33fbd5b01c8e65f4c663f95423a45b16dcf5bb28f1fd0c6791079abd20c267ae"
+      "sha256": "33fbd5b01c8e65f4c663f95423a45b16dcf5bb28f1fd0c6791079abd20c267ae",
+      "preamble": "# Codex Project Instructions\n\ndevlyn-cli installs `/devlyn:ideate` (optional) and `/devlyn:resolve` (required) into Claude Code, plus the contract below. Codex CLI reads this file when invoked inside a project that has it. The principles are non-negotiable on every change.\n\n",
+      "body": {
+        "length": 11891,
+        "sha256": "52326a832df6d5ab13bddca5a1a01ad338a3db71d172c70d3eaed806668db4d8"
+      }
     },
     {
       "versions": [
@@ -21,7 +31,12 @@
         "3.1.2"
       ],
       "length": 12581,
-      "sha256": "acd3672efaa33e75455f8530a7425e950c01c822c6f5d85d7dbc9d7ff1958028"
+      "sha256": "acd3672efaa33e75455f8530a7425e950c01c822c6f5d85d7dbc9d7ff1958028",
+      "preamble": "# Codex Project Instructions\n\ndevlyn-cli installs `/devlyn:ideate` (optional) and `/devlyn:resolve` (required) into Claude Code, plus the contract below. Codex CLI reads this file when invoked inside a project that has it. The principles are non-negotiable on every change.\n\n",
+      "body": {
+        "length": 12306,
+        "sha256": "0de6061f9dff8e88964e542bb8a5e113996e480bef597774fb15eaa766472129"
+      }
     }
   ],
   "CLAUDE.md": [
@@ -30,14 +45,24 @@
         "3.0.0"
       ],
       "length": 24434,
-      "sha256": "29ddcc5ef4d5b44b2ba6aae22bd3c0c033ceaa47b240bd647aaefbe00f2a6e4e"
+      "sha256": "29ddcc5ef4d5b44b2ba6aae22bd3c0c033ceaa47b240bd647aaefbe00f2a6e4e",
+      "preamble": "# Project Instructions\n\ndevlyn-cli installs `/devlyn:ideate` (optional) and `/devlyn:resolve` (required) into Claude Code, plus the contract below. These principles are non-negotiable on every change \u2014 yours and any sub-agent's.\n\n",
+      "body": {
+        "length": 24204,
+        "sha256": "555d8b9a4c154ec5225105919836a4d9831c76c1b1c7ee4c19fecac8fbd1c948"
+      }
     },
     {
       "versions": [
         "3.0.1"
       ],
       "length": 25417,
-      "sha256": "50301bf98507c83da1576be7f443885236e7d421ff2e40fd077ed9652ea3a2e0"
+      "sha256": "50301bf98507c83da1576be7f443885236e7d421ff2e40fd077ed9652ea3a2e0",
+      "preamble": "# Project Instructions\n\ndevlyn-cli installs `/devlyn:ideate` (optional) and `/devlyn:resolve` (required) into Claude Code, plus the contract below. These principles are non-negotiable on every change \u2014 yours and any sub-agent's.\n\n",
+      "body": {
+        "length": 25187,
+        "sha256": "53a933e22369438a5d9dd7aa5f778909aeba5a38d5e2e68b8a36dab5c874d84d"
+      }
     },
     {
       "versions": [
@@ -46,7 +71,12 @@
         "3.1.2"
       ],
       "length": 26152,
-      "sha256": "d11a863907dabdf827063df7133a8a46a14e018f608884f08c601bf36e0f3f0c"
+      "sha256": "d11a863907dabdf827063df7133a8a46a14e018f608884f08c601bf36e0f3f0c",
+      "preamble": "# Project Instructions\n\ndevlyn-cli installs `/devlyn:ideate` (optional) and `/devlyn:resolve` (required) into Claude Code, plus the contract below. These principles are non-negotiable on every change \u2014 yours and any sub-agent's.\n\n",
+      "body": {
+        "length": 25922,
+        "sha256": "dd9f0f63f559a3b9a6e2bbf102045b01f6b73bce684dd27124ee6d6af3641b91"
+      }
     }
   ]
 }

package/bin/instructions.js

@@ -5,29 +5,52 @@ 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 starts = [...new Set([0, ...(text.startsWith('\uFEFF') ? [1] : []),
+    ...Array.from(text.matchAll(/^# (?:Codex )?Project Instructions\r?$/gm), (m) => m.index)])].sort((a, b) => a - b);
   const ranges = [];
   for (const start of starts) {
     for (const template of templates) {
-      let end = 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 = /^## North Star\r?$/m.exec(prefix);
+        const header = template.preamble.slice(0, template.preamble.indexOf('\n\n') + 2);
+        if (body && normalize(prefix).startsWith(header)) {
+          const bodyStart = start + body.index;
+          end = matchedEnd(text, bodyStart, template.body);
+          // Remove only an exact original preamble; preserve an edited one in full.
+          const preambleEnd = matchedEnd(text, start, { length: template.preamble.length, sha256: digest(template.preamble) });
+          custom = text.slice(preambleEnd ?? start, bodyStart);
+        }
       }
-      if (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;
       }
     }
   }
@@ -35,12 +58,18 @@ function legacyRanges(text, templates) {
 }
 
 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 +92,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)) {
@@ -97,16 +140,23 @@ function updateInstructions(name) {
     content = current.slice(0, start.index + (start[0].startsWith('\uFEFF') ? 1 : 0)) + block + current.slice(end.index + end[0].length);
   } else {
     const normalized = normalize(template);
+    const bodyStart = normalized.indexOf('## North Star\n');
+    const preamble = normalized.slice(0, bodyStart);
+    const body = normalized.slice(bodyStart);
     const ranges = legacyRanges(current, [
-      { length: normalized.length, sha256: digest(normalized) },
+      { 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);
+      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 (/^devlyn-cli installs |^# Devlyn Agent Instructions\r?$|^This contract serves one goal: any capable engine|^Engine roles: orchestrator =/m.test(current)) {
+      if (LEGACY.test(current)) {
         return conflict('unrecognized or edited legacy template');
       }
       content = current + (current ? eol + eol : '') + block;
@@ -124,7 +174,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 +184,4 @@ function updateInstructions(name) {
   return true;
 }
 
-module.exports = { updateInstructions };
+module.exports = { updateInstructions, InstructionError };

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: