@khoavu882/doflow 2.0.0 → 2.0.1

package/src/runtime/intake/index.js

@@ -0,0 +1,136 @@
+'use strict';
+
+/**
+ * The `intake` verb (136 IC-001): `doflow-run intake --action <sort|preview|undo|list|file-prompt>`. This module
+ * resolves the feature folder, runs the engine's action and maps its result to an exit status; it never
+ * prompts. Exit 0 = done (a sort with zero moves too), 1 = a finding to act on (a sort or undo that skipped or
+ * failed an entry, or an undo with nothing left to undo), 2 = the call cannot proceed (no active feature, an
+ * unknown action, no input for `file-prompt`, a manifest from a newer schema, a lock that could not be taken).
+ * `--json` prints the engine's object unmodified.
+ */
+
+const nodeFs = require('node:fs');
+const path = require('node:path');
+const { resolveActiveFeature } = require('../feature-resolve.js');
+const { finishRuntime, usageError } = require('../cli-result.js');
+const { loadTaxonomy, isPlainText } = require('./taxonomy.js');
+const { IntakeUsageError } = require('./manifest.js');
+const { previewSort, sortFolder, undoRun, listFolder, filePrompt, CONTEXT_DIR } = require('./engine.js');
+
+const VALID_ACTIONS = ['sort', 'preview', 'undo', 'list', 'file-prompt'];
+
+/**
+ * The bytes of `--file`, opened without blocking and checked on the open descriptor: a regular file (a link to one
+ * is followed; a FIFO, a device or a folder is refused, and a FIFO is never waited on) of at most `maxBytes`.
+ */
+function readRegularFile(file        , maxBytes        , fsImpl     )         {
+  const fd = fsImpl.openSync(path.resolve(file), nodeFs.constants.O_RDONLY | (nodeFs.constants.O_NONBLOCK || 0));
+  try {
+    const stat = fsImpl.fstatSync(fd);
+    if (!stat.isFile()) throw new IntakeUsageError(`--file ${file} is not a regular file; file-prompt reads only a regular text file`);
+    if (stat.size > maxBytes) throw new IntakeUsageError(`--file ${file} is ${stat.size} bytes; file-prompt takes at most ${maxBytes}`);
+    return fsImpl.readFileSync(fd);
+  } finally {
+    fsImpl.closeSync(fd);
+  }
+}
+
+/** At most `maxBytes + 1` bytes of stdin: one over the cap is enough to refuse, and a huge stream is never held whole. */
+function readStdinCapped(maxBytes        , fsImpl     )         {
+  const buffer = Buffer.alloc(maxBytes + 1);
+  let length = 0;
+  while (length < buffer.length) {
+    let read        ;
+    try {
+      read = fsImpl.readSync(0, buffer, length, buffer.length - length, null);
+    } catch (error     ) {
+      if (error.code === 'EOF') break; // Windows reports the end of a closed pipe as an error
+      throw error;
+    }
+    if (read === 0) break;
+    length += read;
+  }
+  return buffer.subarray(0, length);
+}
+
+/**
+ * The prompt text as bytes, unchanged: from `--stdin` or from `--file <path>`. Either way it must be plain text
+ * (no NUL byte, valid UTF-8) of at most `maxBytes`, so a binary or a huge file is never filed as a prompt.
+ */
+function readInput({ stdin, file }     , fsImpl     , maxBytes        )         {
+  if (!stdin && !file) throw new IntakeUsageError('--action file-prompt needs the text from --stdin or --file <path>');
+  if (stdin && file) throw new IntakeUsageError('--stdin and --file cannot be combined');
+  const from = stdin ? 'stdin' : `--file ${file}`;
+  let bytes        ;
+  try {
+    bytes = stdin ? readStdinCapped(maxBytes, fsImpl) : readRegularFile(file, maxBytes, fsImpl);
+  } catch (error     ) {
+    if (error instanceof IntakeUsageError) throw error;
+    throw new IntakeUsageError(`cannot read ${from}: ${error.message}`);
+  }
+  if (bytes.length > maxBytes) throw new IntakeUsageError(`${from} is ${stdin ? `over ${maxBytes}` : bytes.length} bytes; file-prompt takes at most ${maxBytes}`);
+  if (!isPlainText(bytes)) throw new IntakeUsageError(`${from} is not plain text (it holds a NUL byte or is not valid UTF-8); file-prompt files text only`);
+  return bytes;
+}
+
+/**
+ * Runs one action and returns its result without printing.
+ * @returns {{exitCode:number, result?:Object, usage?:string}}
+ */
+function runIntake({ action, projectRoot, slug = null, flags = {}, now = new Date(), fsImpl = nodeFs, taxonomyOptions = {} }     )                                                     {
+  try {
+    if (!VALID_ACTIONS.includes(action)) throw new IntakeUsageError(`unknown --action '${action}'. Valid: ${VALID_ACTIONS.join(', ')}`);
+    const feature = resolveActiveFeature({ projectRoot, slug });
+    if (feature.error) throw new IntakeUsageError(feature.message);
+    const loaded = loadTaxonomy({ projectRoot: feature.repoRoot, ...taxonomyOptions, fsImpl });
+    if (!loaded.ok) throw new IntakeUsageError(`the intake categories cannot be used (${loaded.reason}): ${loaded.detail}`);
+    const common = { contextDir: path.join(feature.featureFolder, CONTEXT_DIR), taxonomy: loaded.taxonomy, now, fsImpl };
+    let result     ;
+    if (action === 'sort') result = sortFolder(common);
+    else if (action === 'preview') result = previewSort(common);
+    else if (action === 'list') result = listFolder(common);
+    else if (action === 'undo') result = undoRun({ ...common, runId: flags.runId || null });
+    else result = filePrompt({ ...common, bytes: readInput(flags, fsImpl, loaded.taxonomy.pointerMaxBytes), stage: flags.stage || null });
+    const finding = (Array.isArray(result.skipped) && result.skipped.length > 0) || (Array.isArray(result.kept) && result.kept.length > 0) || result.state === 'nothing-to-undo';
+    return { exitCode: finding ? 1 : 0, result };
+  } catch (error     ) {
+    if (error instanceof IntakeUsageError) return { exitCode: 2, usage: error.message };
+    // Another writer holds the manifest lock: the call cannot proceed now (IC-001), so it is usage, not a finding.
+    if (/^Could not lock/.test(error?.message || '')) return { exitCode: 2, usage: error.message };
+    throw error;
+  }
+}
+
+function humanLines(result     )           {
+  const lines           = [];
+  if (result.state === 'absent') return [`no ${CONTEXT_DIR} folder in this feature; nothing to ${result.action}`];
+  if (result.action === 'sort' || result.action === 'preview') {
+    for (const move of result.moves) lines.push(`${result.action === 'preview' ? 'would move' : 'moved'} ${move.from} -> ${move.to}  [${move.category}]`);
+    for (const skip of result.skipped) lines.push(`skipped ${skip.path} (${skip.reason}${skip.detail ? `: ${skip.detail}` : ''})`);
+    lines.push(`${result.moves.length} ${result.action === 'preview' ? 'to move' : 'moved'}, ${result.skipped.length} skipped, ${result.unmatched.length} unmatched${result.runId ? `; undo with --action undo --run-id ${result.runId}` : ''}`);
+  } else if (result.action === 'undo') {
+    if (result.state === 'nothing-to-undo') return ['no run left to undo'];
+    for (const move of result.restored) lines.push(`restored ${move.to} -> ${move.from}`);
+    for (const skip of result.skipped) lines.push(`skipped ${skip.to} (${skip.reason}${skip.detail ? `: ${skip.detail}` : ''})`);
+    for (const move of result.kept) lines.push(`kept ${move.to} (failed move from ${move.from}${move.reason ? `: ${move.reason}` : ''})`);
+    for (const dir of result.removedDirs) lines.push(`removed empty folder ${dir}`);
+    lines.push(`${result.restored.length} restored, ${result.skipped.length} skipped${result.kept.length ? `, ${result.kept.length} kept` : ''} (${result.runId})`);
+  } else if (result.action === 'list') {
+    for (const file of result.files) lines.push(`${file.path}  ${file.category ?? '-'}  ${file.kind}  ${file.bytes} bytes  ${file.unreadable ? 'unreadable' : file.sha256}${file.pointer ? '  pointer' : ''}`);
+    lines.push(`${result.files.length} file${result.files.length === 1 ? '' : 's'}`);
+  } else {
+    lines.push(`filed ${result.path} (${result.bytes} bytes, ${result.sha256}; ${result.runId})`);
+  }
+  return lines;
+}
+
+/** `intake` verb. Exit 0 = done, 1 = a finding, 2 = usage. `--json` prints the result object unmodified. */
+function handleIntakeCommand({ action = 'sort', projectRoot, slug = null, json = false, flags = {} }      = {})         {
+  const run = runIntake({ action, projectRoot: projectRoot || process.cwd(), slug, flags });
+  if (run.usage !== undefined) return usageError('intake', run.usage, json);
+  if (json) console.log(JSON.stringify(run.result, null, 2));
+  else for (const line of humanLines(run.result)) console.log(line);
+  return finishRuntime(run.exitCode);
+}
+
+module.exports = { handleIntakeCommand, runIntake, readInput, humanLines, VALID_ACTIONS };

