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

package/src/runtime/lifecycle/retention.ts

@@ -0,0 +1,212 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * Which event files the retention switch may delete. `DOFLOW_RETENTION_HOURS` overrides the window;
+ * when it is unset, the declared default applies only while the project's `prune` setting is on.
+ * Events are grouped into deletion units, the follow-ups and goals they name
+ * joined by any event that names more than one, and a unit goes only as a whole: when every item in
+ * it is settled in the fold (a follow-up done or dismissed, a goal done) and its newest event is
+ * older than the window. A unit whose removal would change anything else the fold shows (another
+ * item, a feature, a release, a conflict) is kept.
+ *
+ * `parseWindow` remains pure. `retentionWindow` composes its unset case with the declared storage
+ * default and the project's prune setting; explicit environment values retain their existing meaning.
+ */
+
+const nodeFs = require('node:fs');
+const { isDeepStrictEqual } = require('node:util');
+const { REPO_ROOT } = require('../../helper/repo-root.ts');
+const { loadStorageRegistry } = require('../storage/registry.ts');
+const { resolveRoots, readPruneSetting } = require('../storage/roots.ts');
+const { foldInto, finalize } = require('./fold.ts');
+
+const HOUR_MS = 3600000;
+
+/** @returns {{state: 'off'} | {state: 'on', hours: number, ms: number} | {state: 'invalid', raw: string}} */
+function parseWindow(env: Record<string, string | undefined> = process.env): { state: 'off' } | { state: 'on'; hours: number; ms: number } | { state: 'invalid'; raw: string } {
+  const raw = env.DOFLOW_RETENTION_HOURS;
+  if (raw === undefined || raw === '') return { state: 'off' };
+  if (/^[1-9][0-9]*$/.test(raw) && Number.isSafeInteger(Number(raw))) {
+    const hours = Number(raw);
+    return { state: 'on', hours, ms: hours * HOUR_MS };
+  }
+  return { state: 'invalid', raw: String(raw) };
+}
+
+/** Composes IC-013's explicit environment override with the declared lifecycle default. */
+function retentionWindow({ env = process.env, projectRoot, registry, fsImpl = nodeFs }: any = {}): any {
+  const parsed = parseWindow(env);
+  if (parsed.state === 'invalid') return parsed;
+  if (parsed.state === 'on') return { ...parsed, source: 'env' };
+  let activeRegistry: any;
+  try {
+    activeRegistry = registry || loadStorageRegistry({ repoRoot: REPO_ROOT, fsImpl });
+  } catch {
+    return { state: 'off' };
+  }
+  const roots = resolveRoots({ registry: activeRegistry, projectRoot, env });
+  if (readPruneSetting({ registry: activeRegistry, roots, rootId: 'project-state', fsImpl }).setting !== 'on') return { state: 'off' };
+  const lifecycleStore = activeRegistry.stores.find((store: any) => store.id === 'lifecycle-events');
+  if (!lifecycleStore) throw new Error('Storage registry has no lifecycle-events store');
+  const hours = lifecycleStore.bound.defaultHours;
+  return { state: 'on', hours, ms: hours * HOUR_MS, source: 'default' };
+}
+
+function isText(value: any): boolean { return typeof value === 'string' && value.trim() !== ''; }
+
+/** The item keys an event names, or none when it is not about a follow-up or a goal. */
+function itemsOf(event: any): string[] {
+  const d = event.data;
+  const ids = (list: any): string[] => (Array.isArray(list) && list.length > 0 && list.every(isText) ? list : []);
+  switch (event.type) {
+    case 'followup.added': return isText(d.id) ? [`followup:${d.id}`] : [];
+    case 'followup.taken':
+    case 'followup.promoted': return ids(d.ids).map((id: string) => `followup:${id}`);
+    case 'followup.settled': return (isText(d.id) ? [d.id] : ids(d.ids)).map((id: string) => `followup:${id}`);
+    case 'goal.added':
+    case 'goal.item-added':
+    case 'goal.checked':
+    case 'goal.done':
+    case 'goal.linked': return isText(d.goal) ? [`goal:${d.goal}`] : [];
+    default: return [];
+  }
+}
+
+/** Groups the items into units: items named together by one event share a unit. */
+function unitsOf(events: any[], shouldStop?: () => boolean): any[] | null {
+  const parent = new Map<string, string>();
+  const find = (key: string): string | null => {
+    while (parent.get(key) !== key) {
+      if (shouldStop?.()) return null;
+      parent.set(key, parent.get(parent.get(key) as string) as string);
+      key = parent.get(key) as string;
+    }
+    return key;
+  };
+  const named: Array<{ event: any; items: string[] }> = [];
+  for (const event of events) {
+    if (shouldStop?.()) return null;
+    named.push({ event, items: [...new Set(itemsOf(event))] });
+  }
+  for (const { items } of named) {
+    if (shouldStop?.()) return null;
+    for (const key of items) if (!parent.has(key)) parent.set(key, key);
+    for (const key of items.slice(1)) {
+      const root = find(key), head = find(items[0]);
+      if (root === null || head === null) return null;
+      parent.set(root, head);
+    }
+  }
+  const units = new Map<string, any>();
+  for (const { event, items } of named) {
+    if (shouldStop?.()) return null;
+    if (items.length === 0) continue;
+    const head = find(items[0]);
+    if (head === null) return null;
+    if (!units.has(head)) units.set(head, { items: new Set(), events: [] });
+    const unit = units.get(head);
+    for (const key of items) unit.items.add(key);
+    unit.events.push(event);
+  }
+  return [...units.values()];
+}
+
+function isSettled(state: any, key: string): boolean {
+  const [kind, id] = [key.slice(0, key.indexOf(':')), key.slice(key.indexOf(':') + 1)];
+  if (kind === 'followup') {
+    const item = state.items.get(id);
+    return Boolean(item) && (item.state === 'done' || item.state === 'dismissed');
+  }
+  const goal = state.goals.get(id);
+  return Boolean(goal) && goal.status === 'done';
+}
+
+/** The parts of a fold that removing a unit must leave unchanged. */
+function comparable(result: any): any {
+  const { followups, features, merged, goals, releases, conflicts } = result;
+  return { followups, features, merged, goals, releases, conflicts };
+}
+
+/** Whether dropping `removed` units changes nothing but the removed items themselves. */
+function refoldEqual(events: any[], full: any, removed: any[], now: Date, shouldStop?: () => boolean): boolean | null {
+  if (shouldStop?.()) return null;
+  const gone = new Set<string>(), keys = new Set<string>();
+  for (const unit of removed) {
+    if (shouldStop?.()) return null;
+    for (const event of unit.events) gone.add(event.id);
+    for (const key of unit.items) keys.add(key);
+  }
+  const expected = {
+    ...full,
+    followups: full.followups.filter((f: any) => !keys.has(`followup:${f.id}`)),
+    goals: full.goals.filter((g: any) => !keys.has(`goal:${g.goal}`)),
+    conflicts: full.conflicts.filter((c: any) => !gone.has(c.event)),
+  };
+  const remaining: any[] = [];
+  for (const event of events) {
+    if (shouldStop?.()) return null;
+    if (!gone.has(event.id)) remaining.push(event);
+  }
+  const state = foldInto(remaining, { now, shouldStop });
+  if (state.incomplete) return null;
+  return isDeepStrictEqual(comparable(finalize(state)), comparable(expected));
+}
+
+/**
+ * @param {Object[]} events IC-002 envelopes, as readEvents returns them
+ * @param {{now: Date, windowMs: number, shouldStop?: Function}} options
+ * @returns {{files: string[], units: Array<{items: string[], newestAt: string, files: string[]}>, incomplete?: true}}
+ *   files: `<id>.json` names, sorted
+ */
+function selectExpired(events: any[], { now, windowMs, shouldStop }: any = {}): any {
+  const incomplete = (): any => ({ files: [], units: [], incomplete: true });
+  if (shouldStop?.()) return incomplete();
+  const state = foldInto(events, { now, shouldStop });
+  if (state.incomplete || shouldStop?.()) return incomplete();
+  const cutoff = now.getTime() - windowMs;
+  const served = new Set<string>();
+  for (const feature of state.tracked.values()) {
+    if (shouldStop?.()) return incomplete();
+    if (feature.goal) served.add(feature.goal);
+  }
+  const named = unitsOf(events, shouldStop);
+  if (!named || shouldStop?.()) return incomplete();
+  const candidates: any[] = [];
+  for (const unit of named) {
+    if (shouldStop?.()) return incomplete();
+    const newest = unit.events.reduce((max: string, event: any) => (Date.parse(event.at) > Date.parse(max) ? event.at : max), unit.events[0].at);
+    if (shouldStop?.()) return incomplete();
+    let eligible = Date.parse(newest) < cutoff;
+    if (eligible) for (const key of unit.items) {
+      if (shouldStop?.()) return incomplete();
+      if (!isSettled(state, key) || (key.startsWith('goal:') && served.has(key.slice('goal:'.length)))) { eligible = false; break; }
+    }
+    if (eligible) candidates.push({ ...unit, newestAt: newest });
+  }
+  const full = finalize(state);
+  let selected = candidates;
+  const allSafe = refoldEqual(events, full, candidates, now, shouldStop);
+  if (allSafe === null || shouldStop?.()) return incomplete();
+  if (!allSafe) {
+    selected = [];
+    const ordered = [...candidates].sort((a: any, b: any) => Date.parse(a.newestAt) - Date.parse(b.newestAt));
+    if (shouldStop?.()) return incomplete();
+    for (const unit of ordered) {
+      if (shouldStop?.()) return incomplete();
+      const safe = refoldEqual(events, full, [...selected, unit], now, shouldStop);
+      if (safe === null) return incomplete();
+      if (safe) selected.push(unit);
+    }
+  }
+  const units: any[] = [];
+  for (const unit of selected) {
+    if (shouldStop?.()) return incomplete();
+    units.push({ items: [...unit.items].sort(), newestAt: unit.newestAt, files: unit.events.map((event: any) => `${event.id}.json`).sort() });
+  }
+  if (shouldStop?.()) return incomplete();
+  return { files: units.flatMap((unit: any) => unit.files).sort(), units };
+}
+
+module.exports = { parseWindow, retentionWindow, selectExpired };

