@khoavu882/doflow 2.0.0 → 2.0.1

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;
     }
@@ -1107,6 +1115,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/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/slots.js

@@ -185,7 +185,7 @@ const refuse = (why        ) => Object.assign(new Error(why), { code: 'EBUSY' })
  * directory name this lock does not make once the lock is 10 s old, as in task-state. An older
  * runtime's lock (its `owner.json` token) is judged the same way. `reclaimed` records that this acquire
  * judged a lock reclaimable, so it holds only after `quiet` (every reclaim quiets; user ruling, 117
- * decisions: amends 115 C-4's "dead owner reclaimed at once"). See docs/architecture.md, "The slot lock".
+ * decisions: amends 115 C-4's "dead owner reclaimed at once").
  */
 function slotLock(fsImpl     , deps     ) {
   const start = deps.procStart(deps.pid);

package/src/runtime/task-classifier.js

@@ -6,7 +6,8 @@ const path = require('node:path');
 const fs = require('node:fs');
 const { TextDecoder } = require('node:util');
 const { WorkflowEngine, CALLER_ROLES } = require('./workflow-engine.js');
-const { finishRuntime } = require('./cli-result.js');
+const { finishRuntime, usageError } = require('./cli-result.js');
+const { ViewUsageError, resolveView, projectBrief, viewLines, withEnvelope, emitJson } = require('./verb-view.js');
 const { REPO_ROOT } = require('../helper/repo-root.js');
 const { loadAdviceRegistry } = require('./advice/registry.js');
 const { createAdviceClient } = require('./advice/client.js');
@@ -421,6 +422,25 @@ class TaskClassifier {
   }
 }
 
+/**
+ * The brief view of a classify answer (feature 137, IC-005): the fields the skills' classify call sites read.
+ * Everything else is dropped; `--view full` returns the whole object.
+ */
+const CLASSIFY_BRIEF = Object.freeze({
+  verb: 'classify',
+  carry: Object.freeze(['taskClass', 'callingSkill']),
+  keep: Object.freeze([
+    '$.outcome', '$.taskClass', '$.proposedClass', '$.callingSkill', '$.reason', '$.message', '$.validClasses',
+    '$.suggestions', '$.callerSuggestions', '$.fit.state', '$.fit.reason', '$.fit.hostingClasses', '$.secondOpinion',
+    '$.workflow.taskClass', '$.workflow.handoff', '$.workflow.stageIds', '$.workflow.hasImplementationStage',
+    '$.workflow.requiresImplementationReadiness', '$.workflow.stages[].id', '$.workflow.stages[].skill',
+    '$.workflow.stages[].agent', '$.workflow.stages[].kind', '$.workflow.stages[].optional',
+    '$.workflow.stages[].readinessTemplate', '$.workflow.stages[].mutatesSource', '$.workflow.gates[].id',
+    '$.workflow.gates[].afterStage', '$.workflow.gates[].kind', '$.workflow.gates[].trigger',
+    '$.workflow.gates[].prompt',
+  ]),
+});
+
 /**
  * Handles `doflow classify` — validate a proposed task class against the workflow registry.
  *
@@ -437,16 +457,31 @@ class TaskClassifier {
  * @param {string} [options.request] request text for a second opinion
  * @param {string} [options.requestFile] file containing request text for a second opinion
  * @param {boolean} [options.json=false]
+ * @param {string} [options.view] `brief` or `full` (default): the JSON answer's view; text output is the same in both
  * @returns {number|Promise<number>} exit code; advisory calls are asynchronous
  */
-function handleClassifyCommand({ taskClass, rationale, proposedBy, callingSkill, request, requestFile, taskId, projectRoot, env = process.env, json = false }      = {}) {
+function handleClassifyCommand({ taskClass, rationale, proposedBy, callingSkill, request, requestFile, taskId, projectRoot, view, env = process.env, json = false }      = {}) {
+  let resolvedView;
+  try {
+    resolvedView = resolveView(view, 'full');
+  } catch (error     ) {
+    if (error instanceof ViewUsageError) return usageError('classify', error.message, json);
+    throw error;
+  }
+  const printJson = (opinion     ) => {
+    const answer = { ...decision, secondOpinion: opinion };
+    if (resolvedView === 'full') return emitJson(answer);
+    return emitJson(withEnvelope(projectBrief(answer, CLASSIFY_BRIEF.keep), {
+      view: 'brief', next: viewLines('full', { spec: CLASSIFY_BRIEF, carried: { taskClass, callingSkill }, json: true }),
+    }));
+  };
   const classifier = new TaskClassifier({ repoRoot: REPO_ROOT });
   const decision = classifier.classify({ taskClass, rationale, proposedBy, callingSkill });
   const exitCode = decision.outcome === CLASSIFICATION_OUTCOMES.ACCEPTED
     ? 0 : decision.reason === REJECTION_REASONS.MISSING_CLASS ? 2 : 1;
   const hasRequest = request !== undefined || requestFile !== undefined;
   if (!hasRequest) {
-    if (json) console.log(JSON.stringify({ ...decision, secondOpinion: null }, null, 2));
+    if (json) printJson(null);
     else printClassifyDecision(decision, null);
     return finishRuntime(exitCode);
   }
@@ -528,7 +563,7 @@ function handleClassifyCommand({ taskClass, rationale, proposedBy, callingSkill,
         opinion = emptySecondOpinion('unavailable', 'config-invalid');
       }
     }
-    if (json) console.log(JSON.stringify({ ...decision, secondOpinion: opinion }, null, 2));
+    if (json) printJson(opinion);
     else printClassifyDecision(decision, opinion);
     return finishRuntime(exitCode);
   }

package/src/runtime/task-state.js

@@ -103,8 +103,7 @@ function sleep(ms        )       {
 // Runtimes from before this protocol see a directory they did not create: they wait on a fresh one,
 // and on a stale one their rmdir fails (it is not empty), so they fail closed ("Could not lock",
 // `store-locked`) instead of taking it; their release of a lock reclaimed from them fails the same
-// way. Whatever a process leaves when it dies is reclaimed once LOCK_STALE_MS old. The bounds (what
-// this does not cover) are listed once, in docs/architecture.md under "The task-state lock".
+// way. Whatever a process leaves when it dies is reclaimed once LOCK_STALE_MS old.
 const OWNER_PREFIX = 'owner-';
 // The longest a fresh acquire may take from its mkdir to its entry and still trust the directory is
 // its own: half the stale age, so a process that judged it stale cannot have done so before the
@@ -307,7 +306,7 @@ function ownedRelease(fsImpl     , lockDir        , me       )      {
     try { fsImpl.rmdirSync(entry); } catch { return; } // reclaimed: the lock is not ours to remove
     // Removed only if it is still that directory: a release stalled here past LOCK_STALE_MS may find
     // an older runtime's new (empty) lock at the path. What stays is the gap between this stat and the
-    // rmdir (docs/architecture.md, "The task-state lock", bound 3).
+    // rmdir.
     try {
       if (mine && sameDir(mine, fsImpl.statSync(lockDir))) fsImpl.rmdirSync(lockDir);
     } catch { /* a waiting process's entry is in it; that process holds next */ }