@khoavu882/doflow 2.0.0 → 2.0.2

package/src/runtime/review/start.js

@@ -109,15 +109,16 @@ function readBounded(file        , maxBytes        )
   }
 }
 
-function parseRecordLines(file        )                                         {
+function parseRecordLines(file        )                                                       {
   const read = readBounded(file, MAX_RECORD_BYTES);
   if ('error' in read) return { error: read.error };
+  const text = 'text' in read ? read.text : '';
   const records        = [];
-  for (const [index, line] of ('text' in read ? read.text : '').split('\n').entries()) {
+  for (const [index, line] of text.split('\n').entries()) {
     if (!line.trim()) continue;
     try { records.push(JSON.parse(line)); } catch (error     ) { return { error: `line ${index + 1}: ${error.message}` }; }
   }
-  return { records };
+  return { records, text };
 }
 
                                                                                             
@@ -243,20 +244,23 @@ function loadGatePolicy(cwd               )
  * is on, so the class seat floor binds; maint-thin), the gate policy (the shipped gates.json narrowed by the
  * project's `.doflow/gates.override.json`, read as roadmap gate-b reads it, 119 IC-005; null when there is no task class, so
  * no floor), the protocols registry and the enforcement inputs (`loadEnforcementInputs`). A base, override or registry the loaders reject is a refusal carrying the loader's
- * reason (and the override file). Shared with the `protocol` verb.
+ * reason (and the override file). Shared with the `protocol` verb. `replaced` names the settings a prepared run
+ * (`config validate --prepared-run`) writes to the project layer: an invalid project candidate of such a key is
+ * replaced by it, so it does not refuse here.
  */
-function loadProtocolInputs(taskClass               , cwd        , env                                     = process.env) 
+function loadProtocolInputs(taskClass               , cwd        , env                                     = process.env, replaced                      = new Set()) 
                                                                                                                                                                                                                             {
   const settingsView                                                    = {};
   try {
     const settings = require('../settings/resolve.js').loadSettings({ projectRoot: path.resolve(cwd), env });
     for (const key of PROTOCOL_SETTINGS) {
       const resolution = settings.get(key);
-      // C-6: an invalid project or local review.* candidate would silently fall back to the default: refuse instead.
-      // A preset key refuses an invalid user candidate too.
-      const invalid = key.endsWith('.preset') ? invalidPresetCandidate(resolution)
-        : key.startsWith('review.') ? invalidProjectCandidate(resolution) : undefined;
-      if (invalid) return { error: 'settings-unavailable', message: `${key} in ${invalid.source}: ${invalid.reason}` };
+      // C-6: an invalid project or local review.* candidate would silently fall back to the default: refuse instead,
+      // except a project candidate that a prepared run replaces. A preset key refuses an invalid user candidate too.
+      const judged = replaced.has(key) ? { ...resolution, candidates: (resolution.candidates ?? []).filter((c     ) => c.layer !== 'project') } : resolution;
+      const stands = key.endsWith('.preset') ? invalidPresetCandidate(judged)
+        : key.startsWith('review.') ? invalidProjectCandidate(judged) : undefined;
+      if (stands) return { error: 'settings-unavailable', message: `${key} in ${stands.source}: ${stands.reason}` };
       settingsView[key] = { value: resolution.value, layer: resolution.origin.layer };
     }
   } catch (error     ) {
@@ -429,12 +433,14 @@ async function handleReviewStart({ slug, base, preset, json = false, cwd, env, r
     result.applicable = result.notApplicable === null;
 
     let nextCommand                = null;
+    let seen                                                               = null;
     if (result.applicable) {
       const state = readHeadState(cwd, env);
       result.head = state.head;
       result.clean = state.clean;
       const parsed = parseRecordLines(verificationRunRecordFile(verificationRunsRoot(cwd), verifyId          ));
       if ('error' in parsed) return refuse('records-unreadable', parsed.error);
+      seen = { head: state.head, clean: state.clean, text: parsed.text };
       result.reasons = reviewPrecondition({ records: parsed.records, head: state.head, clean: state.clean, slug: verifyId });
       if (result.reasons.length) {
         result.ok = false;
@@ -507,6 +513,14 @@ async function handleReviewStart({ slug, base, preset, json = false, cwd, env, r
     const decided = resolveProtocol({ ...facts, advicePick: null });
     if (!decided.ok) return refuseResolution(decided.reason);
     const advice = await askAdvice({ decision: { depth: decided.protocol.depth, scope }, risk: result.risk, taskClass, slug: resolvedSlug, files: paths ? paths.length : null, cwd, env, adviceClient });
+    // The advice await can take a while: what the precondition and the risk were read from must still stand.
+    if (seen && advice.status !== 'off') {
+      const now = readHeadState(cwd, env);
+      const records = parseRecordLines(verificationRunRecordFile(verificationRunsRoot(cwd), verifyId          ));
+      if (now.head !== seen.head || now.clean !== seen.clean || 'error' in records || records.text !== seen.text) {
+        return refuse('state-moved', 'HEAD, the working tree or the verification records changed while the advice was asked; run review start again');
+      }
+    }
     const resolved = resolveProtocol({ ...facts, advicePick: advice.pick });
     if (!resolved.ok) return refuseResolution(resolved.reason);
     const { protocol } = resolved;

package/src/runtime/roadmap/attendance.js

@@ -0,0 +1,137 @@
+'use strict';
+
+/**
+ * `doflow-run attendance --task-id <slug> [--run <id>]` (autonomy plan section 2): a read-only answer
+ * to "is a person watching this stage?", printed as `unattended <source>` or `attended <reason>`, exit
+ * 0. A skill reads it once per stage and resolves its own questions to recorded defaults when the
+ * answer is `unattended`; no hook reads it.
+ *
+ * `unattended` when either holds:
+ *   (a) `DOFLOW_SESSION_ROLE` is `worker` (the launcher sets it), matched case-insensitively and
+ *       literally: an unrecognised value is NOT a worker here, although the hook identity policy
+ *       treats it as one, because uncertainty must read as `attended`; or
+ *   (b) all of: the run record `.doflow/state/roadmap/runs/<run>.json` is open (no `closedAt`); its
+ *       slot for the seed row with this slug holds a `perform` or the loop's `postMerge` marker (the stage is
+ *       still pending; the loop clears the marker on its next merge step) and no `held` or
+ *       `paused` mark; that row is not on `hold`; and the autopilot kill switch is enabled (the reader the policy decisions use).
+ * Anything else, including a missing or unreadable record, is `attended`. The signal is derived from
+ * state the runtime owns; a forged value only reaches the verbs the forging session itself calls.
+ *
+ * This module is imported only by the CLI. The person-only code (seed, autopilot settings, config
+ * write, gates, decision register, package trust, merge) never imports it nor reads
+ * `DOFLOW_SESSION_ROLE` (test/guards/attendance-scope.test.ts).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { listCheckouts } = require('../checkouts.js');
+
+const RUN_ID = /^rl-[0-9]{8}-[0-9a-hjkmnp-tv-z]{4}$/;
+const ALLOWED_FLAGS = new Set(['--task-id', '--run', '--json']);
+
+function mainRootOf(cwd        )         {
+  try {
+    const info = listCheckouts({ cwd });
+    if (info && info.ok && info.main) return info.main;
+  } catch { /* fall back to the working directory */ }
+  return path.resolve(cwd);
+}
+
+/**
+ * The validation loop.ts readRunFile applies (steps, n and log included). loop.ts does not export it
+ * and is edited in parallel by other packages, so the check is repeated here; a record that fails it
+ * is unreadable to the loop and therefore reads as `attended`, never as a signal.
+ */
+function validRecord(value     )          {
+  return Boolean(value) && value.schema === 1 && typeof value.runId === 'string' && RUN_ID.test(value.runId)
+    && Number.isSafeInteger(value.steps) && Number.isSafeInteger(value.n)
+    && Boolean(value.rows) && typeof value.rows === 'object' && Array.isArray(value.log)
+    && typeof value.createdAt === 'string';
+}
+
+function readRecord(file        , fsImpl     )      {
+  const value = JSON.parse(fsImpl.readFileSync(file, 'utf8'));
+  if (!validRecord(value)) throw new Error('not a schema 1 run record');
+  return value;
+}
+
+/** The named run's record, else the newest open one; null when there is none. Throws when unreadable. */
+function loadRun(runsDir        , requested                    , fsImpl     )      {
+  if (requested) {
+    try { return readRecord(path.join(runsDir, `${requested}.json`), fsImpl); }
+    catch (error     ) { if (error.code === 'ENOENT') return null; throw error; }
+  }
+  let names          ;
+  try { names = fsImpl.readdirSync(runsDir); }
+  catch (error     ) { if (error.code === 'ENOENT') return null; throw error; }
+  const open = names.filter((name) => /^rl-.*\.json$/.test(name)).sort()
+    .map((name) => readRecord(path.join(runsDir, name), fsImpl))
+    .filter((record) => !record.closedAt)
+    .sort((a, b) => (a.createdAt < b.createdAt ? -1 : a.createdAt > b.createdAt ? 1 : a.runId < b.runId ? -1 : 1));
+  return open.at(-1) || null;
+}
+
+/**
+ * @param {{taskId: string, run?: string, env?: object, cwd?: string, root?: string, fsImpl?: object, readKillSwitch?: Function}} options
+ * @returns {{attendance: 'unattended'|'attended', source?: string, reason?: string, run?: string}}
+ */
+function resolveAttendance(options      = {})      {
+  const env = options.env || process.env;
+  const fsImpl = options.fsImpl || fs;
+  const attended = (reason        ) => ({ attendance: 'attended', reason });
+  if (String(env.DOFLOW_SESSION_ROLE || '').toLowerCase() === 'worker') return { attendance: 'unattended', source: 'worker-role' };
+
+  const root = options.root || mainRootOf(options.cwd || process.cwd());
+  let record     ;
+  try { record = loadRun(path.join(root, '.doflow', 'state', 'roadmap', 'runs'), options.run, fsImpl); }
+  catch { return attended('run-unreadable'); }
+  if (!record) return attended('no-run');
+  if (record.closedAt) return attended('run-closed');
+
+  let rows       ;
+  try { rows = require('./rows.js').parseSeed(fsImpl.readFileSync(path.join(root, 'agent-docs', 'roadmap', 'rows.json'), 'utf8')).rows; }
+  catch { return attended('seed-unreadable'); }
+  const row = rows.find((entry     ) => entry && entry.slug === options.taskId);
+  if (!row) return attended('row-unknown');
+  if (row.hold) return attended('row-held');
+  const slot = record.rows?.[row.id];
+  // A held or paused slot is machine state the loop stopped on for a person (hold, gate, dispatch, budget).
+  if (slot?.held) return attended('slot-held');
+  if (slot?.paused) return attended('slot-paused');
+  // A finished row has no stage left, whatever marker an interrupted step left behind.
+  if (slot?.done) return attended('slot-done');
+  // A pending stage is the slot's `perform`, or the marker the loop leaves when it issues the post-merge
+  // verification perform (that perform is returned without being stored as slot.perform).
+  const perform = slot?.perform;
+  const postMerge = slot?.postMerge;
+  const performPending = Boolean(perform) && typeof perform === 'object' && typeof perform.stage === 'string';
+  const postMergePending = Boolean(postMerge) && typeof postMerge === 'object' && postMerge.purpose === 'post-merge' && typeof postMerge.stage === 'string';
+  if (!performPending && !postMergePending) return attended('no-pending-perform');
+
+  let enabled = false;
+  try { enabled = (options.readKillSwitch || require('../settings/autopilot.js').readKillSwitch)(env).enabled === true; } catch { enabled = false; }
+  if (!enabled) return attended('switch-off');
+  return { attendance: 'unattended', source: 'run-record', run: record.runId };
+}
+
+/** The CLI handler: exit 0 with the answer, 2 for a usage fault. */
+function handleAttendanceCommand(options      = {})         {
+  const json = Boolean(options.json);
+  const usage = (detail        )         => {
+    if (json) console.log(JSON.stringify({ schema: 1, error: 'usage', detail }));
+    else console.error(`doflow attendance: error: ${detail}`);
+    process.exitCode = 2;
+    return 2;
+  };
+  const extra = ((options.flags || [])            ).map((flag) => flag.split('=')[0]).find((flag) => !ALLOWED_FLAGS.has(flag));
+  if (extra !== undefined) return usage(`unsupported flag ${extra}; only --task-id, --run and --json apply`);
+  if (typeof options.taskId !== 'string' || !options.taskId) return usage('--task-id <row slug> is required');
+  if (options.run !== undefined && !RUN_ID.test(String(options.run))) return usage('--run must be rl-<yyyymmdd>-<4 crockford characters>');
+  const answer = resolveAttendance({ taskId: options.taskId, run: options.run, env: options.env, cwd: options.cwd });
+  if (json) console.log(JSON.stringify({ schema: 1, ...answer }));
+  else console.log(answer.attendance === 'unattended' ? `unattended ${answer.source}${answer.run ? ` ${answer.run}` : ''}` : `attended ${answer.reason}`);
+  process.exitCode = 0;
+  return 0;
+}
+
+module.exports = { resolveAttendance, handleAttendanceCommand };

package/src/runtime/roadmap/gates.js

@@ -251,10 +251,13 @@ function evaluate(policy     , cls        , gateId        , facts       )      {
         const decisions = Array.isArray(backing?.decisions) ? backing.decisions.filter(object) : [];
         for (const finding of converged) {
           if (finding.status === 'refuted' && !evidenceLocator(finding.evidence)) reasons.push(`refuted-without-evidence:${finding.id}`);
-          if (finding.status === 'user-accepted' && !decisions.some((d     ) => d.id === finding.decision && USER_CHANNELS.has(d.channel))) reasons.push(`accepted-without-user-decision:${finding.id}`);
+          // AU D4: a note or should-fix may rest on a default-channel (agent) decision, so an unattended session
+          // records what it decided without claiming a person did. A blocker (or any other severity) keeps both checks.
+          const blocker = finding.severity !== 'note' && finding.severity !== 'should-fix';
+          if (finding.status === 'user-accepted' && !decisions.some((d     ) => d.id === finding.decision && (USER_CHANNELS.has(d.channel) || (!blocker && d.channel === 'default')))) reasons.push(`accepted-without-user-decision:${finding.id}`);
           // C5: any session can add a question-channel register entry, so channel membership is not a
-          // person. Policy evaluation never accepts a user-accepted disposition; a person decides that gate.
-          if (finding.status === 'user-accepted') reasons.push(`user-accepted-needs-person:${finding.id}`);
+          // person. Policy evaluation never accepts a user-accepted blocker; a person decides that gate.
+          if (finding.status === 'user-accepted' && blocker) reasons.push(`user-accepted-needs-person:${finding.id}`);
           if (finding.status === 'fixed' && backing?.ancestors?.[finding.fixedIn] !== true) reasons.push(`fixed-not-ancestor:${finding.id}`);
         }
       }

package/src/runtime/roadmap/loop.js

@@ -15,6 +15,7 @@ const path = require('node:path');
 const crypto = require('node:crypto');
 const { execFileSync: defaultExecFileSync } = require('node:child_process');
 const { listCheckouts } = require('../checkouts.js');
+const { readRegularFileText } = require('../task-scope.js');
 const { withGitMemo } = require('../git-memo.js');
 const {
   parseSeed,
@@ -23,6 +24,7 @@ const {
   render,
   renderRoadmapFile,
   check,
+  LOOP_CLASSES,
 } = require('./rows.js');
 const { gatherGitFacts, sha256Digest } = require('./facts.js');
 const { loadPolicy, verifyRecordReasons } = require('./gates.js');
@@ -376,6 +378,8 @@ const PLAN_FILES = ['plan.md', 'planning/plan.md'];
 const DISPATCH_ACTOR = 'doflow-dispatch';
 /** The actor this loop names in the dispatch commands it yields. */
 const LOOP_ACTOR = 'doflow-roadmap';
+/** The envelope's attendance field: the literal the stage skill reads. attendance.ts (P3) owns the verb and the rule. */
+const attendanceOf = (runId        )                                      => ({ mode: 'unattended', run: runId });
 const QUOTA = /^quota\b/i;
 /** Stage artifacts, two layouts each (the decision-register.ts artifact list). */
 const DOC_ARTIFACTS                           = {
@@ -658,11 +662,17 @@ const tripwireFile = (ctx     )         => path.join(ctx.dir, 'tripwire', 'event
 function readTripwire(ctx     )      {
   const file = tripwireFile(ctx);
   try {
-    const value = JSON.parse(ctx.fsImpl.readFileSync(file, 'utf8'));
+    try { ctx.fsImpl.lstatSync(file); } catch (error     ) {
+      if (error.code === 'ENOENT') return { schema: 1, reverts: [], unverified: [] };
+      throw error;
+    }
+    // A bounded read: a link, a FIFO or a file over the record cap is never opened as the record.
+    const text = readRegularFileText(file, ctx.fsImpl);
+    if (text === null) throw new Error('not a regular file within the record size cap');
+    const value = JSON.parse(text);
     if (!value || value.schema !== 1 || !Array.isArray(value.reverts) || !Array.isArray(value.unverified)) throw new Error('not a schema 1 tripwire record');
     return value;
   } catch (error     ) {
-    if (error.code === 'ENOENT') return { schema: 1, reverts: [], unverified: [] };
     throw new Unreadable(['tripwire'], error.message);
   }
 }
@@ -680,21 +690,37 @@ function runRecordFileOf(checkout        , row     )         {
   return verificationRunRecordFile(verificationRunsRoot(checkout), row.slug);
 }
 
-/** IC-008: the bytes a stage must change. The implementation artifact is the feature branch head. */
-function stageArtifact(ctx     , row     , worktree        , stage        )                                              {
-  if (stage === 'implementation') {
+/** Stage kinds with no file of their own: performed = a new, non-backfilled handoff of the stage (AU-P1). */
+const HANDOFF_ONLY_KINDS = ['reproduction', 'analysis', 'retrieval'];
+
+/** The stage kind of a program node, else the stage id (the feature chain's ids are its kinds). */
+const kindOf = (run     , stage        )         => (run?.program || []).find((n     ) => n?.type === 'stage' && n.id === stage)?.kind ?? stage;
+
+/**
+ * IC-008: the bytes a stage must change, keyed by the stage's KIND so a class's own stage ids
+ * (regression-verification, authoring, ...) resolve. implementation and synthesis: the feature
+ * branch head; verification: the verify run record; reproduction, analysis, retrieval: no file,
+ * the count of the stage's handoffs; the rest: the stage's document.
+ */
+function stageArtifact(ctx     , row     , worktree        , stage        , kind         = stage, run      = null)                                              {
+  if (kind === 'implementation' || kind === 'synthesis') {
     const { featureHead } = readHeads(ctx, row);
     return { artifact: `refs/heads/feat/${row.slug}`, sha256: sha256Digest(featureHead) };
   }
-  if (stage === 'verification') {
+  if (HANDOFF_ONLY_KINDS.includes(kind)) {
+    const handoffs = (run?.history || []).filter((entry     ) => entry && entry.node === stage
+      && ((entry.action === 'complete-stage' && !entry.backfilled) || entry.action === 'annotate')).length;
+    return { artifact: `handoff:${stage}`, sha256: sha256Digest(String(handoffs)) };
+  }
+  if (kind === 'verification') {
     // Where `verify --action report` appends (IC-007): the lifecycle root, not the feature checkout.
     const file = runRecordFileOf(worktree, row);
     try { return { artifact: file, sha256: sha256Digest(ctx.fsImpl.readFileSync(file)) }; }
     catch (error     ) { if (error.code === 'ENOENT') return { artifact: file, sha256: null }; throw new Unreadable([`artifact:${file}`], error.message); }
   }
   const base = artifactRootOf(ctx, row, worktree);
-  const candidates = DOC_ARTIFACTS[stage];
-  if (!candidates) throw new Unreadable([`stage:${stage}`], `no artifact is declared for stage '${stage}'`);
+  const candidates = DOC_ARTIFACTS[kind];
+  if (!candidates) throw new Unreadable([`stage:${stage}`], `no artifact is declared for stage '${stage}' (kind '${kind}')`);
   for (const rel of candidates) {
     try { return { artifact: rel, sha256: sha256Digest(ctx.fsImpl.readFileSync(path.join(base, rel))) }; }
     catch (error     ) { if (error.code !== 'ENOENT') throw new Unreadable([`artifact:${path.join(base, rel)}`], error.message); }
@@ -726,33 +752,47 @@ function verifyArgvOf(ctx     , row     , worktree        )                  {
   return typeof script === 'string' && script.trim() ? ['npm', 'test'] : null;
 }
 
+/**
+ * `verify --scope`: the change-scope tier is required at every risk level and resolves from a plan or
+ * a declared scope. Four loop classes declare theirs in the readiness record (verify refuses a flag
+ * that differs from it); documentation has no readiness stage and no plan, so the row's own write set
+ * is its declared scope.
+ */
+const scopeFlagsOf = (row     )           => (row.class === 'documentation' && Array.isArray(row.writeSet) && row.writeSet.length
+  ? ['--scope', row.writeSet.join(',')] : []);
+
 /** IC-008 envelope. Argv arrays only: the session runs them, nothing here is a shell string. */
-function envelopeFor(ctx     , row     , worktree        , stage        , skill        , before     , verifyCommand                  = null)      {
+function envelopeFor(ctx     , row     , worktree        , stage        , skill        , before     , verifyCommand                  = null,
+  kind         = stage, dispatches          = stage === 'implementation')      {
   const handoff = ['orchestrate', '--action', 'handoff', '--task-id', row.slug, '--calling-skill', skill, '--note', '<text>'];
   const base = { outcome: 'perform', runId: ctx.record.runId, row: row.id, slug: row.slug, stage, skill, worktree,
-    artifactRoot: artifactRootOf(ctx, row, worktree), before, issuedAt: ctx.now().toISOString() };
+    artifactRoot: artifactRootOf(ctx, row, worktree), before, issuedAt: ctx.now().toISOString(), attendance: attendanceOf(ctx.record.runId) };
   const next = ['roadmap', '--action', 'next', '--run', ctx.record.runId];
-  if (stage === 'verification') {
-    return { ...base, after: [['verify', '--action', 'report', '--task-id', row.slug, '--baseline-ref', mergeBaseOf(ctx, row)], handoff], next };
+  if (kind === 'verification') {
+    return { ...base, after: [['verify', '--action', 'report', '--task-id', row.slug, '--baseline-ref', mergeBaseOf(ctx, row), ...scopeFlagsOf(row)], handoff], next,
+      afterNote: 'verify exits non-zero for a FAIL or INCONCLUSIVE result and still records it: run the handoff next whatever it exits' };
   }
-  if (stage !== 'implementation') return { ...base, after: handoff, next };
+  // Only the feature chain dispatches workers (plan tasks); the other classes' implementation is a plain stage.
+  // Nothing but the session commits its edits here, and a stage whose branch head did not move is not performed.
+  if (!dispatches) return { ...base, ...(kind === 'implementation' || kind === 'synthesis' ? { commit: { branch: `feat/${row.slug}` } } : {}), after: handoff, next };
   return { ...base, after: [
-    ['dispatch', '--action', 'start', '--slug', row.slug, '--by', LOOP_ACTOR, '--billing-cap', 'free', ...(verifyCommand ? ['--verify-argv', JSON.stringify(verifyCommand)] : [])],
+    ['dispatch', '--action', 'start', '--slug', row.slug, '--by', LOOP_ACTOR, '--billing-cap', 'free', '--fallback', 'auto', ...(verifyCommand ? ['--verify-argv', JSON.stringify(verifyCommand)] : [])],
     ['dispatch', '--action', 'run', '--slug', row.slug, '--by', LOOP_ACTOR],
     handoff,
   ], next };
 }
 
 /** IC-008: performed = the artifact exists, its bytes changed, and the stage's own handoff is newer. */
-function performedCheck(ctx     , row     , worktree        , run     , perform     )                                {
-  const current = stageArtifact(ctx, row, worktree, perform.stage);
+function performedCheck(ctx     , row     , worktree        , run     , perform     )                                                     {
+  const current = stageArtifact(ctx, row, worktree, perform.stage, kindOf(run, perform.stage), run);
   if (current.sha256 === null) return { ok: false, current };
 
   // FU-rcshhx: allow adopting rows whose design/plan artifacts were already completed and recorded
-  // in the orchestration run history, even if current.sha256 === perform.before?.sha256.
+  // in the orchestration run history, even if current.sha256 === perform.before?.sha256. A completion that a
+  // later skill's catch-up only backfilled is not such a record (AU-P1).
   const isDesignOrPlan = perform.stage === 'design' || perform.stage === 'planning';
   const alreadyCompleted = isDesignOrPlan && (run.history || []).some((entry     ) =>
-    entry && entry.node === perform.stage && (entry.action === 'complete-stage' || entry.action === 'annotate')
+    entry && entry.node === perform.stage && ((entry.action === 'complete-stage' && !entry.backfilled) || entry.action === 'annotate')
   );
   if (alreadyCompleted) return { ok: true, current };
 
@@ -761,7 +801,7 @@ function performedCheck(ctx     , row     , worktree        , run     , perform
   const handedOff = (run.history || []).some((entry     ) => entry && entry.node === perform.stage
     && ((entry.action === 'complete-stage' && !entry.backfilled) || entry.action === 'annotate')
     && Date.parse(entry.at) > issued);
-  return { ok: handedOff, current };
+  return { ok: handedOff, current, handedOff };
 }
 
 function orchestrationFor(ctx     , row     , worktree        )                          {
@@ -775,7 +815,9 @@ function orchestrationFor(ctx     , row     , worktree        )
   // artifactRootOf finds it (the feature checkout, else the main one).
   const planExitCheck = () => require('../plan-content.js').planStageExit({ roots: [...new Set([worktree, runRoot, ctx.root])], slug: row.slug });
   const orch = new WorkflowOrchestrator({ repoRoot: ctx.repoRoot, projectRoot: runRoot, sourceRoot: worktree,
-    stateDir: path.join(runRoot, '.doflow', 'state', 'orchestration'), featureSlug: row.slug, fsImpl: ctx.fsImpl, env: ctx.env, cwd: worktree, planExitCheck });
+    stateDir: path.join(runRoot, '.doflow', 'state', 'orchestration'), featureSlug: row.slug, fsImpl: ctx.fsImpl, env: ctx.env, cwd: worktree, planExitCheck,
+    // FR-006, as the orchestrate verb wires it: the ledger is found from any checkout of the row.
+    taskAttemptCheck: () => require('../task-attempts.js').checkCompletion({ slug: row.slug, cwd: worktree, fsImpl: ctx.fsImpl }) });
   let run     ;
   try { run = orch.readRun(row.slug); } catch (error     ) { throw new Unreadable([source], error.message); }
   if (run && (!Array.isArray(run.program) || !Number.isInteger(run.cursor) || typeof run.state !== 'string' || !Array.isArray(run.history))) {
@@ -981,6 +1023,10 @@ async function mergeStep(ctx     , row     , source
   const intent = source.intent || null;
   let gate      = null;
   let approvedHead                = null;
+  // The attendance marker of an earlier post-merge perform is consumed by this call (re-set below when the
+  // verification is still pending), so it never outlives the step it names. It is not a `perform`: the
+  // performed checks and the merge step read only slot.perform and the merge intent.
+  delete slot.postMerge;
   if (intent && slot.held?.kind === 'intent') delete slot.held;
   if (!intent) {
     const entry = [...source.run.history].reverse().find((h     ) => h?.action === 'decide-gate' && h.node === 'gate-b' && h.detail === 'approve');
@@ -1020,8 +1066,11 @@ async function mergeStep(ctx     , row     , source
       const before = { artifact: runRecordFileOf(intent.developWorktree, row), sha256: null };
       const perform = { outcome: 'perform', runId: ctx.record.runId, row: row.id, slug: row.slug, stage: 'verification', skill: 'do-test',
         purpose: 'post-merge', worktree: intent.developWorktree, artifactRoot: null, head: intent.commit, before, issuedAt: ctx.now().toISOString(),
-        after: ['verify', '--action', 'report', '--task-id', row.slug, '--baseline-ref', intent.developHead, ...postMergePlan(ctx, row, intent)],
+        attendance: attendanceOf(ctx.record.runId),
+        after: ['verify', '--action', 'report', '--task-id', row.slug, '--baseline-ref', intent.developHead, ...postMergePlan(ctx, row, intent), ...scopeFlagsOf(row)],
         next: ['roadmap', '--action', 'next', '--run', ctx.record.runId] };
+      // AU-P10: the one fact attendance.ts reads to answer `unattended` for this stage (the envelope above says so too).
+      slot.postMerge = { stage: 'verification', purpose: 'post-merge', head: intent.commit, issuedAt: perform.issuedAt };
       return finish(ctx, { outcome: 'perform', row: row.id, slug: row.slug, perform });
     }
   }
@@ -1115,19 +1164,20 @@ async function gateStep(ctx     , row     , orch     , gateId        , worktree
     audit: `${gateId} ${row.slug} denied by policy: ${result.reasons.join(', ')}${result.rule ? ` (rule ${result.rule})` : ''}` });
 }
 
-function performStep(ctx     , row     , worktree        , node     )      {
+function performStep(ctx     , row     , worktree        , node     , run     )      {
   const slot = (ctx.record.rows[row.id] ||= {});
-  if (node.id === 'review') {
+  const kind = node.kind ?? node.id;
+  if (kind === 'review') {
     // IC-007: gate-b's own verify rule, applied before the review envelope is spent. No question, no prompt.
     const head = readHeads(ctx, row).featureHead;
     const reasons = postMergeReasons(row, worktree, head, ctx.fsImpl);
     if (reasons.length) {
       return heldDeny(ctx, row, 'review', reasons[0],
-        sha256Digest(JSON.stringify({ reasons, head, record: stageArtifact(ctx, row, worktree, 'verification').sha256 })), { step: 'review', reasons });
+        sha256Digest(JSON.stringify({ reasons, head, record: stageArtifact(ctx, row, worktree, 'verification', 'verification').sha256 })), { step: 'review', reasons });
     }
     if (slot.held?.kind === 'review') delete slot.held;
   }
-  slot.perform = envelopeFor(ctx, row, worktree, node.id, node.skill, stageArtifact(ctx, row, worktree, node.id));
+  slot.perform = envelopeFor(ctx, row, worktree, node.id, node.skill, stageArtifact(ctx, row, worktree, node.id, kind, run), null, kind, false);
   return finish(ctx, { outcome: 'perform', row: row.id, slug: row.slug, perform: slot.perform });
 }
 
@@ -1238,7 +1288,7 @@ function implementationStep(ctx     , row     , worktree        )      {
         slot.perform = envelopeFor(ctx, row, worktree, 'implementation', 'do-execute-plan',
           { artifact: `refs/heads/feat/${row.slug}`, sha256: slot.claimHead ? sha256Digest(slot.claimHead) : null }, verifyCommand);
       }
-      return finish(ctx, { ...base, outcome: 'denied', reason: 'stage-not-performed', rule: 'perform/implementation', perform: slot.perform });
+      return hold('stage-not-performed', { outcome: 'denied', reason: 'stage-not-performed', rule: 'perform/implementation', perform: slot.perform });
     }
     case 'blocked':
       return hold('stuck', { outcome: 'blocked', reason: 'stuck', rule: facts.repeated ? 'dispatch/repeated' : 'dispatch/blocked', annotations: { dispatch: 'blocked', cause: facts.cause } });
@@ -1252,10 +1302,32 @@ function implementationStep(ctx     , row     , worktree        )      {
   }
 }
 
+/**
+ * A feature run gets its decision register from do-brainstorm, which creates the folder. The other
+ * classes have no such stage, and gate-b's policy approval is recorded in that register, so the loop
+ * creates it once, before any artifact lands in the folder. A folder that already holds artifacts and
+ * no register is left alone (initRegister's `predates-register`): the gate then names it unreadable.
+ */
+function ensureRegister(ctx     , row     , worktree        )      {
+  const { initRegister } = require('../decision-register.js');
+  const featureDir = path.join(worktree, 'agent-docs', 'doflow', row.slug);
+  if (ctx.fsImpl.existsSync(path.join(featureDir, 'decisions', 'register.json'))) {
+    if (ctx.record.rows[row.id]?.held?.kind === 'register') delete ctx.record.rows[row.id].held;
+    return null;
+  }
+  const stop = boundary(ctx, row);
+  if (stop) return stop;
+  const made = initRegister({ featureDir, slug: row.slug, fsImpl: ctx.fsImpl });
+  if (!made.finding) return null;
+  // The folder predates a register: gate-b could not record its approval. Denied once, then held by digest.
+  return heldDeny(ctx, row, 'register', 'facts-unreadable', sha256Digest(JSON.stringify([made.finding, made.message])),
+    { step: 'pick', rule: 'loop/facts', annotations: { unreadable: ['decision-register'], finding: made.finding } });
+}
+
 /** One in-flight row: pending perform check, then its orchestration state. Returns a result or a skip. */
 async function stepRow(ctx     , row     , worktrees                     )               {
   const slot = (ctx.record.rows[row.id] ||= {});
-  if (row.class !== 'feature') return { skip: 'class-unsupported' };
+  if (!LOOP_CLASSES.includes(row.class)) return { skip: 'class-unsupported' };
   // A seed hold (decision C8) also stops autopilot from advancing a row already in flight.
   if (row.hold) return { skip: 'row-held' };
   // maint-thin: so does a proposed row (a branch a person started by hand); a person promotes it first.
@@ -1268,13 +1340,19 @@ async function stepRow(ctx     , row     , worktrees                     )
     // A claim interrupted after `worktree add`: finish it.
     const stop = boundary(ctx, row);
     if (stop) return stop;
-    orch.start({ taskId: row.slug, taskClass: 'feature', now: ctx.now() });
+    orch.start({ taskId: row.slug, taskClass: row.class, now: ctx.now(), loopProgram: true });
     return finish(ctx, { outcome: 'acted', step: 'pick', row: row.id, slug: row.slug, annotations: { worktree }, audit: `pick ${row.slug}: run started in ${worktree}` });
   }
+  if (row.class !== 'feature') {
+    const refused = ensureRegister(ctx, row, worktree);
+    if (refused) return refused;
+  }
   const node = run.cursor < run.program.length ? run.program[run.cursor] : null;
-  const atImplementation = run.state === 'RUNNING' && node?.type === 'stage' && node.id === 'implementation';
+  // Only the feature chain dispatches workers at implementation; any other class's implementation is a plain stage.
+  const dispatches = row.class === 'feature';
+  const atImplementation = dispatches && run.state === 'RUNNING' && node?.type === 'stage' && node.id === 'implementation';
   if (slot.perform && !(atImplementation && slot.perform.stage === 'implementation')) {
-    if (slot.perform.stage === 'implementation') {
+    if (dispatches && slot.perform.stage === 'implementation') {
       // The session handed off right after `dispatch run`: land the dispatch before checking the head.
       const landing = landDispatch(ctx, row, worktree, dispatchFactsOf(ctx, row));
       if (landing) return landing;
@@ -1289,16 +1367,29 @@ async function stepRow(ctx     , row     , worktrees                     )
       }
     }
     if (!checked.ok) {
+      // K59: a stage that never hands off is denied once per input state, then held by digest, so it
+      // neither spends a step per call nor keeps other rows from advancing. A changed artifact or a
+      // new handoff changes the digest and the stage is judged again.
+      const digest = sha256Digest(JSON.stringify({ stage: slot.perform.stage, sha256: checked.current.sha256, handedOff: Boolean(checked.handedOff) }));
+      if (slot.held?.kind === 'stage' && slot.held.inputsDigest === digest) return { skip: `held:${slot.held.reason}` };
+      slot.held = { kind: 'stage', reason: 'stage-not-performed', inputsDigest: digest };
+      // A handoff-only stage whose only handoff was a catch-up backfill (another skill's handoff walked past it) can never
+      // change its digest on its own: only an annotate of the stage, which counts as a handoff, releases the hold.
+      const backfilled = (run.history || []).some((entry     ) => entry && entry.node === slot.perform.stage && entry.backfilled === true);
+      const release = HANDOFF_ONLY_KINDS.includes(kindOf(run, slot.perform.stage))
+        ? { release: ['orchestrate', '--action', 'annotate', '--task-id', row.slug, '--node', slot.perform.stage, '--note', '<what was done>'], backfilled }
+        : undefined;
       return finish(ctx, { outcome: 'denied', reason: 'stage-not-performed', row: row.id, slug: row.slug, rule: `perform/${slot.perform.stage}`,
-        evidence: [{ locator: checked.current.artifact, sha256: checked.current.sha256 }], perform: slot.perform });
+        evidence: [{ locator: checked.current.artifact, sha256: checked.current.sha256 }], annotations: release, perform: slot.perform });
     }
+    if (slot.held?.kind === 'stage' || slot.held?.kind === 'dispatch') delete slot.held;
     delete slot.perform;
   }
   if (run.state === 'REJECTED') return { skip: 'run-rejected' };
   if (run.state === 'AWAITING_GATE' && node?.type === 'gate') return gateStep(ctx, row, orch, node.id, worktree);
   if (run.state === 'COMPLETED') return mergeStep(ctx, row, { run, worktree });
   if (run.state === 'RUNNING' && node?.type === 'stage') {
-    return node.id === 'implementation' ? implementationStep(ctx, row, worktree) : performStep(ctx, row, worktree, node);
+    return dispatches && node.id === 'implementation' ? implementationStep(ctx, row, worktree) : performStep(ctx, row, worktree, node, run);
   }
   throw new Unreadable([`orchestration:${row.slug}`], `run state '${run.state}' has no actionable node`);
 }
@@ -1324,6 +1415,7 @@ function finishMergedRow(ctx     , row     , rows       , statuses     , worktre
   const cleaned = cleanupFeature({ intent: { featureWorktree: worktree, featureBranch: `feat/${row.slug}`, featureHead }, report: artifacts,
     root: ctx.root, develop, execFileSync: ctx.execFileSync, execOptions: ctx.gitOptions, fsImpl: ctx.fsImpl });
   slot.done = true;
+  delete slot.postMerge; // a row merged without an open intent has no post-merge verification left to mark
   if (!cleaned) {
     if (slot.held?.kind === 'cleanup' && !written) return { skip: 'cleanup-kept' };
     slot.held = { kind: 'cleanup', reason: 'cleanup-kept' };
@@ -1354,7 +1446,7 @@ async function claimStep(ctx     , row     , seed     , developHead        )
   const stopStart = boundary(ctx, row);
   if (stopStart) return stopStart;
   const { orch } = orchestrationFor(ctx, row, worktree);
-  orch.start({ taskId: row.slug, taskClass: 'feature', now: ctx.now() });
+  orch.start({ taskId: row.slug, taskClass: row.class, now: ctx.now(), loopProgram: true });
   return finish(ctx, { outcome: 'acted', step: 'pick', row: row.id, slug: row.slug, annotations: { worktree, developHead },
     audit: `pick ${row.slug} at ${developHead} into ${worktree}` });
 }
@@ -1633,4 +1725,6 @@ module.exports = {
   // The lease primitive, exported for its interleaving test (C8).
   acquireLease,
   releaseLease, resolveMainRoot, noPsAlive,
+  // The orchestrator the loop builds for a row, exported for its wiring test (FU-e4yr45).
+  orchestrationFor,
 };