@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.4

package/src/runtime/lifecycle/goal.js

@@ -0,0 +1,249 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * The goal service (IC-022, FR-013, FR-014): add, item, check, link, list and done, over the
+ * lifecycle event store. A goal is DoFlow's own record of one outcome and its checklist, independent
+ * of any harness command that shares the name (NFR-004). Every function takes the IC-001 root, writes
+ * only events and returns a result object without printing, as the follow-up service does.
+ *
+ *   - A refusal is returned `{ok:false, action, finding, message}` and never thrown (exit 1).
+ *   - A caller mistake throws `FollowupUsageError` (exit 2), before anything is written.
+ *   - Every free-text field is masked, one line and bounded (`oneLine`), before it is stored.
+ *   - Progress is computed here from the fold and the derived feature statuses, never written, so it
+ *     is the same on every harness and costs no model tokens (NFR-006).
+ */
+
+const nodeFs = require('node:fs');
+const { isSafeSlug, invalidSlugRefusal } = require('../task-scope.js');
+const { appendEvents, readFold } = require('./event-store.js');
+const { deriveStatuses } = require('./status.js');
+const { FollowupUsageError, oneLine, channelBy } = require('./followup.js');
+const { goalView, goalConflicts, goalConflictNext } = require('./overview.js');
+
+const GOAL_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const GOAL_ID_MAX = 40;
+const ITEM_ID = /^C[1-9][0-9]{0,5}$/;
+/** Items one `goal.added` may carry: a checklist this long is a plan, not a goal. */
+const ITEMS_MAX = 100;
+/** Channels that name the user (DEC-004); `default` is the agent. */
+const USER_CHANNELS = ['question', 'gate', 'prompt'];
+/** Fold conflicts that are a refusal under their own name; any other conflict is an `illegal-transition`. */
+const CONFLICT_FINDINGS = new Set(['goal-exists', 'unknown-goal', 'unknown-item', 'goal-already-linked', 'untracked-feature', 'evidence-required']);
+
+function refusal(action     , finding     , message     ) { return { ok: false, action, finding, message }; }
+
+function refusalFrom(action     , failed     ) {
+  const finding = failed.conflict && CONFLICT_FINDINGS.has(failed.conflict.code) ? failed.conflict.code : failed.finding;
+  return refusal(action, finding, failed.message);
+}
+
+function goalIdOf(raw     ) {
+  if (raw === undefined || raw === null || raw === '') throw new FollowupUsageError('--goal is required: a kebab-case goal id of at most 40 characters');
+  const id = String(raw);
+  if (id.length > GOAL_ID_MAX || !GOAL_ID.test(id)) {
+    throw new FollowupUsageError(`--goal must be kebab-case (lowercase letters and digits joined by single dashes) and at most ${GOAL_ID_MAX} characters`);
+  }
+  return id;
+}
+
+function itemIdOf(raw     ) {
+  const list = Array.isArray(raw) ? raw : raw === undefined ? [] : [raw];
+  if (list.length !== 1) throw new FollowupUsageError('--item takes exactly one checklist id such as C3 for --action check');
+  if (!ITEM_ID.test(String(list[0]))) throw new FollowupUsageError(`--item must be a checklist id such as C3 (got '${String(list[0]).slice(0, 40)}')`);
+  return String(list[0]);
+}
+
+/** One masked, one-line, bounded text; a problem is a usage error naming the flag. */
+function textOf(raw     , label     ) {
+  const problems      = [];
+  const text = raw === undefined ? null : oneLine(raw, label, problems);
+  if (problems.length) throw new FollowupUsageError(problems.join('; '));
+  return text;
+}
+
+function requiredText(raw     , label     ) {
+  if (raw === undefined || raw === null) throw new FollowupUsageError(`${label} is required`);
+  return textOf(raw, label);
+}
+
+function unknownGoal(action     , fold     , id     ) {
+  const known = fold.goals.map((g     ) => g.goal);
+  return refusal(action, 'unknown-goal', `${id} is not a goal${known.length ? `; the goals are ${known.join(', ')}` : '; none has been added'}. Nothing was written.`);
+}
+
+/** The next free `C<n>`: one past the largest number in use, so an id is never reused. */
+function nextItemId(goal     ) {
+  let top = 0;
+  for (const item of goal.items) {
+    const m = /^C(\d+)$/.exec(item.id);
+    if (m) top = Math.max(top, Number(m[1]));
+  }
+  return `C${top + 1}`;
+}
+
+const progressOf = (goal     ) => ({ met: goal.items.filter((i     ) => i.met).length, total: goal.items.length });
+
+function checkLine(goalId     , item     ) {
+  return `Record a met item with evidence: doflow-run goal --action check --goal ${goalId} --item ${item} --evidence "<what shows it>"`;
+}
+
+function doneLine(goalId     ) {
+  return `Every item of ${goalId} is met; ask the user, then: doflow-run goal --action done --goal ${goalId} --channel question`;
+}
+
+// ── add, item ──────────────────────────────────────────────────────────────────────────────────
+
+/** IC-022 `add`: one `goal.added` event with the outcome and the checklist, ids `C1`, `C2`, ... */
+function addGoal({ root, goal, statement, items, channel, now = new Date(), fsImpl = nodeFs }     ) {
+  const id = goalIdOf(goal);
+  const outcome = requiredText(statement, '--statement');
+  const list = Array.isArray(items) ? items : items === undefined ? [] : [items];
+  if (list.length === 0) throw new FollowupUsageError('--item is required for --action add: at least one checklist item (repeat --item for more)');
+  if (list.length > ITEMS_MAX) throw new FollowupUsageError(`--item was given ${list.length} times; a goal starts with at most ${ITEMS_MAX} items`);
+  const problems      = [];
+  const checklist = list.map((raw, index) => ({ id: `C${index + 1}`, text: oneLine(raw, `--item ${index + 1}`, problems) }));
+  if (problems.length) throw new FollowupUsageError(problems.join('; '));
+  const by = channelBy(channel);
+  if (readFold(root, { fsImpl, now }).goals.some((g     ) => g.goal === id)) return refusal('add', 'goal-exists', `${id} already exists. Nothing was written.`);
+  const out = appendEvents(root, [{ type: 'goal.added', by, data: { goal: id, outcome, items: checklist } }], { now, fsImpl });
+  if (!out.ok) return refusalFrom('add', out);
+  return {
+    ok: true, action: 'add', goal: id, outcome, items: checklist, events: out.written.map((w     ) => w.file),
+    next: [`Link a feature that serves it: doflow-run goal --action link --goal ${id} --slug <slug>`, checkLine(id, 'C1')],
+  };
+}
+
+/** IC-022 `item`: one `goal.item-added` event; the id is the next free `C<n>`. */
+function addItem({ root, goal, text, channel, now = new Date(), fsImpl = nodeFs }     ) {
+  const id = goalIdOf(goal);
+  const itemText = requiredText(text, '--text');
+  const by = channelBy(channel);
+  // The id is chosen before the lock, so a writer that took it first makes this call refuse; a retry picks the next one.
+  for (let attempt = 0; ; attempt += 1) {
+    const fold = readFold(root, { fsImpl, now });
+    const found = fold.goals.find((g     ) => g.goal === id);
+    if (!found) return unknownGoal('item', fold, id);
+    const item = { id: nextItemId(found), text: itemText };
+    const out = appendEvents(root, [{ type: 'goal.item-added', by, data: { goal: id, item } }], { now, fsImpl });
+    if (out.ok) return { ok: true, action: 'item', goal: id, item, events: out.written.map((w     ) => w.file), next: [checkLine(id, item.id)] };
+    const raced = out.conflict && out.conflict.code === 'illegal-transition' && /already has item/.test(out.conflict.reason);
+    if (!raced || attempt >= 4) return refusalFrom('item', out);
+  }
+}
+
+// ── check, link ────────────────────────────────────────────────────────────────────────────────
+
+/** IC-022 `check`: `goal.checked` with `met: true`, or `met: false` under `--unmet`; evidence either way (DEC-015). */
+function checkItem({ root, goal, item, evidence, unmet = false, channel, now = new Date(), fsImpl = nodeFs }     ) {
+  const id = goalIdOf(goal);
+  const itemId = itemIdOf(item);
+  const proof = requiredText(evidence, '--evidence');
+  const by = channelBy(channel);
+  const before = readFold(root, { fsImpl, now });
+  const found = before.goals.find((g     ) => g.goal === id);
+  if (!found) return unknownGoal('check', before, id);
+  if (!found.items.some((i     ) => i.id === itemId)) {
+    return refusal('check', 'unknown-item', `${id} has no item ${itemId}; its items are ${found.items.map((i     ) => i.id).join(', ')}. Nothing was written.`);
+  }
+  const met = !unmet;
+  const out = appendEvents(root, [{ type: 'goal.checked', by, data: { goal: id, item: itemId, met, evidence: proof } }], { now, fsImpl });
+  if (!out.ok) return refusalFrom('check', out);
+  const after = readFold(root, { fsImpl, now }).goals.find((g     ) => g.goal === id) || found;
+  const progress = progressOf(after);
+  const proposeDone = after.status === 'open' && progress.total > 0 && progress.met === progress.total;
+  const unchecked = after.items.find((i     ) => !i.met);
+  return {
+    ok: true, action: 'check', goal: id, item: itemId, met, evidence: proof, progress, proposeDone, events: out.written.map((w     ) => w.file),
+    next: proposeDone ? [doneLine(id)] : unchecked && after.status === 'open' ? [checkLine(id, unchecked.id)] : [],
+  };
+}
+
+/** IC-022 `link`: one `goal.linked` event; a feature serves one goal at most (DEC-009). */
+function linkFeature({ root, goal, slug, replace = false, channel, now = new Date(), fsImpl = nodeFs }     ) {
+  const id = goalIdOf(goal);
+  if (!slug) throw new FollowupUsageError('--slug is required for --action link');
+  if (!isSafeSlug(slug)) throw new FollowupUsageError(invalidSlugRefusal(slug).message);
+  const by = channelBy(channel);
+  const fold = readFold(root, { fsImpl, now });
+  if (!fold.goals.some((g     ) => g.goal === id)) return unknownGoal('link', fold, id);
+  const feature = fold.features.find((f     ) => f.slug === slug);
+  if (!feature) return refusal('link', 'untracked-feature', `${slug} is not a tracked feature, so no goal can link it; run doflow-run lifecycle --action init --slug ${slug} first. Nothing was written.`);
+  if (feature.goal === id) return { ok: true, action: 'link', goal: id, slug, linked: 'already', replaced: null, events: [], next: [] };
+  if (feature.goal && !replace) {
+    return refusal('link', 'goal-already-linked', `${slug} already serves ${feature.goal}; a feature serves one goal at most. Pass --replace to move it to ${id}. Nothing was written.`);
+  }
+  const out = appendEvents(root, [{ type: 'goal.linked', by, data: { goal: id, slug, replace: Boolean(replace) } }], { now, fsImpl });
+  if (!out.ok) return refusalFrom('link', out);
+  return { ok: true, action: 'link', goal: id, slug, linked: 'new', replaced: feature.goal || null, events: out.written.map((w     ) => w.file), next: [] };
+}
+
+// ── list ───────────────────────────────────────────────────────────────────────────────────────
+
+/** IC-022 progress for one goal: items, `progress`, `proposeDone`, linked features by status and the nudges. */
+function progressView(goal     , fold     , statuses     , conflicts = []) {
+  const view = goalView(goal, fold.features, statuses, conflicts);
+  return {
+    goal: goal.goal, outcome: goal.outcome, status: goal.status,
+    items: goal.items.map((i     ) => ({ id: i.id, text: i.text, met: i.met, evidence: i.evidence })),
+    progress: view.items, proposeDone: view.proposeDone, features: view.features, nudges: view.nudges,
+    ...(view.conflicts ? { conflicts: view.conflicts } : {}),
+    ...(goal.status === 'done' ? { reason: goal.reason } : {}),
+  };
+}
+
+/** IC-022 `list`: every goal, or the one named, with its progress. Reads git only when a goal has a linked feature. */
+function listGoals({ root, goal, now = new Date(), fsImpl = nodeFs }     ) {
+  const id = goal === undefined ? null : goalIdOf(goal);
+  const fold = readFold(root, { fsImpl, now });
+  const shown = id === null ? fold.goals : fold.goals.filter((g     ) => g.goal === id);
+  if (id !== null && shown.length === 0) return unknownGoal('list', fold, id);
+  const linked = new Set(fold.features.filter((f     ) => shown.some((g     ) => g.goal === f.goal)).map((f     ) => f.slug));
+  const statuses = linked.size ? deriveStatuses({ root, fold }) : { statuses: {} };
+  const conflictsByGoal = goalConflicts(root, fold, fsImpl);
+  const goals = shown.map((g     ) => progressView(g, fold, statuses, conflictsByGoal.get(g.goal)));
+  const next = [];
+  for (const g of goals.filter((x     ) => x.status === 'open')) {
+    if (g.proposeDone) next.push(doneLine(g.goal));
+    else {
+      const unchecked = g.items.find((i     ) => !i.met);
+      if (unchecked) next.push(checkLine(g.goal, unchecked.id));
+    }
+  }
+  for (const g of goals.filter((x     ) => x.conflicts)) next.push(...goalConflictNext(g.goal, g.conflicts));
+  const result      = { ok: true, action: 'list', goals, conflicts: fold.conflicts, unreadable: fold.unreadable, unreadableReasons: fold.unreadableReasons, next };
+  if (statuses.reason) result.reason = statuses.reason;
+  return result;
+}
+
+// ── done ───────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * IC-022 `done`: one `goal.done` event. Only the user closes a goal (DEC-004), so `default` is
+ * refused; with unmet items it is refused unless `--reason` says why the user closes it anyway.
+ */
+function doneGoal({ root, goal, reason, channel, now = new Date(), fsImpl = nodeFs }     ) {
+  const id = goalIdOf(goal);
+  const why = textOf(reason, '--reason');
+  const by = channelBy(channel);
+  if (!USER_CHANNELS.includes(channel)) {
+    return refusal('done', 'not-user', `only the user marks a goal done: pass --channel question, gate or prompt once the user has said so (got ${channel ? `'${channel}'` : 'no channel'}). Nothing was written.`);
+  }
+  const fold = readFold(root, { fsImpl, now });
+  const found = fold.goals.find((g     ) => g.goal === id);
+  if (!found) return unknownGoal('done', fold, id);
+  if (found.status === 'done') return refusal('done', 'already-done', `${id} is already done. Nothing was written.`);
+  const unmet = found.items.filter((i     ) => !i.met).map((i     ) => i.id);
+  if (unmet.length && !why) {
+    return refusal('done', 'items-unmet', `${id} has unmet items (${unmet.join(', ')}); check them with evidence, or pass --reason to say why the user closes it anyway. Nothing was written.`);
+  }
+  const out = appendEvents(root, [{ type: 'goal.done', by, data: { goal: id, reason: why } }], { now, fsImpl });
+  if (!out.ok) return refusalFrom('done', out);
+  return { ok: true, action: 'done', goal: id, reason: why, unmet, events: out.written.map((w     ) => w.file), next: [] };
+}
+
+module.exports = {
+  addGoal, addItem, checkItem, linkFeature, listGoals, doneGoal,
+  GOAL_ID_MAX, ITEMS_MAX, USER_CHANNELS,
+};

