devlyn-cli 3.1.2 → 3.1.3

package/AGENTS.md

@@ -1,6 +1,6 @@
 # Codex Project Instructions
 
-devlyn-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.
+devlyn-cli installs planning and full-pipeline skills alongside the execution contract below. Codex CLI reads this file when invoked inside a project that has it. The principles are non-negotiable on every change.
 
 ## North Star
 
@@ -27,22 +27,22 @@ Three discipline rules govern HOW the principles are applied:
 ## Quick Start
 
 ```text
-ideate (optional)  ->  resolve  ->  ship
+inspect intent  ->  direct work or full resolve  ->  ship
 ```
 
 - `/devlyn:ideate` (optional) — unstructured idea → `docs/specs/<id>/spec.md` + `spec.expected.json`. Modes: default Q&A, `--quick` (autonomous-pipeline-safe), `--from-spec <path>`, `--project` (multi-feature).
-- `/devlyn:resolve` — hands-free pipeline for any coding task. Free-form goal, `--spec <path>`, or `--verify-only <ref> --spec <path>`. Phases run inline: PLAN → IMPLEMENT → BUILD_GATE → CLEANUP → VERIFY (fresh-subagent, findings-only).
+- `/devlyn:resolve` — full pipeline for work selected by the conversational-entry rules below. Free-form goal, `--spec <path>`, or `--verify-only <ref> --spec <path>`. Phases: PLAN → IMPLEMENT → BUILD_GATE → CLEANUP → VERIFY (fresh-subagent, findings-only).
 - `/devlyn:design-ui` — required creative UI exploration surface. Spawns a 5-specialist design team (Creative Director, Product Designer, Visual Designer, Interaction Designer, Accessibility Designer) to generate N (default 5) portfolio-worthy HTML/CSS samples. The optional `/devlyn:reap` companion lives in `optional-skills/` and installs only when the user opts in.
 
 Each skill's `SKILL.md` is the source of truth for flags and workflow. Do not duplicate.
 
 Engine roles: orchestrator = whichever CLI the user opened (this contract is symmetric with CLAUDE.md. If you are Codex orchestrating `/devlyn:resolve`, the phase machinery is mandatory regardless of task size; if you will not run it, say so explicitly and stop — do not silently degrade to ad-hoc execution); legacy executor (with optional separate worker/primary/pair profiles) uses the canonical skill's orchestrator-supported default, overridable per run with `--engine <name>` or durably via machine-local `.devlyn/engines.json` `{"executor": "<name>", "pair_judge_priority": ["<name>", ...]}`; PLAN is orchestrator-fixed and never inherits `--engine` or the executor pin; pair judge = first available OTHER engine, default for VERIFY whenever available; risk probes remain conditional and --no-pair opts out. Pins fail closed (`BLOCKED:<engine>-unavailable` / `BLOCKED:invalid-engine-config`); new engines plug in by shipping `_shared/adapters/<name>.md`. `/devlyn:engines` (no args) shows the role table + detected engines; `executor <name>` / `pair <name>,...` / `clear` manage the pins. The executor pin binds the orchestrator in plain conversation too, not only inside a skill run: when you would implement directly and executor is pinned to a non-default engine, route that work through the pin — via `/devlyn:resolve` (reads it at PHASE 0) or by delegating to that engine; no pin / no file → use the canonical skill's orchestrator-supported default. The pair-judge pin stays pipeline-scoped. `/devlyn:engines role` configures explicit engine/model/effort for supported worker and judge routes; `/devlyn:resolve --role-config <path>` overrides roles for one run. Canonical skills define precedence, evidence and unsupported-route errors; absent profiles preserve existing defaults.
 
-Conversational entry: Before writes, inspect requested files and relevant callers/tests. Default to direct execution only for clear, local, reversible, low-risk work with a decisive existing or small task-specific acceptance check. Preserve requested behavior, scope, explicit constraints and the executor pin; make scoped edits, run required checks, review the final diff, and report changes with evidence. One concise route/check explanation suffices; ordinary direct work needs no spec, pipeline state, phase workers or extra approval. For direct/full/queue work, the outer owner reads `references/task-completion.md` relative to the installed `devlyn:resolve` skill's directory: prospective task-branch ownership (linked worktree optional), scoped commit acceptance, then PR/merge and recoverable owned-resource cleanup after required archive/queue commits. Local-only/no-push wins; delivery pending/failure stays separate from product verification.
+Conversational entry: Before loading a workflow or writing files, inspect the requested change and relevant callers/tests. Quoted phase names, past logs and skill-file paths are context, not an instruction to invoke that workflow; follow the current user request. Default to direct execution when inspection makes the requested behavior, affected boundaries and verification tractable in the current context, including bounded multi-file work. Preserve requested behavior, scope, explicit constraints and the executor pin; make scoped edits, run required checks, review the final diff, and report changes with evidence. One concise route/check explanation suffices; ordinary direct work needs no spec, pipeline state, phase workers or extra approval. For direct/full/queue work, the outer owner reads `references/task-completion.md` relative to the installed `devlyn:resolve` skill's directory: prospective task-branch ownership (linked worktree optional), scoped commit acceptance, then PR/merge and recoverable owned-resource cleanup after required archive/queue commits. Local-only/no-push wins; delivery pending/failure stays separate from product verification.
 