package/src/runtime/lifecycle/root.ts

@@ -0,0 +1,71 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * The project root every lifecycle record is keyed by (IC-001, DEC-043). Paths are real paths,
+ * because git reports the resolved spelling and a temp directory is often reached through a symlink.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+interface WorktreeEntry { path: string; bare: boolean; prunable: boolean }
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+}
+
+function real(target: string): string {
+  try { return fs.realpathSync(target); } catch { return path.resolve(target); }
+}
+
+/** The entries of `git worktree list --porcelain`: `{path, bare, prunable}`, in git's order. */
+function worktreeEntries(porcelain: string): WorktreeEntry[] {
+  const entries: WorktreeEntry[] = [];
+  for (const block of porcelain.split(/\n\s*\n/)) {
+    const lines = block.split('\n').map((line) => line.replace(/\r$/, ''));
+    const head = lines.find((line) => line.startsWith('worktree '));
+    if (!head) continue;
+    entries.push({
+      path: head.slice('worktree '.length),
+      bare: lines.some((line) => line.trim() === 'bare'),
+      prunable: lines.some((line) => line === 'prunable' || line.startsWith('prunable ')),
+    });
+  }
+  return entries;
+}
+
+/** A working tree that exists and that git itself calls one: a submodule's or a separate git dir's
+ * entry points at a git directory, where `--is-inside-work-tree` prints `false`. */
+function isRealWorkTree(entry: WorktreeEntry): boolean {
+  if (entry.bare || entry.prunable || !fs.existsSync(entry.path)) return false;
+  try { return git(entry.path, ['rev-parse', '--is-inside-work-tree']).trim() === 'true'; } catch { return false; }
+}
+
+function showToplevel(cwd: string): string | null {
+  try {
+    const top = git(cwd, ['rev-parse', '--show-toplevel']).trim();
+    return top ? real(top) : null;
+  } catch { return null; }
+}
+
+/**
+ * DEC-043. The first entry of `git worktree list --porcelain` when it is a real working tree, so
+ * every linked worktree of one clone shares one store. When the first entry is the bare repository
+ * of a bare-clone layout, there is no main working tree to share, and the current worktree's own
+ * root is used. In every other case, and outside a repository, `--show-toplevel` and then the
+ * working directory.
+ * @param {string} [cwd] defaults to the process working directory
+ * @returns {string} an absolute, real path
+ */
+function projectRoot(cwd: string = process.cwd()): string {
+  let entries: WorktreeEntry[] = [];
+  try { entries = worktreeEntries(git(cwd, ['worktree', 'list', '--porcelain'])); } catch { /* not a repository */ }
+  const first = entries[0];
+  if (first && !first.bare && isRealWorkTree(first)) return real(first.path);
+  return showToplevel(cwd) || real(cwd);
+}
+
+module.exports = { projectRoot, worktreeEntries };

