@khoavu882/doflow 2.0.0 → 2.0.2

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/knowledge/code-retrieval.js

@@ -45,12 +45,14 @@ function lexicalOutcome(result     ) {
 
 function validFreshness(value     ) { return INDEX_STATES.has(value) ? value : 'UNKNOWN'; }
 
-function appendOutcome({ binding, projectRoot, taskId, slug, intent, need, router, provider, capability, id, candidates, indexState, failure, bound = null, complete }     ) {
+function appendOutcome({ binding, projectRoot, taskId, slug, intent, need, router, provider, capability, id, candidates, indexState, failure, bound = null, complete, answered = complete }     ) {
+  // `answered`: the provider finished its own search. `complete` additionally needs a complete corpus. An
+  // empty answer is classified on `answered`, so an incomplete corpus never turns it into a timeout.
   let stored = null;
   if (binding) {
     let status; let reason;
     if (failure) { status = 'UNREACHED'; reason = failureReason(failure, indexState); }
-    else if (!candidates.length && complete) {
+    else if (!candidates.length && answered) {
       if (indexState === 'STALE') { status = 'EMPTY'; reason = 'index-stale'; }
       else if (indexState === 'UNKNOWN') { status = 'UNVERIFIED'; reason = 'index-unverifiable'; }
       else { status = 'EMPTY'; reason = 'empty-answer'; }
@@ -233,10 +235,14 @@ async function executeCodeRetrieval(options      = {}) {
     rankedLists.push({ provider: 'native.rg', capability, queryRef, retrievalAttemptRef: lexicalId, candidates: lexCandidates });
     const lexOutcome = lexicalOutcome(lexResult);
     attempts.push(appendOutcome({ binding, projectRoot, taskId, slug, intent, need, router, provider: 'native.rg', capability,
-      id: lexicalId, candidates: lexCandidates, indexState: 'NOT_APPLICABLE', ...lexOutcome, complete: Boolean(lexResult.complete && inventory.complete) }));
+      id: lexicalId, candidates: lexCandidates, indexState: 'NOT_APPLICABLE', ...lexOutcome, complete: Boolean(lexResult.complete && inventory.complete), answered: Boolean(lexResult.complete) }));
     if (lexOutcome.failure || lexOutcome.bound) gaps.push({ provider: 'native.rg', reason: lexOutcome.failure || lexOutcome.bound, source: 'lexical' });
 
-    if (profile === 'hybrid' && classification.queryClass === 'conceptual') {
+    // Semantic search needs a complete corpus (index build and refresh refuse one too): an incomplete inventory skips
+    // it as a coverage gap, never as a provider attempt or failure. The admission gaps above already say why.
+    if (profile === 'hybrid' && classification.queryClass === 'conceptual' && !inventory.complete) {
+      gaps.push({ source: 'semantic', reason: 'incomplete-corpus-skipped' });
+    } else if (profile === 'hybrid' && classification.queryClass === 'conceptual') {
       const semanticId = makeId();
       let semResult;
       const modelPath = options.modelPath || process.env.SEMBLE_MODEL_PATH || null;
@@ -269,7 +275,7 @@ async function executeCodeRetrieval(options      = {}) {
         rankedLists.push({ provider: 'native.rg', capability, queryRef, retrievalAttemptRef: fallbackId, candidates: fallbackCandidates });
         const fallbackOutcome = lexicalOutcome(fallback);
         attempts.push(appendOutcome({ binding, projectRoot, taskId, slug, intent, need, router, provider: 'native.rg', capability,
-          id: fallbackId, candidates: fallbackCandidates, indexState: 'NOT_APPLICABLE', ...fallbackOutcome, complete: Boolean(fallback.complete && inventory.complete) }));
+          id: fallbackId, candidates: fallbackCandidates, indexState: 'NOT_APPLICABLE', ...fallbackOutcome, complete: Boolean(fallback.complete && inventory.complete), answered: Boolean(fallback.complete) }));
         if (fallbackOutcome.failure || fallbackOutcome.bound) gaps.push({ provider: 'native.rg', reason: fallbackOutcome.failure || fallbackOutcome.bound, source: 'fallback' });
       }
     }

package/src/runtime/knowledge/semble-provider.js

@@ -234,6 +234,9 @@ function inspectArtifacts(index        , inventory     , paths     , model     ,
 // rule: process.kill(pid, 0)) is reclaimed under a claim file named for its token, created `wx`: the claim winner re-reads
 // the lock and removes it only while it still carries the judged token, so a live or newer lock is never removed. A lock
 // from another host, from this process, or without a readable record is never reclaimed.
+// The Python bridge child is what writes the cache, so executeBridge records its pid in the lock as `childPid`; a lock
+// is stale only when the owner and that child are both gone. Ceiling: a Node process killed between spawn and the
+// record leaves a lock without `childPid` (the child is then unprotected for that instant).
 // Ceiling: a reclaimer killed between creating and removing its claim leaves `operation.lock.claim.<token>`, and that
 // lock then waits for a manual removal, which the contention cause names.
 const LOCK_TOKEN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
@@ -243,6 +246,12 @@ function readLockOwner(lock        )      {
     return owner && Number.isInteger(owner.pid) && typeof owner.hostname === 'string' && LOCK_TOKEN.test(owner.token) ? owner : null;
   } catch { return null; }
 }
+function recordLockChild(lock        , childPid        )       {
+  const owner = readLockOwner(lock); if (!owner || owner.pid !== process.pid || !Number.isInteger(childPid)) return;
+  const next = `${lock}.child.${process.pid}`;
+  try { fs.writeFileSync(next, `${JSON.stringify({ ...owner, childPid })}\n`, { flag: 'w', mode: 0o600 }); fs.renameSync(next, lock); }
+  catch { try { fs.unlinkSync(next); } catch {} }
+}
 function reclaimStaleLock(lock        , owner     , hostname        )          {
   const claim = `${lock}.claim.${owner.token}`;
   try { fs.writeFileSync(claim, `${JSON.stringify({ pid: process.pid, hostname })}\n`, { flag: 'wx', mode: 0o600 }); }
@@ -262,7 +271,7 @@ async function acquireSemanticLock(paths     , { isAlive = defaultIsAlive, hostn
       return () => { fs.closeSync(fd); if (readLockOwner(paths.lock)?.token === token) fs.unlinkSync(paths.lock); };
     } catch (error     ) { if (error.code !== 'EEXIST') throw error; }
     const owner = readLockOwner(paths.lock);
-    if (owner && owner.hostname === hostname && owner.pid !== process.pid && !isAlive(owner.pid) && reclaimStaleLock(paths.lock, owner, hostname)) continue;
+    if (owner && owner.hostname === hostname && owner.pid !== process.pid && !isAlive(owner.pid) && !(Number.isInteger(owner.childPid) && isAlive(owner.childPid)) && reclaimStaleLock(paths.lock, owner, hostname)) continue;
     if (Date.now() >= deadline) {
       throw fault('lock-contention', 'UNKNOWN', `another semantic index operation holds ${paths.lock}${owner ? ` (pid ${owner.pid} on ${owner.hostname})` : ''}; `
         + 'run the command again when it finishes. A lock whose process has exited on this host is reclaimed automatically; '
@@ -300,6 +309,7 @@ function executeBridge(request     , options     , paths     , sandbox        )
       TRANSFORMERS_CACHE: library, XDG_CACHE_HOME: library, SEMBLE_GRAMMARS_CACHE_DIR: path.join(library, 'grammars'), TORCH_HOME: library,
       TMPDIR: library, TEMP: library, TMP: library, TOKENIZERS_PARALLELISM: 'false', SEMBLE_INDEX_WORKERS: '0' };
     const child = spawn(options.python, [options.bridgePath || path.join(__dirname, 'semble-bridge.py')], { cwd: paths.state, env, stdio: ['pipe', 'pipe', 'pipe'], shell: false });
+    if (child.pid) recordLockChild(paths.lock, child.pid);
     let stdout = ''; let outputBytes = 0; let failure                = null; let done = false;
     const stop = (reason        ) => { if (!failure) failure = reason; child.kill('SIGKILL'); };
     const timer = setTimeout(() => stop('provider-timeout'), deadline);
@@ -362,4 +372,4 @@ async function runSembleQuery(options     )               {
   finally { try { if (temp) fs.rmSync(temp, { recursive: true, force: true }); } catch {} try { if (release) release(); } catch {} }
 }
 module.exports = { SEMBLE_VERSION, SEMBLE_LIMITS, runSembleQuery, resolveSembleInterpreter, checkSembleVersion, semanticStatePaths, digest, fault, inside, safeDirectories,
-  regularBytes, scanTree, inspectModel, inspectBm25, validateInventory, readSource, checkSources, inspectArtifacts, acquireSemanticLock, cleanupTemporary, executeBridge, readCompleted, modelLinkRoots };
+  regularBytes, scanTree, inspectModel, inspectBm25, validateInventory, readSource, checkSources, inspectArtifacts, acquireSemanticLock, recordLockChild, cleanupTemporary, executeBridge, readCompleted, modelLinkRoots };