devlyn-cli 4.2.20 → 4.2.22

package/README.md

@@ -35,7 +35,7 @@ That's it. The installer asks:
 
 In a project, AGENTS.md readers load the skills from `.agents/skills/`; Claude Code loads only `.claude/skills/` and reads AGENTS.md when the project has no CLAUDE.md; a CLAUDE.md the installer creates imports an existing AGENTS.md (`@AGENTS.md`). Global installs skills only: `~/.agents/skills/` (omp, Pi, Grok) and `~/.codex/skills/` (Codex), plus `~/.claude/skills/` for Claude Code. Every target gets the `devlyn-ideate` skill and the `devlyn-engines` utility. In Codex / omp / Pi, invoke them as skills (`$devlyn-ideate`); in Claude Code and Grok they're slash commands (`/devlyn-ideate`). Rerunning refreshes skills and the managed instruction block while preserving project rules outside it. See [Migration from earlier versions](#migration-from-earlier-versions) for legacy migration and merge recovery.
 
-Without prompts, `npx devlyn-cli -y` installs AGENTS.md + `.agents/skills/` plus every target this project already has; add `--claude` for Claude Code. With `--global` it installs for every project on this machine, plus `~/.claude/skills/` with `--claude` or when it already has a devlyn install. After a project install or update, the installer names the changed files to commit, including installed files a `.gitignore` hides, so teammates and `/devlyn-ideate` drains can use them.
+Without prompts, `npx devlyn-cli -y` installs AGENTS.md + `.agents/skills/` plus every target this project already has; add `--claude` for Claude Code. With `--global` it installs for every project on this machine, plus `~/.claude/skills/` with `--claude` or when it already has a devlyn install. The installer leaves Git to you: it prints no commit guidance after a project install or update. When Git ignores some, but not all, files of an installed skill folder, it prints one line with their count and an example ignore rule.
 
 `npx devlyn-cli update` — Update every devlyn install already here (this project and your global skill folders) to this version; installs nothing new.
 
@@ -62,7 +62,7 @@ Give ideate an intent or a document. It writes a loop package — a meta-prompt
 | `/devlyn-ideate status` | Pending, active, accepted and failed counts; the next runnable task; delivery and recovery blockers. |
 | `/devlyn-ideate drain` | Runs the queue serially and hands-free. |
 
-A bare intent is planned and, when your request authorizes the work, added and drained without another confirmation; no arguments shows status. Questions come only when the answer changes behavior, scope, data semantics, acceptance or delivery, each with a recommended answer; `--autonomous` plans without questions, recording ordinary low-consequence, reversible defaults within the request, including user-visible details; material ambiguity in intended outcomes, persistent data or state semantics, or public surface beyond the request stops planning with a concrete question. Each task runs in its own worktree with the executor pinned by `/devlyn-engines` (default: the CLI you opened; Pi and Grok need a pin) under your installed CLAUDE.md/AGENTS.md instructions. Tasks start from committed state, the branch you added the loop on or the remote base for `auto`/`pr`, so commit the installer's changes and whatever a plan depends on before adding a loop, and push them for `auto`/`pr`. It is marked `[x]` only when its declared checks pass on its committed source and its required reviews cover it: the checks run through the drain's runner (a wholly clean run the executor lists for that source is reused; the drain runs any other check itself), and review coverage is attested by records the executor submits; a failed task becomes `[F]` with its reason and blocks only its dependents. An interrupted drain resumes without repeating accepted work. `--local-only` (or `--no-push`) keeps delivery local: each accepted task stays on its `devlyn/<loop-id>/<task-id>` branch in a retained worktree, nothing is merged or pushed, and the drain report's `Bring into` command is `git merge --ff <latest accepted task branch>`.
+A bare intent is planned and, when your request authorizes the work, added and drained without another confirmation; no arguments shows status. Questions come only when the answer changes behavior, scope, data semantics, acceptance or delivery, each with a recommended answer; `--autonomous` plans without questions, recording ordinary low-consequence, reversible defaults within the request, including user-visible details; material ambiguity in intended outcomes, persistent data or state semantics, or public surface beyond the request stops planning with a concrete question. Each task runs in its own worktree with the executor pinned by `/devlyn-engines` (default: the CLI you opened; Pi and Grok need a pin) under your installed CLAUDE.md/AGENTS.md instructions. Tasks start from committed state, the branch you added the loop on or the remote base for `auto`/`pr`, so a task's worktree holds only what is committed there. A task would run without installed CLAUDE.md/AGENTS.md that exist only in this checkout, so add stops while they differ from HEAD, and drain waits while they differ from the task's start commit. It is marked `[x]` only when its declared checks pass on its committed source and its required reviews cover it: the checks run through the drain's runner (a wholly clean run the executor lists for that source is reused; the drain runs any other check itself), and review coverage is attested by records the executor submits; a failed task becomes `[F]` with its reason and blocks only its dependents. An interrupted drain resumes without repeating accepted work. `--local-only` (or `--no-push`) keeps delivery local: each accepted task stays on its `devlyn/<loop-id>/<task-id>` branch in a retained worktree, nothing is merged or pushed, and the drain report's `Bring into` command is `git merge --ff <latest accepted task branch>`.
 
 ### Delivery
 

package/bin/devlyn.js