-Use full `/devlyn:resolve` for material ambiguity, subsystem/design work, security/auth/payment/persistence/concurrency/public-API-contract changes, or inconclusive inspection/checks. Counts of lines, files or words alone do not establish low risk. Explicit resolve (even small), formal spec workflows and queue drains retain all canonical phases, independent verification, pins and failure handling. If new risk appears mid-edit, preserve the delta in the full run's scope/evidence; do not hide it in a new baseline or reconfirm existing authorization.
+Use full `/devlyn:resolve` automatically only when inspection identifies interacting requirements or verification work too complex to manage reliably in the current context, such as coupled durable state, concurrent ownership and failure recovery across boundaries. Name the concrete interaction or verification gap. Domain labels (security/auth/payment/persistence/concurrency/API), file count and a spec document alone do not trigger it. Investigate or clarify missing intent/access first; a pipeline cannot supply them. Direct work still requires risk-proportionate checks and independent review for consequential changes. Explicit resolve (even small), explicit spec-mode workflows and queue drains retain all canonical phases, independent verification, pins and failure handling. If the full-route condition emerges mid-edit, carry the existing delta into its scope/evidence; do not reset the baseline or reconfirm existing authorization.
 
-Full-route handoff + loop engineering: the orchestrating model — not the user — invokes the skills. `/devlyn:queue` fronts the intent queue (`docs/specs/queue.md`): no args = status, `add <intent>`, `drain` = serial unattended drain per the contract below. Large agreed work is written to `docs/specs/<id>/spec.md` (always a spec file — the user's reviewed contract; free-form large assumes-and-logs instead of halting, zero-scope-signal goals still halt to ideate), summarized once for user review, then run hands-free via `--spec`. Outer loop per task: before the first full run, commit the scoped queue-item delta (when applicable) and linked spec bundle; findings-backed verdicts (NEEDS_WORK, verify/build-gate exhaustion) get a committed spec amendment before re-run, max 3 iterations; infrastructure / invalid-input / engine-availability / implement-empty BLOCKED verdicts surface immediately. Unattended queue drain (`docs/specs/queue.md`, strictly serial): assumptions may only take scope-narrowing, reversible, non-user-visible defaults — material ambiguity marks the item `[F] needs-review`; commit every terminal `[x]` / `[F]` transition before advancing. The canonical commit order is `config/skills/devlyn:resolve/references/outer-loop.md`.
+Full-route handoff + loop engineering: the orchestrating model — not the user — invokes the skills. `/devlyn:queue` fronts the intent queue (`docs/specs/queue.md`): no args = status, `add <intent>`, `drain` = serial unattended drain per the contract below. Work selected for full resolve is written to `docs/specs/<id>/spec.md` (always a spec file — the user's reviewed contract; free-form large assumes-and-logs instead of halting, zero-scope-signal goals still halt to ideate), summarized once for user review, then run hands-free via `--spec`. Outer loop per task: before the first full run, commit the scoped queue-item delta (when applicable) and linked spec bundle; findings-backed verdicts (NEEDS_WORK, verify/build-gate exhaustion) get a committed spec amendment before re-run, max 3 iterations; infrastructure / invalid-input / engine-availability / implement-empty BLOCKED verdicts surface immediately. Unattended queue drain (`docs/specs/queue.md`, strictly serial): assumptions may only take scope-narrowing, reversible, non-user-visible defaults — material ambiguity marks the item `[F] needs-review`; commit every terminal `[x]` / `[F]` transition before advancing. The canonical commit order is `config/skills/devlyn:resolve/references/outer-loop.md`.
 
 ## Subtractive-First Editing
 

package/CLAUDE.md

@@ -1,6 +1,6 @@
 # Project Instructions
 
-devlyn-cli installs `/devlyn:ideate` (optional) and `/devlyn:resolve` (required) into Claude Code, plus the contract below. These principles are non-negotiable on every change — yours and any sub-agent's.
+devlyn-cli installs planning and full-pipeline skills alongside the execution contract below. These principles are non-negotiable on every change — yours and any sub-agent's.
 
 ## North Star
 
@@ -28,10 +28,10 @@ The runtime sub-agent contract below (Subtractive-first / Goal-locked / No-worka
 
 ## Quick Start
 
-Engine selection follows the role map below.
+Choose direct work or full resolve using the conversational-entry rules below; engine selection follows the role map.
 
 1. `/devlyn:ideate` (optional) — unstructured idea → `docs/specs/<id>/spec.md` + `spec.expected.json`. Modes: default Q&A, `--quick` (autonomous-pipeline-safe), `--from-spec <path>`, `--project`.
-2. `/devlyn:resolve` — hands-free pipeline for any coding task. Free-form goal, `--spec <path>`, or `--verify-only <diff> --spec <path>`. Phases: PLAN → IMPLEMENT → BUILD_GATE → CLEANUP → VERIFY (fresh subagent, findings-only).
+2. `/devlyn:resolve` — full pipeline for work selected by the conversational-entry rules below. Free-form goal, `--spec <path>`, or `--verify-only <diff> --spec <path>`. Phases: PLAN → IMPLEMENT → BUILD_GATE → CLEANUP → VERIFY (fresh subagent, findings-only).
 
 Each skill's `SKILL.md` is the source of truth for its flags and workflow — don't duplicate them here.
 
@@ -51,13 +51,13 @@ Each skill's `SKILL.md` is the source of truth for its flags and workflow — do
 
 ### Conversational entry + full-route handoff
 
-Before writes, inspect requested files and relevant callers/tests. Default to direct execution only for clear, local, reversible, low-risk work with a decisive existing or small task-specific acceptance check. Preserve requested behavior, scope, explicit constraints and the executor pin; make scoped edits, run required checks, review the final diff, and report changes with evidence. One concise route/check explanation suffices; ordinary direct work needs no spec, pipeline state, phase workers or extra approval. For direct/full/queue work, the outer owner reads `references/task-completion.md` relative to the installed `devlyn:resolve` skill's directory: prospective task-branch ownership (linked worktree optional), scoped commit acceptance, then PR/merge and recoverable owned-resource cleanup after required archive/queue commits. Local-only/no-push wins; delivery pending/failure stays separate from product verification.
+Before loading a workflow or writing files, inspect the requested change and relevant callers/tests. Quoted phase names, past logs and skill-file paths are context, not an instruction to invoke that workflow; follow the current user request. Default to direct execution when inspection makes the requested behavior, affected boundaries and verification tractable in the current context, including bounded multi-file work. Preserve requested behavior, scope, explicit constraints and the executor pin; make scoped edits, run required checks, review the final diff, and report changes with evidence. One concise route/check explanation suffices; ordinary direct work needs no spec, pipeline state, phase workers or extra approval. For direct/full/queue work, the outer owner reads `references/task-completion.md` relative to the installed `devlyn:resolve` skill's directory: prospective task-branch ownership (linked worktree optional), scoped commit acceptance, then PR/merge and recoverable owned-resource cleanup after required archive/queue commits. Local-only/no-push wins; delivery pending/failure stays separate from product verification.
 
-Use full `/devlyn:resolve` for material ambiguity, subsystem/design work, security/auth/payment/persistence/concurrency/public-API-contract changes, or inconclusive inspection/checks. Counts of lines, files or words alone do not establish low risk. Explicit resolve (even small), formal spec workflows and queue drains retain all canonical phases, independent verification, pins and failure handling. If new risk appears mid-edit, preserve the delta in the full run's scope/evidence; do not hide it in a new baseline or reconfirm existing authorization.
+Use full `/devlyn:resolve` automatically only when inspection identifies interacting requirements or verification work too complex to manage reliably in the current context, such as coupled durable state, concurrent ownership and failure recovery across boundaries. Name the concrete interaction or verification gap. Domain labels (security/auth/payment/persistence/concurrency/API), file count and a spec document alone do not trigger it. Investigate or clarify missing intent/access first; a pipeline cannot supply them. Direct work still requires risk-proportionate checks and independent review for consequential changes. Explicit resolve (even small), explicit spec-mode workflows and queue drains retain all canonical phases, independent verification, pins and failure handling. If the full-route condition emerges mid-edit, carry the existing delta into its scope/evidence; do not reset the baseline or reconfirm existing authorization.
 
-The user does not invoke skills manually; the orchestrating model does. Large tasks agreed in conversation:
+The user does not invoke skills manually; the orchestrating model does. For work selected for full resolve:
 
-1. Write the agreed contract to `docs/specs/<id>/spec.md` (+ `spec.expected.json` when mechanical verifications exist). Always a spec file for large work — a written spec is the user's reviewed contract; free-form large now assumes-and-logs instead of halting (zero-scope-signal goals still halt to ideate).
+1. Write the agreed contract to `docs/specs/<id>/spec.md` (+ `spec.expected.json` when mechanical verifications exist). Use a spec file for the selected work — a written spec is the user's reviewed contract; free-form large now assumes-and-logs instead of halting (zero-scope-signal goals still halt to ideate).
 2. Present a one-screen plan-contract summary — the user's single review checkpoint, BEFORE the pipeline starts.
 3. On go-ahead, commit the scoped queue-item delta (when applicable) and linked spec bundle, then invoke `/devlyn:resolve --spec <path>` hands-free to completion.
 4. **Per-task outer loop**: read the terminal verdict. Successful normal-run archive → outer-owner completion per the canonical task-completion reference, after any terminal queue commit. Verdicts backed by spec/verification findings (NEEDS_WORK, verify/build-gate exhaustion) → adjudicate the findings, amend the spec (recorded in the spec file; spec stays read-only inside a run), commit that scoped amendment, then re-invoke — at most 3 outer iterations, then surface with the findings trail. Infrastructure, invalid-input, engine-availability, and implement-empty BLOCKED verdicts are not spec-amendable: surface immediately. Every iteration re-enters through committed durable artifacts (spec, findings, run archive), never conversation memory.

package/README.md

@@ -31,12 +31,12 @@ That's it. The installer opens with a single **agent selector** — pick any com
 
 ---
 
-## How It Works — Two Skills, Full Cycle
+## How It Works — Direct Work or Full Pipeline
 
-devlyn-cli turns your AI coding agent into a hands-free development pipeline. The pipeline surface is two skills, with `/devlyn:design-ui` installed as the required creative UI surface:
+devlyn-cli supports direct execution for clear, low-risk work with decisive checks and a full pipeline for work that needs it. The pipeline surface is two skills, with `/devlyn:design-ui` installed as the required creative UI surface:
 
 ```
-ideate (optional)  →  resolve  →  ship
+inspect intent  →  direct work or full resolve  →  ship
 ```
 
 Non-Claude agents (Codex / omp / Pi / Grok): when one of these is selected, the workflows install as that agent's skills. In Codex / omp / Pi, use `$devlyn:ideate`, `$devlyn:resolve`, or `$devlyn:design-ui`; in Grok, use `/devlyn:ideate`, `/devlyn:resolve`, or `/devlyn:design-ui`, the same slash-command form as Claude Code.
@@ -60,9 +60,9 @@ Default mode produces a `docs/specs/<id>-<slug>/spec.md` plus `spec.expected.jso
 
 Skip ideate entirely if you have a spec or just want to describe the work — `/devlyn:resolve` accepts free-form goals too.
 
-### Step 2 — Resolve with `/devlyn:resolve`
+### Choose direct execution or `/devlyn:resolve`
 
-Before writes, inspect requested files and relevant callers/tests. Clear, local, reversible, low-risk conversational edits with a decisive acceptance check run directly, honoring scope, constraints and executor pins; finish required checks and diff review, then accept the scoped commit for owner completion below. Material ambiguity, subsystem/design work, security/auth/payment/persistence/concurrency/public-API-contract changes or no decisive check use full `/devlyn:resolve`. Explicit resolve (including small tasks), formal specs and queue drains keep the full workflow below. Pass a spec, a free-form goal, or a diff to verify.
+Inspect the requested behavior, affected callers and tests first. Default to direct work when its scope and verification are tractable, including bounded multi-file changes; honor constraints and executor pins, run risk-proportionate checks and independent review for consequential changes, then review the diff and deliver. Automatically use full `/devlyn:resolve` only for concrete interacting requirements or verification too complex to manage reliably in the current context, such as coupled durable state, concurrent ownership and failure recovery. Domain labels, file count and a spec document alone do not trigger it. Investigate or clarify missing intent/access first. Explicit resolve (including small tasks), explicit spec-mode workflows and queue drains keep the full workflow below.
 
 ```
 /devlyn:resolve "fix the login bug"                                # free-form
@@ -227,6 +227,21 @@ ids.
 
 ### Migration from earlier versions
 
+Reinstall with the new version to refresh instructions and skills for the selected
+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.
+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`.
+
 <!-- legacy-surface-map:begin — retired command names below are documented as OLD, not current; lint Check 10c skips this block -->
 Earlier versions of devlyn-cli shipped 16+ slash commands. The iter-0034 Phase 4 cutover (2026-05-04) and the 2026-05-14 follow-up consolidated them down to the three current commands. Upgrades automatically purge the legacy skill directories from `~/.claude/skills/`.
 

package/bin/devlyn.js

@@ -9,6 +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');
 
 // 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
@@ -700,20 +701,6 @@ function installSkillsForCLI(cliKey) {
   return copied;
 }
 
-// Strip the legacy "# Devlyn Agent Instructions" block (the retired evaluator
-// agent) that earlier installs appended to instruction files, so upgrades scrub
-// it instead of carrying it forever. Anchors on the LAST marker so user content
-// above a stray copy of the block is preserved.
-const DEVLYN_AGENTS_MARKER = '# Devlyn Agent Instructions';
-function stripManagedBlock(content) {
-  const markerIdx = content.lastIndexOf(DEVLYN_AGENTS_MARKER);
-  if (markerIdx > 0) {
-    const sepIdx = content.lastIndexOf('\n---', markerIdx);
-    return content.slice(0, sepIdx > 0 ? sepIdx : markerIdx).trimEnd();
-  }
-  return content.trimEnd();
-}
-
 // One-line description of exactly what selecting a CLI target installs, so the
 // unified selector stays honest.
 function targetDesc(cli) {
@@ -723,35 +710,10 @@ function targetDesc(cli) {
   return `${cli.instructionsFile} instructions only`;
 }
 
-// Install the packaged base instruction file for a CLI (project AGENTS.md for
-// codex/omp/pi). Creates it from the packaged base when missing; on existing
-// files, scrubs the legacy appended block and otherwise leaves user content
-// untouched. Returns true when the destination was written.
+// Shared instruction ownership and preservation rules apply to every CLI.
 function installInstructionsForCLI(cliKey) {
   const cli = CLI_TARGETS[cliKey];
-  if (!cli || !cli.baseInstructionsFile) return false;
-
-  const destFile = path.join(process.cwd(), cli.instructionsFile);
-  const baseInstructionsSrc = path.join(__dirname, '..', cli.baseInstructionsFile);
-  let content = null;
-  if (fs.existsSync(destFile)) {
-    const current = fs.readFileSync(destFile, 'utf8');
-    if (current.includes(DEVLYN_AGENTS_MARKER)) {
-      content = stripManagedBlock(current) + '\n';
-    } else {
-      log(`  → Preserved existing ${cli.instructionsFile}. Compare with the bundled template at ${baseInstructionsSrc} and merge relevant instructions.`, 'dim');
-    }
-  } else {
-    if (fs.existsSync(baseInstructionsSrc)) {
-      content = fs.readFileSync(baseInstructionsSrc, 'utf8');
-    }
-  }
-  if (content === null) return false;
-
-  log(`\n🤖 Installing instructions for ${cli.name}...`, 'cyan');
-  fs.writeFileSync(destFile, content);
-  log(`  → ${cli.instructionsFile}`, 'dim');
-  return true;
+  return cli?.baseInstructionsFile ? updateInstructions(cli.baseInstructionsFile) : false;
 }
 
 // Install both instructions and skills for a single CLI. Used by the
@@ -803,8 +765,9 @@ 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. Behavior is unchanged from the previous unconditional core install.
+// is chosen. Check instruction conflicts before changing settings or skills.
 function installClaudeCore() {
+  updateInstructions('CLAUDE.md');
   const targetDir = getTargetDir();
   const skillsDir = path.join(targetDir, 'skills');
   log('\n📁 Installing Claude Code config to .claude/', 'green');
@@ -831,15 +794,6 @@ function installClaudeCore() {
     log(`\n🧹 Cleaned up ${removed} deprecated file${removed > 1 ? 's' : ''}`, 'yellow');
   }
 
-  // Copy Claude project instructions to project root. Other CLI instruction
-  // files are installed only when explicitly selected below or via `agents`.
-  const claudeMdSrc = path.join(__dirname, '..', 'CLAUDE.md');
-  const claudeMdDest = path.join(process.cwd(), 'CLAUDE.md');
-  if (fs.existsSync(claudeMdSrc)) {
-    fs.copyFileSync(claudeMdSrc, claudeMdDest);
-    log('  → CLAUDE.md', 'dim');
-  }
-
   // Keep installer-managed pipeline state and install metadata out of git.
   const gitignorePath = path.join(process.cwd(), '.gitignore');
   const gitignoreEntries = ['.devlyn/', '.claude/skills/.devlyn-install.json'];
@@ -1314,10 +1268,14 @@ switch (command) {
       log('\n🤖 Installing agents for all supported CLIs...', 'blue');
       const count = installSelectedCLITargets(Object.keys(CLI_TARGETS));
       log(`\n✅ Agents installed for ${count} CLI${count !== 1 ? 's' : ''}`, 'green');
-    } else if (subArg && CLI_TARGETS[subArg]) {
+    } else if (Object.keys(CLI_TARGETS).includes(subArg)) {
       // Install for a specific CLI
       installAgentsForCLI(subArg);
       log('\n✅ Done!', 'green');
+    } else if (subArg !== undefined) {
+      log(`Unknown CLI target: ${JSON.stringify(subArg)}`, 'yellow');
+      log(`Supported: ${Object.keys(CLI_TARGETS).join(', ')}, all`, 'dim');
+      process.exit(1);
     } else {
       // Auto-detect and install
       const detected = detectOtherCLIs();

package/bin/instruction-templates.json

@@ -0,0 +1,52 @@
+{
+  "AGENTS.md": [
+    {
+      "versions": [
+        "3.0.0"
+      ],
+      "length": 11091,
+      "sha256": "099e68f3e203fa735bb1ebcd780a0e18bde462ea7de5f74fb3d17cee5e64b63a"
+    },
+    {
+      "versions": [
+        "3.0.1"
+      ],
+      "length": 12166,
+      "sha256": "33fbd5b01c8e65f4c663f95423a45b16dcf5bb28f1fd0c6791079abd20c267ae"
+    },
+    {
+      "versions": [
+        "3.1.0",
+        "3.1.1",
+        "3.1.2"
+      ],
+      "length": 12581,
+      "sha256": "acd3672efaa33e75455f8530a7425e950c01c822c6f5d85d7dbc9d7ff1958028"
+    }
+  ],
+  "CLAUDE.md": [
+    {
+      "versions": [
+        "3.0.0"
+      ],
+      "length": 24434,
+      "sha256": "29ddcc5ef4d5b44b2ba6aae22bd3c0c033ceaa47b240bd647aaefbe00f2a6e4e"
+    },
+    {
+      "versions": [
+        "3.0.1"
+      ],
+      "length": 25417,
+      "sha256": "50301bf98507c83da1576be7f443885236e7d421ff2e40fd077ed9652ea3a2e0"
+    },
+    {
+      "versions": [
+        "3.1.0",
+        "3.1.1",
+        "3.1.2"
+      ],
+      "length": 26152,
+      "sha256": "d11a863907dabdf827063df7133a8a46a14e018f608884f08c601bf36e0f3f0c"
+    }
+  ]
+}

package/bin/instructions.js

@@ -0,0 +1,137 @@
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const legacyTemplates = require('./instruction-templates.json');
+
+const BEGIN = '<!-- devlyn:instructions:begin';
+const END = '<!-- devlyn:instructions:end -->';
+const normalize = (text) => text.replace(/\r\n/g, '\n');
+const digest = (text) => crypto.createHash('sha256').update(text).digest('hex');
+
+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);
+}
+
+// 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 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++;
+      }
+      if (digest(normalize(text.slice(start, end))) === template.sha256
+          && !ranges.some((range) => range.start === start && range.end === end)) {
+        ranges.push({ start, end });
+      }
+    }
+  }
+  return ranges;
+}
+
+function retainFile(file, bytes) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  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.`);
+    }
+  } else {
+    fs.writeFileSync(file, bytes, { flag: 'wx', mode: 0o600 });
+  }
+}
+
+function updateInstructions(name) {
+  const templatePath = path.join(__dirname, '..', name);
+  const template = 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(process.cwd(), name);
+  const stat = fs.lstatSync(dest, { throwIfNoEntry: false });
+  const sourceStat = fs.statSync(templatePath);
+  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);
+  // 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.`);
+  }
+  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 });
+  }
+  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`);
+    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.`);
+  };
+  let content;
+  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 || digest(normalize(current.slice(bodyStart, end.index))) !== start[1]) {
+      return conflict('managed defaults were edited');
+    }
+    content = current.slice(0, start.index + (start[0].startsWith('\uFEFF') ? 1 : 0)) + block + current.slice(end.index + end[0].length);
+  } else {
+    const normalized = normalize(template);
+    const ranges = legacyRanges(current, [
+      { length: normalized.length, sha256: digest(normalized) },
+      ...(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);
+    } else {
+      if (/^devlyn-cli installs |^# Devlyn Agent Instructions\r?$|^This contract serves one goal: any capable engine|^Engine roles: orchestrator =/m.test(current)) {
+        return conflict('unrecognized or edited legacy template');
+      }
+      content = current + (current ? eol + eol : '') + block;
+    }
+  }
+  const bytes = Buffer.from(content);
+  if (bytes.equals(before)) return false;
+  if (exists) {
+    const backup = path.join(recovery, `${name}.${digest(before)}.backup`);
+    retainFile(backup, before);
+    console.log(`  → Saved previous ${name}: ${backup}`);
+  }
+  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 Error(`${name} changed during installation; preserved it. Rerun installation.`);
+    }
+    fs.renameSync(temp, dest);
+  } finally {
+    if (fs.existsSync(temp)) fs.unlinkSync(temp);
+  }
+  console.log(`  → Updated Devlyn defaults in ${name}; project-specific instructions preserved`);
+  return true;
+}
+
+module.exports = { updateInstructions };

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

