@khoavu882/doflow 2.0.0 → 2.0.2

package/src/cli/index.js

@@ -53,6 +53,16 @@ function assertNoBackupRequiresForce(o     )       {
   }
 }
 
+/**
+ * Reports an argument error and exits. `review` answers in its own JSON usage shape when `--json` is anywhere in the
+ * arguments (before or after the bad one); every other verb prints the plain line on stderr.
+ */
+function argError(o     , argv          , message        , code        )        {
+  if (o.cmd === 'review' && argv.includes('--json')) console.log(JSON.stringify({ ok: false, error: 'usage', message }));
+  else console.error(`doflow: ${message}`);
+  process.exit(code);
+}
+
 function parseArgs(argv          )      {
   const o      = { cmd: null, positional: [], targets: [], mcp: null, dryRun: false, force: false, adopt: false,
     otlpHttp: false,
@@ -68,7 +78,7 @@ function parseArgs(argv          )      {
     if (a.startsWith('-')) o.flagsGiven.push(a);
     // `--commit` is the roadmap verb's own flag: anywhere else it must reach the default branch and get
     // that verb's unknown-flag answer, as it did before it was added. '' matches no case.
-    switch (a === '--commit' && o.cmd !== 'roadmap' ? '' : a) {
+    switch (a === '--commit' && o.cmd !== 'roadmap' ? '' : a.startsWith('--action=') ? '--action' : a) {
       case '-h': case '--help': o.help = true; break;
       case '-v': o.version = true; break;
       case '--version':
@@ -92,7 +102,7 @@ function parseArgs(argv          )      {
       case '--':
         if (o.cmd === 'slot') { o.slotCommand = argv.slice(i + 1); i = argv.length; break; }
         if (o.cmd === 'plan-check') break;
-        console.error(unknownFlagMessage(a)); process.exit(unknownFlagExit(o.cmd));
+        argError(o, argv, unknownFlagMessage(a), unknownFlagExit(o.cmd));
         break;
       // worker --action run|describe|select: the isolated-edit recipe and baseline (082 IC-014).
       case '--edit': o.edit = true; break;
@@ -148,10 +158,12 @@ function parseArgs(argv          )      {
         o.tools = val.split(',').map((s) => s.trim()).filter(Boolean); i++; break;
       }
       case '--action': {
-        const val = argv[i + 1];
+        // `--action <value>` or `--action=<value>`.
+        const inline = a.startsWith('--action=');
+        const val = inline ? a.slice('--action='.length) : argv[i + 1];
         // `review`, `protocol`, `config`, `primary` and `package` answer a missing value as usage, exit 2; other verbs keep exit 1.
-        if (val === undefined || val.startsWith('-')) { console.error(`doflow: ${a} requires a value`); process.exit(o.cmd === 'review' || o.cmd === 'protocol' || o.cmd === 'config' || o.cmd === 'primary' || o.cmd === 'fleet' || o.cmd === 'transcript' || o.cmd === 'package' ? 2 : 1); }
-        o.action = val; o.actionGiven = true; i++; break;
+        if (val === undefined || val === '' || val.startsWith('-')) argError(o, argv, '--action requires a value', o.cmd === 'review' || o.cmd === 'protocol' || o.cmd === 'config' || o.cmd === 'primary' || o.cmd === 'fleet' || o.cmd === 'transcript' || o.cmd === 'package' || o.cmd === 'worktree' ? 2 : 1);
+        o.action = val; o.actionGiven = true; if (!inline) i++; break;
       }
       case '--task-class': {
         const val = argv[i + 1];
@@ -236,7 +248,7 @@ function parseArgs(argv          )      {
         if (runtime !== null) { i = runtime; break; }
         // slot, primary, fleet and transcript report an unknown flag as their own usage error (exit 2, 115 IC-008, 120 IC-008).
         if (a.startsWith('-') && (o.cmd === 'slot' || o.cmd === 'primary' || o.cmd === 'fleet' || o.cmd === 'transcript')) (o.extraFlags = o.extraFlags || []).push(a);
-        else if (a.startsWith('-') && o.cmd !== 'plan-check') { console.error(unknownFlagMessage(a)); process.exit(unknownFlagExit(o.cmd)); }
+        else if (a.startsWith('-') && o.cmd !== 'plan-check') argError(o, argv, unknownFlagMessage(a), unknownFlagExit(o.cmd));
         else if (!o.cmd) o.cmd = a;
         else o.positional.push(a);
       }
@@ -248,18 +260,18 @@ function parseArgs(argv          )      {
 
 /** Verbs that answer an unrecognised flag as a usage error (exit 2); every other verb keeps exit 1. */
 function unknownFlagExit(cmd               )         {
-  return cmd === 'protocol' || cmd === 'config' || cmd === 'rules' || cmd === 'review' ? 2 : 1;
+  return cmd === 'protocol' || cmd === 'config' || cmd === 'rules' || cmd === 'review' || cmd === 'worktree' || cmd === 'attendance' ? 2 : 1;
 }
 
 /** Longest part of an unrecognised argument echoed back; the rest is cut and marked. */
 const UNKNOWN_FLAG_ECHO_CHARS = 80;
 
-/** The unknown-flag error: the argument is untrusted text, so it is made print-safe (no control
+/** The unknown-flag message (without the `doflow: ` prefix): the argument is untrusted text, so it is made print-safe (no control
  * characters, one line) and cut to a bounded length (FU-8eqytg). */
 function unknownFlagMessage(arg        )         {
   const safe = printSafe(String(arg));
   const shown = safe.length > UNKNOWN_FLAG_ECHO_CHARS ? `${safe.slice(0, UNKNOWN_FLAG_ECHO_CHARS)}...` : safe;
-  return `doflow: unknown flag '${shown}'`;
+  return `unknown flag '${shown}'`;
 }
 
 /** Single-value arguments of the runtime verbs → the option key each one writes. */
@@ -277,6 +289,7 @@ const RUNTIME_STRING_FLAGS = new Map([
   ['--request', 'request'],            // classify: request text for an advisory second opinion
   ['--request-file', 'requestFile'],   // classify: request text read from a file
   // decision --action add. `--statement`, `--stage`, `--slug` and `--batch` above are shared.
+  ['--run-id', 'runId'],               // intake --action undo: the sort run to undo (default: the latest)
   ['--topic', 'topic'],                // the subject key a decision is live on
   ['--channel', 'channel'],            // question | gate | prompt | default | resolution
   ['--supersedes', 'supersedes'],      // comma-separated DEC-### ids this decision replaces
@@ -434,8 +447,9 @@ const RUNTIME_STRING_FLAGS = new Map([
   ['--dir', 'dir'],                   // package --action new: authored package target directory
   ['--name', 'name'],                  // slot: the slot's name, 1 to 64 characters of a-z, 0-9 and - (115 IC-008)
   ['--label', 'label'],                // slot --action run: the holder's label, at most 80 characters (115 IC-008)
-  ['--cursor', 'cursor'],              // transcript --action read: the cursor an earlier read returned (093 IC-022)
-  ['--limit', 'limit'],                // transcript --action read: at most this many events, validated in the verb (093 IC-022)
+  ['--cursor', 'cursor'],              // transcript --action read: the cursor an earlier read returned (093 IC-022) · followup --action list: the nextCursor of an earlier page (137 IC-004)
+  ['--limit', 'limit'],                // transcript --action read: at most this many events, validated in the verb (093 IC-022) · followup --action list: the page size (137 IC-004)
+  ['--view', 'view'],                  // followup --action list, lifecycle --action overview, classify: brief or full, validated in the verb (137 IC-001)
   ['--window', 'window'],              // transcript --action stats: minutes, 1 to 60, validated in the verb (093 IC-023)
   ['--port', 'port'],                  // ui: the Console's port, 0 to 65535, checked in commands/ui.ts (092 IC-008)
 ]);
@@ -496,14 +510,14 @@ function parseRuntimeFlag(arg        , argv          , i        , o     )
     // `--batch <file|->`. Rejecting it made the documented spelling exit 2 while only `--batch=-`
     // worked — a help text endorsing a form the parser refuses.
     const isStdin = value === '-';
-    if (value === undefined || (value.startsWith('-') && !isStdin)) { console.error(`doflow: ${name} requires a value`); process.exit(2); }
+    if (value === undefined || (value.startsWith('-') && !isStdin)) argError(o, argv, `${name} requires a value`, 2);
     next = i + 1;
   }
-  if (value === '') { console.error(`doflow: ${name} requires a value`); process.exit(2); }
+  if (value === '') argError(o, argv, `${name} requires a value`, 2);
 
   if (RUNTIME_INT_FLAGS.has(name)) {
     const parsed = parseInt(value, 10);
-    if (!Number.isFinite(parsed) || parsed < 0) { console.error(`doflow: ${name} expects a non-negative integer, got '${value}'`); process.exit(2); }
+    if (!Number.isFinite(parsed) || parsed < 0) argError(o, argv, `${name} expects a non-negative integer, got '${value}'`, 2);
     o[key] = parsed;
   } else if (RUNTIME_LIST_FLAGS.has(name)) {
     // --exclude and --exclude-family both accept comma lists or repeated flags. Keep --exclude's
@@ -546,7 +560,7 @@ Commands:
   context-grant        Grant one compacted summary to a launched run and lineage (--summary, --to-run, --to-lineage)
   retrieval-plan       Declare a stage's information needs, attempt retrieval, then report every declared item
   outcome              Record a task's terminal state with its basis, or show it (--task-id)
-  classify             Validate a proposed task class and return its workflow (--task-class)
+  classify             Validate a proposed task class and return its workflow (--task-class [--view brief|full])
   workflow             Resolve a task class to its stages, gates and readiness templates
   orchestrate          Start or resume a run: complete stages, decide gates (--action)
   research-request     Open, list or resolve a feature-stage research question (--task-id)
@@ -577,15 +591,16 @@ Commands:
                        config unset <key> --layer user|project|local [--json]   remove the key from that layer's file
   scaffold             Emit the reviewable code scaffold the active feature's artifacts imply
   decision             Register, list or compact the active feature's decisions (--action init|add|list|compact)
-  followup             Record, list, take, settle, promote or report what a feature left unfinished (--action add|list|take|settle|promote|report)
-  lifecycle            Open follow-ups, feature tracking, releases and status for the project (--action overview|init|release|status|merged)
+  intake               Sort, preview, undo, list or file prompt text for the active feature's additional-context folder (--action sort|preview|undo|list|file-prompt)
+  followup             Record, list, take, settle, promote or report what a feature left unfinished (--action add|list|take|settle|promote|report; list: [--view brief|full] [--cursor <c>] [--limit <n>] [--ids <FU-id,...>])
+  lifecycle            Open follow-ups, feature tracking, releases and status for the project (--action overview|init|release|status|merged; overview: [--view brief|full])
   goal                 Add, check, link, list or close a goal and its checklist (--action add|item|check|link|list|done)
   failure              List, settle or switch off the failures DoFlow captured on this machine (--action list|settle|capture)
                        (a value beginning with '-' must be written --flag=value)
   roadmap              Session-driven autopilot runner (--action render|status|next|audit|init-policy [--check] [--row <id>] [--run <id>]).
                        roadmap --action init-policy [--commit] writes the gate policy for review, or with --commit commits it onto local develop when develop is not checked out in a worktree (otherwise it prints the commands to run there; never pushes);
                        roadmap seed --action check|apply|amend --draft <path> [--json] validates and writes new rows;
-                       rows written while autopilot is on land proposed; roadmap promote <id...> [--json] (person, autopilot off) makes them ready
+                       rows written while autopilot is on land proposed; roadmap promote <id...> [--json] (person: asks y/N on the terminal) makes them ready
   plan-check           Check a plan's task lines the way the task-attempt ledger reads them: plan-check <plan path> [--json]
   review               Validate a feature's review/findings.json; print errors, advisories and counts (exit 0 valid, 1 invalid, 2 usage).
                        review --action check [--slug <name> | --path <findings.json>] [--json]
@@ -604,6 +619,10 @@ Commands:
   transcript           Read an agent's recent events, or the project's traffic (read-only, run in a project).
                        transcript --action read --agent <key> [--cursor <c>] [--limit <n>] [--json]   masked events and DoFlow's record events (exit 0, 1 agent-not-in-project or session-not-in-project, 2 usage)
                        transcript --action stats [--window <minutes 1..60>] [--json]   events per minute, tool calls, tokens, who works with whom (exit 0, 2 usage)
+  worktree             Remove a merged feature's worktree and branch, never by force (--action cleanup).
+                       worktree --action cleanup --slug <row slug> [--json]   copies agent-docs/doflow/<slug> back to the main checkout first (exit 0 cleaned, 1 kept or lease-held with the reason, 2 usage)
+  attendance           Say whether a person is watching a stage (read-only).
+                       attendance --task-id <row slug> [--run <rl-id>] [--json]   prints "unattended <source>" or "attended <reason>" (exit 0, 2 usage)
   package              List the contribution points a package may fill, check a package directory, show the packages, add and update a local package, or turn it on and off.
                        package --action points [--json]
                        package --action check --path <dir> [--json]   (read-only; exit 0 clean, 1 findings, 2 usage)
@@ -673,6 +692,7 @@ Runtime verb arguments (accept --flag value or --flag=value):
                        failure: list|settle|capture
                        roadmap: render|status|next|audit|init-policy (seed: check|apply|amend; promote <id...>)
                        slot: run|list|peek|release
+                       worktree: cleanup
                        models: sync|list|describe
                        review: check|start
                        protocol: list|resolve
@@ -700,7 +720,9 @@ Runtime verb arguments (accept --flag value or --flag=value):
                                             disposition in the JSON; 2 usage or an unreadable store or plan)
       --rationale, --proposed-by, --calling-skill    classify
       --request <text>, --request-file <file>  classify (mutually exclusive; optional second opinion)
-      --intent, --query, --check            route
+      --view brief|full                     followup --action list (default brief), lifecycle --action overview, classify (default full); brief drops detail, full is the whole answer
+      --cursor <c>, --limit <n>             followup --action list (the cursor is opaque: pass back a page's nextCursor); also transcript --action read
+      --intent, --query, --check, --harness  route
       --statement, --claim-id,
       --evidence-id, --relation             claim
       --kind, --provenance, --provider,
@@ -772,6 +794,8 @@ Runtime verb arguments (accept --flag value or --flag=value):
       --tag, --confirm, --feature,
       --exclude (repeatable), --reason      lifecycle (release, merged)
       --fp, --as, --reason, --set, --all    failure (list, settle, capture)
+      --run-id <id>                         intake --action undo (default: the latest sort run that has a move to undo)
+      --stdin | --file <path>, --stage      intake --action file-prompt (the text, unchanged, from exactly one of --stdin or --file; --stage names the filing stage)
       --harness, --need (repeatable),
       --model-check, --budget-tokens,
       --task, --token, --prompt-file,

package/src/cli/runtime-commands.js

@@ -54,6 +54,7 @@ const { handleLeakScanCommand } = require('../runtime/leak-scan.js');
 const { handleRecoverCommand } = require('../runtime/recovery.js');
 const { handleScaffoldCommand } = require('../runtime/scaffold/generate.js');
 const { handleDecisionCommand, isReservedChannel, CHANNEL_RESERVED } = require('../runtime/decision-register.js');
+const { handleIntakeCommand } = require('../runtime/intake/index.js');
 const { handleFollowupCommand, handleLifecycleCommand, handleGoalCommand } = require('../runtime/lifecycle/cli.js');
 const { projectRoot: lifecycleProjectRoot } = require('../runtime/lifecycle/root.js');
 const { upkeepAfterVerb } = require('../runtime/storage/upkeep.js');
@@ -66,6 +67,8 @@ const { handleProtocolCommand } = require('../runtime/review/protocol-command.js
 const { handleRulesCommand } = require('../runtime/rules-report.js');
 const { handlePackageCommand } = require('../runtime/packages/command.js');
 const { handleModelsCommand } = require('../runtime/models/command.js');
+const { handleWorktreeCommand } = require('../runtime/roadmap/worktree-cleanup.js');
+const { handleAttendanceCommand } = require('../runtime/roadmap/attendance.js');
 // `plan-check` is read-only (115 IC-001): no upkeep, which would write `.gitignore` and `upkeep-due`.
 // `review` writes only its one telemetry line (095 IC-003).
 // `protocol` only prints the registry and the resolved protocol (119 IC-004), so it has nothing to keep up.
@@ -73,9 +76,10 @@ const { handleModelsCommand } = require('../runtime/models/command.js');
 // `primary` only prints the resolved main session (120 IC-008) and writes nothing.
 // `fleet` only lists the projects this machine knows from two read-only stores (093 IC-019) and writes nothing.
 // `transcript` only reads agents' transcripts and DoFlow's own records and prints them (093 IC-022, IC-023); it writes nothing.
+// `attendance` is read-only; `worktree --action cleanup` removes a merged feature's worktree under the roadmap lease and writes no DoFlow state, so neither runs upkeep.
 // `package` stays here (122 IC-012): `new` writes only the target folder; `add --plan`, `update --plan` and `remove` write the store and lock and run upkeep (see `runsUpkeep`).
 // `slot` is not here: `run`, `list` and `release` write the slot files and run upkeep; only `slot --action peek` is read-only and skips it (093 IC-018 b, see `runsUpkeep`).
-const NO_UPKEEP = new Set(['storage', 'config', 'plan-check', 'review', 'protocol', 'rules', 'primary', 'package', 'models', 'fleet', 'transcript']);
+const NO_UPKEEP = new Set(['storage', 'config', 'plan-check', 'review', 'protocol', 'rules', 'primary', 'package', 'models', 'fleet', 'transcript', 'worktree', 'attendance']);
 const runsUpkeep = (o     )          => (!NO_UPKEEP.has(o.cmd) && !(o.cmd === 'slot' && o.actionGiven && o.action === 'peek'))
   || (o.cmd === 'package' && ((typeof o.planId === 'string' && (o.action === 'add' || o.action === 'update')) || o.action === 'remove'));
 // Required on first use, so a CLI whose failure modules cannot be loaded still runs every other verb.
@@ -378,10 +382,12 @@ function dispatchRuntimeCommandInner(o     , moment     )      {
     // The feature is resolved from the working directory (or --slug) by the same resolver
     // `scaffold` uses; the flags are the caller's own statements, validated by the register module.
     case 'decision': return handleDecisionCommand({ action: o.action, projectRoot: evidenceRoot(o), slug: o.slug, json: o.json, flags: { topic: o.topic, statement: o.statement, channel: o.channel, stage: o.stage, rationale: o.rationale, supersedes: o.supersedes, refs: o.refs, source: o.source, batch: o.batchPath, all: o.all } });
+    // 136: the feature is resolved the way `decision` resolves it; the engine moves files only inside its additional-context folder.
+    case 'intake': return handleIntakeCommand({ action: o.action, projectRoot: evidenceRoot(o), slug: o.slug, json: o.json, flags: { runId: o.runId, stdin: o.stdin, file: o.file, stage: o.stage } });
     // Feature 046: the project's follow-up store lives at the repository root (never `-g`, which
     // the handlers refuse), so the working directory is the starting point, not a scope switch.
-    case 'followup': return handleFollowupCommand({ action: o.actionGiven ? o.action : undefined, cwd: evidenceRoot(o), global: o.global, slug: o.slug, json: o.json, flags: { statement: o.statement, stage: o.stage, source: o.source, taskClass: o.taskClass, taskId: o.taskId, release: o.release, batch: o.batchPath, channel: o.channel, state: o.state, ids: o.ids, as: o.as, reason: o.reason, evidence: o.evidence, title: o.title, file: o.file, stdin: o.stdin, text: o.text, feature: o.feature, tag: o.tag, confirm: o.confirm, exclude: o.exclude } });
-    case 'lifecycle': return handleLifecycleCommand({ action: o.actionGiven ? o.action : undefined, cwd: evidenceRoot(o), global: o.global, slug: o.slug, json: o.json, flags: { take: o.take, intent: o.intent, goal: o.goal, maintain: o.maintain, since: o.since, tag: o.tag, confirm: o.confirm, feature: o.feature, exclude: o.exclude, reason: o.reason, channel: o.channel } });
+    case 'followup': return handleFollowupCommand({ action: o.actionGiven ? o.action : undefined, cwd: evidenceRoot(o), global: o.global, slug: o.slug, json: o.json, flags: { statement: o.statement, stage: o.stage, source: o.source, taskClass: o.taskClass, taskId: o.taskId, release: o.release, batch: o.batchPath, channel: o.channel, state: o.state, ids: o.ids, view: o.view, cursor: o.cursor, limit: o.limit, as: o.as, reason: o.reason, evidence: o.evidence, title: o.title, file: o.file, stdin: o.stdin, text: o.text, feature: o.feature, tag: o.tag, confirm: o.confirm, exclude: o.exclude } });
+    case 'lifecycle': return handleLifecycleCommand({ action: o.actionGiven ? o.action : undefined, cwd: evidenceRoot(o), global: o.global, slug: o.slug, json: o.json, flags: { view: o.view, take: o.take, intent: o.intent, goal: o.goal, maintain: o.maintain, since: o.since, tag: o.tag, confirm: o.confirm, feature: o.feature, exclude: o.exclude, reason: o.reason, channel: o.channel } });
     case 'goal': return handleGoalCommand({ action: o.actionGiven ? o.action : undefined, cwd: evidenceRoot(o), global: o.global, slug: o.slug, json: o.json, flags: { goal: o.goal, statement: o.statement, item: o.item, text: o.text, evidence: o.evidence, unmet: o.unmet, replace: o.replace, reason: o.reason, channel: o.channel } });
     // The failure store is per machine, so `-g` changes nothing and the working directory only matters
     // to `settle --as imported`, which looks for the DoFlow repository from there.
@@ -389,7 +395,7 @@ function dispatchRuntimeCommandInner(o     , moment     )      {
     // The rest of design §4.2's Node arm. REPO_ROOT locates the registries that ship with the
     // package (workflows, capabilities, verification); evidenceRoot(o) locates the caller's own
     // state and source tree, following the same scope rules as every other command.
-    case 'classify': return handleClassifyCommand({ taskClass: o.taskClass, rationale: o.rationale, proposedBy: o.proposedBy, callingSkill: o.callingSkill, request: o.request, requestFile: o.requestFile, taskId: o.taskId, projectRoot: evidenceRoot(o), json: o.json });
+    case 'classify': return handleClassifyCommand({ taskClass: o.taskClass, rationale: o.rationale, proposedBy: o.proposedBy, callingSkill: o.callingSkill, view: o.view, request: o.request, requestFile: o.requestFile, taskId: o.taskId, projectRoot: evidenceRoot(o), json: o.json });
     case 'workflow': return handleWorkflowCommand({ taskClass: o.taskClass, json: o.json });
     case 'orchestrate': return handleOrchestrateCommand({ action: o.action, taskId: o.taskId, taskClass: o.taskClass, stage: o.stage, gate: o.gate, node: o.node, decision: o.decision, policy: o.policy, note: o.note, reason: o.reason, forced: o.forced, verificationPlan: o.verificationPlan, scope: o.scope, invariants: o.invariants, result: o.result, mcpOutcome: o.mcpOutcome, callingSkill: o.callingSkill, slug: o.slug, recordSlug: storeSlug, dryRun: o.dryRun, json: o.json, repoRoot: REPO_ROOT, stateRoot: storeRoot, sourceRoot: evidenceRoot(o), buildAdapters: buildAdapterRegistry });
     case 'research-request': return handleResearchRequestCommand({ slug: storeSlug, action: o.action === 'status' ? 'list' : o.action, taskId: requireTaskId(o), stageId: o.stageId, question: o.question, reason: o.reason, blocking: o.blocking === undefined ? undefined : o.blocking === 'true' ? true : o.blocking === 'false' ? false : o.blocking, requestId: o.requestId, outcome: o.researchOutcome, claimId: o.claimId, evidenceIds: o.evidenceIds, gap: o.gap, json: o.json, projectRoot: storeRoot, sourceRoot: evidenceRoot(o) });
@@ -409,7 +415,7 @@ function dispatchRuntimeCommandInner(o     , moment     )      {
     case 'brief-tools': return handleBriefToolsCommand({ owner: o.owner, tier: o.tier, harness: o.harness, slug: o.slug, headingLevel: o.headingLevel, tasks: o.tasks, json: o.json, repoRoot: REPO_ROOT, projectRoot: storeRoot, buildAdapters: buildAdapterRegistry });
     case 'advise': return handleAdviseCommand({ action: o.action, actionGiven: o.actionGiven, kind: o.kind, server: o.server, state: o.state, stateFile: o.stateFile, staticAnswer: o.staticAnswer, questionsFile: o.questionsFile, taskId: o.taskId, pickId: o.pickId, actual: o.actual, model: o.model, endpoint: o.endpoint, off: o.off, project: o.project, force: o.force, global: o.global, json: o.json, projectRoot: evidenceRoot(o) });
     case 'model-role': return handleModelRoleCommand({ role: o.role, exclude: o.exclude, excludeFamilies: o.excludeFamily, json: o.json, repoRoot: REPO_ROOT });
-    case 'route': return handleRouteCommand({ intent: o.intent, query: o.query, check: o.check, json: o.json, projectRoot: evidenceRoot(o) });
+    case 'route': return handleRouteCommand({ intent: o.intent, query: o.query, harness: o.harness, check: o.check, json: o.json, projectRoot: evidenceRoot(o) });
     case 'claim': return handleClaimCommand({ slug: storeSlug, taskId: requireTaskId(o), action: o.action, statement: o.statement, claimId: o.claimId, evidenceId: o.evidenceId, replacedBy: o.replacedBy, relation: o.relation, role: o.role, json: o.json, stateRoot: storeRoot });
     case 'context-pack': return handleContextPackCommand({ taskId: requireTaskId(o), taskClass: o.taskClass, objective: o.objective, json: o.json, stateRoot: storeRoot, sourceRoot: evidenceRoot(o), slug: storeSlug, explicitSlug: o.slug || null, mandatoryFile: o.mandatoryFile, harness: o.harness, maxBytes: o.maxBytes, bare: o.bare, noRecord: o.noRecord, reason: o.reason, since: o.since, expand: o.expand });
     // 078 IC-005 and IC-013: identity is the process environment's alone, never a flag.
@@ -432,6 +438,8 @@ function dispatchRuntimeCommandInner(o     , moment     )      {
     case 'fleet': return handleFleetCommand({ action: o.actionGiven ? o.action : undefined, json: o.json, flags: o.flagsGiven, env: process.env, cwd: process.cwd() });
     case 'transcript': return handleTranscriptCommand({ action: o.actionGiven ? o.action : undefined, agent: o.agent, cursor: o.cursor, limit: o.limit, window: o.window, json: o.json, flags: o.flagsGiven, env: process.env, cwd: process.cwd() });
     case 'models': return handleModelsCommand({ action: o.actionGiven ? o.action : (o.positional?.[0] || 'list'), positional: o.positional, harness: o.harness, model: o.model, json: o.json, projectRoot: evidenceRoot(o) });
+    case 'worktree': return handleWorktreeCommand({ action: o.actionGiven ? o.action : undefined, slug: o.slug, json: o.json, flags: o.flagsGiven, env: process.env, cwd: process.cwd() });
+    case 'attendance': return handleAttendanceCommand({ taskId: o.taskId, run: o.run, json: o.json, flags: o.flagsGiven, env: process.env, cwd: process.cwd() });
     default: console.error(`doflow: unknown command '${o.cmd}'`); process.exit(1);
   }
 }

package/src/cli/shared.js

@@ -10,7 +10,7 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const { REPO_ROOT } = require('../helper/repo-root.js');
-const { doflowPaths } = require('../install/paths.js');
+const { doflowPaths, canonicalPath, canonicalLedger } = require('../install/paths.js');
 const { readInstallManifest } = require('../install/manifest.js');
 const { DEFAULT_BACKUP_RETENTION, formatBytes } = require('../install/backup.js');
 const { stateRoot, readLedger } = require('../state/index.js');
@@ -64,7 +64,9 @@ function buildAdapterRegistry()      {
 
 /** Resolve {global, projectRoot} scope options for src/install/targets.js#toolDirs from parsed args. */
 function scopeOf(o     )                                           {
-  return { global: o.global, projectRoot: o.positional[0] || '.' };
+  // The single place a project path enters the verbs: canonical, so an aliased spelling (macOS
+  // /var -> /private/var) and the real one name the same scope, ledger rows and lock.
+  return { global: o.global, projectRoot: o.global ? (o.positional[0] || '.') : canonicalPath(o.positional[0] || '.') };
 }
 
 function installPaths(scope     )      {
@@ -141,7 +143,7 @@ function scopeSelectionState(scope     )      {
   const scopeRoot = scope.global ? os.homedir() : path.resolve(scope.projectRoot);
   return {
     lock: readLock(scope.global ? { scope: 'global', homeDir: scopeRoot } : { scope: 'project', projectRoot: scopeRoot }),
-    ledger: readLedger(stateRoot({ scope: scope.global ? 'global' : 'project', projectRoot: scopeRoot, homeDir: scopeRoot })),
+    ledger: canonicalLedger(readLedger(stateRoot({ scope: scope.global ? 'global' : 'project', projectRoot: scopeRoot, homeDir: scopeRoot })), scopeRoot),
     manifestServers: readInstallManifest({ scopeRoot })?.mcpServers ?? null,
   };
 }

package/src/helper/marker-merge.js

@@ -70,8 +70,7 @@ function mergeMarkedSection(srcAbs        , dstAbs        , { dryRun = false, co
       // original file's matching trailing "\n" (if present) must be consumed here —
       // otherwise a replace with no real change grows the file by one newline
       // every time it runs (breaks idempotency).
-      let afterEnd = endIdx + MARKER_END.length;
-      if (existing[afterEnd] === '\n') afterEnd += 1;
+      const afterEnd = afterEndMarker(existing, endIdx + MARKER_END.length);
       newContent = existing.slice(0, startIdx) + section + existing.slice(afterEnd);
     }
   }
@@ -84,10 +83,16 @@ function mergeMarkedSection(srcAbs        , dstAbs        , { dryRun = false, co
   return { changed: true };
 }
 
+/** `at` moved past the one line break (LF or CRLF) that follows an end marker, if there is one. */
+function afterEndMarker(text        , at        )         {
+  if (text[at] === '\n') return at + 1;
+  return text[at] === '\r' && text[at + 1] === '\n' ? at + 2 : at;
+}
+
 /**
  * Where `text`'s doflow span is: the first of `startMarkers`, the first MARKER_END after it, and no
  * start marker after that end (a second span is `malformed`). `after` is past the end marker and the
- * one '\n' that follows it.
+ * one line break (LF or CRLF) that follows it.
  */
 function markedSpan(text        , startMarkers           = [MARKER_START])                                                                                             {
   const found = startMarkers.map((marker) => ({ at: text.indexOf(marker), length: marker.length })).filter((item) => item.at !== -1);
@@ -95,10 +100,9 @@ function markedSpan(text        , startMarkers           = [MARKER_START])
   const first = found.reduce((a, b) => (b.at < a.at ? b : a));
   const end = text.indexOf(MARKER_END, first.at + first.length);
   if (end === -1) return { state: 'malformed' };
-  let after = end + MARKER_END.length;
-  if (startMarkers.some((marker) => text.indexOf(marker, after) !== -1)) return { state: 'malformed' };
-  if (text[after] === '\n') after += 1;
-  return { state: 'ok', start: first.at, after };
+  const closed = end + MARKER_END.length;
+  if (startMarkers.some((marker) => text.indexOf(marker, closed) !== -1)) return { state: 'malformed' };
+  return { state: 'ok', start: first.at, after: afterEndMarker(text, closed) };
 }
 
 /**

package/src/install/backup-set.js

@@ -89,8 +89,9 @@ function addCandidate(candidates                  , file        , harness
  * lock); an entry at or under one of them is reported in `excluded`, not backed up.
  * `records` lists DoFlow record files backed up beside those files although an `exclude` root holds
  * them (the ownership ledger), with no harness; a rollback restores only the ledger rows of the files
- * it writes back (backup.ts mergeRestoredLedger). They join only a set that holds some file already,
- * so a run that backs up nothing still backs up nothing.
+ * it writes back (backup.ts mergeRestoredLedger). They join a set that holds some file already, or one whose
+ * plan gives up a retired harness's ledger row (only the ledger is then snapshotted); a run that changes
+ * neither backs up nothing.
  */
 function backupSetFromPlan({ plan, scope, scopeRoot, exclude = [], records = [], fsImpl = fs }     )      {
   const candidates = new Map();
@@ -131,7 +132,10 @@ function backupSetFromPlan({ plan, scope, scopeRoot, exclude = [], records = [],
   const excluded = [...mcpOnly]
     .filter(([target, onlyMcp]) => onlyMcp && !candidates.has(target))
     .map(([target]) => ({ path: target, reason: 'mcp-entries-only' }));
-  if (candidates.size) for (const file of records) addCandidate(candidates, file, null, 'record');
+  // A retired harness's row given up (every sweep action but `defer`) is a ledger change even when no file
+  // changes: the ledger alone is snapshotted then, so a rollback restores the row. Deferred rows stay.
+  const givesUpRow = plan.changes.some((change     ) => change.retired === true && change.action !== 'defer');
+  if (candidates.size || givesUpRow) for (const file of records) addCandidate(candidates, file, null, 'record');
   return toBackupSet(candidates, { scope, scopeRoot, exclude, excluded, records, fsImpl });
 }
 

package/src/install/backup.js

@@ -591,11 +591,12 @@ function planRestore({ bid, backupRoot, scope, scopeRoot, targets, explicitTarge
  * staler than the current one; a current row of it the backup lacks stays. A restored row whose file
  * a live harness now claims is released by the next sweep (claim rule 2), file untouched.
  */
-function mergeRestoredLedger(backup     , current     , restored             , retired              = new Set())      {
+function mergeRestoredLedger(backup     , current     , restored             , retired              = new Set(), lost              = new Set())      {
   if (!current) return backup;
   const at = (target     ) => typeof target === 'string' && restored.has(path.resolve(target));
   const whole = (row     ) => retired.has(row?.harness);
-  const back = backup.resources.filter((r     ) => at(r.target) || whole(r));
+  // A retired row whose file this restore tried and could not write back stays out: it would name a file the next sweep drops as absent.
+  const back = backup.resources.filter((r     ) => at(r.target) || (whole(r) && !(typeof r.target === 'string' && lost.has(path.resolve(r.target)))));
   const backKeys = new Set(back.filter(whole).map(ownershipKey));
   const targets = Object.entries(backup.targets ?? {}).filter(([id]) => retired.has(id));
   return {
@@ -610,20 +611,23 @@ function mergeRestoredLedger(backup     , current     , restored             , r
 }
 
 /** Ids the registry retires (row 127 IC-001): `registry` when a caller passes one, else the shipped
- * registry. One that cannot be read retires nothing, which leaves the merge per restored file. */
+ * registry. One that cannot be read throws, so a restore stops before it writes anything rather than
+ * silently skipping the retired rows and targets. */
 function retiredIds(registry     )              {
   if (registry === undefined) {
     const { REPO_ROOT } = require('../helper/repo-root.js');
-    try { registry = require('../registry/index.js').loadRegistry({ repoRoot: REPO_ROOT }); } catch { registry = null; }
+    try { registry = require('../registry/index.js').loadRegistry({ repoRoot: REPO_ROOT }); } catch (err     ) {
+      throw new BackupError(`cannot read the registry to find retired harnesses: ${err?.message ?? err}`);
+    }
   }
   return new Set((Array.isArray(registry?.retired) ? registry.retired : []).map((entry     ) => entry?.id).filter((id     ) => typeof id === 'string'));
 }
 
 /** The bytes a ledger restore item writes: the backup's ledger merged onto the current one. */
-function restoredLedgerBytes(item     , restored             , retired             , fsImpl     )         {
+function restoredLedgerBytes(item     , restored             , retired             , lost             , fsImpl     )         {
   const backup = validateLedger(JSON.parse(fsImpl.readFileSync(item.stored, 'utf8')));
   const current = fsImpl.existsSync(item.path) ? validateLedger(JSON.parse(fsImpl.readFileSync(item.path, 'utf8'))) : null;
-  return Buffer.from(`${JSON.stringify(validateLedger(mergeRestoredLedger(backup, current, restored, retired)), null, 2)}\n`);
+  return Buffer.from(`${JSON.stringify(validateLedger(mergeRestoredLedger(backup, current, restored, retired, lost)), null, 2)}\n`);
 }
 
 /**
@@ -641,6 +645,8 @@ function executeRestore(plan     , { backupRoot, dryRun = false, registry, fsImp
     return { restored: plan.v1.tools.map((t     ) => t.tool), failed: [], absent: [], refused: [], untargeted: 0, legacy: true };
   }
 
+  // Read before the first write: an unreadable registry stops the restore with nothing changed.
+  const retired = dryRun || plan.narrowed || !plan.restore.some((item     ) => item.ledger) ? new Set        () : retiredIds(registry);
   const restored = [];
   const failed = [];
   const files = new Set        ();
@@ -654,7 +660,7 @@ function executeRestore(plan     , { backupRoot, dryRun = false, registry, fsImp
     try {
       const dir = path.dirname(item.path);
       fsImpl.mkdirSync(dir, { recursive: true });
-      const bytes = item.ledger ? restoredLedgerBytes(item, files, plan.narrowed ? new Set() : retiredIds(registry), fsImpl) : fsImpl.readFileSync(item.stored);
+      const bytes = item.ledger ? restoredLedgerBytes(item, files, retired, new Set([...failed.map((f     ) => f.path), ...plan.refused.map((f     ) => f.path)].filter((p     ) => typeof p === 'string').map((p        ) => path.resolve(p))), fsImpl) : fsImpl.readFileSync(item.stored);
       let isLink = false;
       try {
         isLink = fsImpl.lstatSync(item.path).isSymbolicLink();

package/src/install/context.js

@@ -7,6 +7,7 @@
 // native type-stripping — no build step, no runtime dependency. Body stays CommonJS so a `.js`
 // caller's `require('../install/context.js')` keeps working while the tree is still `.js`.
 const path = require('node:path');
+const { canonicalPath } = require('./paths.js');
 const { sourceCommit: gitSourceCommit } = require('../helper/git.js');
 
                                
@@ -27,7 +28,7 @@ const { sourceCommit: gitSourceCommit } = require('../helper/git.js');
 function resolveContext({ repoRoot, global, projectRoot, targets, dirs, sourceCommit, managedResources }                     )      {
   const context      = {
     scope: global ? 'global' : 'project',
-    scopeRoot: global ? path.dirname(dirs.claude) : path.resolve(projectRoot),
+    scopeRoot: global ? path.dirname(dirs.claude) : canonicalPath(projectRoot),
     targets,
     dirs: Object.fromEntries(targets.map((t) => [t, dirs[t]])),
     repoRoot,

package/src/install/manifest.js

@@ -25,6 +25,20 @@ function canonicalManifestPath(scopeRoot        )         {
   return path.join(path.resolve(scopeRoot), '.doflow', MANIFEST_FILE_NAME);
 }
 
+/** Atomic same-directory write of the manifest document. */
+function atomicWrite(file        , manifest        , date      )       {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  // Security: the temp file must live next to `file` itself, not a shared os.tmpdir() — a
+  // world-writable /tmp plus a PID+timestamp-derived (i.e. guessable) name is a symlink-race
+  // waiting to happen (plant a symlink at the predicted path, the write clobbers its target).
+  // 'wx' (O_CREAT|O_EXCL) refuses to open through an existing symlink or file at all, and being
+  // on the same filesystem as `file` makes the final rename a guaranteed atomic same-fs op
+  // (os.tmpdir() offered no such guarantee — e.g. containers where /tmp is a separate tmpfs mount).
+  const tmp = path.join(path.dirname(file), `.install-manifest-${process.pid}-${date.getTime()}.json.tmp`);
+  fs.writeFileSync(tmp, `${JSON.stringify(manifest, null, 2)}\n`, { flag: 'wx' });
+  fs.renameSync(tmp, file); // atomic on the same filesystem, matches sync.sh's mktemp + mv
+}
+
                               
                      
                      
@@ -88,19 +102,29 @@ function writeManifest({ scopeRoot, claudeDir, scriptVersion, operation, repoRoo
   const resources = managedResources ?? existingManagedResources;
   if (resources !== undefined) manifest.managed_resources = resources;
 
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  // Security: the temp file must live next to `file` itself, not a shared os.tmpdir() — a
-  // world-writable /tmp plus a PID+timestamp-derived (i.e. guessable) name is a symlink-race
-  // waiting to happen (plant a symlink at the predicted path, the write clobbers its target).
-  // 'wx' (O_CREAT|O_EXCL) refuses to open through an existing symlink or file at all, and being
-  // on the same filesystem as `file` makes the final rename a guaranteed atomic same-fs op
-  // (os.tmpdir() offered no such guarantee — e.g. containers where /tmp is a separate tmpfs mount).
-  const tmp = path.join(path.dirname(file), `.install-manifest-${process.pid}-${date.getTime()}.json.tmp`);
-  fs.writeFileSync(tmp, `${JSON.stringify(manifest, null, 2)}\n`, { flag: 'wx' });
-  fs.renameSync(tmp, file); // atomic on the same filesystem, matches sync.sh's mktemp + mv
+  atomicWrite(file, manifest, date);
   return file;
 }
 
+/**
+ * After a removal: stop listing `tools` as installed. Nothing else in the record changes except the
+ * operation and time, and a missing or unreadable manifest is left alone (nothing lists them).
+ * Returns whether the file was rewritten.
+ */
+function forgetManifestTools({ scopeRoot, tools, date = new Date() }                                                     )          {
+  const file = canonicalManifestPath(scopeRoot);
+  if (!fs.existsSync(file)) return false;
+  let manifest     ;
+  try { manifest = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return false; }
+  const listed = tools.filter((tool) => manifest?.tools && Object.hasOwn(manifest.tools, tool));
+  if (!listed.length) return false;
+  for (const tool of listed) delete manifest.tools[tool];
+  manifest.last_operation = 'remove';
+  manifest.last_run = date.toISOString().replace(/\.\d+Z$/, 'Z');
+  atomicWrite(file, manifest, date);
+  return true;
+}
+
 /** null if no manifest yet. */
 function readManifestFile(file        )      {
   if (!fs.existsSync(file)) return null;
@@ -141,5 +165,5 @@ function readManifest(claudeDir        )      {
 
 module.exports = {
   LEGACY_MANIFEST_FILE_NAME, MANIFEST_FILE_NAME, manifestPath, canonicalManifestPath,
-  writeManifest, readManifest, readInstallManifest,
+  writeManifest, forgetManifestTools, readManifest, readInstallManifest,
 };

package/src/install/paths.js

@@ -3,6 +3,7 @@
 // TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): authored as `.ts`, run directly by Node
 // native type-stripping — no build step, no runtime dependency. Body stays CommonJS so a `.js`
 // caller's `require('../install/paths.js')` keeps working while the rest of the tree is still `.js`.
+const fs = require('node:fs');
 const path = require('node:path');
 
 const DOFLOW_DIR_NAME = '.doflow';
@@ -72,7 +73,44 @@ function doflowPaths({ scopeRoot }            )              {
   };
 }
 
+/** The one spelling of a path that ownership comparisons use: `fs.realpathSync` of the resolved path,
+ * or the resolved path itself when it does not exist (nothing to follow yet). macOS reaches the
+ * temp folder as both /var/... and /private/var/..., and a ledger row written under one spelling
+ * must match the other. */
+function canonicalPath(target        )         {
+  const resolved = path.resolve(target);
+  try { return fs.realpathSync(resolved); } catch { return resolved; }
+}
+
+function rebaseString(value        , from        , to        )         {
+  if (value === from) return to;
+  return value.startsWith(from + path.sep) ? to + value.slice(from.length) : value;
+}
+
+function rebaseDeep(value     , from        , to        )      {
+  if (typeof value === 'string') return rebaseString(value, from, to);
+  if (Array.isArray(value)) return value.map((item) => rebaseDeep(item, from, to));
+  if (value && typeof value === 'object') {
+    const out      = {};
+    for (const key of Object.keys(value)) out[key] = rebaseDeep(value[key], from, to);
+    return out;
+  }
+  return value;
+}
+
+/** A ledger read from disk, with every path that names the scope root under a different spelling of
+ * it (the aliased path an earlier install recorded) rewritten to `scopeRoot`, the canonical one.
+ * The stored format is unchanged; a ledger already in canonical form, with no scope root of its
+ * own, or recording an unrelated directory is returned as it came. */
+function canonicalLedger(ledger     , scopeRoot        )      {
+  const recorded = ledger && typeof ledger.scopeRoot === 'string' && ledger.scopeRoot ? path.resolve(ledger.scopeRoot) : null;
+  if (!recorded || recorded === scopeRoot || canonicalPath(recorded) !== scopeRoot) return ledger;
+  return rebaseDeep(ledger, recorded, scopeRoot);
+}
+
 module.exports = {
+  canonicalPath,
+  canonicalLedger,
   DOFLOW_DIR_NAME,
   BACKUP_DIR_NAME,
   INSTALL_MANIFEST_FILE_NAME,

package/src/install/targets.js

@@ -14,6 +14,7 @@
 // caller's `require('../install/targets.js')` keeps working while the rest of the tree is still `.js`.
 const os = require('node:os');
 const path = require('node:path');
+const { canonicalPath } = require('./paths.js');
 
 const VALID = ['claude', 'codex', 'copilot', 'kiro', 'opencode', 'pi', 'antigravity'];
 
@@ -58,6 +59,14 @@ function resolveTargets(requested                      , { registry }
   return [...new Set(targets)];
 }
 
+/** The harnesses an install manifest lists as installed, in VALID order; [] when there is no
+ * manifest or it lists none DoFlow still knows (a retired id is not a target). `update` without
+ * `-t` acts on these instead of DEFAULT_TARGETS, so it never installs a harness the scope lacks. */
+function installedTargets(manifest     )           {
+  const tools = manifest?.tools ?? {};
+  return VALID.filter((id) => Object.hasOwn(tools, id) && tools[id]?.installed !== false);
+}
+
                            
                    
                        
@@ -91,7 +100,7 @@ function resolveTargets(requested                      , { registry }
  */
 function toolDirs(opts                  = {})                         {
   const { global = false, projectRoot = '.' } = opts;
-  const root = global ? os.homedir() : path.resolve(projectRoot);
+  const root = global ? os.homedir() : canonicalPath(projectRoot);
   return {
     claude: path.join(root, '.claude'),
     codex: path.join(root, '.codex'),
@@ -102,4 +111,4 @@ function toolDirs(opts                  = {})                         {
   };
 }
 
-module.exports = { VALID, DEFAULT_TARGETS, resolveTargets, toolDirs };
+module.exports = { VALID, DEFAULT_TARGETS, resolveTargets, installedTargets, toolDirs };