@khoavu882/doflow 2.0.0 → 2.0.1

package/src/runtime/lifecycle/followup.js

@@ -22,6 +22,7 @@ const { STAGES: CHAIN_STAGES } = require('../decision-register.js');
 const { isSafeSlug, invalidSlugRefusal } = require('../task-scope.js');
 const { resolveActiveFeature } = require('../feature-resolve.js');
 const { SETTLE_AS, withDerivedDone } = require('./fold.js');
+const { pageItems } = require('../verb-view.js');
 const { appendEvents, readFold, byFromChannel, randomChars } = require('./event-store.js');
 const { deriveStatuses } = require('./status.js');
 const { writeIntent, kebabTitle } = require('./intent-writer.js');
@@ -334,12 +335,37 @@ function reportFollowup({ root, statement, input, release, feature, channel, now
 
 // ── list ───────────────────────────────────────────────────────────────────────────────────────
 
-/** IC-006 `list`: `state` is open (default), taken, done, dismissed or all. */
-function listFollowups({ root, state = 'open', hasBody, fsImpl = nodeFs, statuses, now = new Date() }     ) {
-  if (state !== 'all' && !STATES.includes(state)) throw new FollowupUsageError(`--state must be one of ${[...STATES, 'all'].join(', ')} (got '${state}')`);
+/** The most items one list answer holds, however large a `--limit` asks for (IC-004). */
+const LIST_MAX_LIMIT = 100;
+
+/** The key the fold orders on and a list cursor names: the creating event's time in ms, then its event id (IC-008). */
+function followupOrderKey(item     ) {
+  const created = item.history[0];
+  return { atMs: Date.parse(created.at), event: created.event };
+}
+
+/**
+ * IC-006 `list`: `state` is open (default), taken, done, dismissed or all. `ids` keeps the named items (and, with no
+ * `state`, looks in every state); an id that is no item at all is the `unknown-id` refusal. With `cursor`, `limit` or
+ * `defaultLimit` the answer holds one page of `items` plus `shown` and `nextCursor`; with none it is the whole list.
+ */
+function listFollowups({ root, state, ids, cursor, limit, defaultLimit = null, hasBody, fsImpl = nodeFs, statuses, now = new Date() }     ) {
+  const wanted = ids === undefined ? null : parseIds(ids);
+  const wantedState = state === undefined ? (wanted ? 'all' : 'open') : state;
+  if (wantedState !== 'all' && !STATES.includes(wantedState)) throw new FollowupUsageError(`--state must be one of ${[...STATES, 'all'].join(', ')} (got '${wantedState}')`);
   const { fold, followups } = loadFollowups(root, { hasBody, fsImpl, statuses, now });
-  const items = state === 'all' ? followups : followups.filter((item     ) => item.state === state);
-  return { ok: true, action: 'list', state, count: items.length, items, conflicts: fold.conflicts, unreadable: fold.unreadable, unreadableReasons: fold.unreadableReasons, next: [] };
+  let matched = followups;
+  if (wanted) {
+    const known = new Set(followups.map((item     ) => item.id));
+    const unknown = wanted.filter((id) => !known.has(id));
+    if (unknown.length) return refusal('list', 'unknown-id', `${unknown.join(', ')} ${unknown.length === 1 ? 'is' : 'are'} not a follow-up in this store. Nothing was listed.`);
+    matched = followups.filter((item     ) => wanted.includes(item.id));
+  }
+  if (wantedState !== 'all') matched = matched.filter((item     ) => item.state === wantedState);
+  const answer      = { ok: true, action: 'list', state: wantedState, count: matched.length, items: matched, conflicts: fold.conflicts, unreadable: fold.unreadable, unreadableReasons: fold.unreadableReasons, next: [] };
+  if (cursor === undefined && limit === undefined && defaultLimit === null) return answer;
+  const page = pageItems(matched, { cursor, limit, defaultLimit, maxLimit: LIST_MAX_LIMIT, key: followupOrderKey });
+  return { ...answer, items: page.items, shown: page.shown, nextCursor: page.nextCursor };
 }
 
 // ── take, settle, promote ──────────────────────────────────────────────────────────────────────
@@ -431,7 +457,7 @@ function promoteFollowups({ root, ids, title, channel, now = new Date(), fsImpl
 }
 
 module.exports = {
-  addFollowups, reportFollowup, listFollowups, takeFollowups, settleFollowups, promoteFollowups,
+  addFollowups, reportFollowup, listFollowups, followupOrderKey, takeFollowups, settleFollowups, promoteFollowups,
   loadFollowups, readBatchFile, resolveFeatureSlug, parseIds, oneLine, channelBy,
   FollowupUsageError, STAGES, STATES, SOURCE_KINDS, STATEMENT_MAX,
 };

package/src/runtime/lifecycle/overview.js

@@ -17,6 +17,7 @@ const { appendEvents, readFold, readEvents } = require('./event-store.js');
 const { deriveStatuses, bucketize, behindNote } = require('./status.js');
 const { FollowupUsageError, parseIds } = require('./followup.js');
 const { describeActive } = require('../feature-pointer.js');
+const { commandLine } = require('../verb-view.js');
 
 /** The failure store, or null when its module cannot be loaded: the overview then reports no failures. */
 function failureStoreOrNull() {
@@ -130,7 +131,7 @@ function goalView(goal     , features     , statuses     , conflicts      = [])
 
 function nextLines({ shown, open, items, intents, goals, maintain, pendingItems, failures }     ) {
   const next = [];
-  if (shown < open) next.push('List the rest: doflow-run followup --action list');
+  if (shown < open) next.push(`Page through all ${open} open follow-ups: ${commandLine('followup', 'list', {})}`);
   if (items.length) next.push(`Take items into the new feature when its folder exists: doflow-run lifecycle --action init --slug <slug> --take ${items[0].id}`);
   if (intents.length) {
     next.push(`Start from a promoted intent: /do-brainstorm --intent ${intents[0].path}, then doflow-run lifecycle --action init --slug <slug> --intent ${intents[0].path}`);

package/src/runtime/packages/points.js

@@ -42,6 +42,15 @@ function presetValidator(kind        ) {
   };
 }
 
+/** An intake category contributed by a package (136 IC-006): IC-005's category shape, whose `id` is the contribution id. */
+function intakeCategoryValidator(id        , entry     , context      = {})           {
+  const { validateCategory } = require('../intake/taxonomy.js');
+  const location = context.packageId ? `package '${context.packageId}' intake category '${id}'` : `intake category '${id}'`;
+  const errors           = validateCategory(entry, location);
+  if (entry && typeof entry === 'object' && !Array.isArray(entry) && entry.id !== id) errors.push(`${location}.id must equal the contribution id '${id}'`);
+  return errors;
+}
+
 function workerValidator(id        , worker     , context      = {})           {
   const errors           = [];
   const location = context.packageId ? `package '${context.packageId}' worker '${id}'` : `worker '${id}'`;
@@ -168,6 +177,7 @@ const POINT_VALIDATORS
   'agent-v1': agentValidator,
   'worker-v1': workerValidator,
   'capability-provider-v1': capabilityProviderValidator,
+  'intake-category-v1': intakeCategoryValidator,
 });
 
 function isObject(value     )          {

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

@@ -23,6 +23,7 @@ const {
   render,
   renderRoadmapFile,
   check,
+  LOOP_CLASSES,
 } = require('./rows.js');
 const { gatherGitFacts, sha256Digest } = require('./facts.js');
 const { loadPolicy, verifyRecordReasons } = require('./gates.js');
@@ -376,6 +377,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                           = {
@@ -680,21 +683,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 +745,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 +794,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        )                          {
@@ -981,6 +1014,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 +1057,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 +1155,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 +1279,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 +1293,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 +1331,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 +1358,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 +1406,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 +1437,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}` });
 }

package/src/runtime/roadmap/merge.js

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