@@ -55,7 +55,7 @@ python3 "$DEVLYN_SHARED_DIR/run-bounded.py" 600 --stdin-file "<judge-prompt-file
 
 ## Identity
 
-You are Claude by Anthropic. Anthropic's prompt-engineering guide for this model governs your behavior on top of the canonical phase prompt below. When the canonical body and this header conflict on tactics, the canonical body wins on what to deliver; this header wins on how to deliver it.
+You are Claude by Anthropic. Anthropic's prompt-engineering guide for this model governs your behavior on top of the canonical phase prompt below.
 
 ## Output discipline
 
@@ -73,10 +73,6 @@ When the canonical body lists tools, use them when their result would change you
 
 For long-horizon coding, review, and agentic runs, assume the harness selected `high` or `xhigh` effort unless told otherwise. Spend that depth on upfront task/constraint understanding and end-state verification, not on verbose narration. If the user or orchestrator gives a complete task in one turn, proceed autonomously instead of requiring progressive clarification.
 
-## Validation pattern
-
-When the canonical body asks you to verify your output before declaring done ("self-check" instructions), execute that step literally — re-read the spec's acceptance criteria, run the listed verification commands if available, list any gap. This is not optional. Mechanical gates owned by the harness (spec-verify-check.py, build-gate.py) are the primary correctness guard; your self-check is the secondary layer that catches what regex cannot.
-
 ## Anti-patterns
 
 You interpret instructions literally and explicitly. The official guide is explicit about three failure modes:

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

