@khoavu882/doflow 2.0.0 → 2.0.2

package/src/runtime/roadmap/merge.js

@@ -342,7 +342,11 @@ function copyFeatureFolder(from        , to        , fsImpl     , report     , r
   }
 }
 
-/** `report` (optional) receives `copied`, `skipped` and, when the cleanup is kept, `failure`. */
+/**
+ * `report` (optional) receives `copied`, `skipped` and, when the cleanup is kept, `kept` (head-moved,
+ * not-on-develop, wrong-branch, dirty, copy-failed, copy-conflict, worktree-remains or git-failed)
+ * and, for the copy and git faults, `failure`.
+ */
 function cleanupFeature({ intent, root, develop, execFileSync, execOptions, fsImpl, report = {} }     )          {
   report.copied = 0; report.skipped = []; report.conflicts = [];
   const feature = intent.featureWorktree;
@@ -350,24 +354,29 @@ function cleanupFeature({ intent, root, develop, execFileSync, execOptions, fsIm
   try {
     let featureHead        ;
     try { featureHead = String(execFileSync('git', ['-C', root, 'rev-parse', '--verify', `refs/heads/${branch}`], execOptions)).trim(); }
-    catch { return !feature || !fsImpl.existsSync(feature); }
-    if (featureHead !== intent.featureHead) return false;
+    catch {
+      if (!feature || !fsImpl.existsSync(feature)) return true;
+      report.kept = 'worktree-remains';
+      return false;
+    }
+    if (featureHead !== intent.featureHead) { report.kept = 'head-moved'; return false; }
     // Only a tip already on develop may lose its worktree: a branch someone kept committing on keeps
     // both the worktree (and its gitignored agent-docs/.doflow files) and the branch.
     try { execFileSync('git', ['-C', root, 'merge-base', '--is-ancestor', featureHead, 'refs/heads/develop'], execOptions); }
-    catch { return false; }
+    catch { report.kept = 'not-on-develop'; return false; }
     if (feature && fsImpl.existsSync(feature)) {
       const current = String(execFileSync('git', ['-C', feature, 'symbolic-ref', '-q', 'HEAD'], execOptions)).trim();
-      if (current !== `refs/heads/${branch}`) return false;
-      if (String(execFileSync('git', ['-C', feature, 'status', '--porcelain', '--untracked-files=all'], execOptions)) !== '') return false;
+      if (current !== `refs/heads/${branch}`) { report.kept = 'wrong-branch'; return false; }
+      if (String(execFileSync('git', ['-C', feature, 'status', '--porcelain', '--untracked-files=all'], execOptions)) !== '') { report.kept = 'dirty'; return false; }
       const slug = branch.replace(/^feat\//, '');
       const folder = path.join(feature, 'agent-docs', 'doflow', slug);
       // The folder is gitignored, so `worktree remove` would delete it: copy it first, keep on any failure.
       if (slug && !slug.includes('/') && fsImpl.existsSync(folder)) {
         try { copyFeatureFolder(folder, path.join(root, 'agent-docs', 'doflow', slug), fsImpl, report); }
-        catch (error     ) { report.failure = `artifact copy failed: ${error.message}`; return false; }
+        catch (error     ) { report.failure = `artifact copy failed: ${error.message}`; report.kept = 'copy-failed'; return false; }
         if (report.conflicts.length) {
           report.failure = `kept: main checkout copy differs from the worktree copy of ${report.conflicts.join(', ')}`;
+          report.kept = 'copy-conflict';
           return false;
         }
       }
@@ -375,7 +384,7 @@ function cleanupFeature({ intent, root, develop, execFileSync, execOptions, fsIm
     }
     execFileSync('git', ['-C', develop, 'branch', '-d', '--', branch], execOptions);
     return true;
-  } catch (error     ) { report.failure ||= error.message; return false; }
+  } catch (error     ) { report.failure ||= error.message; report.kept ||= 'git-failed'; return false; }
 }
 
 module.exports = { mergeRoadmapRow, readOpenIntents, writeIntent, cleanupFeature };

package/src/runtime/roadmap/rows.js

@@ -13,8 +13,7 @@ function safeText(value     )         {
   if (typeof value === 'string') {
     try {
       text = JSON.stringify(value).slice(1, -1)
-        .replace(/\u2028/g, '\\u2028')
-        .replace(/\u2029/g, '\\u2029');
+        .replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu, (c        ) => { const cp = c.codePointAt(0)          ; return cp > 0xffff ? `\\u{${cp.toString(16)}}` : `\\u${cp.toString(16).padStart(4, '0')}`; });
     } catch {
       text = '';
     }
@@ -733,13 +732,22 @@ function deriveStatus(
   return { statuses, rowStatus };
 }
 
+/**
+ * The task classes the roadmap loop runs: the feature chain, and the four classes that take a
+ * gate-b-only policy (core/registry/gates.json). research, review and operations stay out: they
+ * produce no change the loop could merge. dependency-change stays out too: a change to any
+ * package.json dependency key is always denied `protected-path:package.json` (gates.ts), so such a
+ * row could never merge without a person; a user ruling reopens it.
+ */
+const LOOP_CLASSES                    = Object.freeze(['feature', 'bug', 'refactor', 'documentation', 'trivial-edit']);
+
 /**
  * S1 Pick table: chooses the next ready row in seed order.
  * - Ready only when all needs are merged
  * - Write set disjoint from all in-flight rows
  * - WIP bound (default 2)
  * - Row without a write set runs alone
- * - Non-feature class is class-unsupported
+ * - A class outside LOOP_CLASSES (research, review, operations, dependency-change, anything else) is class-unsupported
  * - Yields one reason per skipped row
  */
 function pick(
@@ -782,7 +790,7 @@ function pick(
     }
 
     // Class check
-    if (row.class !== 'feature') {
+    if (!LOOP_CLASSES.includes(row.class)) {
       skips[row.id] = 'class-unsupported';
       continue;
     }
@@ -856,7 +864,8 @@ function render(
   for (const row of rows) {
     const info = getInfo(row.id);
     const needsStr = row.needs && row.needs.length > 0 ? row.needs.join(', ') : '-';
-    const statusStr = info.status;
+    // A not-started row of a class the loop does not run waits for a person, not for time: `manual`.
+    const statusStr = info.status === 'not-started' && !LOOP_CLASSES.includes(row.class) ? 'manual' : info.status;
 
     let evidenceStr = '-';
     if (info.evidence) {
@@ -1107,6 +1116,7 @@ module.exports = {
   check,
   seedFindings,
   registryClasses,
+  LOOP_CLASSES,
   SEED_RULES,
   ROW_KEYS,
   TOP_KEYS,

package/src/runtime/roadmap/seed.js

@@ -54,6 +54,11 @@ const { readSeedSwitch } = require('../settings/autopilot.js');
                             
                      
                   
+                                                                                                              
+                                              
+                                                                                           
+                          
+                                  
  
 
 function judgeDraft({
@@ -379,7 +384,7 @@ function printTextResult(
   if ((op === 'apply' || op === 'amend') && result.ok) {
     line1 += `, ${result.writes} files written`;
     if (Array.isArray(result.proposed) && result.proposed.length > 0) {
-      line1 += `, ${result.proposed.length} proposed (no person verified, or autopilot is not verifiably off; a person runs in their terminal, with autopilot off: doflow roadmap promote ${result.proposed.map(safeText).join(' ')})`;
+      line1 += `, ${result.proposed.length} proposed (no person verified, or autopilot is not verifiably off; a person runs in their terminal: doflow roadmap promote ${result.proposed.map(safeText).join(' ')})`;
     }
   }
   if (result.seed && result.seed.sha256 === null) {
@@ -481,6 +486,9 @@ function handleSeedCommand(options                           = {})         {
     err = (s        ) => console.error(s),
     classes,
     isTTY = process.stdin.isTTY === true,
+    confirm,
+    ttyClock,
+    ttySleep,
   } = options;
 
   const usage = (message        )         => {
@@ -583,13 +591,37 @@ function handleSeedCommand(options                           = {})         {
   }
 
   // 4. Apply / Amend action
-  // (a) maint-thin: a seed write is allowed whatever the switch says. Rows land as drafted (ready) only when BOTH
-  // autopilot is verifiably off (the fail-closed seed reader) AND stdin is an interactive terminal: a model with a
-  // shell controls the environment (an empty config home reads as off), so the switch alone cannot tell a person.
-  // Otherwise every row it adds or amends lands `proposed`, which autopilot never picks or advances until a person
-  // runs `roadmap promote`.
+  // (a) maint-thin / AU C05: a seed write is allowed whatever the switch says. Rows land as drafted (ready) only when
+  // stdin is an interactive terminal AND either autopilot is verifiably off (the fail-closed seed reader) or a person
+  // answers yes to the same `/dev/tty` [y/N] that `roadmap promote` uses. A model with a shell controls the
+  // environment (an empty config home reads as off), so the switch alone cannot tell a person; and without the prompt
+  // a model with a pty could land ready rows while autopilot is on, which widens the queue. No terminal, or no/other
+  // answer, lands every row it adds or amends `proposed`, which autopilot never picks or advances until a person runs
+  // `roadmap promote`. The prompt comes before the roadmap lease (Ctrl-C would otherwise leave the lease behind) and
+  // only for a draft that judges clean against the store as read now. No flag or environment variable skips it.
   const switchReader = readSwitch || readSeedSwitch;
-  const landProposed = isTTY !== true || switchReader(env, fsImpl).enabled !== false;
+  let landProposed = isTTY !== true || switchReader(env, fsImpl).enabled !== false;
+  if (landProposed && isTTY === true) {
+    const preFacts = gitFacts || gatherGitFacts({ root });
+    const pre = preFacts.unreadable && preFacts.unreadable.length > 0 ? null
+      : judgeDraft({ draftRaw, seedRaw, gitFacts: preFacts, op: action, classes });
+    if (pre && pre.ok) {
+      const rowsList = (JSON.parse(draftRaw).rows || []).filter((r     ) => r && typeof r === 'object');
+      const ids = rowsList.map((r     ) => safeText(r.id));
+      const titles = rowsList.map((r     ) => `  ${safeText(r.id)}  ${safeText(r.title)}`);
+      const prompt = `${titles.join('\n')}\nLand ${ids.length} row(s) ready for autopilot (autopilot is not verifiably off): ${ids.join(' ')}? [y/N] `;
+      let answer                = null;
+      try {
+        if (confirm) answer = confirm(prompt);
+        else {
+          const read = readTtyLine(prompt, { timeoutMs: SEED_PROMPT_TIMEOUT_MS, now: ttyClock, sleep: ttySleep });
+          answer = read.answer;
+          if (read.timedOut) err(`doflow roadmap seed: the [y/N] prompt timed out after ${Math.round(SEED_PROMPT_TIMEOUT_MS / 1000)} s with no answer; rows land proposed (run: doflow roadmap promote <id...>)`);
+        }
+      } catch { answer = null; }
+      if (typeof answer === 'string' && /^(y|yes)$/i.test(answer.trim())) landProposed = false;
+    }
+  }
 
   // (b) Acquire lease
   const leaseDir = path.join(root, '.doflow', 'state', 'roadmap');
@@ -818,25 +850,97 @@ function handleSeedCommand(options                           = {})         {
                 
                
                  
-                                                                              
                                              
-            
                
                 
                    
                             
                             
                   
+                                                                                                              
+                                              
  
 
+/** How long the seed prompt waits for a person before it counts as "no" (promote waits without limit). */
+const SEED_PROMPT_TIMEOUT_MS = 60000;
+const TTY_POLL_MS = 25;
+
+function sleepMs(ms        )       {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+                          
+                                                                                                                
+                     
+                     
+                               
+ 
+
+/**
+ * Reads one answer line from the controlling terminal (`/dev/tty`), never from stdin, an argument or the environment.
+ * `answer` is null when the terminal cannot be opened or read, the line is too long, or the optional timeout passes
+ * (`timedOut`). A timed read opens the terminal non-blocking and polls, so a pty that stays open without an answer
+ * cannot hold the caller for ever.
+ */
+function readTtyLine(prompt        , options                 = {})                                               {
+  const { timeoutMs = 0, now = Date.now, sleep = sleepMs } = options;
+  const timed = timeoutMs > 0;
+  let fd        ;
+  try { fd = timed ? fs.openSync('/dev/tty', fs.constants.O_RDWR | fs.constants.O_NONBLOCK) : fs.openSync('/dev/tty', 'r+'); } catch { return { answer: null, timedOut: false }; }
+  const deadline = timed ? now() + timeoutMs : Infinity;
+  let timedOut = false;
+  // one byte; 0 at end of input, -1 when the timeout passed
+  const readByte = (buf        )         => {
+    for (;;) {
+      try { return fs.readSync(fd, buf, 0, 1, null); }
+      catch (error     ) {
+        if (!timed || (error?.code !== 'EAGAIN' && error?.code !== 'EWOULDBLOCK')) throw error;
+        if (now() >= deadline) { timedOut = true; return -1; }
+        sleep(TTY_POLL_MS);
+      }
+    }
+  };
+  try {
+    fs.writeSync(fd, prompt);
+    const buf = Buffer.alloc(1);
+    let line = '';
+    let ended = false;
+    for (let i = 0; i < 64 && !ended; i += 1) {
+      const n = readByte(buf);
+      if (n < 0) return { answer: null, timedOut: true };
+      if (n === 0 || buf[0] === 10) ended = true;
+      else line += String.fromCharCode(buf[0]);
+    }
+    // drain what is left of the typed line (bounded), so it is not left in the terminal queue
+    const tooLong = !ended;
+    for (let i = 0; i < 4096 && !ended; i += 1) {
+      const n = readByte(buf);
+      if (n < 0) return { answer: null, timedOut: true };
+      if (n === 0 || buf[0] === 10) ended = true;
+    }
+    return { answer: tooLong ? null : line, timedOut: false };
+  } catch {
+    return { answer: null, timedOut };
+  } finally {
+    try { fs.closeSync(fd); } catch { /* ignore close failure */ }
+  }
+}
+
+/** The untimed reader `roadmap promote` uses: a person runs that verb and may take as long as they need. */
+function readTtyAnswer(prompt        )                {
+  return readTtyLine(prompt).answer;
+}
+
 /**
- * maint-thin: `roadmap promote <id...>`, person only. A model with a shell controls the environment, so an
- * environment check alone cannot tell a person: pointing XDG_CONFIG_HOME at an empty folder reads as "off". The verb
- * therefore first requires an interactive terminal on stdin (refused `needs-person-tty`, nothing written), then reads
- * the switch with the fail-closed seed reader as a second check: unless autopilot is verifiably off it refuses
- * `needs-person` and writes nothing. Under the roadmap lease it drops the
- * `proposed` mark of every named row, so autopilot may pick it. All or nothing: an unknown id, a row that is not
- * proposed, or a duplicate id is a finding and nothing is written. Exit 0 promoted, 1 refused or findings, 2 usage.
+ * maint-thin: `roadmap promote <id...>`, person only. A model with a shell controls the environment, so neither an
+ * environment check nor the autopilot switch can tell a person. The verb requires an interactive terminal on stdin
+ * (refused `needs-person-tty`, nothing written), validates the named rows, then prints their ids and titles and asks
+ * `[y/N]` on the controlling terminal (`/dev/tty`): no `/dev/tty`, or an answer other than y/yes, is refused
+ * `needs-person-confirm` and nothing is written. No flag or environment variable skips the prompt, and the autopilot
+ * switch is not read. The prompt comes before the roadmap lease (Ctrl-C would otherwise leave the lease behind); under
+ * the lease the store is read again and must equal what was shown, then the verb drops the `proposed` mark of every
+ * named row, so autopilot may pick it. All or nothing: an unknown id, a row that is not proposed, or a duplicate id is a finding (reported before any
+ * prompt) and nothing is written. Exit 0 promoted, 1 refused or findings, 2 usage.
  */
 function handlePromoteCommand(options                              = {})         {
   const {
@@ -845,15 +949,14 @@ function handlePromoteCommand(options                              = {})
     root = resolveMainRoot(process.cwd()),
     fsImpl = fs,
     gitFacts,
-    readSwitch,
     alive,
-    env = process.env,
     pid,
     host,
     now,
     out = (s        ) => console.log(s),
     err = (s        ) => console.error(s),
     isTTY = process.stdin.isTTY === true,
+    confirm = readTtyAnswer,
   } = options;
   const emit = (result     , code        , detail         )         => {
     if (json) out(JSON.stringify(result));
@@ -879,13 +982,32 @@ function handlePromoteCommand(options                              = {})
     return emit({ ...base, reason: 'needs-person-tty' }, 1,
       'promote runs only from an interactive terminal: a person runs doflow roadmap promote in their own shell');
   }
-  const switchReader = readSwitch || readSeedSwitch;
-  if (switchReader(env, fsImpl).enabled !== false) {
-    const { configHome } = require('../config-home.js');
-    const home = configHome(env).dir;
-    const homeText = home ? safeText(home) : 'the config home (none resolves: set HOME or XDG_CONFIG_HOME)';
-    return emit({ ...base, reason: 'needs-person' }, 1,
-      `autopilot is not verifiably off for this config home; a person sets autopilot.enabled to off in ${homeText}/settings.json or creates ${homeText}/autopilot/off, then promotes`);
+
+  // Read, validate and ask BEFORE taking the lease: Ctrl-C kills the process inside the terminal read, so a lease held
+  // across the prompt would be left behind. The lease is taken after the answer, and the store is read again under it.
+  let raw        ;
+  try { raw = fsImpl.readFileSync(storePath, 'utf8'); }
+  catch (error     ) { return emit({ ...base, findings: ids.map((id) => ({ rule: 'row-not-found', rowId: id, message: `no store at ${storePath}: ${safeText(error.message)}` })) }, 1); }
+  const storeFindings = seedFindings(raw);
+  if (storeFindings.length > 0) return emit({ ...base, findings: storeFindings }, 1);
+  const doc = JSON.parse(raw);
+  const findings        = [];
+  const seen = new Set        ();
+  for (const id of ids) {
+    const row = doc.rows.find((r     ) => r.id === id);
+    if (seen.has(id)) findings.push({ rule: 'duplicate-id', rowId: id, message: `Row '${safeText(id)}' is named twice` });
+    else if (!row) findings.push({ rule: 'row-not-found', rowId: id, message: `Row '${safeText(id)}' not found in store` });
+    else if (row.proposed !== true) findings.push({ rule: 'row-not-proposed', rowId: id, message: `Row '${safeText(id)}' is not proposed` });
+    seen.add(id);
+  }
+  if (findings.length > 0) return emit({ ...base, findings }, 1);
+  const titles = ids.map((id) => `  ${safeText(id)}  ${safeText(doc.rows.find((r     ) => r.id === id).title)}`);
+  const prompt = `${titles.join('\n')}\nPromote ${ids.length} row(s): ${ids.map(safeText).join(' ')}? [y/N] `;
+  let answer                = null;
+  try { answer = confirm(prompt); } catch { answer = null; }
+  if (typeof answer !== 'string' || !/^(y|yes)$/i.test(answer.trim())) {
+    return emit({ ...base, reason: 'needs-person-confirm' }, 1,
+      'promote needs a person to answer y on the controlling terminal (/dev/tty); there is no flag or variable that skips the prompt');
   }
 
   const leaseDir = path.join(root, '.doflow', 'state', 'roadmap');
@@ -901,22 +1023,12 @@ function handlePromoteCommand(options                              = {})
   const lease = acquireLease(leaseDir, me, alive || noPsAlive, fsImpl);
   if (!lease.ok) return emit({ ...base, reason: 'lease-held' }, 1);
   try {
-    let raw        ;
-    try { raw = fsImpl.readFileSync(storePath, 'utf8'); }
-    catch (error     ) { return emit({ ...base, findings: ids.map((id) => ({ rule: 'row-not-found', rowId: id, message: `no store at ${storePath}: ${safeText(error.message)}` })) }, 1); }
-    const storeFindings = seedFindings(raw);
-    if (storeFindings.length > 0) return emit({ ...base, findings: storeFindings }, 1);
-    const doc = JSON.parse(raw);
-    const findings        = [];
-    const seen = new Set        ();
-    for (const id of ids) {
-      const row = doc.rows.find((r     ) => r.id === id);
-      if (seen.has(id)) findings.push({ rule: 'duplicate-id', rowId: id, message: `Row '${safeText(id)}' is named twice` });
-      else if (!row) findings.push({ rule: 'row-not-found', rowId: id, message: `Row '${safeText(id)}' not found in store` });
-      else if (row.proposed !== true) findings.push({ rule: 'row-not-proposed', rowId: id, message: `Row '${safeText(id)}' is not proposed` });
-      seen.add(id);
-    }
-    if (findings.length > 0) return emit({ ...base, findings }, 1);
+    let current                = null;
+    try { current = fsImpl.readFileSync(storePath, 'utf8'); } catch { current = null; }
+    if (current !== raw) {
+      return emit({ ...base, reason: 'needs-person-confirm' }, 1,
+        'the roadmap store changed after the rows were shown; nothing was written, run doflow roadmap promote again');
+    }
     const rows = doc.rows.map((r     ) => {
       if (!ids.includes(r.id)) return r;
       const { proposed, ...ready } = r;

package/src/runtime/roadmap/worktree-cleanup.js

@@ -0,0 +1,147 @@
+'use strict';
+
+/**
+ * `doflow-run worktree --action cleanup --slug <slug>` (autonomy plan section 7c): remove one merged
+ * feature's worktree and branch with merge.ts's non-force `cleanupFeature`, after copying the
+ * worktree's gitignored `agent-docs/doflow/<slug>` back to the main checkout. It refuses, with the
+ * reason printed and exit 1, whenever `cleanupFeature` keeps the feature (`report.kept`), the roadmap
+ * lease is held (`lease-held`), the row has no `DoFlow-Row` trailer merge on develop (`not-merged`, the
+ * evidence the loop requires; a tip merely contained in develop is not enough) or the caller stands
+ * inside the worktree (`cwd-inside-worktree`). There is no `--force` (G53). This module is not part of the
+ * person-only set and must not import attendance.ts (attendance-scope guard).
+ *
+ * Exit: 0 `cleaned`, 1 `kept` or `denied` (reason in the output), 2 usage.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync: defaultExecFileSync } = require('node:child_process');
+const { acquireLease, releaseLease, resolveMainRoot, noPsAlive } = require('./loop.js');
+const { cleanupFeature } = require('./merge.js');
+const { parseSeed, deriveStatus } = require('./rows.js');
+const { gatherGitFacts } = require('./facts.js');
+
+/** A row slug is `<id>-<words>`; the pattern keeps a path separator and `..` out of every join below. */
+const SLUG = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+const ALLOWED_FLAGS = new Set(['--action', '--slug', '--json']);
+
+function execOptionsFor(root        , env     )      {
+  const environment = { ...env };
+  for (const key of Object.keys(environment)) if (/^GIT_(?:DIR|WORK_TREE|COMMON_DIR|INDEX_FILE|OBJECT_DIRECTORY|ALTERNATE_OBJECT_DIRECTORIES|CONFIG_COUNT|CONFIG_KEY_\d+|CONFIG_VALUE_\d+)$/.test(key)) delete environment[key];
+  return { cwd: root, encoding: 'utf8', env: environment, stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 64 * 1024 * 1024 };
+}
+
+/** Branch ref to worktree path, as `git worktree list` reports them. */
+function listWorktrees(root        , execFileSync     , execOptions     )                      {
+  const out = String(execFileSync('git', ['-C', root, 'worktree', 'list', '--porcelain', '-z'], execOptions));
+  const map = new Map                ();
+  for (const block of out.split('\0\0').filter(Boolean)) {
+    const fields = block.split('\0');
+    const listed = fields.find((s) => s.startsWith('worktree '))?.slice(9);
+    const worktree = listed === undefined ? listed : path.resolve(listed);
+    const branch = fields.find((s) => s.startsWith('branch '))?.slice(7);
+    if (worktree && branch) map.set(branch, worktree);
+  }
+  return map;
+}
+
+/** True when the seed row for `slug` has a `DoFlow-Row` trailer merge on develop (deriveStatus, as the loop reads it). */
+function mergeEvidence({ root, slug, fsImpl }     )                                                              {
+  let rows       ;
+  try { rows = parseSeed(fsImpl.readFileSync(path.join(root, 'agent-docs', 'roadmap', 'rows.json'), 'utf8')).rows; }
+  catch { return { error: 'facts-unreadable', unreadable: ['seed'] }; }
+  const row = rows.find((entry     ) => entry && entry.slug === slug);
+  if (!row) return { error: 'row-unknown' };
+  const facts = gatherGitFacts({ root });
+  if (facts.unreadable?.length) return { error: 'facts-unreadable', unreadable: facts.unreadable };
+  const info = deriveStatus([row], facts).statuses.get(row.id);
+  return { merged: info?.status === 'merged' && info.evidence?.kind === 'trailer' };
+}
+
+/** True when `cwd` is the worktree or inside it (real paths, so a symlinked temp folder cannot hide it). */
+function callerInside(worktree               , cwd        , fsImpl     )          {
+  if (!worktree) return false;
+  const real = (value        )         => { try { return fsImpl.realpathSync(value); } catch { return path.resolve(value); } };
+  const relative = path.relative(real(worktree), real(cwd));
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+/**
+ * @returns {{code: number, result: object}} the exit code and the JSON body; never throws for a refusal.
+ */
+function cleanupWorktree(options      = {})                                {
+  const fsImpl = options.fsImpl || fs;
+  const env = options.env || process.env;
+  const execFileSync = options.execFileSync || defaultExecFileSync;
+  const slug = options.slug;
+  const body = (outcome        , extra      = {}) => ({ schema: 1, action: 'cleanup', outcome, slug, ...extra });
+  if (typeof slug !== 'string' || !SLUG.test(slug) || slug.includes('..')) {
+    return { code: 2, result: { schema: 1, action: 'cleanup', error: 'usage', detail: '--slug <row slug> is required (letters, digits, dot, underscore, hyphen)' } };
+  }
+  const root = options.root || resolveMainRoot(options.cwd || process.cwd());
+  const execOptions = execOptionsFor(root, env);
+  const dir = path.join(root, '.doflow', 'state', 'roadmap');
+  const me = { schema: 1, pid: options.pid ?? process.pid, start: new Date(Date.now() - (process       ).uptime() * 1000).toISOString(),
+    host: options.host ?? os.hostname(), runId: null, acquiredAt: new Date().toISOString() };
+  const lease = acquireLease(dir, me, options.alive || noPsAlive, fsImpl);
+  if (!lease.ok) {
+    const holder = lease.holder && typeof lease.holder === 'object' ? { pid: lease.holder.pid ?? null, host: lease.holder.host ?? null, runId: lease.holder.runId ?? null } : null;
+    return { code: 1, result: body('denied', { reason: 'lease-held', holder }) };
+  }
+  try {
+    let worktrees                     ;
+    try { worktrees = listWorktrees(root, execFileSync, execOptions); }
+    catch { return { code: 1, result: body('denied', { reason: 'facts-unreadable', rule: 'cleanup/facts', unreadable: ['worktrees'] }) }; }
+    const develop = worktrees.get('refs/heads/develop');
+    if (!develop) return { code: 1, result: body('denied', { reason: 'no-develop-worktree' }) };
+    const worktree = worktrees.get(`refs/heads/feat/${slug}`) || null;
+    let featureHead                = null;
+    try { featureHead = String(execFileSync('git', ['-C', root, 'rev-parse', '--verify', `refs/heads/feat/${slug}`], execOptions)).trim(); }
+    catch { /* branch already gone: only a leftover worktree can remain */ }
+    if (featureHead === null && worktree === null) return { code: 0, result: body('cleaned', { already: true, artifacts: { copied: 0, skipped: [], conflicts: [] } }) };
+    const artifacts      = {};
+    // The loop cleans a row only on trailer evidence (loop.ts, merged rows with no intent): a branch
+    // whose tip merely sits inside develop (a row claimed a moment ago) is not a merged feature.
+    const evidence = mergeEvidence({ root, slug, fsImpl });
+    if (evidence.error) return { code: 1, result: body('denied', { reason: evidence.error, rule: 'cleanup/merge-evidence', unreadable: evidence.unreadable }) };
+    if (!evidence.merged) { artifacts.kept = 'not-merged'; return { code: 1, result: body('kept', { reason: artifacts.kept, artifacts }) }; }
+    // Removing the directory the caller stands in would strand its session.
+    if (callerInside(worktree, options.cwd ?? process.cwd(), fsImpl)) {
+      artifacts.kept = 'cwd-inside-worktree';
+      return { code: 1, result: body('kept', { reason: artifacts.kept, artifacts }) };
+    }
+    const cleaned = cleanupFeature({ intent: { featureWorktree: worktree, featureBranch: `feat/${slug}`, featureHead },
+      root, develop, execFileSync, execOptions, fsImpl, report: artifacts });
+    if (cleaned) return { code: 0, result: body('cleaned', { artifacts }) };
+    return { code: 1, result: body('kept', { reason: artifacts.kept || 'git-failed', artifacts }) };
+  } finally {
+    releaseLease(dir, me, fsImpl);
+  }
+}
+
+/** The CLI handler: `--action cleanup --slug <slug> [--json]`; any other action is usage. */
+function handleWorktreeCommand(options      = {})         {
+  const json = Boolean(options.json);
+  const usage = (detail        )         => {
+    if (json) console.log(JSON.stringify({ schema: 1, error: 'usage', detail }));
+    else console.error(`doflow worktree: error: ${detail}`);
+    process.exitCode = 2;
+    return 2;
+  };
+  if (options.action !== 'cleanup') return usage('--action cleanup is the only action');
+  const extra = ((options.flags || [])            ).map((flag) => flag.split('=')[0]).find((flag) => !ALLOWED_FLAGS.has(flag));
+  if (extra !== undefined) return usage(`unsupported flag ${extra}; only --action, --slug and --json apply`);
+  const { code, result } = cleanupWorktree({ slug: options.slug, cwd: options.cwd, env: options.env, root: options.root });
+  if (result.error === 'usage') return usage(result.detail);
+  if (json) console.log(JSON.stringify(result));
+  else if (result.outcome === 'cleaned') console.log(`cleaned ${result.slug}${result.already ? ' (already gone)' : ''}`);
+  else {
+    const failure = result.artifacts?.failure ? ` (${result.artifacts.failure})` : '';
+    console.log(`${result.outcome} ${result.slug}: ${result.reason}${failure}`);
+  }
+  process.exitCode = code;
+  return code;
+}
+
+module.exports = { cleanupWorktree, handleWorktreeCommand };

package/src/runtime/settings/files.js

@@ -35,6 +35,8 @@ const BOM = '\uFEFF';
                 
                                                                                   
                                      
+                                                                                           
+                  
  
 
 function isObject(value         )                                   {
@@ -265,7 +267,7 @@ function readLayerFile(file        , { registry, fsImpl = nodeFs, includeDocumen
     values.set(key, { raw, value: error ? null : raw, error });
   }
   return { status: 'ok', code: null, offset: null, reason: null, values, notes,
-    ...(includeDocument ? { document: parsed                            } : {}) };
+    ...(includeDocument ? { document: parsed                           , source: text } : {}) };
 }
 
 module.exports = { MAX_BYTES, jsonFailure, validateValue, readLayerFile };

package/src/runtime/settings/prepared-run.js

@@ -188,6 +188,7 @@ function validatePrepared(doc                     , ctx     )          {
   if (Object.hasOwn(doc, 'presets') && !isObject(doc.presets)) errors.push(entry('presets', null, 'type', 'presets must be an object with review and debate preset ids'));
   let loaded      = null; // the start verb's inputs, loaded once and only when a preset is checked
   const inputs = ()      => (loaded ??= ctx.inputs(taskClass));
+  let settingsFault                = null; // a live settings fault the prepared values do not replace: one entry per preset
   for (const kind of ['review', 'debate']) {
     if (!Object.hasOwn(presets, kind)) continue;
     const order           = presetIds(protocols, kind); // the effective core order: the only ids that have a rank
@@ -201,6 +202,10 @@ function validatePrepared(doc                     , ctx     )          {
     // The effective preset setting (C-3): the user/project/local layers `review --action start` reads, with this
     // file's own entry as the project layer, applied by the resolver's rule (settingsPick) to the loosest preset.
     const settingKey = `${kind}.preset`;
+    if (settingsFault === null) {
+      try { inputs(); } catch (error     ) { if (!error.settings) throw error; settingsFault = error.message; }
+    }
+    if (settingsFault !== null) { errors.push(entry(key, null, 'settings-unavailable', settingsFault)); continue; }
     const view                      = { ...inputs().settingsView };
     const current = view[settingKey];
     if (typeof settings[settingKey] === 'string' && (!current || ['default', 'user', 'project'].includes(current.layer))) {
@@ -239,6 +244,11 @@ function report(file        , errors         , json         , notes           =
   return finishRuntime(errors.length === 0 ? 0 : 1);
 }
 
+/** The settings keys the prepared run writes to the project layer: applied before the live settings are judged. */
+function replaced(doc                     )              {
+  return new Set(isObject(doc.settings) ? Object.keys(doc.settings).filter((key) => doc.settings[key] !== null) : []);
+}
+
 function handlePreparedRun({ file, json, registry, repoRoot, projectRoot, env, fsImpl = nodeFs }     )         {
   let text        ;
   try { text = fsImpl.readFileSync(path.resolve(file), 'utf8'); } catch { return usageError('config', `cannot read the prepared run ${file}`, json); }
@@ -255,8 +265,8 @@ function handlePreparedRun({ file, json, registry, repoRoot, projectRoot, env, f
       registry, protocols: protocols.registry, classes: taskClasses(repoRoot, fsImpl), env, projectRoot: root, repoRoot, fsImpl, notes,
       // what `review --action start` loads: the protocol settings view and gates.json narrowed by the project's override
       inputs: (taskClass               )      => {
-        const inputs = require('../review/start.js').loadProtocolInputs(taskClass, root, env);
-        if ('error' in inputs) throw Object.assign(new Error(inputs.message), { usage: true });
+        const inputs = require('../review/start.js').loadProtocolInputs(taskClass, root, env, replaced(doc));
+        if ('error' in inputs) throw Object.assign(new Error(inputs.message), inputs.error === 'settings-unavailable' ? { settings: true } : { usage: true });
         return inputs;
       },
     };

package/src/runtime/settings/registry.js

@@ -294,7 +294,7 @@ function validateSettingsRegistry(raw         , refs           = { meta: REF_MET
       const safe = spec.failSafe;
       // Records and worker lists use the consumer's invalid path as their fail-safe (IC-003).
       // A project-only key's candidates never widen (resolve.ts canWiden), so no fail-safe value is ever
-      // taken; the consumer's invalid path voids it (worker/launch.ts dropDatabases), so the state form is allowed.
+      // taken; the consumer's invalid path voids it, so the state form is allowed.
       const stateSafe = (keyed || workerList || spec.scope === 'project-only') && isObject(safe) && safe.state === 'invalid';
       if (!stateSafe && (!has(spec, 'failSafe') || (isObject(safe) && !has(safe, 'gate')))) err('is securityRelevant and needs a failSafe value or {gate}');
     }

package/src/runtime/settings/resolve.js

@@ -214,6 +214,18 @@ function loadSettings({ projectRoot = null, global = false, env = process.env, r
   return view;
 }
 
+/**
+ * The registry to pass `loadSettings` with `fsImpl`: none for the real file system (the shipped one),
+ * else the registry read through that file system. Throws when it is unusable (callers fail closed).
+ */
+function registryOn(fsImpl     )                     {
+  if (fsImpl === nodeFs) return {};
+  const { loadSettingsRegistry } = require('./registry.js');
+  const loaded = loadSettingsRegistry({ fsImpl });
+  if (!loaded.ok) throw new Error(loaded.detail);
+  return { registry: loaded.registry };
+}
+
 function buildView(registry     , home     , root               , global         , env     , fsImpl     , protocols     , only                 )      {
   const { REGISTRY_FILE } = require('./registry.js');
   const { REF_META } = require('./refs.js');
@@ -710,4 +722,4 @@ function buildView(registry     , home     , root               , global
   return view;
 }
 
-module.exports = { loadSettings, clearSettingsCache };
+module.exports = { loadSettings, registryOn, clearSettingsCache };