package/src/runtime/lifecycle/intent-writer.js

@@ -0,0 +1,86 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * Promotion to a new intent (IC-024, FR-005). Creates `agent-docs/intent/<kebab-title>.md` under the
+ * IC-001 root from headings fixed in this file, never from a template file: an installed runtime
+ * ships no template where it could read one. `core/shared/templates/doflow/intent-template.md`
+ * holds the same five headings and a guard test compares the two lists. An existing file is never
+ * touched; the create is exclusive, so a refusal is the file system's own answer.
+ */
+
+const nodeFs = require('node:fs');
+const path = require('node:path');
+
+const INTENT_DIR_REL = path.join('agent-docs', 'intent');
+const TITLE_MAX = 80;
+const SLUG_MAX = 60;
+
+/** The five intent headings after the first, each with the one-line prompt the new file carries. */
+const INTENT_SECTIONS = [
+  { heading: '1. Problem', prompt: null },
+  { heading: '2. Proposed outcome', prompt: '(What would be observably different if this were addressed?)' },
+  { heading: '3. Affected', prompt: '(Who and what this touches.)' },
+  { heading: '4. Constraints', prompt: '(What already bounds this; write "none known" if nothing does.)' },
+  { heading: '5. Open questions', prompt: '(What you do not know yet.)' },
+];
+
+/** `Cart robustness!` -> `cart-robustness`; empty when the title holds no letter or digit. */
+function kebabTitle(title     )         {
+  return String(title).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, SLUG_MAX).replace(/-+$/, '');
+}
+
+function sourceParts(source     )        {
+  switch (source.kind) {
+    case 'stage': return [source.kind, source.feature, source.stage];
+    case 'run': return [source.kind, source.taskClass, source.taskId, source.stage];
+    case 'release': return [source.kind, source.release];
+    case 'report': return [source.kind, source.release, source.feature];
+    case 'failure': return [source.kind, source.ref];
+    default: return [source.kind];
+  }
+}
+
+/**
+ * @param {{title:string, by:'user'|'agent', date:string, items:Array<{id:string,statement:string,source:Object}>}} intent
+ * @returns {string} the file content
+ */
+function renderIntent({ title, by, date, items }                                                                                                           )         {
+  const lines = [
+    `# Intent: ${title}`,
+    '',
+    `**Raised by:** ${by}, through doflow-run followup --action promote · **Date:** ${date}`,
+  ];
+  for (const { heading, prompt } of INTENT_SECTIONS) {
+    lines.push('', `## ${heading}`, '');
+    if (prompt) lines.push(prompt);
+    else for (const item of items) lines.push(`- ${item.id}: ${item.statement} (source: ${sourceParts(item.source).filter(Boolean).join(', ')})`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * Creates the intent file with an exclusive create.
+ * @returns {{ok:true, file:string, path:string}|{ok:false, finding:'intent-exists'|'invalid-title', message:string}}
+ *   `path` is root-relative with `/` separators.
+ */
+function writeIntent(root        , intent     , { fsImpl = nodeFs }      = {})      {
+  const title = String(intent.title ?? '').trim();
+  const name = kebabTitle(title) || intent.fallbackName || '';
+  if (!name || title.length > TITLE_MAX || /[\r\n\u2028\u2029\u0085]/.test(title)) {
+    return { ok: false, finding: 'invalid-title', message: `the title must be one line of at most ${TITLE_MAX} characters with a letter or digit in it. Nothing was written.` };
+  }
+  const rel = path.join(INTENT_DIR_REL, `${name}.md`);
+  const file = path.join(root, rel);
+  fsImpl.mkdirSync(path.dirname(file), { recursive: true });
+  try {
+    fsImpl.writeFileSync(file, renderIntent({ ...intent, title }), { encoding: 'utf8', flag: 'wx' });
+  } catch (error     ) {
+    if (error.code === 'EEXIST') return { ok: false, finding: 'intent-exists', message: `${rel.split(path.sep).join('/')} already exists and was left untouched. Nothing was written.` };
+    throw error;
+  }
+  return { ok: true, file, path: rel.split(path.sep).join('/') };
+}
+
+module.exports = { writeIntent, renderIntent, kebabTitle, INTENT_SECTIONS, TITLE_MAX };

package/src/runtime/lifecycle/overview.js

@@ -0,0 +1,292 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * `lifecycle --action overview | init | status` (IC-007, IC-008, IC-021): the project's open
+ * follow-ups, intents, goals and feature statuses, and the writes that tie a new feature to them.
+ * Each function returns a result object without printing. The overview is read-only: it creates no
+ * folder and writes no file.
+ */
+
+const nodeFs = require('node:fs');
+const path = require('node:path');
+const { isSafeSlug, invalidSlugRefusal } = require('../task-scope.js');
+const { withDerivedDone } = require('./fold.js');
+const { appendEvents, readFold, readEvents } = require('./event-store.js');
+const { deriveStatuses, bucketize, behindNote } = require('./status.js');
+const { FollowupUsageError, parseIds } = require('./followup.js');
+
+/** The failure store, or null when its module cannot be loaded: the overview then reports no failures. */
+function failureStoreOrNull() {
+  try { return require('../failure/store.js'); } catch { return null; }
+}
+
+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;
+
+const refusal = (action     , finding     , message     ) => ({ ok: false, action, finding, message });
+
+function statusMap(derived     ) {
+  return Object.fromEntries(Object.entries(derived.statuses).map(([slug, entry]               ) => [slug, entry.status]));
+}
+
+/** The new and regressed failure entries inside the DoFlow repository, else null. */
+function failureEntries(root     ) {
+  const failureStore = failureStoreOrNull();
+  if (failureStore === null || !failureStore.isDoflowRepo(root)) return null;
+  return failureStore.loadEntries().entries.filter((e     ) => failureStore.SHOWN_BY_DEFAULT.has(e.status)).map(failureStore.listedEntry);
+}
+
+/** Reports first, then the oldest first; the id keeps equal instants in a stable order. */
+function byDiscoveryOrder(a     , b     ) {
+  const report = Number(b.source.kind === 'report') - Number(a.source.kind === 'report');
+  if (report !== 0) return report;
+  const delta = Date.parse(a.history[0].at) - Date.parse(b.history[0].at);
+  return delta !== 0 ? delta : (a.id < b.id ? -1 : 1);
+}
+
+function shownItem(item     , pending     ) {
+  const shown      = {
+    id: item.id, statement: item.statement, source: item.source, state: item.state,
+    promoted: Boolean(item.intent), intent: item.intent, added: item.added,
+  };
+  if (pending !== undefined) shown.pending = pending;
+  return shown;
+}
+
+/** A bucket for display: the true count and the most recently tracked slugs, in tracking order. */
+function shownBucket(slugs     ) {
+  const shown = slugs.slice(-FEATURES_SHOWN);
+  return { count: slugs.length, shown, more: slugs.length - shown.length };
+}
+
+/**
+ * The fold's conflicts raised by goal events, by the goal they name. The fold's conflict carries only
+ * the event id, so the goal comes from the event; a dropped `goal.item-added` also carries the item id
+ * and its text, which is data from another clone, shown but never put into a `next` line. A dropped item
+ * whose text the goal now holds (the user re-added it) is no longer reported.
+ * @returns {Map<string, Array<Object>>}
+ */
+function goalConflicts(root     , fold     , fsImpl = nodeFs) {
+  const byGoal = new Map();
+  const raised = fold.conflicts.filter((c     ) => typeof c.type === 'string' && c.type.startsWith('goal.'));
+  if (raised.length === 0) return byGoal;
+  const events = new Map          (readEvents(root, { fsImpl }).events.map((e     ) => [e.id, e]));
+  for (const c of raised) {
+    const event = events.get(c.event);
+    const goal = event && event.data && event.data.goal;
+    if (typeof goal !== 'string') continue;
+    const entry = { ...c };
+    if (c.type === 'goal.item-added' && event.data.item) {
+      // Event files are never removed, so the dropped item is resolved once the goal holds an item with that text.
+      const held = fold.goals.find((g     ) => g.goal === goal);
+      if (held && held.items.some((i     ) => i.text === String(event.data.item.text ?? ''))) continue;
+      Object.assign(entry, { item: event.data.item.id, text: event.data.item.text });
+    }
+    if (!byGoal.has(goal)) byGoal.set(goal, []);
+    byGoal.get(goal).push(entry);
+  }
+  return byGoal;
+}
+
+/** One `next` line per kind of goal conflict, telling the user how to resolve it. */
+function goalConflictNext(goalId     , conflicts     ) {
+  const next = [];
+  if (conflicts.some((c     ) => c.type === 'goal.item-added')) {
+    next.push(`An item added to ${goalId} from another clone was dropped because its id was already taken; re-add it under a new text: doflow-run goal --action item --goal ${goalId} --text "<the item>"`);
+  }
+  if (conflicts.some((c     ) => c.type === 'goal.added')) {
+    next.push(`Another clone added goal ${goalId} first and its record won; re-add yours under a different goal id: doflow-run goal --action add --goal <new-id> --statement "<outcome>"`);
+  }
+  if (conflicts.some((c     ) => c.type !== 'goal.item-added' && c.type !== 'goal.added')) {
+    next.push(`An event for ${goalId} from another clone was dropped (see conflicts); redo it with doflow-run goal --action list as the current state`);
+  }
+  return next;
+}
+
+/** Progress, linked features by status and the nudges of one open goal (IC-022). */
+function goalView(goal     , features     , statuses     , conflicts      = []) {
+  const linked = features.filter((f     ) => f.goal === goal.goal).map((f     ) => f.slug);
+  const buckets = bucketize(Object.fromEntries(linked.map((slug     ) => [slug, statuses.statuses[slug] || { status: 'unknown' }])), linked);
+  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`;
+    for (const item of goal.items.filter((i     ) => !i.met)) nudges.push(`${item.id} is unchecked and ${who}`);
+  }
+  return {
+    goal: goal.goal, outcome: goal.outcome,
+    items: { met, total: goal.items.length },
+    proposeDone: goal.status === 'open' && goal.items.length > 0 && met === goal.items.length,
+    features: buckets,
+    nudges,
+    ...(conflicts.length ? { 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 (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}`);
+  }
+  if (goals.length) next.push(`Link the new feature to a goal: add --goal ${goals[0].goal} to the init line`);
+  for (const g of goals.filter((x     ) => x.conflicts)) next.push(...goalConflictNext(g.goal, g.conflicts));
+  if (maintain && pendingItems.length) {
+    const id = pendingItems[0].id;
+    const unpromoted = pendingItems.find((i     ) => !i.promoted);
+    next.push(
+      `Keep open: doflow-run followup --action settle --ids ${id} --as kept --reason "<why it stays>" --channel question`,
+      `Dismiss: doflow-run followup --action settle --ids ${id} --as dismissed --reason "<why>" --channel question`,
+      ...(unpromoted ? [`Promote to a new intent: doflow-run followup --action promote --ids ${unpromoted.id} --title "<intent title>" --channel question`] : []),
+      `Start a fix: doflow-run followup --action settle --ids ${id} --as fix --reason "<where it is routed>" --channel question`,
+      `Done outside a feature: doflow-run followup --action settle --ids ${id} --as done --evidence "<what shows it>" --channel question`,
+    );
+  }
+  if (failures && failures.length) {
+    next.push('Settle a failure entry: doflow-run failure --action settle --fp <fp> --as noise|fixed|imported --reason "<why>"');
+  }
+  if (maintain) {
+    for (const goal of goals.filter((g     ) => g.proposeDone)) {
+      next.push(`Every item of ${goal.goal} is met; ask the user, then: doflow-run goal --action done --goal ${goal.goal} --channel question`);
+    }
+  }
+  return next;
+}
+
+/**
+ * IC-007.
+ * @param {Object} options
+ * @param {string} options.root the IC-001 root
+ * @param {boolean} [options.maintain] the `/do maintain` view: up to 50 items and `pending`
+ * @param {string} [options.since] ISO time; with `maintain`, an open item with no settlement at or after it is pending
+ */
+function buildOverview({ root, maintain = false, since, now = new Date(), fsImpl = nodeFs }     ) {
+  let sinceMs = null;
+  if (since !== undefined && since !== null) {
+    sinceMs = Date.parse(since);
+    if (!Number.isFinite(sinceMs)) throw new FollowupUsageError(`--since must be an ISO time such as 2026-10-05T09:00:00Z (got '${since}')`);
+  }
+  const fold = readFold(root, { fsImpl, now });
+  const derived = deriveStatuses({ root, fold });
+  const followups = withDerivedDone(fold.followups, statusMap(derived));
+  const open = followups.filter((item     ) => item.state === 'open');
+  const limit = maintain ? MAINTAIN_SHOWN : DISCOVERY_SHOWN;
+  // A promotion settles an item for the maintain loop as much as a settlement does: it stays open with an intent.
+  const settledSince = (item     ) => item.history.some((h     ) => (h.type === 'followup.settled' || h.type === 'followup.promoted') && (sinceMs === null || Date.parse(h.at) >= sinceMs));
+  const pendingOf = (item     ) => !settledSince(item);
+  // Maintain shows pending items first (IC-007), so a loop over more than MAINTAIN_SHOWN items reaches the rest.
+  const ordered = [...open].sort((a, b) => (maintain ? Number(pendingOf(b)) - Number(pendingOf(a)) : 0) || byDiscoveryOrder(a, b));
+  const items = ordered.slice(0, limit).map((item) => shownItem(item, maintain ? pendingOf(item) : undefined));
+
+  const intentGroups = new Map();
+  for (const item of open.filter((i     ) => i.intent)) {
+    if (!intentGroups.has(item.intent)) intentGroups.set(item.intent, []);
+    intentGroups.get(item.intent).push(item.id);
+  }
+  const intents = [...intentGroups].map(([intentPath, ids]) => ({ path: intentPath, items: ids }));
+  const conflictsByGoal = goalConflicts(root, fold, fsImpl);
+  const goals = fold.goals.filter((g     ) => g.status === 'open').map((g     ) => goalView(g, fold.features, derived, conflictsByGoal.get(g.goal)));
+
+  const result      = {
+    ok: true,
+    mode: maintain ? 'maintain' : 'discovery',
+    releaseMode: derived.releaseMode,
+    integrationRef: derived.integrationRef,
+    // Follow-ups, goals and intents need no git: when git fails the overview still answers, every feature
+    // status `unknown`, and says why here (null when git answered).
+    gitError: derived.failure || null,
+    followups: { open: open.length, shown: items.length, items },
+    intents,
+    goals,
+    features: derived.features,
+    // The bounded form of the two buckets that only grow; `features` keeps every slug (IC-007).
+    featuresShown: { finished: shownBucket(derived.features.finished), awaitingRelease: shownBucket(derived.features.awaitingRelease) },
+    conflicts: fold.conflicts,
+    unreadable: fold.unreadable,
+    unreadableReasons: fold.unreadableReasons,
+    // Failure entries come from the machine-wide failure store, which only the DoFlow repository's own
+    // maintain view reads (IC-023); nothing in the project store feeds it. Read-only: the overview
+    // never rotates the failure files, which is the `failure` verb's step.
+    failures: maintain ? failureEntries(root) : null,
+  };
+  if (derived.reason) result.reason = derived.reason;
+  if (derived.integrationBehind > 0) Object.assign(result, { integrationBehind: derived.integrationBehind, note: behindNote(derived.integrationRef, derived.integrationBehind) });
+  if (maintain) result.pending = open.filter(pendingOf).length;
+  result.next = nextLines({ shown: items.length, open: open.length, items, intents, goals, maintain, pendingItems: items.filter((i) => i.pending), failures: result.failures });
+  return result;
+}
+
+// ── init ───────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * IC-008: tracks a feature, optionally taking items and linking a goal, in one all-or-nothing write.
+ * The feature folder is looked for under the IC-001 root itself, never in the current worktree, so a
+ * folder that exists only in a linked worktree is refused.
+ */
+function initFeature({ root, slug, take, intent, goal, now = new Date(), fsImpl = nodeFs }     ) {
+  if (!slug) throw new FollowupUsageError('--slug is required for --action init');
+  const bad = invalidSlugRefusal(slug);
+  if (bad) throw new FollowupUsageError(bad.message);
+  const folder = path.join(root, 'agent-docs', 'doflow', slug);
+  let isFolder = false;
+  try { isFolder = fsImpl.statSync(folder).isDirectory(); } catch { /* absent */ }
+  if (!isFolder) {
+    return refusal('init', 'no-feature-folder', `agent-docs/doflow/${slug} does not exist under the store root ${root}; a folder that exists only in a linked worktree does not count. Nothing was written.`);
+  }
+  const wanted = take === undefined || take === null ? [] : parseIds(take, '--take');
+  const fold = readFold(root, { fsImpl, now });
+  const tracked = fold.features.find((f     ) => f.slug === slug);
+  const ids = [...wanted];
+  if (intent) {
+    for (const item of fold.followups) if (item.state === 'open' && item.intent === intent && !ids.includes(item.id)) ids.push(item.id);
+  }
+  const drafts = [];
+  if (!tracked) drafts.push({ type: 'feature.tracked', by: 'agent', data: { slug } });
+  if (ids.length) drafts.push({ type: 'followup.taken', by: 'agent', data: { ids, feature: slug } });
+  if (goal) {
+    const current = tracked && tracked.goal;
+    if (current && current !== goal) return refusal('init', 'goal-already-linked', `${slug} already serves ${current}; link it with --replace through the goal verb instead. Nothing was written.`);
+    if (current !== goal) drafts.push({ type: 'goal.linked', by: 'agent', data: { goal, slug, replace: false } });
+  }
+  const next = [];
+  if (intent && ids.length === 0) next.push(`No open follow-up names ${intent}; nothing was taken from it`);
+  let events = [];
+  if (drafts.length) {
+    const out = appendEvents(root, drafts, { now, fsImpl });
+    if (!out.ok) {
+      const code = out.conflict && ['unknown-id', 'untracked-feature', 'goal-already-linked', 'unknown-goal'].includes(out.conflict.code) ? out.conflict.code : out.finding;
+      return refusal('init', code, out.message);
+    }
+    events = out.written.map((w     ) => w.file);
+  }
+  return { ok: true, action: 'init', slug, tracked: tracked ? 'already' : 'new', taken: ids, goal: goal || (tracked && tracked.goal) || null, events, next };
+}
+
+// ── status ─────────────────────────────────────────────────────────────────────────────────────
+
+/** IC-021 `status`: the derived status of one tracked feature. */
+function featureStatus({ root, slug, now = new Date(), fsImpl = nodeFs }     ) {
+  if (!slug) throw new FollowupUsageError('--slug is required for --action status');
+  if (!isSafeSlug(slug)) throw new FollowupUsageError(invalidSlugRefusal(slug).message);
+  const fold = readFold(root, { fsImpl, now });
+  if (!fold.features.some((f     ) => f.slug === slug)) {
+    return refusal('status', 'untracked-feature', `${slug} is not a tracked feature, so no status is derived for it; run doflow-run lifecycle --action init --slug ${slug} first.`);
+  }
+  const derived = deriveStatuses({ root, fold });
+  const entry = derived.statuses[slug];
+  const result      = {
+    ok: true, action: 'status', slug, status: entry.status, integrationRef: derived.integrationRef,
+    evidence: entry.evidence, release: entry.release,
+    takenItems: fold.followups.filter((item     ) => item.takenBy === slug && item.state === 'taken').map((item     ) => item.id),
+  };
+  if (derived.reason) result.reason = derived.reason;
+  if (derived.integrationBehind > 0) Object.assign(result, { integrationBehind: derived.integrationBehind, note: behindNote(derived.integrationRef, derived.integrationBehind) });
+  return result;
+}
+
+module.exports = { buildOverview, initFeature, featureStatus, goalView, goalConflicts, goalConflictNext, DISCOVERY_SHOWN, MAINTAIN_SHOWN, FEATURES_SHOWN };