@khoavu882/doflow 2.0.0-beta.5 → 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/inventory/coverage.js

@@ -8,7 +8,7 @@
  * States which of the report's findings the existing repair path can actually act on. That set is
  * narrower than the set of findings, and the difference is not self-evident:
  *
- *   $ doflow status -g          → 321 pending changes across 8 harnesses
+ *   $ doflow status -g          → 321 pending changes across several harnesses
  *   $ doflow reconcile -g --dry-run → 10 drifts for 1 harness
  *
  * Both numbers are internally consistent. `status` reads the ledger, which records what DoFlow

package/src/runtime/inventory/index.js

@@ -162,7 +162,7 @@ function planBasis(snapshot     )      {
  * source fingerprint, **and** the recorded ledger row equal to it too — which is right for its own
  * purpose, planning a write that also refreshes the row. It means a change is emitted whenever the
  * row alone is stale, and that happens routinely: the shared hooks asset projects one destination for
- * claude, codex, gemini, kiro and antigravity while ownership is recorded per harness, so a sibling's
+ * claude, codex, pi, kiro and antigravity while ownership is recorded per harness, so a sibling's
  * install legitimately refreshes bytes the other harnesses' rows still describe by their old hash.
  * Reading such a change as divergence reported one file, identical bytes, under contradictory
  * verdicts per harness, with a remedy offering to "restore" a file that was already correct.

package/src/runtime/inventory/precedence.js

@@ -21,7 +21,7 @@
  * first-match reading of that same order would get it backwards).
  *
  * A `merged` mode means the copies are combined rather than chosen between, so no single copy
- * "wins". An `unestablished` mode means the order may be documented (`gemini` documents one) or
+ * "wins". An `unestablished` mode means the order may be documented (no shipped harness does today) or
  * may not (`pi`, `antigravity` document neither), but either way the rule for choosing between
  * copies is not — so no winner is named. Those two cases are separate states under IC-003 and the
  * withheld reason says which: a documented order with an undocumented winner names the order it
@@ -96,7 +96,7 @@ function resolveShadowVerdict(presentScopes     , precedence     )      {
 
   if (mode === 'unestablished') {
     // IC-003 keeps these two states distinct: an order established with the mode explicitly
-    // unestablished (`gemini`) is not the same finding as an order sought and found undocumented
+    // unestablished is not the same finding as an order sought and found undocumented
     // (`pi`, `antigravity`). Both withhold the verdict; only one of them knows the reading order.
     const orderIsEstablished = Array.isArray(order) && order.length > 0;
     return {

package/src/runtime/inventory/siblings.js

@@ -23,7 +23,7 @@ const path = require('node:path');
  *
  * **The bound on cost (R6).** Only the parent directories of assets already enumerated from the
  * ledger are read — one level, never recursed into. A managed tree that nests (Kiro's steering tree
- * mirrors `core/shared/guidance/`, `rules/` and `mcp/` included) is still covered completely
+ * mirrors the core set of `core/shared/guidance/`, `rules/` included) is still covered completely
  * without a walk, because every subdirectory holding a managed file is itself the parent of a
  * managed resource and so is inspected on its own account. `mcp-builder/` and `skill-creator/`
  * sitting beside a managed skills directory are never enumerated: neither is the parent of a
@@ -51,10 +51,12 @@ const path = require('node:path');
  *     *every* file it copies under an `applyTo: '**'` front-matter header, so every file landing in
  *     `.github/instructions/` is always applied. Asset `instructions.copilot`, native dir
  *     `instructions`.
- *   - `src/adapters/kiro/index.js` (header comment, lines 8-12) — "Kiro receives DoFlow's *full*
- *     guidance tree as steering files", with no single-file instruction surface at all. Asset
+ *   - `src/adapters/kiro/index.js` (header comment, lines 8-12) — Kiro has no single-file
+ *     instruction surface and loads every steering file without front-matter. DoFlow-produced
+ *     steering holds only the core set (selected via `guidance-manifest`), but the directory is
+ *     still loaded wholesale, so an unmanaged file there is operative. Asset
  *     `guidance.context-layer` for the `kiro` harness only, native dir `steering`; the same asset's
- *     `../.doflow/guidance` projection for claude/codex/gemini/antigravity is name-resolved by
+ *     `../.doflow/guidance` projection for the other harnesses is name-resolved by
  *     explicit import and is not in this set.
  *
  * This is the single place to change. If the registry later declares load semantics per projection,