@@ -4,7 +4,7 @@
 
 ## Identity
 
-You are OpenAI's Codex model. OpenAI's prompt-guidance for this model governs your behavior on top of the canonical phase prompt below. When the canonical body and this header conflict on tactics, the canonical body wins on what to deliver; this header wins on how to deliver it.
+You are OpenAI's Codex model. OpenAI's prompt-guidance for this model governs your behavior on top of the canonical phase prompt below.
 
 ## Output discipline
 
@@ -19,10 +19,6 @@ canonical file and its `.agents` mirror are byte-identical, inspect the
 canonical file only. Open self-test bodies or MECHANICAL raw streams only for a
 named clause that remains unresolved after the broad pass.
 
-## Validation pattern
-
-Validation is concrete commands and tools, not self-belief. When the canonical body lists verification commands, execute them and trust their output. Do not substitute your judgment for a deterministic check the harness has provided. When validation tools are available (test runners, lint, type-check, the harness's `spec-verify-check.py`), run them before declaring success. The minimum evidence sufficient to answer correctly, cited precisely — then stop.
-
 ## Anti-patterns
 
 The official guide warns explicitly about carrying over instructions from older prompt stacks — earlier models needed more help, and process-heavy directives now narrow GPT-5.5's search space.

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

@@ -8,10 +8,6 @@ You are the model running behind the `omp` CLI. Follow the canonical phase promp
 
 Keep phase output machine-consumable and concise. Write the artifacts the canonical body names, update `.devlyn/pipeline.state.json` only where that phase owns the state write, and avoid narrative outside the required phase result.
 
-## Validation Pattern
-
-When the canonical body names deterministic commands, run those commands and trust their exit codes. Do not replace BUILD_GATE, phase gates, or VERIFY mechanical checks with same-context judgment.
-
 ## Fresh Context
 
 Each native `task` tool invocation with a fresh `context` is a fresh phase worker. Do not call `/devlyn:resolve` recursively from inside a phase prompt; execute only the phase body you received.

package/config/skills/_shared/expected.schema.json

@@ -147,13 +147,13 @@
     },
     "required_files": {
       "type": "array",
-      "description": "Files that must exist after the arm runs.",
+      "description": "Files specified by literal paths that must exist after the arm runs; globs are not expanded.",
       "items": { "type": "string", "minLength": 1 },
       "default": []
     },
     "forbidden_files": {
       "type": "array",
-      "description": "Files that must NOT appear in the arm's diff (e.g. tooling artifacts the spec didn't request).",
+      "description": "Exact Git-relative paths (forward slashes, no leading ./) that must NOT appear in the diff, including both rename names; globs and directory prefixes are not expanded.",
       "items": { "type": "string", "minLength": 1 },
       "default": []
     },