@@ -357,17 +357,16 @@ function listContents() {
 // are in place. An optional skill found under an old spelling is installed under its new name
 // before the old copy goes, so an interrupted migration never loses it. An unedited 0.6.0-0.7.1
 // copy is refreshed in place. Any other folder under a 4.0 name is the user's own; `-y` leaves it.
-function refreshRenamedSkills(skillsDir, written, installedSkills) {
+function refreshRenamedSkills(skillsDir, installedSkills) {
   const optional = new Set(OPTIONAL_ADDONS.filter((addon) => addon.type === 'local').map((addon) => addon.name));
   const refreshed = [];
   for (const [oldName, newName] of Object.entries(RENAMED_SKILLS)) {
     const found = legacySkillPaths(skillsDir, oldName).filter((fullPath) => fs.existsSync(fullPath));
     if (found.length > 0 && optional.has(newName) && canRefreshRenamed(skillsDir, newName)) {
-      installOptionalSkillInto(skillsDir, newName, written, installedSkills);
+      installOptionalSkillInto(skillsDir, newName, installedSkills);
       refreshed.push(newName);
     } else if (isShippedCopy(path.join(skillsDir, newName), PRE_STANDARD_SKILL_MD_SHA256)) {
       refreshPreStandardCopy(skillsDir, newName);
-      written.push(path.join(skillsDir, newName));
       installedSkills.set(path.join(skillsDir, newName), [path.join(skillsDir, newName, 'SKILL.md')]);
       refreshed.push(newName);
     }
@@ -609,23 +608,22 @@ function singleSelect(message, items, initial) {
 }
 
 // After preflight has cleared every selected addon before any change.
-function installLocalSkill(skillName, roots, written = [], installedSkills = new Map()) {
+function installLocalSkill(skillName, roots, installedSkills = new Map()) {
   if (!fs.existsSync(path.join(OPTIONAL_SKILLS_SOURCE, skillName))) {
     log(`   ⚠️  Skill "${skillName}" not found`, 'yellow');
     return false;
   }
   log(`\n🛠️  Installing ${skillName}...`, 'cyan');
   for (const root of roots) {
-    installOptionalSkillInto(root, skillName, written, installedSkills);
+    installOptionalSkillInto(root, skillName, installedSkills);
     writeInstallMarker(root, [skillName], readInstallManifest(root));
-    written.push(path.join(root, DEVLYN_INSTALL_MARKER));
   }
   return true;
 }
 
 // One optional skill into one skill-loader directory, replacing any older copy of it. A
 // copy under its name before the 4.0.0 rename goes only once the new one is complete.
-function installOptionalSkillInto(target, skillName, written, installedSkills) {
+function installOptionalSkillInto(target, skillName, installedSkills) {
   const dest = path.join(target, skillName);
   const stage = fs.mkdtempSync(path.join(target, '.devlyn-skill-'));
   const stagedSkill = path.join(stage, skillName);
@@ -635,7 +633,6 @@ function installOptionalSkillInto(target, skillName, written, installedSkills) {
     fs.rmSync(dest, { recursive: true, force: true });
     fs.renameSync(stagedSkill, dest);
     installedSkills.set(dest, files.map((file) => path.join(dest, path.relative(stagedSkill, file))));
-    written.push(dest);
   } finally {
     fs.rmSync(stage, { recursive: true, force: true });
   }
@@ -693,7 +690,7 @@ function installAddon(addon) {
 
 // The core skills into one skill root, replacing older copies and retired skills, then the
 // marker that records a complete install.
-function installCoreSkills(skillsDir, written = [], installedSkills = new Map()) {
+function installCoreSkills(skillsDir, installedSkills = new Map()) {
   const sourceSkillsDir = path.join(CONFIG_SOURCE, 'skills');
   log(`\n📁 Installing devlyn skills to ${skillsDir.replace(os.homedir(), '~')}`, 'green');
   fs.mkdirSync(skillsDir, { recursive: true });
@@ -706,12 +703,10 @@ function installCoreSkills(skillsDir, written = [], installedSkills = new Map())
     // Full replace: copyRecursive is an overlay, so stale files would otherwise persist.
     fs.rmSync(dest, { recursive: true, force: true });
     installedSkills.set(dest, copyRecursive(src, dest, skillsDir));
-    written.push(dest);
   }
   assertCompleteSkillInstall(sourceSkillsDir, skillsDir, DEVLYN_CORE_SKILLS);
-  const refreshed = refreshRenamedSkills(skillsDir, written, installedSkills);
+  const refreshed = refreshRenamedSkills(skillsDir, installedSkills);
   writeInstallMarker(skillsDir, [...DEVLYN_CORE_SKILLS, ...refreshed], previous);
-  written.push(path.join(skillsDir, DEVLYN_INSTALL_MARKER));
 }
 
 function readProjectGitignore() {
@@ -763,9 +758,7 @@ function updateProjectGitignore(markerEntry) {
   if (!gitignoreContent.equals(original)) {
     fs.writeFileSync(gitignorePath, gitignoreContent);
     log('  → .gitignore (updated project install rules)', 'dim');
-    return true;
   }
-  return false;
 }
 
 // With the Claude target in the same run, an AGENTS.md that links to this project's CLAUDE.md (a
@@ -786,18 +779,16 @@ function agentsMdIsClaudeMd() {
 }
 
 function installAgentsProject(withClaude, installedSkills = new Map()) {
-  const written = [];
   if (!agentsMdIsClaudeMd()) {
-    if (updateInstructions('AGENTS.md')) written.push('AGENTS.md');
+    updateInstructions('AGENTS.md');
   } else if (withClaude) {
     log('  → AGENTS.md is CLAUDE.md here, so it gets the devlyn block written there', 'dim');
   } else {
     throw new InstructionError('AGENTS.md is CLAUDE.md under another name here. Choose CLAUDE.md as well '
       + '(npx devlyn-cli -y --claude) so the devlyn block is written once, into CLAUDE.md.');
   }
-  installCoreSkills(skillRoots('agents', false)[0], written, installedSkills);
-  if (updateProjectGitignore('.agents/skills/.devlyn-install.json')) written.push('.gitignore');
-  return written;
+  installCoreSkills(skillRoots('agents', false)[0], installedSkills);
+  updateProjectGitignore('.agents/skills/.devlyn-install.json');
 }
 
 // Whether Claude Code reads the devlyn defaults of AGENTS.md through an `@AGENTS.md` import in this CLAUDE.md text.
@@ -821,9 +812,8 @@ function installClaudeInstructions() {
     throw new InstructionError('Claude Code reads AGENTS.md here, and its devlyn defaults need an update. Codex, omp, Pi and Grok '
       + 'read them too, with .agents/skills, so choose AGENTS.md as well (npx devlyn-cli -y --claude) to update both together.');
   }
-  const changed = updateInstructions('CLAUDE.md', initial, !imported);
+  updateInstructions('CLAUDE.md', initial, !imported);
   if (imported) log('  → CLAUDE.md imports AGENTS.md, which holds the devlyn block', 'dim');
-  return changed;
 }
 
 // Project CLAUDE.md and .claude/: skills and settings.
@@ -852,9 +842,9 @@ function installClaudeCore(installedSkills = new Map()) {
       && (!settings.env || typeof settings.env !== 'object' || Array.isArray(settings.env))) {
     throw unmergeable('env must be a JSON object');
   }
-  const written = installClaudeInstructions() ? ['CLAUDE.md'] : [];
-  installCoreSkills(skillsDir, written, installedSkills);
-  if (updateProjectGitignore('.claude/skills/.devlyn-install.json')) written.push('.gitignore');
+  installClaudeInstructions();
+  installCoreSkills(skillsDir, installedSkills);
+  updateProjectGitignore('.claude/skills/.devlyn-install.json');
 
   // One-hour foreground Bash calls and one-hour prompt caching serve a drain host that waits in the foreground.
   let settingsChanged = false;
@@ -874,7 +864,6 @@ function installClaudeCore(installedSkills = new Map()) {
   if (settingsChanged) {
     replaceFile(settingsPath, JSON.stringify(settings, null, 2) + '\n');
     log('  → settings.json', 'dim');
-    written.push('.claude/settings.json');
   }
   // Their ownership cannot be established, so the other retired settings stay; name the ones present.
   const retired = [
@@ -884,7 +873,6 @@ function installClaudeCore(installedSkills = new Map()) {
   if (retired.length > 0) {
     log(`  Retired devlyn settings may remain in .claude/settings.json: ${retired.join(', ')} — delete those you did not add yourself.`, 'yellow');
   }
-  return written;
 }
 
 // Replace this directory entry, never a hardlink's other names.
@@ -991,7 +979,7 @@ function withUserSkillLocks(roots, action, { existingOnly = false } = {}) {
   }
 }
 
-// Installs the targets in one scope; returns the skill roots written.
+// Installs the targets in one scope; returns the installed skill roots.
 function install(targets, global, optionalNames = [], plan, afterInstall = () => {}) {
   // In the home folder CLAUDE.md, AGENTS.md (agents read a parent folder's too) and
   // .claude/settings.json would apply to every project. Same folder by identity, so a link or
@@ -1004,30 +992,29 @@ function install(targets, global, optionalNames = [], plan, afterInstall = () =>
   }
   const roots = targets.flatMap((target) => skillRoots(target, global));
   return withUserSkillLocks(global ? roots : [], () => {
-    const written = [];
     const installedSkills = new Map();
     if (!global) readProjectGitignore();
     plan ??= preflightSkills(roots, optionalNames);
     // AGENTS.md first, whatever order the menu gave: a new CLAUDE.md holds the block only when AGENTS.md does not.
     for (const target of ['agents', 'claude'].filter((name) => targets.includes(name))) {
-      if (global) skillRoots(target, true).forEach((root) => installCoreSkills(root, [], installedSkills));
-      else if (target === 'agents') written.push(...installAgentsProject(targets.includes('claude'), installedSkills));
-      else written.push(...installClaudeCore(installedSkills));
+      if (global) skillRoots(target, true).forEach((root) => installCoreSkills(root, installedSkills));
+      else if (target === 'agents') installAgentsProject(targets.includes('claude'), installedSkills);
+      else installClaudeCore(installedSkills);
     }
-    for (const name of optionalNames) installLocalSkill(name, roots, written, installedSkills);
+    for (const name of optionalNames) installLocalSkill(name, roots, installedSkills);
     afterInstall();
     log(`\n✅ devlyn ${PKG.version} installed`, 'green');
     if (global) log('The principles block installs per project: run npx devlyn-cli in the project without --global.');
     noticeGlobalDrift(roots);
-    cleanupScope(global ? os.homedir() : projectDir(), global, written,
+    cleanupScope(global ? os.homedir() : projectDir(), global,
       global ? [] : targets.map((target) => target === 'agents' ? 'AGENTS.md' : 'CLAUDE.md'));
-    if (!global) noticeProjectChanges(written, installedSkills);
+    if (!global) noticeIgnoredInstallFiles(installedSkills);
     return roots;
   });
 }
 
 // Cleanup visits existing paths in the command's scope; it never creates an install.
-function cleanupScope(base, global, written, activeInstructions = []) {
+function cleanupScope(base, global, activeInstructions = []) {
   const warned = new Set();
   let found = false;
   const warning = (file, error) => {
@@ -1051,7 +1038,6 @@ function cleanupScope(base, global, written, activeInstructions = []) {
     if (!realParents(file) || !fs.lstatSync(file, { throwIfNoEntry: false })) return false;
     found = true;
     fs.rmSync(file, { recursive: true }); // lstat/realParents never follows a link; rm removes the link itself.
-    written.push(file);
     log(`  ✕ ${path.relative(base, file)} (removed)`, 'dim');
     return true;
   });
@@ -1103,7 +1089,6 @@ function cleanupScope(base, global, written, activeInstructions = []) {
             const data = JSON.parse(fs.readFileSync(marker, 'utf8'));
             for (const name of removed) delete data.skills[name];
             replaceFile(marker, JSON.stringify(data, null, 2) + '\n');
-            written.push(marker);
           });
         }
       };
@@ -1132,7 +1117,6 @@ function cleanupScope(base, global, written, activeInstructions = []) {
     if (settings && typeof settings === 'object' && cleanRetiredSettings(settings)) {
       found = true;
       replaceFile(settingsFile, JSON.stringify(settings, null, 2) + '\n');
-      written.push(settingsFile);
       log('  ✕ .claude/settings.json retired entries (removed)', 'dim');
     }
   });
@@ -1144,75 +1128,34 @@ function cleanupScope(base, global, written, activeInstructions = []) {
       const evaluatorOnly = ['CLAUDE.md', 'AGENTS.md'].includes(name);
       if (!updateInstructions(name, '', false, false, base, evaluatorOnly)) return;
       found = true;
-      if (updateInstructions(name, '', false, true, base, evaluatorOnly)) written.push(file);
+      updateInstructions(name, '', false, true, base, evaluatorOnly);
     });
   }
   return found;
 }
 
-// Advisory only: a successful install stays successful when Git is unavailable or fails.
-function noticeProjectChanges(paths, installedSkills = new Map()) {
-  if (!paths.length && !installedSkills.size) return;
+// Advisory only: check files this run copied, grouped by skill; a wholly ignored skill
+// folder is deliberate. check-ignore omits tracked files, and Git failures stay silent.
+function noticeIgnoredInstallFiles(installedSkills) {
   const cwd = projectDir();
-  const relative = (name) => path.relative(cwd, path.resolve(cwd, name)).split(path.sep).join('/');
-  paths = [...new Set(paths.map(relative))];
+  const groups = [...installedSkills.values()].map((files) =>
+    files.map((file) => path.relative(cwd, file).split(path.sep).join('/')));
+  const files = groups.flat();
+  if (!files.length) return;
   const env = { ...gitEnvironment(), GIT_OPTIONAL_LOCKS: '0' };
   const git = (args, input) => spawnSync('git', ['-C', cwd, ...args], { encoding: 'utf8', env, input });
-  const repo = git(['rev-parse', '--show-toplevel']);
-  if (repo.error || repo.status !== 0) return;
-  const status = git(['status', '--porcelain=v1', '-z', '--untracked-files=all', '--no-renames',
-    '--', ...paths.map((name) => `:(icase,literal)${name}`)]);
-  if (status.error || status.status !== 0) return;
-  // Porcelain paths are repository-relative, even when installing in a nested project.
-  const changed = status.stdout.split('\0').filter(Boolean).map((entry) =>
-    path.relative(cwd, path.resolve(repo.stdout.replace(/\r?\n$/, ''), entry.slice(3))).split(path.sep).join('/'));
-  // Keep the installed folder/file scope, using Git's spelling on case-insensitive volumes.
-  const pending = [...new Set(paths.flatMap((name) => [...new Set(changed
-    .map((file) => file.split('/').slice(0, name.split('/').length).join('/')))]
-    .filter((file) => {
-      if (file === name) return true;
-      if (file.toLowerCase() !== name.toLowerCase()) return false;
-      // Case folding alone can include independently edited files on case-sensitive volumes.
-      // Removed paths have no identity left to compare, so require their exact spelling.
-      try {
-        const written = fs.lstatSync(path.resolve(cwd, name), { bigint: true, throwIfNoEntry: false });
-        const reported = fs.lstatSync(path.resolve(cwd, file), { bigint: true, throwIfNoEntry: false });
-        return written && reported && written.dev === reported.dev && written.ino === reported.ino;
-      } catch (error) {
-        log(`Cannot compare Git path ${file} with installed path ${name}: ${error.message}`, 'yellow');
-        return false;
-      }
-    })))];
-  // Check only files this run copied, grouped by skill: ignoring a whole skill is deliberate.
-  // check-ignore omits tracked files, so a complete committed install stays quiet on reruns.
-  const groups = [...installedSkills.values()].map((files) => files.map(relative));
-  const files = groups.flat();
-  let ignored = [];
-  let rule;
-  if (files.length) {
-    const result = git(['check-ignore', '-z', '--stdin'], files.join('\0') + '\0');
-    if (result.error || ![0, 1].includes(result.status)) return;
-    const matches = new Set(result.stdout.split('\0').filter(Boolean));
-    ignored = [...new Set(groups.flatMap((group) => {
-      const hidden = group.filter((file) => matches.has(file));
-      return hidden.length === group.length ? [] : hidden;
-    }))];
-    if (ignored.length) {
-      const verbose = git(['check-ignore', '-v', '-z', '--stdin'], ignored[0] + '\0');
-      if (verbose.error || verbose.status !== 0) return;
-      const [source, line, pattern] = verbose.stdout.split('\0');
-      rule = `${source}:${line}: ${pattern}`;
-    }
-  }
-  if (!pending.length && !ignored.length) return;
-  const quote = (name) => /^[a-zA-Z0-9_./-]+$/.test(name) ? name : `'${name.replace(/'/g, "'\\''")}'`;
-  log('Optional — commit (and push) these changes if teammates or /devlyn-ideate task worktrees should use them:', 'yellow');
-  if (ignored.length) log(`.gitignore hides ${ignored.length} installed files (${rule}).`, 'yellow');
-  const commands = [];
-  if (pending.length) commands.push(`git add -- ${pending.map(quote).join(' ')}`);
-  if (ignored.length) commands.push(`git add -f -- ${ignored.map(quote).join(' ')}`);
-  commands.push(`git commit -m "chore(devlyn): update devlyn-cli to ${PKG.version}"`);
-  log(`  ${commands.join(' && ')}`, 'dim');
+  const result = git(['check-ignore', '-z', '--stdin'], files.join('\0') + '\0');
+  if (result.error || ![0, 1].includes(result.status)) return;
+  const matches = new Set(result.stdout.split('\0').filter(Boolean));
+  const ignored = [...new Set(groups.flatMap((group) => {
+    const hidden = group.filter((file) => matches.has(file));
+    return hidden.length === group.length ? [] : hidden;
+  }))];
+  if (!ignored.length) return;
+  const verbose = git(['check-ignore', '-v', '-z', '--stdin'], ignored[0] + '\0');
+  if (verbose.error || verbose.status !== 0) return;
+  const [source, line, pattern] = verbose.stdout.split('\0');
+  log(`Git ignores ${ignored.length} installed file${ignored.length === 1 ? '' : 's'} (example rule: ${source}:${line}: ${pattern}).`, 'dim');
 }
 
 // A devlyn install in a user root this run does not refresh drifts and can shadow the
@@ -1235,8 +1178,7 @@ function noticeGlobalDrift(installed) {
 }
 
 // Skip project setup in the home folder, where instructions would affect every project.
-// Lock user roots, preflight all roots, check versions, then write; user roots go first
-// so the project's commit guidance remains the last output.
+// Lock user roots, preflight all roots, check versions, then write.
 function update() {
   showLogo();
   log('─'.repeat(44), 'dim');
@@ -1273,10 +1215,9 @@ function update() {
   const projectRoots = targets.flatMap((target) => skillRoots(target, false));
   const roots = [...userRoots, ...projectRoots];
   if (!roots.length) {
-    const written = [];
-    const userCleanup = cleanupScope(os.homedir(), true, written);
-    const projectCleanup = (home?.dev !== here.dev || home?.ino !== here.ino) && cleanupScope(projectDir(), false, written);
-    if (userCleanup || projectCleanup) { noticeProjectChanges(written.filter((file) => !path.isAbsolute(file) || file.startsWith(projectDir() + path.sep))); return; }
+    const userCleanup = cleanupScope(os.homedir(), true);
+    const projectCleanup = (home?.dev !== here.dev || home?.ino !== here.ino) && cleanupScope(projectDir(), false);
+    if (userCleanup || projectCleanup) return;
     throw new InstructionError(['No devlyn install here to update. Run npx devlyn-cli to install.', ...linkNotices].join('\n'));
   }
 
@@ -1305,17 +1246,15 @@ function update() {
         + newer.join('\n') + '\nRun npx devlyn-cli@latest update.');
     }
 
-    userRoots.forEach((root) => installCoreSkills(root, [], new Map()));
-    if (targets.length) install(targets, false, [], plan, () => cleanupScope(os.homedir(), true, []));
+    userRoots.forEach((root) => installCoreSkills(root));
+    if (targets.length) install(targets, false, [], plan, () => cleanupScope(os.homedir(), true));
     else {
-      cleanupScope(os.homedir(), true, []);
+      cleanupScope(os.homedir(), true);
       log(`\n✅ devlyn ${PKG.version} installed`, 'green');
       noticeGlobalDrift(userRoots);
     }
     if (!targets.length && (home?.dev !== here.dev || home?.ino !== here.ino)) {
-      const written = [];
-      cleanupScope(projectDir(), false, written);
-      noticeProjectChanges(written);
+      cleanupScope(projectDir(), false);
     }
   });
 }

package/bin/skill-history.json

@@ -100,6 +100,7 @@
       "978e4210e49b42827c98cf6e40c868c87dc6e3533a2b779ca2fa05abfc16ad0f",
       "9815b6e6963e068872a6dbeae24068143bf92042bb035f67bafd1a224d65bcb0",
       "998343c148618b937556b58b83749c05d5aa3283280d751c118da6a542fb87f2",
+      "9dd3ec225818efe0ad3726192db94ff129154e995617a9d3c150fc58ad0f9f2c",
       "9f14ca629e41730b1a9fb5d0ad1a39cff558fe34758d6ceccbb9de498f9f384e",
       "a11950a5880346f03257c688fd8bc6f8c29fc0b7c05c90e8f5211d5fb7665774",
       "a405a99b988f6edd2eabb0504b36309bb4cf0c3b97eab26bb7ef257e4515dbf3",

package/config/skills/_shared/task-complete.py

@@ -21,6 +21,7 @@ import stat
 import subprocess
 import sys
 import tempfile
+import time
 import unittest
 import uuid
 
@@ -789,11 +790,35 @@ def complete(args):
             require(remote_head(receipt, receipt["branch"]) == receipt["publish_sha"], "remote head race before merge")
             refused = None
             if not pr.get("autoMergeRequest"):
-                try:
-                    require(info["mergeCommitAllowed"], "repository disallows merge commits")
-                    gh(receipt, "pr", "merge", str(pr["number"]), "--auto", "--merge", "--match-head-commit", receipt["publish_sha"])
-                except CompletionError as error:
-                    refused = str(error)
+                if not info["mergeCommitAllowed"]:
+                    refused = "repository disallows merge commits"
+                else:
+                    owner, name = receipt["repository"].split("/")
+                    auto_allowed = json.loads(command([
+                        "gh", "api", "graphql", "--hostname", "github.com", "-f",
+                        "query=query($owner:String!,$name:String!){repository(owner:$owner,name:$name){autoMergeAllowed}}",
+                        "-f", "owner="+owner, "-f", "name="+name,
+                        "--jq", ".data.repository.autoMergeAllowed | tojson",
+                    ]))
+                    require(isinstance(auto_allowed, bool), "repository autoMergeAllowed must be a JSON boolean")
+                    auto = ["--auto"] if auto_allowed else []
+                    if not auto:
+                        # UNKNOWN can reach gh's direct merge mutation; wait for a
+                        # resolved state and permit only gh's immediate-merge set.
+                        for attempt in range(10):
+                            state = json.loads(gh(receipt, "pr", "view", str(pr["number"]), "--json", "mergeStateStatus"))["mergeStateStatus"]
+                            require(isinstance(state, str) and state, "invalid mergeStateStatus")
+                            if state != "UNKNOWN":
+                                break
+                            if attempt < 9:
+                                time.sleep(2)
+                        if state not in {"CLEAN", "HAS_HOOKS", "UNSTABLE"}:
+                            refused = "pull request is not mergeable: " + state
+                    if not refused:
+                        try:
+                            gh(receipt, "pr", "merge", str(pr["number"]), *auto, "--merge", "--match-head-commit", receipt["publish_sha"])
+                        except CompletionError as error:
+                            refused = str(error)
             pr = json.loads(gh(receipt, "pr", "view", str(pr["number"]), "--json", PR_FIELDS))
             validate_pr(receipt, pr)
             if pr["state"] != "MERGED":
@@ -885,6 +910,16 @@ def remote(ref):
 if a[:2] == ['repo', 'view']:
     assert a[2:] == ['github.com/test/project', '--json', 'nameWithOwner,url,defaultBranchRef,mergeCommitAllowed'], 'unsupported gh repo view arguments: '+str(a)
     print(json.dumps({'nameWithOwner':'test/project', 'url':'https://github.com/test/project', 'defaultBranchRef':{'name':d.get('default_branch','main')}, 'mergeCommitAllowed':d.get('merge_allowed',True)}))
+elif a[:1] == ['api']:
+    assert a == ['api', 'graphql', '--hostname', 'github.com', '-f',
+                 'query=query($owner:String!,$name:String!){repository(owner:$owner,name:$name){autoMergeAllowed}}',
+                 '-f', 'owner=test', '-f', 'name=project',
+                 '--jq', '.data.repository.autoMergeAllowed | tojson'], 'unsupported gh api arguments: '+str(a)
+    d['auto_setting_reads'] = d.get('auto_setting_reads',0)+1
+    save()
+    if d.get('auto_setting_error'):
+        print('auto-merge setting read failed',file=sys.stderr); sys.exit(1)
+    print(d.get('auto_setting_output', json.dumps(d.get('auto_allowed',True))))
 elif a[:2] == ['pr', 'list']:
     assert '--repo' in a and a[a.index('--repo')+1] == 'github.com/test/project'
     print(json.dumps([pr for pr in prs if pr['headRefName'] == a[a.index('--head')+1]]))
@@ -898,21 +933,42 @@ elif a[:2] == ['pr', 'create']:
     print(url)
     if d.pop('interrupt_create',False): save(); sys.exit(1)
 elif a[:2] == ['pr', 'view']:
-    print(json.dumps(prs[int(a[2])-1]))
+    pr = prs[int(a[2])-1]
+    fields = a[4]
+    assert a[3:] == ['--json', fields, '--repo', 'github.com/test/project']
+    assert fields in ('mergeStateStatus', 'number,url,headRefName,baseRefName,headRefOid,headRepository,headRepositoryOwner,isCrossRepository,state,mergedAt,mergeCommit,autoMergeRequest')
+    if fields == 'mergeStateStatus':
+        if d.get('merge_state_error'):
+            print('merge state read failed',file=sys.stderr); sys.exit(1)
+        if d.get('merge_states'):
+            d['merge_state'] = d['merge_states'].pop(0)
+        state = d.get('merge_state', 'BLOCKED' if d.get('pending') else 'CLEAN')
+        d.setdefault('merge_state_views', []).append(state)
+        save()
+        print(json.dumps({'mergeStateStatus': state}))
+    else:
+        print(json.dumps(pr))
 elif a[:2] == ['pr', 'merge'] and '--disable-auto' in a:
     d['disables'] = d.get('disables',0)+1
     prs[int(a[2])-1]['autoMergeRequest'] = None
     save()
 elif a[:2] == ['pr', 'merge']:
-    assert '--admin' not in a and '--delete-branch' not in a
-    assert '--auto' in a and '--merge' in a and '--match-head-commit' in a
     pr = prs[int(a[2])-1]
     sha = a[a.index('--match-head-commit')+1]
+    auto = ['--auto'] if '--auto' in a else []
+    assert a[3:] == auto + ['--merge', '--match-head-commit', sha, '--repo', 'github.com/test/project']
     assert sha == remote('refs/heads/'+pr['headRefName'])
     d['merges'] = d.get('merges',0)+1
-    if not d.get('auto_allowed',True) and d.get('pending'):
+    d.setdefault('merge_calls', []).append(a)
+    state = d.get('merge_state', 'BLOCKED' if d.get('pending') else 'CLEAN')
+    immediately_mergeable = state in {'CLEAN', 'HAS_HOOKS', 'UNSTABLE'}
+    if auto and not immediately_mergeable and not d.get('auto_allowed',True):
         save(); print('repository disallows auto merge',file=sys.stderr); sys.exit(1)
-    if d.get('pending'):
+    if d.get('merge_error'):
+        save(); print('merge attempt refused',file=sys.stderr); sys.exit(1)
+    if not auto and not immediately_mergeable and state != 'UNKNOWN':
+        save(); print('pull request is not mergeable: '+state,file=sys.stderr); sys.exit(1)
+    if auto and not immediately_mergeable:
         pr['autoMergeRequest'] = {'enabledAt':'now'}
     else:
         g = [os.environ['REAL_GIT'],'--git-dir',d['bare']]
@@ -1042,7 +1098,7 @@ class CompletionTests(unittest.TestCase):
 
     def merge_pr(self):
         self.configure(pending=False)
-        self.run_cmd(["gh", "pr", "merge", "1", "--auto", "--merge", "--match-head-commit", self.sha])
+        self.run_cmd(["gh", "pr", "merge", "1", "--auto", "--merge", "--match-head-commit", self.sha, "--repo", "github.com/test/project"])
 
     def anchor_state(self, work=None):
         work = work or self.work
@@ -2119,6 +2175,127 @@ ctypes.CDLL(None).pthread_exit(None)
         self.assertEqual(self.g("ls-remote", "origin", "refs/heads/task/fixture").split()[0], race)
         self.assertNotEqual(self.g("branch", "--list", "task/fixture"), "")
 
+    def test_auto_disallowed_unknown_then_clean_merges_directly(self):
+        self.allocate(); self.accept()
+        self.configure(auto_allowed=False, merge_states=["UNKNOWN", "UNKNOWN", "CLEAN"])
+        result, _ = self.complete("--mode", "auto", "--writers-stopped")
+        self.assertEqual(result["status"], "COMPLETE")
+        d = json.loads(self.data.read_text(encoding="utf-8"))
+        self.assertEqual(d["merge_state_views"], ["UNKNOWN", "UNKNOWN", "CLEAN"])
+        self.assertEqual(d["merge_calls"], [["pr", "merge", "1", "--merge", "--match-head-commit", self.sha,
+                                            "--repo", "github.com/test/project"]])
+        self.assertEqual(d["prs"][0]["state"], "MERGED")
+        self.assertIsNone(d["prs"][0]["autoMergeRequest"])
+
+    def test_auto_disallowed_blocked_refuses_without_merge(self):
+        self.allocate(); self.accept()
+        for state in ("BLOCKED", "BEHIND", "DIRTY", "DRAFT", "NEW_STATE"):
+            with self.subTest(state=state):
+                self.configure(auto_allowed=False, merge_state=state)
+                result, _ = self.complete("--mode", "auto")
+                self.assertEqual(result["status"], "PR")
+                self.assertIn("not mergeable: " + state, result["merge_refused"])
+        d = json.loads(self.data.read_text(encoding="utf-8"))
+        self.assertEqual(d["merge_state_views"], ["BLOCKED", "BEHIND", "DIRTY", "DRAFT", "NEW_STATE"])
+        self.assertEqual(d.get("merge_calls", []), [])
+        self.assertEqual(d["prs"][0]["state"], "OPEN")
+        self.assertIsNone(d["prs"][0]["autoMergeRequest"])
+        self.assertTrue(self.task.exists())
+
+    def test_auto_allowed_unknown_keeps_auto_pending(self):
+        self.allocate(); self.accept()
+        self.configure(auto_allowed=True, merge_state="UNKNOWN")
+        result, _ = self.complete("--mode", "auto")
+        self.assertEqual(result["status"], "PENDING")
+        self.assertNotIn("merge_refused", result)
+        d = json.loads(self.data.read_text(encoding="utf-8"))
+        self.assertEqual(d.get("merge_state_views", []), [])
+        self.assertEqual(d["merge_calls"], [["pr", "merge", "1", "--auto", "--merge", "--match-head-commit", self.sha,
+                                            "--repo", "github.com/test/project"]])
+        self.assertEqual(d["prs"][0]["state"], "OPEN")
+        self.assertTrue(d["prs"][0]["autoMergeRequest"])
+        self.assertTrue(self.task.exists())
+        self.configure(auto_setting_error=True)
+        result, _ = self.complete()
+        self.assertEqual(result["status"], "PENDING")
+        self.assertEqual(json.loads(self.data.read_text(encoding="utf-8"))["auto_setting_reads"], 1)
+
+    def test_auto_disallowed_unknown_bound_refuses_without_merge(self):
+        self.allocate(); self.accept()
+        self.configure(auto_allowed=False, merge_state="UNKNOWN")
+        result, _ = self.complete("--mode", "auto")
+        self.assertEqual(result["status"], "PR")
+        self.assertIn("not mergeable: UNKNOWN", result["merge_refused"])
+        d = json.loads(self.data.read_text(encoding="utf-8"))
+        self.assertEqual(d["merge_state_views"], ["UNKNOWN"] * 10)
+        self.assertEqual(d.get("merge_calls", []), [])
+        self.assertEqual(d["prs"][0]["state"], "OPEN")
+        self.assertIsNone(d["prs"][0]["autoMergeRequest"])
+        self.assertTrue(self.task.exists())
+
+    def test_auto_disallowed_other_immediate_states_attempt_direct_merge(self):
+        self.allocate(); self.accept()
+        for state in ("HAS_HOOKS", "UNSTABLE"):
+            with self.subTest(state=state):
+                self.configure(auto_allowed=False, merge_state=state, merge_error=True, merge_calls=[])
+                result, _ = self.complete("--mode", "auto")
+                self.assertEqual(result["status"], "PR")
+                self.assertIn("merge attempt refused", result["merge_refused"])
+                d = json.loads(self.data.read_text(encoding="utf-8"))
+                self.assertEqual(d["merge_calls"], [["pr", "merge", "1", "--merge",
+                                                    "--match-head-commit", self.sha, "--repo", "github.com/test/project"]])
+
+    def test_auto_setting_read_failure_or_invalid_value_blocks_with_resume(self):
+        self.allocate(); self.accept()
+        for values in ({"auto_setting_error": True}, *({"auto_setting_error": False, "auto_setting_output": output}
+                        for output in ('null', '"true"', '"false"', '0', '1', '{}', '[]', '', 'invalid'))):
+            with self.subTest(values=values):
+                self.configure(**values)
+                result, process = self.complete("--mode", "auto", "--writers-stopped", success=False)
+                self.assertNotEqual(process.returncode, 0)
+                self.assertEqual(result["status"], "BLOCKED")
+                if values.get("auto_setting_output") == 'null':
+                    self.assertEqual(result["reason"], "repository autoMergeAllowed must be a JSON boolean")
+                self.assertIn(str(self.receipt), result["resume"])
+                self.assertNotIn("merge_refused", result)
+                d = json.loads(self.data.read_text(encoding="utf-8"))
+                self.assertEqual(d.get("merge_calls", []), [])
+                self.assertEqual(d["prs"][0]["state"], "OPEN")
+        self.configure(auto_setting_output='false')
+        result, _ = self.cli(*shlex.split(result["resume"])[2:])
+        self.assertEqual(result["status"], "COMPLETE")
+
+    def test_auto_disallowed_status_poll_failure_blocks_with_resume(self):
+        self.allocate(); self.accept()
+        self.configure(auto_allowed=False, merge_state_error=True)
+        result, process = self.complete("--mode", "auto", "--writers-stopped", success=False)
+        self.assertNotEqual(process.returncode, 0)
+        self.assertEqual(result["status"], "BLOCKED")
+        self.assertIn("merge state read failed", result["reason"])
+        self.assertIn(str(self.receipt), result["resume"])
+        self.assertNotIn("merge_refused", result)
+        d = json.loads(self.data.read_text(encoding="utf-8"))
+        self.assertEqual(d.get("merge_calls", []), [])
+        self.assertEqual(d["prs"][0]["state"], "OPEN")
+        self.configure(merge_state_error=False)
+        result, _ = self.cli(*shlex.split(result["resume"])[2:])
+        self.assertEqual(result["status"], "COMPLETE")
+
+    def test_merge_attempt_refusal_keeps_pr(self):
+        self.allocate(); self.accept()
+        self.configure(auto_allowed=False, merge_error=True)
+        result, _ = self.complete("--mode", "auto")
+        self.assertEqual(result["status"], "PR")
+        self.assertIn("merge attempt refused", result["merge_refused"])
+        self.assertEqual(json.loads(self.data.read_text(encoding="utf-8"))["merges"], 1)
+
+    def test_pr_mode_does_not_read_auto_setting(self):
+        self.allocate(); self.accept()
+        self.configure(auto_setting_error=True)
+        result, _ = self.complete("--mode", "pr")
+        self.assertEqual(result["status"], "PR")
+        self.assertEqual(json.loads(self.data.read_text(encoding="utf-8")).get("auto_setting_reads", 0), 0)
+
     def test_policy_and_local_only_persist(self):
         self.allocate(); self.accept()
         self.configure(merge_allowed=False)
@@ -2133,7 +2310,7 @@ ctypes.CDLL(None).pthread_exit(None)
         self.configure(merge_allowed=True, auto_allowed=False, pending=True)
         result, _ = self.complete("--mode", "auto")
         self.assertEqual(result["status"], "PR")
-        self.assertIn("disallows auto merge", result["merge_refused"])
+        self.assertIn("not mergeable: BLOCKED", result["merge_refused"])
         self.assertTrue(self.task.exists())
         # Local-only cannot rewrite the delivery of a pushed PR; a local allocation keeps it (test_local_chain_*).
         result, _ = self.complete("--no-push", success=False)

package/config/skills/_shared/task-completion.md

@@ -182,7 +182,7 @@ the user's delivery restriction. These per-task choices persist in the receipt;
 head and base PR. While OPEN, it cancels owned auto-merge, reports `PR` with its URL
 and retains the checkout. Once MERGED by any method, either mode cleans released
 resources in that call, on resume or at the next allocation. Default `auto` also requests
-`gh pr merge --auto --merge --match-head-commit <accepted SHA>`. Repository
+a `--merge --match-head-commit <accepted SHA>` merge. Repository
 checks/reviews and merge policy remain authoritative: no admin bypass, strategy
 fallback or repository setting changes. When the repository disallows merge
 commits or refuses the request, delivery reports `PR` with `merge_refused` and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlyn-cli",
-  "version": "4.2.20",
+  "version": "4.2.22",
   "description": "Loop & harness engineering for AI coding agents (Claude Code, Codex, and any AGENTS.md-driven agent) — core engineering principles for CLAUDE.md/AGENTS.md and a loop designer that splits one intent into tasks agents drain hands-free",
   "homepage": "https://github.com/fysoul17/devlyn-cli#readme",
   "bin": {