@khoavu882/doflow 2.0.0 → 2.0.2

package/src/runtime/lifecycle/cli.js

@@ -15,14 +15,40 @@ const followup = require('./followup.js');
 const { StoreUnsafeError, StoreLockedError } = require('./event-store.js');
 const { prepareStore } = require('./store-upkeep.js');
 const { printSafe } = require('../mask.js');
-const { buildOverview, initFeature, featureStatus, activeFeature } = require('./overview.js');
+const { buildOverview, capOverviewBrief, initFeature, featureStatus, activeFeature } = require('./overview.js');
 const { recordFeature, clearSlug } = require('../feature-pointer.js');
 const { releaseFeatures, recordMerged } = require('./release.js');
 const goal = require('./goal.js');
+const { ViewUsageError, resolveView, projectBrief, viewLines, withEnvelope, serializeJson } = require('../verb-view.js');
 
 const FOLLOWUP_ACTIONS = ['add', 'list', 'take', 'settle', 'promote', 'report'];
 const LIFECYCLE_ACTIONS = ['overview', 'init', 'release', 'status', 'merged'];
 const GOAL_ACTIONS = ['add', 'item', 'check', 'link', 'list', 'done'];
+/** The brief `followup --action list` answer (feature 137, IC-004): the fields that let a caller choose an item. */
+const FOLLOWUP_LIST_BRIEF = Object.freeze({
+  verb: 'followup',
+  action: 'list',
+  carry: Object.freeze(['state', 'ids', 'limit']),
+  keep: Object.freeze([
+    '$.ok', '$.action', '$.state', '$.count', '$.items[].id', '$.items[].state', '$.items[].statement',
+    '$.conflicts', '$.unreadable', '$.unreadableReasons',
+  ]),
+});
+/** The brief `lifecycle --action overview` answer (feature 137, IC-006): keep paths, so a new full field is dropped until named here. */
+const OVERVIEW_BRIEF = Object.freeze({
+  verb: 'lifecycle',
+  action: 'overview',
+  carry: Object.freeze(['maintain', 'since']),
+  keep: Object.freeze([
+    '$.ok', '$.mode', '$.releaseMode', '$.integrationRef', '$.gitError', '$.followups.open', '$.followups.shown',
+    '$.followups.items[].id', '$.followups.items[].statement', '$.followups.items[].source', '$.followups.items[].pending',
+    '$.intents', '$.goals[].goal', '$.goals[].outcome', '$.goals[].items', '$.goals[].proposeDone', '$.goals[].nudges',
+    '$.goals[].conflicts', '$.conflicts', '$.unreadable', '$.unreadableReasons', '$.failures', '$.reason', '$.note',
+    '$.integrationBehind', '$.pending', '$.omitted', '$.next',
+  ]),
+});
+/** A brief list answers one page of this many items unless `--limit` says otherwise. */
+const BRIEF_PAGE = 10;
 /** The flags each goal action takes, besides --goal, --channel and --json; any other one given is a usage error. */
 const GOAL_FLAGS                      = {
   add: ['statement', 'item'], item: ['text'], check: ['item', 'evidence', 'unmet'],
@@ -40,6 +66,7 @@ function followupLines(result     ) {
     case 'list':
       if (result.items.length === 0) lines.push(`No ${result.state === 'all' ? '' : `${result.state} `}follow-ups.`);
       for (const i of result.items) lines.push(`${i.id}  ${i.state}${i.takenBy ? ` by ${i.takenBy}` : ''}${i.intent ? ` -> ${i.intent}` : ''}  (${sourceText(i.source)}, ${i.added})  ${i.statement}`);
+      for (const line of result.next) lines.push(`next: ${line}`);
       break;
     case 'take': lines.push(`${result.feature} took ${result.ids.join(', ')}`); break;
     case 'settle': lines.push(`settled ${result.ids.join(', ')} as ${result.as}`); break;
@@ -129,7 +156,7 @@ function goalLines(r     ) {
 
 /** Prints a result and sets the exit status; shared by the verbs. */
 function emit(result     , json     , lines     ) {
-  if (json) console.log(JSON.stringify(result, null, 2));
+  if (json) console.log(serializeJson(result));
   else if (result.ok === false) console.log(printSafe(`${result.finding}: ${result.message}`));
   else for (const line of lines(result)) console.log(printSafe(line));
   return finishRuntime(result.ok === false ? 1 : 0);
@@ -140,7 +167,7 @@ function guarded(verb     , action     , json     , fn     ) {
   try {
     return fn();
   } catch (error     ) {
-    if (error instanceof followup.FollowupUsageError || error instanceof StoreUnsafeError) return usageError(verb, error.message, json);
+    if (error instanceof followup.FollowupUsageError || error instanceof ViewUsageError || error instanceof StoreUnsafeError) return usageError(verb, error.message, json);
     if (error instanceof StoreLockedError) return emit({ ok: false, action, finding: 'store-locked', message: error.message }, json, () => []);
     throw error;
   }
@@ -157,6 +184,29 @@ function refuseGlobal(verb     , global     , json     ) {
   return global ? usageError(verb, `${verb} works on the project store at the repository root and refuses -g`, json) : null;
 }
 
+/**
+ * Prints a `followup --action list` answer in the view it asked for (IC-004). Brief projects the page onto the keep
+ * list; a full call with no cursor and no limit is the service object, untouched. Every other answer carries the
+ * envelope and the next lines. Text mode shows the page's items in the usual format and the next lines only when
+ * the page is not the whole list.
+ */
+function emitList(result     , view     , flags     , json     ) {
+  if (result.ok === false) return emit(result, json, followupLines);
+  const paged = result.shown !== undefined;
+  const carried = { state: flags.state, ids: flags.ids, limit: flags.limit };
+  const lines = !paged ? [] : [
+    ...viewLines('page', { spec: FOLLOWUP_LIST_BRIEF, carried, nextCursor: result.nextCursor, view, json: Boolean(json) }),
+    ...(view === 'brief' ? viewLines('page-full', { spec: FOLLOWUP_LIST_BRIEF, carried, cursor: flags.cursor, shown: result.shown, json: Boolean(json) }) : []),
+  ];
+  if (!json) return emit({ ...result, next: result.shown < result.count ? lines : [] }, false, followupLines);
+  if (view === 'brief') {
+    const body = projectBrief(result, FOLLOWUP_LIST_BRIEF.keep);
+    return emit(withEnvelope(body, { view, shown: result.shown, nextCursor: result.nextCursor, next: lines }), true, followupLines);
+  }
+  if (!paged) return emit(result, true, followupLines);
+  return emit(withEnvelope(result, { view, shown: result.shown, nextCursor: result.nextCursor, next: lines }), true, followupLines);
+}
+
 /**
  * `followup` verb. Actions: add, list, take, settle, promote, report.
  * @param {Object} options
@@ -175,6 +225,12 @@ function handleFollowupCommand({ action, cwd, global = false, slug = null, json
         if (flags[name] !== undefined && flags[name] !== false) throw new followup.FollowupUsageError(`--${name} applies to --action report only`);
       }
     }
+    if (action !== 'list') {
+      for (const name of ['view', 'cursor', 'limit']) {
+        if (flags[name] !== undefined && flags[name] !== false) throw new followup.FollowupUsageError(`--${name} applies to --action list only`);
+      }
+    }
+    const view = action === 'list' ? resolveView(flags.view, 'brief') : null;
     for (const name of ['tag', 'confirm', 'exclude']) {
       if (flags[name] !== undefined && flags[name] !== false) throw new followup.FollowupUsageError(`--${name} applies to the lifecycle verb's --action release only, not to followup`);
     }
@@ -198,7 +254,9 @@ function handleFollowupCommand({ action, cwd, global = false, slug = null, json
         defaults: { stage: flags.stage, slug, source: flags.source, taskClass: flags.taskClass, taskId: flags.taskId, release: flags.release, batch },
       });
     } else if (action === 'list') {
-      result = followup.listFollowups({ root, state: flags.state });
+      return emitList(followup.listFollowups({
+        root, state: flags.state, ids: flags.ids, cursor: flags.cursor, limit: flags.limit, defaultLimit: view === 'brief' ? BRIEF_PAGE : null,
+      }), view, flags, json);
     } else if (action === 'take') {
       result = followup.takeFollowups({ root, ids: flags.ids, slug, channel: flags.channel });
     } else if (action === 'settle') {
@@ -230,13 +288,25 @@ function handleLifecycleCommand({ action, cwd, global = false, slug = null, json
         if (flags[name] !== undefined && flags[name] !== false) throw new followup.FollowupUsageError(`--${name} applies to --action release only`);
       }
     }
+    if (act !== 'overview' && flags.view !== undefined && flags.view !== false) throw new followup.FollowupUsageError('--view applies to --action overview only');
+    const view = act === 'overview' ? resolveView(flags.view, 'full') : null;
     if (flags.reason !== undefined && act !== 'merged') throw new followup.FollowupUsageError('--reason applies to --action merged only');
     const root = projectRoot(cwd || process.cwd());
     const refusedStore = upkeep('lifecycle', act, root);
     if (refusedStore) return emit(refusedStore, json, lifecycleLines);
     let result;
-    if (act === 'overview') result = buildOverview({ root, maintain: Boolean(flags.maintain), since: flags.since });
-    else if (act === 'init') {
+    if (act === 'overview') {
+      result = buildOverview({ root, maintain: Boolean(flags.maintain), since: flags.since });
+      // The text answer is the same in both views (IC-001); only the JSON brief is cut to one page of items. Maintain
+      // keeps its 50: that loop settles every pending item. The next lines name the paged list and carry no full-view line.
+      if (view === 'brief' && json) {
+        const items = flags.maintain ? result.followups.items : result.followups.items.slice(0, BRIEF_PAGE);
+        const brief      = capOverviewBrief({ ...result, followups: { ...result.followups, shown: items.length, items } });
+        // Something cut from a list: the next lines also say how to get everything.
+        const next = brief.omitted ? [...result.next, ...viewLines('full', { spec: OVERVIEW_BRIEF, carried: { maintain: flags.maintain, since: flags.since }, json: true })] : undefined;
+        return emit(withEnvelope(projectBrief(brief, OVERVIEW_BRIEF.keep), { view, ...(next ? { next } : {}) }), true, lifecycleLines);
+      }
+    } else if (act === 'init') {
       result = initFeature({ root, slug, take: flags.take, intent: flags.intent, goal: flags.goal });
       if (result.ok) recordFeature({ storeRoot: root, cwd: cwd || process.cwd(), slug });
     }

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() {
@@ -27,6 +28,8 @@ const DISCOVERY_SHOWN = 15;
 const MAINTAIN_SHOWN = 50;
 /** Slugs shown per finished or awaiting-release bucket: those lists only grow, and the overview runs on every brainstorm. */
 const FEATURES_SHOWN = 10;
+/** Entries per list in the JSON brief overview: intents, the ids of one intent, the nudges of one goal (137 FU-2jtkch). */
+const BRIEF_LIST_SHOWN = 10;
 
 const refusal = (action     , finding     , message     ) => ({ ok: false, action, finding, message });
 
@@ -115,7 +118,10 @@ function goalView(goal     , features     , statuses     , conflicts      = [])
   const met = goal.items.filter((i     ) => i.met).length;
   const nudges = [];
   if (buckets.finished.length) {
-    const who = buckets.finished.length === 1 ? `linked feature ${buckets.finished[0]} is finished` : `linked features ${buckets.finished.join(', ')} are finished`;
+    // The nudge names the most recent finished features only; `features.finished` still lists every one.
+    const finished = shownBucket(buckets.finished);
+    const who = buckets.finished.length === 1 ? `linked feature ${buckets.finished[0]} is finished`
+      : `linked features ${finished.shown.join(', ')}${finished.more ? ` (+${finished.more} more)` : ''} are finished`;
     for (const item of goal.items.filter((i     ) => !i.met)) nudges.push(`${item.id} is unchecked and ${who}`);
   }
   return {
@@ -130,7 +136,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}`);
@@ -159,6 +165,31 @@ function nextLines({ shown, open, items, intents, goals, maintain, pendingItems,
   return next;
 }
 
+/**
+ * The JSON brief form of an overview answer: at most BRIEF_LIST_SHOWN intents, ids per intent and nudges per goal. What
+ * was cut is counted in `omitted` (absent when nothing was cut): `intents`, and `intentItems`, `nudges` and
+ * `finished` (the finished features a goal's nudges leave out of their text) per intent or goal that exceeds the
+ * bound. The full view lists everything.
+ */
+function capOverviewBrief(result     ) {
+  const omitted      = {};
+  const intents = result.intents.slice(0, BRIEF_LIST_SHOWN).map((intent     ) => {
+    if (intent.items.length > BRIEF_LIST_SHOWN) {
+      (omitted.intentItems ??= []).push({ path: intent.path, total: intent.items.length, more: intent.items.length - BRIEF_LIST_SHOWN });
+    }
+    return { ...intent, items: intent.items.slice(0, BRIEF_LIST_SHOWN) };
+  });
+  if (result.intents.length > BRIEF_LIST_SHOWN) omitted.intents = { total: result.intents.length, more: result.intents.length - BRIEF_LIST_SHOWN };
+  const goals = result.goals.map((goal     ) => {
+    const finished = goal.features.finished.length;
+    if (finished > FEATURES_SHOWN) (omitted.finished ??= []).push({ goal: goal.goal, total: finished, more: finished - FEATURES_SHOWN });
+    if (goal.nudges.length <= BRIEF_LIST_SHOWN) return goal;
+    (omitted.nudges ??= []).push({ goal: goal.goal, total: goal.nudges.length, more: goal.nudges.length - BRIEF_LIST_SHOWN });
+    return { ...goal, nudges: goal.nudges.slice(0, BRIEF_LIST_SHOWN) };
+  });
+  return { ...result, intents, goals, ...(Object.keys(omitted).length ? { omitted } : {}) };
+}
+
 /**
  * IC-007.
  * @param {Object} options
@@ -312,4 +343,4 @@ function activeFeature({ root, cwd, now = new Date(), fsImpl = nodeFs }     ) {
   return derived.ok ? { ...derived, active } : { ...result, slug: active.slug, message: `${active.slug} is tracked by its run only; \`lifecycle --action init\` to track it.` };
 }
 
-module.exports = { buildOverview, initFeature, featureStatus, activeFeature, goalView, goalConflicts, goalConflictNext, DISCOVERY_SHOWN, MAINTAIN_SHOWN, FEATURES_SHOWN };
+module.exports = { buildOverview, capOverviewBrief, initFeature, featureStatus, activeFeature, goalView, goalConflicts, goalConflictNext, DISCOVERY_SHOWN, MAINTAIN_SHOWN, FEATURES_SHOWN };

package/src/runtime/lifecycle/release.js

@@ -39,6 +39,7 @@ const { isSafeSlug, invalidSlugRefusal } = require('../task-scope.js');
 const { appendEvents, readFold } = require('./event-store.js');
 const { deriveStatuses, readGitFacts, behindNote, subjectNames, readMerges, readBranchTips, readHistory } = require('./status.js');
 const { FollowupUsageError, oneLine, channelBy } = require('./followup.js');
+const { parseSemVer, compareSemVer } = require('../../helper/semver.js');
 
 /** The release-tag pattern of IC-020, the one `git-state` filters by. */
 const RELEASE_TAG = /^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$/;
@@ -125,13 +126,25 @@ function releaseFeatures({ root, tag, confirm = false, features, exclude, channe
     return refusal('release', 'untracked-feature', `${untracked.join(', ')} ${untracked.length === 1 ? 'is' : 'are'} not tracked, so ${untracked.length === 1 ? 'it' : 'they'} cannot be added to or excluded from a release; run doflow-run lifecycle --action init --slug <slug> first. Nothing was written.`);
   }
 
-  // DEC-030: containment in the tag being recorded never finishes a feature before its record exists.
-  const otherTags = { ...facts, release_tags: facts.release_tags.filter((name     ) => name !== tag) };
+  // DEC-030: containment in the tag being recorded never finishes a feature before its record exists. Of the
+  // other tags only an unrecorded one that is stable and earlier than `tag` (lower version, or a strict ancestor of it)
+  // may take a feature out of this release: a pre-release (v1.0.0-rc.1 before v1.0.0) or a later tag
+  // (v2.0.0 when recording v1.0.0) does not. A tag with a record is left in: status reads it by its record.
+  const tagCommit = commitOf(root, `refs/tags/${tag}`);
+  const recordedTags = new Set(fold.releases.map((r     ) => r.tag));
+  const shadows = (name     ) => {
+    const parsed = parseSemVer(name.slice(1));
+    if (!parsed || parsed.prerelease.length > 0) return false;
+    if (compareSemVer(name.slice(1), tag.slice(1)) < 0) return true;
+    // A strict ancestor only: a higher-versioned tag on the very same commit is not earlier.
+    const commit = tagCommit && commitOf(root, `refs/tags/${name}`);
+    return Boolean(commit) && commit !== tagCommit && isAncestor(root, commit, tagCommit);
+  };
+  const otherTags = { ...facts, release_tags: facts.release_tags.filter((name     ) => name !== tag && (recordedTags.has(name) || shadows(name))) };
   const derived = deriveStatuses({ root, fold, facts: otherTags });
   if (derived.releaseMode === 'unknown' || !derived.integrationSha) return refusal('release', 'no-integration-ref', `${derived.reason || `${facts.integration_ref} does not resolve to a commit`}. Nothing was written.`);
 
   // X: the tag's commit once it exists, else the commit the status view pinned the integration ref to (DEC-044).
-  const tagCommit = commitOf(root, `refs/tags/${tag}`);
   const bound = tagCommit || derived.integrationSha;
   const previousTag = previousTagOf(root, { tag, facts, bound });
   // A hotfix merged only into the tag's own history has no evidence on the integration chain: derive against the tag as well.

package/src/runtime/lifecycle/retention.js

@@ -18,7 +18,7 @@
 
 const nodeFs = require('node:fs');
 const { isDeepStrictEqual } = require('node:util');
-const { loadSettings } = require('../settings/resolve.js');
+const { loadSettings, registryOn } = require('../settings/resolve.js');
 const { foldInto, finalize, EVENT_TYPES } = require('./fold.js');
 
 const HOUR_MS = 3600000;
@@ -53,14 +53,7 @@ function retentionWindow({ env = process.env, projectRoot, fsImpl = nodeFs }
   const parsed = parseWindow(env);
   if (parsed.state === 'invalid') return parsed;
   try {
-    let settingsRegistry;
-    if (fsImpl !== nodeFs) {
-      const { loadSettingsRegistry } = require('../settings/registry.js');
-      const loaded = loadSettingsRegistry({ fsImpl });
-      if (!loaded.ok) throw new Error(loaded.detail);
-      settingsRegistry = loaded.registry;
-    }
-    const view = loadSettings({ projectRoot, env, fsImpl, ...(settingsRegistry ? { registry: settingsRegistry } : {}) });
+    const view = loadSettings({ projectRoot, env, fsImpl, ...registryOn(fsImpl) });
     const retention = view.get('storage.retentionHours', 'project');
     if (retention.state === 'invalid') return { state: 'invalid', raw: invalidRaw(retention, env) };
     if (retention.explicit) {
@@ -136,10 +129,12 @@ function unitsOf(events       , shouldStop                )               {
 }
 
 /**
- * Every string value and every object key in the data of the events whose type this version's fold
- * does not know (a newer DoFlow wrote them). The fold ignores them, so retention cannot tell what they change; a unit that
- * one of them names by id is kept whole rather than deleted from under it. Exact matches only:
- * keeping too little is a lost record, keeping too much only a file that stays.
+ * Every string value in the envelope, and every object key inside it, of the events whose type this
+ * version's fold does not know (a newer DoFlow wrote them). The fold ignores them, so retention
+ * cannot tell what they change; a unit that one of them names, by item id, event id or event file
+ * name, is kept whole rather than deleted from under it. The envelope's own field names are its
+ * shape, not references. Exact matches only: keeping too little is a lost record, keeping too much
+ * only a file that stays.
  * @returns {Set<string>|null} null when `shouldStop` fired
  */
 function unknownTypeStrings(events       , shouldStop                )                     {
@@ -148,7 +143,7 @@ function unknownTypeStrings(events       , shouldStop                )
   for (const event of events) {
     if (shouldStop?.()) return null;
     if (known.has(event.type)) continue;
-    const pending        = [event.data];
+    const pending        = Object.values(event);
     while (pending.length > 0) {
       if (shouldStop?.()) return null;
       const value = pending.pop();
@@ -260,7 +255,9 @@ function selectExpired(events       , { now, windowMs, shouldStop }      = {})
   };
   const baseSelected = safeSubset(candidates);
   if (!baseSelected) return incomplete();
-  const unprotected = baseSelected.filter((unit     ) => ![...unit.items].some((key        ) => mentioned.has(key.slice(key.indexOf(':') + 1))));
+  const namedByUnknown = (unit     )          => [...unit.items].some((key        ) => mentioned.has(key.slice(key.indexOf(':') + 1)))
+    || unit.events.some((event     ) => mentioned.has(event.id) || mentioned.has(`${event.id}.json`));
+  const unprotected = baseSelected.filter((unit     ) => !namedByUnknown(unit));
   // Dropping units can leave a set the refold no longer accepts; check it again, inside the subset.
   const selected = unprotected.length === baseSelected.length ? baseSelected : safeSubset(unprotected);
   if (!selected) return incomplete();

package/src/runtime/lifecycle/store-upkeep.js

@@ -342,9 +342,9 @@ function retainLocked(root     , options      = {}) {
   if (!release) return outcome(0, [], true);
   try {
     const swept = sweepStaleTmp(fsImpl, root, now, staleTmpMs, { maxFiles, shouldStop });
-    if (swept.partial) return outcome(0, [], true);
+    if (swept.partial) return outcome(swept.removed, [], true);
     const result = retain(fsImpl, root, window, now, { maxFiles: Math.max(0, maxFiles - swept.removed), shouldStop });
-    return outcome(result.removedCount, result.warning, result.partial, result.selected, result.code);
+    return outcome(swept.removed + result.removedCount, result.warning, result.partial, result.selected, result.code);
   } finally {
     release();
   }
@@ -358,6 +358,16 @@ function needsPrune(fsImpl     , root     , window     , now     ) {
   return selectExpired(readEvents(root, { fsImpl }).events, { now, windowMs: window.ms }).files.length > 0;
 }
 
+/**
+ * Whether the old `agent-docs/lifecycle` copy still waits to be copied. Read-only (no lock, no
+ * write, `DOFLOW_UPKEEP` not consulted), for `doctor`; an unreadable folder counts as not pending.
+ */
+function migrationPending(root        , { fsImpl = nodeFs }      = {}) {
+  try {
+    return !hasMarker(fsImpl, root) && !storeHasEvents(fsImpl, root) && legacyEventFiles(fsImpl, root).length > 0;
+  } catch { return false; }
+}
+
 /**
  * Prepares the project store for one verb invocation.
  * @param {string} root projectRoot() result
@@ -439,4 +449,4 @@ function prepareStore(root        , { env = process.env, now = new Date(), fsImp
   }
 }
 
-module.exports = { prepareStore, retainLocked, removedLine, STALE_TMP_MS, LEGACY_LIFECYCLE_REL, LEGACY_EVENTS_REL, MARKER_REL };
+module.exports = { prepareStore, migrationPending, retainLocked, removedLine, STALE_TMP_MS, LEGACY_LIFECYCLE_REL, LEGACY_EVENTS_REL, MARKER_REL };

package/src/runtime/mask.js

@@ -12,8 +12,8 @@
  * Rules run in the table's order. Normalisation (rules 10 to 13) is a separate step applied to
  * failure messages only, after masking.
  *
- * The module has no I/O and no state; the home directory is read from `HOME` unless the caller
- * passes one.
+ * The module has no I/O and no state; the home directory is read from `HOME` (`USERPROFILE` when
+ * `HOME` is absent or empty, as on Windows) unless the caller passes one.
  */
 
 const MASKED = '<masked>';
@@ -152,7 +152,7 @@ function escapeRegExp(text        )         { return text.replace(/[.*+?^${}()|[
 
 /** The home directory to abbreviate: an absolute path other than the file system root. */
 function homeOf(options      )                {
-  const raw = options && 'home' in options ? options.home : process.env.HOME;
+  const raw = options && 'home' in options ? options.home : (process.env.HOME || process.env.USERPROFILE);
   if (typeof raw !== 'string' || !(raw.startsWith('/') || /^[A-Za-z]:[\\/]/.test(raw))) return null;
   const home = raw.replace(/[\\/]+$/, '');
   return home.length > 1 ? home : null;

package/src/runtime/mcp-consultations.js

@@ -230,14 +230,15 @@ const bySortKey = (a     , b     )         => (a < b ? -1 : a > b ? 1 : 0);
  * Injected readers (all optional; a missing one contributes nothing):
  * - `ledger.queryEvidence({taskId})` -> evidence items (active ones count)
  * - `requests.list(taskId)` -> research requests
- * - `briefRecords` -> IC-018 records already parsed, each `{ runTaskId, stage, tasks, expected }`
+ * - `briefRecords` -> IC-018 records already parsed, each `{ runTaskId, stage, createdAt, tasks, expected }`
  * - `readReport(path)` -> report text, or null when the file is missing
  * - `reach.anyHarnessHas(server)` -> true | false | null (unknown); never decides an outcome
  * - `reach.harnessWith(server)` -> the display name of a harness that has the server, or null
  * - `harnessName(id)` -> a harness id's display name (for a brief record's `harness`)
- * - `addCommand(server)` -> the text after "add it:" in the unavailable notice
+ * - `addCommand(server, harnessId)` -> the text after "add it:" in the unavailable notice; `harnessId` is the harness
+ *   of the brief that found the server unreachable, or null when no brief names one
  * - `since` -> ISO time of the previous stage's completion (or the run start); rule 3 counts only
- *   evidence observed after it
+ *   evidence observed after it, and only brief records created after it
  *
  * @returns {{ record: object, warnings: object[], notices: object[], evidenceToAdd: object[] }}
  */
@@ -266,8 +267,11 @@ function resolveConsultations({
   // ingested (design A6).
   const toolsUsed        = [];
   const fromReports = new Map               ();
+  // A stage visited twice leaves briefs from the earlier visit: when `since` is known only a brief created
+  // after it counts, and a record with no creation time (written before it was stamped) cannot be placed.
   const records = (Array.isArray(briefRecords) ? briefRecords : [])
-    .filter((record     ) => record && stageId && taskId && record.stage === stageId && record.runTaskId === taskId);
+    .filter((record     ) => record && stageId && taskId && record.stage === stageId && record.runTaskId === taskId
+      && (since === null || (typeof record.createdAt === 'string' && record.createdAt > since)));
   const reports                                        = [];
   for (const record of records) {
     for (const task of record.tasks || []) {
@@ -347,10 +351,12 @@ function resolveConsultations({
   // brief writes `unreachable` only where every config the harness merges was read (IC-017).
   const unreachable = new Map             ();
   const reachableOn = new Map             ();
+  const unreachableOn = new Map             ();
   for (const record of records) {
     for (const expected of record.expected || []) {
       if (!expected || typeof expected.server !== 'string') continue;
       if (expected.reach === 'unreachable' && !unreachable.has(expected.server)) unreachable.set(expected.server, record.tasks?.[0]?.id);
+      if (expected.reach === 'unreachable' && !unreachableOn.has(expected.server)) unreachableOn.set(expected.server, record.harness ?? null);
       if (expected.reach === 'reachable' && !reachableOn.has(expected.server)) reachableOn.set(expected.server, record.harness ?? null);
     }
   }
@@ -415,7 +421,7 @@ function resolveConsultations({
           text: `[WARN] mcp: ${server} reported unavailable but ${has} has it configured`,
         });
       }
-      const add = !has && typeof addCommand === 'function' ? addCommand(server) : null;
+      const add = !has && typeof addCommand === 'function' ? addCommand(server, unreachableOn.get(server) ?? null) : null;
       notices.push({
         kind: 'unavailable', server,
         text: `[INFO] mcp: ${server} unavailable to ${skill}${add ? `; add it: ${add}` : ''}`,

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/research-request.js

@@ -95,7 +95,9 @@ class ResearchRequestStore {
   }
 
   stageFor(taskId     , stageId     ) {
-    const run = readTaskState(this.fsImpl, this.runFile(taskId));
+    // The run is read the way every run read is: no link followed, no FIFO or device opened (FU-d88kp0).
+    const { readRunRecord } = require('./implementation-gate.js');
+    const run = readRunRecord(this.fsImpl, this.runFile(taskId), path.join(this.projectRoot, '.doflow', 'state', 'orchestration'));
     if (!run || run.taskClass !== 'feature' || run.state !== 'RUNNING') {
       throw new Error(`Task '${taskId}' has no active feature stage`);
     }

package/src/runtime/review/command.js

@@ -25,15 +25,10 @@ const TELEMETRY_COUNT_KEYS = Object.freeze([
   'plausible', 'unverified_blockers', 'bug_classes',
 ]);
 
-// Inherited location variables would point the check at another repository (C-8).
-const GIT_LOCATION_KEYS = Object.freeze([
-  'GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_OBJECT_DIRECTORY', 'GIT_COMMON_DIR',
-  'GIT_ALTERNATE_OBJECT_DIRECTORIES',
-]);
-
 function defaultGit(args          , cwd        , env     )                            {
   const gitEnv = { ...env };
-  for (const key of GIT_LOCATION_KEYS) delete gitEnv[key];
+  // Inherited location variables would point the check at another repository (C-8); the list is verification's.
+  for (const key of require('../dispatch/verify-run.js').REPO_ENV) delete gitEnv[key];
   return spawnSync('git', ['-C', cwd, ...args], { cwd, env: gitEnv, stdio: 'ignore' });
 }
 
@@ -112,6 +107,7 @@ function handleReviewCommand({
     }
     return handleReviewStart({ slug: hasValue(slug) ? slug : null, base: hasValue(base) ? base : null, preset: hasValue(preset) ? preset : null, json, cwd, env, resolve, adviceClient, out });
   }
+  if (Array.isArray(recordPath)) return usage('--path may be given only once', json, out);
   if (hasValue(base)) return usage('--base is valid only with --action start', json, out);
   if (hasValue(preset)) return usage('--preset is valid only with --action start', json, out);
   if (hasValue(slug) && hasValue(recordPath)) return usage('use either --slug or --path, not both', json, out);