package/config/skills/_shared/platform-support.py

@@ -107,6 +107,7 @@ def system_exit_code(code):
 
 
 if os.name == "nt":
+    import _winapi
     import ctypes
     from ctypes import wintypes
     import msvcrt
@@ -226,7 +227,9 @@ if os.name == "nt":
                     try:
                         if self.child.poll() is None:
                             self.child.kill()
-                        self.child.wait(timeout=5)
+                        # kill() can cache an exit code before the native handle is signaled.
+                        if _winapi.WaitForSingleObject(self.child._handle, 5000) == _winapi.WAIT_TIMEOUT:
+                            raise subprocess.TimeoutExpired(self.child.args, 5)
                     finally:
                         self.child._handle.Close()
             finally:

package/config/skills/_shared/resolve-bootstrap.py

@@ -289,7 +289,7 @@ def init_spec_source(
             block("BLOCKED:invalid-flags", error or f"expected contract not found: {expected}")
     else:
         run_checked([sys.executable, str(helper), "--check", str(path)], cwd)
-        _staged, error = module.stage_from_source(path, staging_dir)
+        _found, _staged, error = module.stage_from_source(path, staging_dir)
         if error:
             block("BLOCKED:invalid-flags", error)
     staged_path = staging_dir / "spec-verify.json"
@@ -333,7 +333,7 @@ def capture_external_diff(cwd: pathlib.Path, ref: str) -> bytes:
     if source.is_file():
         raw = source.read_bytes()
     else:
-        proc = subprocess.run(["git", "diff", "--binary", ref], cwd=cwd, capture_output=True)
+        proc = subprocess.run(["git", "diff", "--binary", "--no-ext-diff", "--src-prefix=a/", "--dst-prefix=b/", ref], cwd=cwd, capture_output=True)
         if proc.returncode != 0:
             block("BLOCKED:invalid-flags", os.fsdecode(proc.stderr or proc.stdout).strip())
         raw = proc.stdout
@@ -1184,6 +1184,16 @@ def self_test() -> int:
         staged = strict_json((work / ".devlyn" / "spec-verify.json").read_text(encoding="utf-8"))
         assert staged["verification_commands"][0]["cmd"] == "printf ok"
         assert spec_result["source"]["spec_sha256"] == sha256(spec_raw)
+        pure_spec = spec_dir / "design.md"
+        pure_spec.write_text(
+            "# Design\n\n<!-- devlyn:verification -->\n## Verification\n\n"
+            '```json\n{"pure_design":true,"verification_commands":[]}\n```\n',
+            encoding="utf-8",
+        )
+        complete_prior(work)
+        pure_result = bootstrap(["--spec", str(pure_spec.relative_to(work))], work, script_shared)
+        assert pure_result["source"]["spec_sha256"] == sha256(pure_spec.read_bytes())
+        assert not (work / ".devlyn/spec-verify.json").exists()
         external_patch.write_bytes(b"stale free-form patch\n")
         complete_prior(work)
         bootstrap(["fresh", "goal"], work, script_shared)
@@ -1205,6 +1215,16 @@ def self_test() -> int:
         assert verify_result["mode"] == "verify-only"
         assert external_patch.read_bytes() == patch_raw
         subprocess.run(["git", "restore", "app.py"], cwd=work, check=True)
+        # Ambient no-prefix config must not change the reader's a/b contract.
+        (work / "app.py").write_text("print('prefix control')\n", encoding="utf-8")
+        settings = ["diff.noprefix"] + (["diff.external"] if os.name != "nt" else [])
+        for setting in settings:
+            subprocess.run(["git", "config", setting, "true"], cwd=work, check=True)
+            try:
+                assert b"diff --git a/app.py b/app.py\n" in capture_external_diff(work, "HEAD")
+            finally:
+                subprocess.run(["git", "config", "--unset", setting], cwd=work, check=True)
+        subprocess.run(["git", "restore", "app.py"], cwd=work, check=True)
         print("PASS bootstrap self-test patch lifecycle: full-mode removal + dirty verify-only exact capture")
 
         for valid_named in (True, False):