package/src/runtime/lifecycle/status.ts

@@ -0,0 +1,353 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * Feature status deriver (IC-021, DEC-022, DEC-044, DEC-030, DEC-035). A tracked feature is
+ * `finished`, `awaiting-release`, `in-progress` or `unknown`, derived on every read from git and the
+ * release records, and never written. A later read can change a status (design R9).
+ *
+ * The git facts that are not about one feature (the integration ref, the feature branch prefixes,
+ * the release tags and the base tag) come from `do-git-state.sh --lifecycle`, so bash and Node never
+ * derive them twice. The rest is a fixed number of plain `git` calls, however many features are
+ * tracked: one `rev-parse` pins the ref, one `for-each-ref` lists the branches, one
+ * `git log --first-parent --merges` lists the merges, one `git tag --list` (tagged mode) gives the
+ * release tags' commits, and one `git rev-list --parents` reads the commit graph of the pinned ref
+ * and those tags. Every ancestry question (which merge brought a branch tip in, which tag contains a
+ * merge) is then answered from that graph in memory, not by a git call per feature.
+ *
+ * Nothing here writes, fetches or reaches a network.
+ *
+ * Accepted ceilings, stated rather than hidden: a feature's merge evidence is only as good as the
+ * merge commit's subject and the branch name (a squash, a rebase and a fast-forward leave none,
+ * so they reach the user through `notDetected` and `lifecycle --action merged`); the merge log and
+ * the graph are read in full, without `--since` or a lower cut (a skewed clock must not hide a
+ * merge), so their cost grows with the history of the integration ref, once per call; git dates
+ * have one-second resolution, so the lower bound is floored to the second.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { REPO_ROOT } = require('../../helper/repo-root.ts');
+const { resolveBashHelper } = require('../../helper/bash-helper.ts');
+
+const MAX_BUFFER = 256 * 1024 * 1024;
+
+/** Where `do-git-state.sh` is: the shared resolver (package copy first, else the one projected beside the runtime). */
+function resolveGitStateHelper(repoRoot: string = REPO_ROOT, existsImpl: (file: string) => boolean = fs.existsSync): string | null {
+  return resolveBashHelper('do-git-state.sh', repoRoot, existsImpl);
+}
+
+function git(root: string, args: string[]): string {
+  return execFileSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: MAX_BUFFER, stdio: ['ignore', 'pipe', 'ignore'] });
+}
+
+/**
+ * The facts from `do-git-state.sh --lifecycle`, read in `root`; `runtimeRoot` is where the runtime
+ * lives, which only a test moves.
+ * @returns {{integration_ref:string|null, feature_prefixes:string[], release_tags:string[], base_tag:string|null}
+ *   |{error:string}}
+ */
+function readGitFacts(root: string, runtimeRoot: string = REPO_ROOT): any {
+  const helper = resolveGitStateHelper(runtimeRoot);
+  if (!helper) return { error: 'git-state-helper-missing' };
+  try {
+    const out = execFileSync('bash', [helper, '--lifecycle'], { cwd: root, encoding: 'utf8', maxBuffer: MAX_BUFFER, stdio: ['ignore', 'pipe', 'ignore'] });
+    const facts = JSON.parse(out);
+    if (facts.error) return { error: facts.error };
+    return facts;
+  } catch (error: any) {
+    return { error: error.code === 'ENOENT' ? 'bash-not-found' : 'git-state-failed' };
+  }
+}
+
+function escapeRegExp(text: string): string { return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+
+/** The slug appears in the subject bounded by its ends or by characters outside `[a-z0-9-]`. */
+function subjectNames(subject: string, slug: string): boolean {
+  return new RegExp(`(?:^|[^a-z0-9-])${escapeRegExp(slug)}(?:$|[^a-z0-9-])`).test(subject);
+}
+
+/** First-parent merges of `ref`, oldest first. */
+function readMerges(root: string, ref: string): Array<{ sha: string; parents: string[]; ct: number; subject: string }> {
+  const out = git(root, ['log', '--first-parent', '--merges', '--format=%H%x09%P%x09%ct%x09%s', ref]);
+  return out.split('\n').filter(Boolean).map((line) => {
+    const [sha, parents, ct, ...subject] = line.split('\t');
+    return { sha, parents: parents.split(' ').filter(Boolean), ct: Number(ct), subject: subject.join('\t') };
+  }).reverse();
+}
+
+/** Branch refs by short name (`feat/x`, `origin/feat/x`) with their tips; local branches first. */
+function readBranchTips(root: string): Array<{ short: string; local: string; sha: string }> {
+  const out = git(root, ['for-each-ref', '--format=%(refname)%09%(objectname)', 'refs/heads', 'refs/remotes']);
+  const tips: Array<{ short: string; local: string; sha: string }> = [];
+  for (const line of out.split('\n').filter(Boolean)) {
+    const [refname, sha] = line.split('\t');
+    if (refname.startsWith('refs/heads/')) tips.push({ short: refname.slice('refs/heads/'.length), local: refname.slice('refs/heads/'.length), sha });
+    else if (refname.startsWith('refs/remotes/')) {
+      const short = refname.slice('refs/remotes/'.length);
+      tips.push({ short, local: short.slice(short.indexOf('/') + 1), sha });
+    }
+  }
+  return tips;
+}
+
+/** The commit a tag names, peeled through any number of tag objects, or null when it is no commit. */
+function peelTag(root: string, refname: string): string | null {
+  try { return git(root, ['rev-parse', '--verify', '--quiet', `${refname}^{commit}`]).trim() || null; } catch { return null; }
+}
+
+/**
+ * The `v*` tags named in `wanted` with their commits, in the order `git tag` lists them (it honours
+ * `tag.sort`, as `git tag --contains` did), so the first containing tag is the one it would name.
+ * @returns {Array<{name:string, commit:string|null}>}
+ */
+function readTagCommits(root: string, wanted: Set<string>): Array<{ name: string; commit: string | null }> {
+  const out = git(root, ['tag', '--list', 'v*', '--format=%(refname)%09%(objecttype)%09%(objectname)%09%(*objecttype)%09%(*objectname)']);
+  const tags: Array<{ name: string; commit: string | null }> = [];
+  for (const line of out.split('\n').filter(Boolean)) {
+    const [refname, type, object, peeledType, peeled] = line.split('\t');
+    const name = refname.slice('refs/tags/'.length);
+    if (!wanted.has(name)) continue;
+    let commit: string | null = null;
+    if (type === 'commit') commit = object;
+    else if (type === 'tag' && peeledType === 'commit') commit = peeled;
+    else if (type === 'tag') commit = peelTag(root, refname); // a tag of a tag: rare, one call each
+    tags.push({ name, commit });
+  }
+  return tags;
+}
+
+/**
+ * The commit graph reachable from `pinned` and `revs`, read by one `git rev-list --parents`, with the
+ * ancestry questions the status and the release ask answered in memory.
+ *
+ * The first-parent chain of `pinned` is numbered oldest first. Each commit is marked with the oldest
+ * chain commit whose history holds it (its `introducer`): for a commit that came in through a merge
+ * that is the merge, and for a commit on the chain it is the commit itself. Each commit also knows the
+ * newest chain commit in its own history (`chainMax`), so "is chain commit C an ancestor of X" is one
+ * comparison: the chain commits in X's history are always a prefix of the chain.
+ *
+ * Every commit asked about must be in the read: `pinned`, one of `revs`, or an ancestor of one.
+ * @param {string} root
+ * @param {string} pinned a full commit sha
+ * @param {string[]} [revs] further full commit shas whose history is read too
+ */
+function readHistory(root: string, pinned: string, revs: string[] = []): { introducer: (sha: string) => string | undefined; isAncestor: (a: string, b: string) => boolean } {
+  const input = `${[pinned, ...revs].join('\n')}\n`;
+  const out = execFileSync('git', ['rev-list', '--parents', '--topo-order', '--stdin'], { cwd: root, input, encoding: 'utf8', maxBuffer: MAX_BUFFER, stdio: ['pipe', 'pipe', 'ignore'] });
+  const parents = new Map<string, string[]>();
+  const order: string[] = [];
+  for (const line of out.split('\n')) {
+    if (!line) continue;
+    const [sha, ...rest] = line.split(' ');
+    parents.set(sha, rest);
+    order.push(sha);
+  }
+  const chain: string[] = [];
+  for (let sha = pinned; parents.has(sha); sha = (parents.get(sha) as string[])[0]) chain.push(sha);
+  chain.reverse();
+  const chainIndex = new Map<string, number>(chain.map((sha, i): [string, number] => [sha, i]));
+
+  const introducer = new Map<string, string>();
+  for (const head of chain) {
+    const stack: string[] = [head];
+    while (stack.length) {
+      const sha = stack.pop() as string;
+      if (introducer.has(sha) || !parents.has(sha)) continue;
+      introducer.set(sha, head);
+      stack.push(...(parents.get(sha) as string[]));
+    }
+  }
+
+  // --topo-order lists no parent before its children, so walking it backwards meets parents first.
+  const chainMax = new Map<string, number>();
+  for (let i = order.length - 1; i >= 0; i -= 1) {
+    const sha = order[i];
+    let max: number = chainIndex.has(sha) ? (chainIndex.get(sha) as number) : -1;
+    if (max === -1) for (const parent of parents.get(sha) as string[]) max = Math.max(max, chainMax.get(parent) ?? -1);
+    chainMax.set(sha, max);
+  }
+
+  const reached = new Map<string, Set<string>>();
+  function ancestorsOf(sha: string): Set<string> {
+    let seen = reached.get(sha);
+    if (seen) return seen;
+    seen = new Set<string>();
+    const stack: string[] = [sha];
+    while (stack.length) {
+      const next = stack.pop() as string;
+      if (seen.has(next) || !parents.has(next)) continue;
+      seen.add(next);
+      stack.push(...(parents.get(next) as string[]));
+    }
+    reached.set(sha, seen);
+    return seen;
+  }
+
+  return {
+    /** The chain commit that brought `sha` into `pinned`'s history, or undefined when it is not in it. */
+    introducer: (sha: string) => introducer.get(sha),
+    /** `a` is `b` or an ancestor of it; `a` must be in the read. */
+    isAncestor(a: string, b: string): boolean {
+      const index = chainIndex.get(a);
+      if (index !== undefined) return index <= (chainMax.get(b) ?? -1);
+      return ancestorsOf(b).has(a);
+    },
+  };
+}
+
+/**
+ * The merge that brought `tip` into the chain, if the evidence rule holds: the oldest first-parent
+ * merge having the tip as an ancestor, committed at or after the lower bound, with the tip on a
+ * non-first parent and not already on the first. A tip that lies on the first-parent chain itself
+ * (a fast-forward, or a branch with no commits of its own) is its own introducer, so it never counts;
+ * a tip the merge holds but its first parent does not came in on a non-first parent.
+ */
+function introducingMerge(history: () => any, mergeBySha: Map<string, any>, tip: string, lowerBound: number): any {
+  const merge = mergeBySha.get(history().introducer(tip));
+  if (!merge || merge.sha === tip || merge.ct < lowerBound) return null;
+  return merge;
+}
+
+/** Evidence of a merge of `slug` into the pinned ref, tried in IC-021's order, or null. */
+function findEvidence({ slug, lowerBound, merges, mergeBySha, newestCt, history, tips, prefixes, confirmed }: any): { kind: string; ref: string | null; commit: string | null } | null {
+  const branchNames = new Set(prefixes.map((prefix: string) => `${prefix}/${slug}`));
+  // No merge is recent enough for this feature: no branch can have one, so the graph need not be read for it.
+  const branchTips = newestCt < lowerBound ? [] : tips.filter((t: any) => branchNames.has(t.local));
+  for (const tip of branchTips) {
+    const merge = introducingMerge(history, mergeBySha, tip.sha, lowerBound);
+    if (merge) return { kind: 'branch', ref: tip.short, commit: merge.sha };
+  }
+  for (let i = merges.length - 1; i >= 0; i -= 1) {
+    if (merges[i].ct >= lowerBound && subjectNames(merges[i].subject, slug)) return { kind: 'merge-subject', ref: merges[i].sha.slice(0, 7), commit: merges[i].sha };
+  }
+  if (confirmed) return { kind: 'confirmed', ref: null, commit: null };
+  return null;
+}
+
+/** A value computed on first use, so a call that needs no graph never reads one. */
+function lazy<T>(make: () => T): () => T {
+  let value: T;
+  let made = false;
+  return () => {
+    if (!made) { value = make(); made = true; }
+    return value;
+  };
+}
+
+const BUCKET: Record<string, string> = { finished: 'finished', 'awaiting-release': 'awaitingRelease', 'in-progress': 'inProgress', unknown: 'unknown' };
+
+function emptyBuckets(): Record<string, string[]> { return { finished: [], awaitingRelease: [], inProgress: [], unknown: [] }; }
+
+/** Slugs grouped in the four buckets IC-007 and IC-022 show. */
+function bucketize(statuses: any, slugs: string[] = Object.keys(statuses)): Record<string, string[]> {
+  const buckets = emptyBuckets();
+  for (const slug of slugs) {
+    const entry = statuses[slug];
+    if (entry) buckets[BUCKET[entry.status]].push(slug);
+  }
+  return buckets;
+}
+
+function result(releaseMode: string, integrationRef: string | null, reason: string | null, statuses: any, notDetected: string[] = [], behind: number = 0): any {
+  return { releaseMode, integrationRef, integrationBehind: behind, reason, statuses, features: bucketize(statuses), notDetected };
+}
+
+/** The one-line note a stale local integration branch earns (DEC-044), or null. */
+function behindNote(ref: string, behind: number): string | null {
+  return behind > 0
+    ? `local ${ref} is ${behind} commit${behind === 1 ? '' : 's'} behind origin/${ref}; a merge that exists only on origin is not seen until you pull`
+    : null;
+}
+
+/**
+ * Derives the status of every tracked feature.
+ *
+ * @param {Object} options
+ * @param {string} options.root the IC-001 root, where git is run
+ * @param {Object} options.fold a fold result (tracked features, merge confirmations, release records)
+ * @param {Object} [options.facts] `readGitFacts` output, for a caller that already has it
+ * @returns {{releaseMode:'tagged'|'untagged'|'unknown', integrationRef:string|null, integrationBehind:number, reason:string|null,
+ *   integrationSha:string|null (the commit the ref was pinned to; absent when nothing was derived),
+ *   evidenceCommits:Object<string,string|null> (slug to the full merge commit of its evidence; absent when nothing was derived),
+ *   statuses:Object<string,{status:string, evidence:{kind:string,ref:string|null}|null, release:string|null}>,
+ *   features:Object<string,string[]>, notDetected:string[],
+ *   failure?:string (git, or the git-facts helper, failed while deriving: `git-state-failed`, `bash-not-found`,
+ *   `git-state-helper-missing`; an environment fault, so every status is `unknown`)}}
+ */
+function deriveStatuses({ root, fold, facts = readGitFacts(root) }: { root: string; fold: any; facts?: any }): any {
+  const tracked = fold.features;
+  const unknown = (reason: string) => result('unknown', facts.integration_ref ?? null, reason,
+    Object.fromEntries(tracked.map((f: any) => [f.slug, { status: 'unknown', evidence: null, release: null }])));
+  if (facts.error) return { ...unknown(`git facts unavailable: ${facts.error}`), failure: facts.error };
+  if (!facts.integration_ref) return unknown('no integration ref resolves (develop, main, master, origin/HEAD)');
+
+  const ref = facts.integration_ref;
+  const releaseMode = facts.release_tags.length > 0 ? 'tagged' : 'untagged';
+  const behind = Number(facts.integration_local_behind_remote) || 0;
+  if (tracked.length === 0) {
+    let sha = null;
+    try { sha = git(root, ['rev-parse', '--verify', `${ref}^{commit}`]).trim(); } catch { /* the ref does not name a commit */ }
+    return { ...result(releaseMode, ref, null, {}, [], behind), integrationSha: sha, evidenceCommits: {} };
+  }
+
+  try {
+    // Pin the ref once: every query below names the same commit.
+    const pinned = git(root, ['rev-parse', '--verify', `${ref}^{commit}`]).trim();
+    const merges = readMerges(root, pinned);
+    const mergeBySha = new Map(merges.map((m): [string, any] => [m.sha, m]));
+    const newestCt = merges.reduce((max, m) => Math.max(max, m.ct), -Infinity);
+    const tips = readBranchTips(root);
+    const mergedSlugs = new Set<string>(fold.merged.map((m: any) => m.slug));
+    const recorded = new Map<string, string>();
+    for (const release of fold.releases) for (const f of release.features) if (!recorded.has(f.slug)) recorded.set(f.slug, release.tag);
+    const recordedTags = new Set(fold.releases.map((r: any) => r.tag));
+    const unrecordedTags = new Set<string>(facts.release_tags.filter((tag: string) => !recordedTags.has(tag)));
+    // Only a tag with no release record can finish a feature by containment (DEC-030), so only those are read.
+    const tags = lazy(() => (releaseMode === 'tagged' && unrecordedTags.size > 0 ? readTagCommits(root, unrecordedTags) : []));
+    const history = lazy(() => readHistory(root, pinned, tags().map((t) => t.commit).filter(Boolean) as string[]));
+
+    const statuses: Record<string, any> = {};
+    const evidenceCommits: Record<string, string | null> = {};
+    const notDetected: string[] = [];
+    for (const feature of tracked) {
+      const lowerBound = Math.floor(Date.parse(feature.trackedAt) / 1000);
+      const evidence = findEvidence({
+        slug: feature.slug, lowerBound, merges, mergeBySha, newestCt, history, tips, prefixes: facts.feature_prefixes, confirmed: mergedSlugs.has(feature.slug),
+      });
+      const shown = evidence && { kind: evidence.kind, ref: evidence.ref };
+      evidenceCommits[feature.slug] = evidence ? evidence.commit : null;
+      let status: string;
+      let release: string | null = null;
+      if (releaseMode === 'untagged') {
+        status = evidence ? 'finished' : 'in-progress';
+      } else if (recorded.has(feature.slug)) {
+        // A record finishes the feature by itself: no containment is looked for.
+        status = 'finished';
+        release = recorded.get(feature.slug) as string;
+      } else {
+        // DEC-030: a merge inside a `v*` tag that has no release record also finishes the feature. A
+        // tag with a record uses only that record, and a feature excluded from it is already outside it.
+        // The evidence commit is a first-parent merge of the pinned ref, so it is in the graph read.
+        const containing = evidence && evidence.commit && unrecordedTags.size > 0
+          ? tags().filter((t) => t.commit && history().isAncestor(evidence.commit as string, t.commit as string)).map((t) => t.name)
+          : [];
+        if (containing.length > 0) { status = 'finished'; release = containing[0]; }
+        else status = evidence ? 'awaiting-release' : 'in-progress';
+      }
+      if (status === 'in-progress') notDetected.push(feature.slug);
+      statuses[feature.slug] = { status, evidence: shown, release };
+    }
+    // `integrationSha` and `evidenceCommits` are for the release preview, which must use the very commit
+    // pinned here (DEC-044) and the full merge commit an evidence names, not its 7-character `ref`.
+    return { ...result(releaseMode, ref, null, statuses, notDetected, behind), integrationSha: pinned, evidenceCommits };
+  } catch (error: any) {
+    // A git failure is an environment fault, not a DoFlow defect: it is reported, never thrown.
+    // `failure` tells a caller git itself failed, which it reports (overview) or refuses on (release, merged).
+    return { ...unknown(`git could not answer (git-state-failed): ${String(error.message).split('\n')[0]}`), failure: 'git-state-failed' };
+  }
+}
+
+module.exports = { deriveStatuses, readGitFacts, resolveGitStateHelper, bucketize, subjectNames, behindNote, readMerges, readBranchTips, readHistory };