package/src/runtime/intake/manifest.js

@@ -0,0 +1,140 @@
+'use strict';
+
+/**
+ * The intake manifest (136 IC-007): `additional-context/.intake/manifest.json`, the one record of every sort
+ * and every filed prompt. It is rewritten whole through a temporary file and a rename, under the
+ * `acquireLock` lock `task-state.ts` provides for its own files, the way `decision-register.ts` writes its
+ * register. The reader refuses what it cannot trust (invalid JSON, a newer schema, a path that leaves the
+ * folder) with an `IntakeUsageError` and never rewrites such a file: the manifest is evidence of what moved.
+ */
+
+const nodeFs = require('node:fs');
+const path = require('node:path');
+const nodeCrypto = require('node:crypto');
+const { acquireLock } = require('../task-state.js');
+
+const MANIFEST_SCHEMA = 1;
+const INTAKE_DIR = '.intake';
+const MANIFEST_FILE = 'manifest.json';
+const STATES = ['planned', 'done', 'failed', 'undone', 'undo-skipped'];
+const HASH = /^sha256:[0-9a-f]{64}$/;
+
+/** A caller mistake or an input the engine refuses to guess at (exit 2). */
+class IntakeUsageError extends Error {}
+
+function manifestFile(contextDir        )         { return path.join(contextDir, INTAKE_DIR, MANIFEST_FILE); }
+
+/** True for a relative path of plain segments: nothing absolute, no `..`, no hidden segment, no backslash. */
+function isConfinedPath(rel     )          {
+  if (typeof rel !== 'string' || rel === '' || rel.includes('\\') || rel.includes('\0')) return false;
+  return rel.split('/').every((segment        ) => segment !== '' && !segment.startsWith('.'));
+}
+
+/**
+ * Refuses a `.intake` that is a link or a plain file: the lock and the manifest would be written wherever it
+ * points. An absent `.intake` is fine (it is created as a real folder).
+ */
+function assertIntakeDir(contextDir        , fsImpl      = nodeFs)       {
+  const dir = path.join(contextDir, INTAKE_DIR);
+  let stat     ;
+  try { stat = fsImpl.lstatSync(dir); } catch (error     ) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return;
+    throw error;
+  }
+  if (stat.isSymbolicLink() || !stat.isDirectory()) throw new IntakeUsageError(`${dir} is not a real folder; intake writes its lock and manifest only inside a real ${INTAKE_DIR} folder. Nothing was written.`);
+}
+
+function badManifest(file        , why        )                   {
+  return new IntakeUsageError(`${file} ${why}; the intake manifest is never rewritten when it cannot be trusted. Restore it or move it aside.`);
+}
+
+function validateMove(move     , file        , where        )       {
+  const ok = move && typeof move === 'object'
+    && (move.from === null || isConfinedPath(move.from))
+    && isConfinedPath(move.to)
+    && typeof move.sha256 === 'string' && HASH.test(move.sha256)
+    && Number.isInteger(move.bytes) && move.bytes >= 0
+    && typeof move.at === 'string'
+    && STATES.includes(move.state)
+    && (move.reason === null || typeof move.reason === 'string');
+  if (!ok) throw badManifest(file, `has a malformed or unconfined move at ${where}`);
+}
+
+/** The manifest, or an empty one when none exists. Throws IntakeUsageError for a file it cannot trust. */
+function readManifest(contextDir        , fsImpl      = nodeFs)      {
+  assertIntakeDir(contextDir, fsImpl);
+  const file = manifestFile(contextDir);
+  if (!fsImpl.existsSync(file)) return { schema: MANIFEST_SCHEMA, runs: [] };
+  let data     ;
+  try {
+    data = JSON.parse(fsImpl.readFileSync(file, 'utf8'));
+  } catch (error     ) {
+    throw badManifest(file, `is not valid JSON (${error.message})`);
+  }
+  if (!data || typeof data !== 'object' || !Number.isInteger(data.schema) || !Array.isArray(data.runs)) {
+    throw badManifest(file, 'is not an intake manifest');
+  }
+  if (data.schema > MANIFEST_SCHEMA) {
+    throw new IntakeUsageError(`${file} is schema ${data.schema} and this DoFlow reads schema ${MANIFEST_SCHEMA}; upgrade DoFlow. The manifest was not touched.`);
+  }
+  if (data.schema !== MANIFEST_SCHEMA) throw badManifest(file, `has schema ${data.schema}`);
+  data.runs.forEach((run     , i        ) => {
+    const ok = run && typeof run === 'object' && typeof run.id === 'string' && ['sort', 'file-prompt'].includes(run.action)
+      && Array.isArray(run.createdDirs) && run.createdDirs.every(isConfinedPath) && Array.isArray(run.moves);
+    if (!ok) throw badManifest(file, `has a malformed run at runs[${i}]`);
+    run.moves.forEach((move     , j        ) => validateMove(move, file, `runs[${i}].moves[${j}]`));
+  });
+  return data;
+}
+
+/**
+ * Writes the manifest whole: temp file, then rename, so a reader sees the old file or the new one. `assertHeld`
+ * (from `withManifestLock`) is checked between the two: a writer that stalled past the lock's staleness and was
+ * reclaimed writes nothing (the way `updateTaskState` does).
+ */
+function writeManifest(contextDir        , manifest     , fsImpl      = nodeFs, assertHeld             = () => {})       {
+  const file = manifestFile(contextDir);
+  fsImpl.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  try {
+    fsImpl.writeFileSync(tmp, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+    assertHeld();
+    fsImpl.renameSync(tmp, file);
+  } catch (error     ) {
+    try { fsImpl.rmSync(tmp, { force: true }); } catch { /* nothing to clean */ }
+    throw error;
+  }
+}
+
+/**
+ * Runs `fn` holding the manifest's lock. A lock that cannot be taken throws the lock error unchanged. `fn` gets
+ * `assertHeld`, which throws an `IntakeUsageError` (exit 2) once the lock was reclaimed by another writer; the
+ * engine calls it before every manifest rename and every move of a user's file, so nothing more is written or moved.
+ */
+function withManifestLock   (contextDir        , fn                               , fsImpl      = nodeFs)    {
+  assertIntakeDir(contextDir, fsImpl);
+  fsImpl.mkdirSync(path.join(contextDir, INTAKE_DIR), { recursive: true });
+  // The first check and the mkdir are two calls: a link put at `.intake` in between would make mkdir succeed
+  // silently and the lock land wherever it points. Looked at again here. Ceiling accepted: a swap after this
+  // look and before the lock is taken is one syscall wide; Node has no openat to close it.
+  assertIntakeDir(contextDir, fsImpl);
+  const release = acquireLock(fsImpl, manifestFile(contextDir));
+  const assertHeld = ()       => {
+    if (typeof release.held === 'function' && !release.held()) {
+      throw new IntakeUsageError(`the intake lock on ${manifestFile(contextDir)} was taken over by another writer (this run stalled too long); nothing further was written or moved. Run the command again.`);
+    }
+  };
+  try {
+    return fn(assertHeld);
+  } finally {
+    release();
+  }
+}
+
+/** `run-<UTC yyyymmddThhmmssZ>-<4 hex>`. */
+function newRunId(now      )         {
+  const stamp = now.toISOString().replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z');
+  return `run-${stamp}-${nodeCrypto.randomBytes(2).toString('hex')}`;
+}
+
+module.exports = { readManifest, writeManifest, withManifestLock, newRunId, manifestFile, isConfinedPath, assertIntakeDir, IntakeUsageError, MANIFEST_SCHEMA, INTAKE_DIR };

package/src/runtime/intake/taxonomy.js

@@ -0,0 +1,206 @@
+'use strict';
+
+/**
+ * The intake taxonomy (136 IC-005): `core/registry/intake.json` read on its own, not through `loadRegistry`,
+ * so a bad file turns intake off with a reason and never fails an installer command (the transcripts pattern,
+ * `src/runtime/transcripts/registry.js`). `validateTaxonomy` checks the closed shape and the id and name
+ * uniqueness; `loadTaxonomy` returns the core categories in file order, then the valid `intake-category`
+ * contributions of active packages (IC-006). A rule matches on a file's name and extension only, never on its content.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { REPO_ROOT } = require('../../helper/repo-root.js');
+
+const INTAKE_FILE = 'core/registry/intake.json';
+
+const TOP_KEYS = ['version', 'description', 'recentWindowSeconds', 'pointerMaxBytes', 'textExtensions', 'promptCategory', 'categories'];
+const CATEGORY_KEYS = ['id', 'names', 'summary', 'rules'];
+const RULE_KEYS = ['extensions', 'namePattern', 'into', 'companionOf'];
+const KEBAB = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const EXTENSION = /^[a-z0-9]+$/;
+const NAME_MAX = 40;
+const INTO_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+function isObject(value     )          {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function unknownKeys(value     , allowed          , where        , errors          )       {
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) errors.push(`${where}.${key} is not an allowed key (allowed: ${allowed.join(', ')})`);
+  }
+}
+
+function extensionList(value     , where        , errors          , { required }                       )       {
+  if (!Array.isArray(value) || (required && value.length === 0)) {
+    errors.push(`${where} must be ${required ? 'a non-empty' : 'an'} array of lower-case extensions without a dot`);
+    return;
+  }
+  for (const ext of value) {
+    if (typeof ext !== 'string' || !EXTENSION.test(ext)) errors.push(`${where} entry ${JSON.stringify(ext)} must be a lower-case extension without a dot`);
+  }
+  if (new Set(value).size !== value.length) errors.push(`${where} names an extension twice`);
+}
+
+function validateRule(rule     , where        , errors          )       {
+  if (!isObject(rule)) { errors.push(`${where} must be an object`); return; }
+  unknownKeys(rule, RULE_KEYS, where, errors);
+  extensionList(rule.extensions, `${where}.extensions`, errors, { required: true });
+  if (Object.hasOwn(rule, 'namePattern')) {
+    if (typeof rule.namePattern !== 'string' || rule.namePattern === '') {
+      errors.push(`${where}.namePattern must be a non-empty regular expression string`);
+    } else {
+      try { new RegExp(rule.namePattern, 'i'); } catch (error     ) { errors.push(`${where}.namePattern does not compile (${error.message})`); }
+    }
+  }
+  if (Object.hasOwn(rule, 'into')) {
+    const into = rule.into;
+    const segments = typeof into === 'string' ? into.split('/') : [];
+    if (typeof into !== 'string' || segments.some((segment        ) => !INTO_SEGMENT.test(segment) || segment === '..')) {
+      errors.push(`${where}.into must be a relative sub-path of plain names, with no '..', no leading dot and no empty segment`);
+    }
+  }
+  if (Object.hasOwn(rule, 'companionOf')) {
+    extensionList(rule.companionOf, `${where}.companionOf`, errors, { required: true });
+    if (Object.hasOwn(rule, 'into')) errors.push(`${where} has companionOf, so it follows its companion and takes no into`);
+  }
+}
+
+/**
+ * The shape errors of one category (IC-005, and IC-006's contributed entry): closed keys, a lower-kebab `id`
+ * and `names`, a summary, and valid rules. Uniqueness across categories is the caller's, who sees them all.
+ */
+function validateCategory(category     , where        )           {
+  const errors           = [];
+  if (!isObject(category)) return [`${where} must be an object`];
+  unknownKeys(category, CATEGORY_KEYS, where, errors);
+  for (const key of CATEGORY_KEYS) {
+    if (!Object.hasOwn(category, key)) errors.push(`${where}.${key} is missing`);
+  }
+  const kebab = (value     )          => typeof value === 'string' && value.length <= NAME_MAX && KEBAB.test(value);
+  if (Object.hasOwn(category, 'id') && !kebab(category.id)) errors.push(`${where}.id must be lower-kebab, at most ${NAME_MAX} characters`);
+  if (Object.hasOwn(category, 'names')) {
+    if (!Array.isArray(category.names) || !category.names.every(kebab)) errors.push(`${where}.names must be an array of lower-kebab names, at most ${NAME_MAX} characters each`);
+  }
+  if (Object.hasOwn(category, 'summary') && (typeof category.summary !== 'string' || category.summary.trim() === '')) {
+    errors.push(`${where}.summary must be a non-empty string`);
+  }
+  if (Object.hasOwn(category, 'rules')) {
+    if (!Array.isArray(category.rules)) errors.push(`${where}.rules must be an array`);
+    else category.rules.forEach((rule     , i        ) => validateRule(rule, `${where}.rules[${i}]`, errors));
+  }
+  return errors;
+}
+
+/** Checks the registry's shape, then that every id and name is used once across all categories. */
+function validateTaxonomy(registry     )                                    {
+  const errors           = [];
+  if (!isObject(registry)) return { ok: false, errors: ['registry must be an object'] };
+  unknownKeys(registry, TOP_KEYS, 'registry', errors);
+  for (const key of TOP_KEYS) {
+    if (!Object.hasOwn(registry, key)) errors.push(`registry.${key} is missing`);
+  }
+  if (Object.hasOwn(registry, 'version') && registry.version !== 1) errors.push('version must be 1');
+  if (Object.hasOwn(registry, 'description') && (typeof registry.description !== 'string' || registry.description.trim() === '')) {
+    errors.push('description must be a non-empty string');
+  }
+  if (Object.hasOwn(registry, 'recentWindowSeconds') && !(Number.isInteger(registry.recentWindowSeconds) && registry.recentWindowSeconds >= 0)) {
+    errors.push('recentWindowSeconds must be an integer of 0 or more');
+  }
+  if (Object.hasOwn(registry, 'pointerMaxBytes') && !(Number.isInteger(registry.pointerMaxBytes) && registry.pointerMaxBytes > 0)) {
+    errors.push('pointerMaxBytes must be a positive integer');
+  }
+  if (Object.hasOwn(registry, 'textExtensions')) extensionList(registry.textExtensions, 'textExtensions', errors, { required: true });
+  if (!Array.isArray(registry.categories) || registry.categories.length === 0) {
+    errors.push('categories must be a non-empty array');
+    return { ok: false, errors };
+  }
+  registry.categories.forEach((category     , i        ) => errors.push(...validateCategory(category, `categories[${i}]`)));
+  const owner = new Map                ();
+  const claim = (name     , id     )       => {
+    if (typeof name !== 'string') return;
+    if (owner.has(name)) errors.push(`'${name}' is used by both '${owner.get(name)}' and '${id}'; ids and names are unique across categories`);
+    else owner.set(name, String(id));
+  };
+  for (const category of registry.categories) {
+    if (!isObject(category)) continue;
+    claim(category.id, category.id);
+    if (Array.isArray(category.names)) for (const name of category.names) claim(name, category.id);
+  }
+  const prompt = registry.categories.find((category     ) => isObject(category) && category.id === registry.promptCategory);
+  if (!prompt) errors.push(`promptCategory '${registry.promptCategory}' is not a category id`);
+  else if (Array.isArray(prompt.rules) && prompt.rules.length > 0) errors.push(`the prompt category '${prompt.id}' must have no rules`);
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * Returns `{ ok: true, taxonomy }` with the core categories in file order, each marked `origin: 'core'`, followed by
+ * the categories active packages contribute (IC-006), or `{ ok: false, reason: 'config-invalid', detail }` when the
+ * core file cannot be read or fails its shape. A contribution is tried after every core category, in ascending
+ * qualified-id order; its `id` becomes the qualified id, which is also its folder name. One whose id or names
+ * collide with a core category or an earlier contribution is left out and named in `problems`. The core list never
+ * depends on the package view: `contributionsFor` yields nothing when the point registry fails to load.
+ * `contributions: false` skips the package view. `view`, `homeDir`, `env`, `projectRoot` and `tmpDir` reach it.
+ */
+function loadTaxonomy({ repoRoot = REPO_ROOT, file, fsImpl = fs, contributions = true, problems, view, homeDir, env, projectRoot, tmpDir }      = {})                                                                    {
+  const target = file || path.join(path.resolve(repoRoot), INTAKE_FILE);
+  let registry     ;
+  try {
+    registry = JSON.parse(fsImpl.readFileSync(target, 'utf8'));
+  } catch (error     ) {
+    return { ok: false, reason: 'config-invalid', detail: `${target}: ${error.message}` };
+  }
+  const validation = validateTaxonomy(registry);
+  if (!validation.ok) return { ok: false, reason: 'config-invalid', detail: validation.errors.join('; ') };
+  const categories = registry.categories.map((category     ) => ({ ...category, origin: 'core' }));
+  if (contributions) {
+    const used = new Set        (categories.flatMap((category     ) => [category.id, ...category.names]));
+    const { contributionsFor } = require('../packages/contributions.js');
+    for (const contribution of contributionsFor('intake-category', 1, { repoRoot, fsImpl, view, homeDir, env, projectRoot, tmpDir, problems })) {
+      const id = contribution.qualifiedId;
+      const clash = [id, ...contribution.data.names].find((name        ) => used.has(name));
+      if (clash !== undefined) {
+        problems?.push(`intake-category contribution '${id}' is left out: '${clash}' is already the id or a name of another category`);
+        continue;
+      }
+      for (const name of [id, ...contribution.data.names]) used.add(name);
+      categories.push({ ...contribution.data, id, origin: id });
+    }
+  }
+  return { ok: true, taxonomy: { ...registry, categories } };
+}
+
+/**
+ * The folder a category files into: the first of its id and known names that is already a folder in the
+ * context folder, else its id (FR-003, IC-005). `existing` is the set of folder names found there.
+ */
+function categoryFolder(category     , existing             )         {
+  return [category.id, ...category.names].find((name        ) => existing.has(name)) ?? category.id;
+}
+
+/** True for bytes a text file can hold: no NUL byte and valid UTF-8. A binary saved as `.md` fails it. */
+function isPlainText(buffer        )          {
+  if (buffer.includes(0)) return false;
+  try {
+    new TextDecoder('utf-8', { fatal: true }).decode(buffer);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * True for a `/`-separated path inside a feature's user-context folder: `agent-docs/doflow/<slug>/additional-context/`
+ * anywhere in it (a main checkout, a linked worktree or a relative path between them). A folder of that name
+ * elsewhere in a project (`src/additional-context/`) is not the user's. The path is normalised first (a backslash
+ * becomes `/`, then `.`, `//` and `a/..` are resolved), so `x/./additional-context/` and `x/y/../additional-context/`
+ * are read as what they name and `additional-context/../../a.ts` as `a.ts`. A `..` left after that is only a leading
+ * one, the relative path between two checkouts, which the rule above keeps.
+ */
+function isUserContextPath(file        )          {
+  const parts           = path.posix.normalize(file.replace(/\\/g, '/')).split('/');
+  return parts.some((part, i) => part === 'agent-docs' && parts[i + 1] === 'doflow' && Boolean(parts[i + 2]) && parts[i + 3] === 'additional-context');
+}
+
+module.exports = { isUserContextPath, isPlainText, loadTaxonomy, validateTaxonomy, validateCategory, categoryFolder, INTAKE_FILE };

package/src/runtime/lifecycle/cli.js

@@ -19,10 +19,36 @@ const { buildOverview, initFeature, featureStatus, activeFeature } = require('./
 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', '$.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 }),
+    ...(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,23 @@ 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 = { ...result, followups: { ...result.followups, shown: items.length, items } };
+        return emit(withEnvelope(projectBrief(brief, OVERVIEW_BRIEF.keep), { view }), 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 });
     }