@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/src/runtime/history-compactor.js

@@ -93,11 +93,18 @@ function classify(bodyLines          , kinds          , canonicalPointer
   return { comments, moved, pointer };
 }
 
-function writeAtomic(fsImpl     , file        , content        )       {
+function writeAtomic(fsImpl     , file        , content        , unchangedSince         )       {
   fsImpl.mkdirSync(path.dirname(file), { recursive: true });
   const tmp = `${file}.${process.pid}.tmp`;
   try {
     fsImpl.writeFileSync(tmp, content, 'utf8');
+    // The text `content` was built from is compared with the file just before the rename, so an edit
+    // made since it was read is kept instead of replaced (FU-1jbmm3). This narrows the window to the
+    // gap between this read and the rename; it cannot close it, which would take a lock on the
+    // artifact itself that its editors would also have to take.
+    if (unchangedSince !== undefined && fsImpl.readFileSync(file, 'utf8') !== unchangedSince) {
+      throw new Error(`${path.basename(file)} changed while it was being compacted`);
+    }
     fsImpl.renameSync(tmp, file);
   } catch (error     ) {
     try { fsImpl.rmSync(tmp, { force: true }); } catch { /* nothing to clean */ }
@@ -189,7 +196,7 @@ function compactArtifact({ fsImpl, featureDir, file, date }
   const body = [blank];
   for (const c of comments) body.push(...c, blank);
   body.push(pointerLine, end === lines.length ? '' : blank);
-  writeAtomic(fsImpl, file, [...lines.slice(0, start + 1), ...body, ...lines.slice(end)].join('\n'));
+  writeAtomic(fsImpl, file, [...lines.slice(0, start + 1), ...body, ...lines.slice(end)].join('\n'), text);
   return { artifact: name, path: rel, archive: archiveRel, lines: moved.length };
 }
 
@@ -204,7 +211,10 @@ function compactArtifact({ fsImpl, featureDir, file, date }
  * @param {string} [options.date] YYYY-MM-DD stamped on the archive chunk; defaults to today (UTC)
  * @param {Object} [options.fsImpl] fs implementation (tests substitute one)
  *
- * Not locked: concurrent callers can interleave archive appends. Call it through
+ * Not locked: concurrent callers can interleave archive appends, and an artifact edited between its
+ * read and its rewrite is detected just before the rename and left as the editor wrote it (the
+ * artifact is reported in `failed`; the moved block is already in the archive and a later run does
+ * not copy it twice), but an edit landing in the last instant before the rename is not. Call it through
  * `compactDecisions` / `runDecision` in decision-register.js, which hold the register lock.
  *
  * Every artifact is attempted. One that cannot be compacted is left as it was and reported in

package/src/runtime/implementation-gate.js

@@ -8,7 +8,7 @@ const { readReadinessRecord, newerVersionOf, RECORD_VERSION } = require('./readi
 const { listCheckouts } = require('./checkouts.js');
 const { readTaskState } = require('./task-state.js');
 const { resolveActiveFeature } = require('./feature-resolve.js');
-const { isSafeSlug } = require('./task-scope.js');
+const { isSafeSlug, flatRecordIsOurs, readRegularFileText, MAX_RECORD_FILE_BYTES } = require('./task-scope.js');
 const { REPO_ROOT } = require('../helper/repo-root.js');
 
 // The implementation gate: which stage of a workflow needs a READY readiness record before it is
@@ -19,6 +19,15 @@ const { REPO_ROOT } = require('../helper/repo-root.js');
 // orchestrator, `verify` and the edit hook (which prints the same bytes) say the same thing.
 
 const GATE = 'doflow gate readiness-before-implementation';
+const RUN_RECORD_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*\.json$/;
+const RUN_NAMESPACE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** Where a checkout keeps its run records, relative to the checkout; the one place the path is named. */
+const RUN_STORE_REL = path.join('.doflow', 'state', 'orchestration');
+
+/** The run store of the checkout at `root`. */
+function runStoreDir(root        )         {
+  return path.join(root, RUN_STORE_REL);
+}
 
 /** What clears a record a newer DoFlow wrote; `readiness` here refuses to overwrite it. */
 const NEWER_NEXT = 'run this command with the DoFlow that wrote the record, or upgrade DoFlow here.';
@@ -55,13 +64,14 @@ function nextCommand({ taskId, slug, template }     ) {
 
 /**
  * The refusal for one check code.
- * @param {'missing'|'not-ready'|'wrong-template'|'unusable'|'ambiguous'} code
+ * @param {'missing'|'not-ready'|'wrong-template'|'unusable'|'ambiguous'|'store-conflict'|'ambiguous-run'} code
  * @param {Object} options
  * @param {string} options.taskId
  * @param {string|null} [options.slug]
  * @param {string} options.template the template the gated stage needs
  * @param {Object|null} [options.record] the record read, for `not-ready` and `wrong-template`
- * @param {Array<string>} [options.candidates] the files found, for `ambiguous`
+ * @param {Array<string>} [options.candidates] the files found, for `ambiguous`; the worktree's then the
+ *   main checkout's, for `store-conflict`
  * @param {string|null} [options.detail] why the record cannot be used, for `unusable`
  * @param {string|null} [options.file] the record's file, for `unusable` when a newer DoFlow wrote it
  * @param {number|null} [options.newerVersion] that newer record version; `readiness` would refuse to
@@ -86,6 +96,8 @@ function refusalText(code     , { taskId, slug = null, template, record = null,
       return `${GATE}: task '${taskId}' has a readiness record that cannot be used (${detail}). ${tail}`;
     case 'ambiguous':
       return `${GATE}: task '${taskId}' has records in more than one other checkout (${candidates.join(', ')}). Next: run the command from the checkout that holds the one you mean, or run ${next} here. Nothing was changed.`;
+    case 'store-conflict':
+      return `${GATE}: task '${taskId}' has a readiness record in this worktree (${candidates[0]}) that differs from the main checkout's (${candidates[1]}). Next: keep one of the two and remove the other, then re-run. Nothing was changed.`;
     case 'ambiguous-run':
       // A readiness record written here cannot say which run is meant, so it is not offered.
       return `${GATE}: task '${taskId}' has runs in more than one other checkout (${candidates.join(', ')}). Next: run verify from the checkout that holds the run you mean. Nothing was changed.`;
@@ -168,35 +180,269 @@ function runSlugOf(run     , root     ) {
   return run && isSafeSlug(run.taskId) && isDir(folderOf(root, run.taskId)) ? run.taskId : null;
 }
 
+/** Whether a store directory can be a run namespace rather than a lock directory. */
+function isRunNamespaceDir(name        )          {
+  return RUN_NAMESPACE_PATTERN.test(name) && !name.includes('..') && !name.endsWith('.lock');
+}
+
+/** The run record files under one checkout's store: flat `<id>.json` and `<slug>/<id>.json`, by
+ * path, without reading them. The one listing `findRunFile` and `orchestrationRuns` share.
+ * With `listing` (IC-001, the list action), a symbolic link is never followed: a linked run file is
+ * kept with `linked: true` so it can be reported as unreadable, and a linked namespace directory is
+ * not entered, so nothing outside the store root is read or named. */
+function runFilesAt(root        , { listing = false }                        = {})                                                                   {
+  const store = runStoreDir(root);
+  const files                                                                   = [];
+  const take = (entry     ) => entry.isFile() || entry.isSymbolicLink();
+  let entries       ;
+  try { entries = fs.readdirSync(store, { withFileTypes: true }); } catch { return []; }
+  for (const entry of entries) {
+    if (take(entry) && RUN_RECORD_PATTERN.test(entry.name)) {
+      files.push({ file: path.join(store, entry.name), namespace: null, linked: entry.isSymbolicLink() });
+    } else if ((entry.isDirectory() || (!listing && entry.isSymbolicLink())) && isRunNamespaceDir(entry.name)) {
+      let nested       ;
+      try { nested = fs.readdirSync(path.join(store, entry.name), { withFileTypes: true }); } catch { continue; }
+      for (const item of nested) {
+        if (take(item) && RUN_RECORD_PATTERN.test(item.name)) {
+          files.push({ file: path.join(store, entry.name, item.name), namespace: entry.name, linked: entry.isSymbolicLink() || item.isSymbolicLink() });
+        }
+      }
+    }
+  }
+  return files.sort((a, b) => a.file < b.file ? -1 : a.file > b.file ? 1 : 0);
+}
+
+/** The largest run file the list action and `readRunRecord` read; a bigger one is reported as `io` /
+ * refused (a journal is a few KiB). */
+const MAX_RUN_FILE_BYTES = MAX_RECORD_FILE_BYTES;
+
+/**
+ * One run's record, read the way the list action reads it (FU-16c2wz): no link is followed on the
+ * way from the store folder `storeDir` to the file or at the file, and the file must be a regular
+ * file of at most `MAX_RUN_FILE_BYTES`, so a FIFO or a device cannot block the read and a link
+ * cannot make it read outside the store. A run file that is not there is `null`; one that must not
+ * be read throws `store-unreadable` naming the file, and nothing of it is read.
+ * @param {Object} fsImpl
+ * @param {string} file the run file, under `storeDir`
+ * @param {string} storeDir the run store folder it belongs to
+ * @returns {Object|null} the parsed record
+ */
+function readRunRecord(fsImpl     , file        , storeDir        )      {
+  if (typeof fsImpl.lstatSync !== 'function' || typeof fsImpl.openSync !== 'function') return readTaskState(fsImpl, file);
+  const text = readRunText(fsImpl, file, storeDir);
+  return text === null ? null : readTaskState({ existsSync: () => true, readFileSync: () => text }, file);
+}
+
+/** `readRunRecord`'s guarded read without the parse: the run file's text, `null` when it is not
+ * there, `store-unreadable` when it must not be read. */
+function readRunText(fsImpl     , file        , storeDir        )              {
+  const relative = path.relative(storeDir, file);
+  const parts = relative === '' || relative.startsWith('..') || path.isAbsolute(relative) ? [] : relative.split(path.sep);
+  const refuse = ()        => {
+    const failure      = new Error(`Run file '${file}' is not a regular file inside the run store (a link, FIFO, device or folder, or larger than ${MAX_RUN_FILE_BYTES} bytes). Nothing was read.`);
+    failure.code = 'store-unreadable';
+    throw failure;
+  };
+  let at = storeDir;
+  for (const part of parts.slice(0, -1)) {
+    at = path.join(at, part);
+    let stat     ;
+    try { stat = fsImpl.lstatSync(at); } catch (error     ) {
+      if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null;
+      throw error;
+    }
+    if (stat.isSymbolicLink()) refuse();
+  }
+  let stat     ;
+  try { stat = fsImpl.lstatSync(file); } catch (error     ) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null;
+    throw error;
+  }
+  if (!stat.isFile()) refuse();
+  const text = readRegularFileText(file, fsImpl);
+  if (text === null) refuse();
+  return text;
+}
+
+/** The run files under one checkout's store, read, with each malformed or unreadable file isolated. */
+function runEntriesAt(root        , origin                   )        {
+  return runFilesAt(root, { listing: true }).map(({ file, namespace, linked }) => {
+    let record      = null;
+    let error              = null;
+    const bytes = linked ? null : readRegularFileText(file);
+    if (bytes === null) error = 'io';
+    else {
+      try { record = JSON.parse(bytes); } catch { error = 'unparseable'; }
+    }
+    return {
+      file,
+      root,
+      origin,
+      slug: namespace || runSlugOf(record, root),
+      record,
+      error,
+    };
+  });
+}
+
+/**
+ * All orchestration journals in the current store and the other checkouts, when Git can list them.
+ * @param {{stateRoot: string, exec?: Function}} options
+ * @returns {{ok: true, entries: Array<Object>}|{ok: false, error: 'cannot-list-checkouts'}}
+ */
+function orchestrationRuns({ stateRoot, exec }     )      {
+  const current = runEntriesAt(stateRoot, 'current');
+  const checkouts = listCheckouts({ cwd: stateRoot, ...(exec ? { exec } : {}) });
+  if (!checkouts.ok && checkouts.reason !== 'not-a-git-repository') {
+    return { ok: false, error: 'cannot-list-checkouts' };
+  }
+  if (!checkouts.ok || checkouts.sandbox) return { ok: true, entries: current };
+
+  const entries = [...current];
+  for (const root of checkouts.others) entries.push(...runEntriesAt(root, 'other'));
+  return { ok: true, entries };
+}
+
+/** Whether a flat record names no feature (no `featureSlug`, no `slug`): such a run is any feature's
+ * (`flatRecordIsOurs`), so a namespaced copy of the same id in the same store shadows it. */
+function namesNoFeature(record     )          {
+  return Boolean(record) && typeof record === 'object'
+    && ![record.featureSlug, record.slug].some((value) => typeof value === 'string' && value !== '');
+}
+
+/**
+ * IC-001/IC-003: one entry per logical run, the copy `status` reads, with `findRunFile`'s
+ * precedence. In one store, the namespaced `<slug>/<id>.json` wins over a flat `<id>.json` that
+ * names that feature (when the slug is the id, the flat file is the run's only path and wins).
+ * A flat file that names no feature, or that cannot be read or is a link, is keyed as `findRunFile`
+ * would first read it, the id as its slug, and stays its own entry. Across stores, the current
+ * store's copy of a key wins over every other checkout's; a current flat file `status` reads for
+ * any feature without a namespaced copy here (one naming no feature, or a link, which status refuses)
+ * also shadows the other checkouts' copies of that id. With no current copy, each other checkout
+ * that holds one keeps its entry (more than one is the case `status` refuses as ambiguous). A
+ * losing copy is dropped: `status` never reads it for this run.
+ * @param {Array<Object>} entries `orchestrationRuns(...).entries`
+ * @returns {Array<Object>} the winning entries, in input order
+ */
+function selectRunEntries(entries       )        {
+  const stem = (entry     ) => path.basename(entry.file, '.json');
+  const namespaceOf = (entry     ) => {
+    const parts = path.relative(runStoreDir(entry.root), entry.file).split(path.sep);
+    return parts.length > 1 ? parts[0] : null;
+  };
+  const named = (entry     ) => entry.record && !namesNoFeature(entry.record) && !entry.error;
+  const linked = (entry     ) => {
+    try { return fs.lstatSync(entry.file).isSymbolicLink(); } catch { return false; }
+  };
+  const keyOf = (entry     ) => {
+    const ns = namespaceOf(entry);
+    if (ns !== null) return `${ns}\0${stem(entry)}`;
+    if (named(entry) && entry.slug) return `${entry.slug}\0${stem(entry)}`;
+    return `${stem(entry)}\0${stem(entry)}`;
+  };
+  const rank = (entry     ) => {
+    const ns = namespaceOf(entry);
+    if (ns === null) return named(entry) && entry.slug !== stem(entry) ? 1 : 0;
+    return ns === stem(entry) ? 2 : 0;
+  };
+  // Ids a current flat file answers for any feature: status reads it before any other checkout.
+  const wildcards = new Set(entries.filter((entry) => entry.origin === 'current' && namespaceOf(entry) === null
+    && ((entry.record && namesNoFeature(entry.record)) || linked(entry))).map(stem));
+  const perRoot = new Map             ();
+  for (const entry of entries) {
+    const local = `${entry.root}\0${keyOf(entry)}`;
+    const held = perRoot.get(local);
+    if (!held || rank(entry) < rank(held)) perRoot.set(local, entry);
+  }
+  const best = new Map               ();
+  for (const entry of perRoot.values()) {
+    const key = keyOf(entry);
+    const held = best.get(key);
+    if (!held) best.set(key, [entry]);
+    else if (held[0].origin === 'current') continue;
+    else if (entry.origin === 'current') best.set(key, [entry]);
+    else held.push(entry);
+  }
+  const winners = new Set     ();
+  for (const list of best.values()) {
+    for (const entry of list) {
+      if (entry.origin !== 'current' && wildcards.has(stem(entry))) continue;
+      winners.add(entry);
+    }
+  }
+  return entries.filter((entry) => winners.has(entry));
+}
+
 /**
  * A task's run file: in this checkout, else in exactly one other checkout whose run belongs to the
- * same feature. Task ids repeat across features, so another checkout's run with the same id but
- * another feature (or none) is not this task's and is never read or updated from here.
+ * same feature. The run of a task id other than its feature's slug is `orchestration/<slug>/<id>.json`
+ * (115 C-1); a flat run of that id is read in its place only when it is this feature's or names none
+ * (D-3). Task ids repeat across features, so another checkout's run with the same id but another
+ * feature (or none) is not this task's and is never read or updated from here.
  * @param {{stateRoot: string, taskId: string, slug: string|null, exec?: Function}} options
  * @returns {{status: 'found'|'missing'|'ambiguous', file: string|null, root: string|null,
  *   origin: 'current'|'other'|null, candidates: Array<string>}}
  */
-function findRunFile({ stateRoot, taskId, slug, exec }     ) {
-  const rel = path.join('.doflow', 'state', 'orchestration', `${taskId}.json`);
+function findRunFile({ stateRoot, taskId, slug, exec, anyNamespace = false }     ) {
+  const found = findRunFileFor({ stateRoot, taskId, slug, exec });
+  return anyNamespace && found.status === 'missing' ? findNamespacedRun({ stateRoot, taskId, exec }) : found;
+}
+
+/**
+ * FU-wrnnaq: the run of `taskId` under whichever feature namespace holds it, for a caller that has
+ * no feature to name (`status` run from another branch). This is the run the list action shows for
+ * the id: this checkout's namespaced run first, else the other checkouts'; exactly one is the run,
+ * more than one is `ambiguous` (the feature must then be named), none is `missing`. `slug` is the
+ * namespace the run is in, for the caller to read it by.
+ * @returns {{status: 'found'|'missing'|'ambiguous', file: string|null, root: string|null,
+ *   origin: 'current'|'other'|null, candidates: Array<string>, slug?: string, byFeature?: true}}
+ */
+function findNamespacedRun({ stateRoot, taskId, exec }     ) {
+  const name = `${taskId}.json`;
   const missing = { status: 'missing', file: null, root: null, origin: null, candidates: [] };
-  if (fs.existsSync(path.join(stateRoot, rel))) {
-    return { status: 'found', file: path.join(stateRoot, rel), root: stateRoot, origin: 'current', candidates: [] };
+  const inRoot = (root        ) => runFilesAt(root).filter((entry) => entry.namespace !== null && path.basename(entry.file) === name);
+  const settle = (entries                                                 , root        , origin                   ) => (
+    entries.length === 1
+      ? { status: 'found', file: entries[0].file, root, origin, candidates: [], slug: entries[0].namespace           }
+      : { ...missing, status: 'ambiguous', byFeature: true, candidates: entries.map((entry) => entry.file) });
+  const here = inRoot(stateRoot);
+  if (here.length > 0) return settle(here, stateRoot, 'current');
+  const checkouts = listCheckouts({ cwd: stateRoot, ...(exec ? { exec } : {}) });
+  if (!checkouts.ok || checkouts.sandbox) return missing;
+  const matches = checkouts.others.flatMap((root        ) => inRoot(root).map((entry) => ({ ...entry, root })));
+  if (matches.length === 0) return missing;
+  return settle(matches, matches[0].root, 'other');
+}
+
+function findRunFileFor({ stateRoot, taskId, slug, exec }     ) {
+  const store = RUN_STORE_REL;
+  const flat = path.join(store, `${taskId}.json`);
+  const namespaced = slug && slug !== taskId ? path.join(store, slug, `${taskId}.json`) : null;
+  const missing = { status: 'missing', file: null, root: null, origin: null, candidates: [] };
+  const here = runFilesAt(stateRoot);
+  const localNamespaced = namespaced && here.find((entry) => path.relative(stateRoot, entry.file) === namespaced);
+  const localFlat = here.find((entry) => path.relative(stateRoot, entry.file) === flat);
+  if (localNamespaced) return { status: 'found', file: localNamespaced.file, root: stateRoot, origin: 'current', candidates: [] };
+  if (localFlat && (!namespaced || flatRecordIsOurs(localFlat.file, slug, fs, true))) {
+    return { status: 'found', file: localFlat.file, root: stateRoot, origin: 'current', candidates: [] };
   }
   if (!slug) return missing;
   const checkouts = listCheckouts({ cwd: stateRoot, ...(exec ? { exec } : {}) });
   if (!checkouts.ok || checkouts.sandbox) return missing;
-  const matches = checkouts.others.filter((root     ) => {
-    const file = path.join(root, rel);
-    if (!fs.existsSync(file)) return false;
-    try {
-      return runSlugOf(JSON.parse(fs.readFileSync(file, 'utf8')), root) === slug;
-    } catch {
-      return false;
-    }
-  });
+  const matches                                        = [];
+  for (const root of checkouts.others) {
+    const files = runFilesAt(root);
+    const found = [namespaced, flat].filter(Boolean).map((rel     ) => files.find((entry) => path.relative(root, entry.file) === rel)).find((entry     ) => {
+      if (!entry) return false;
+      // The same safe read as every other run read: a linked run or namespace folder, a FIFO or a
+      // device in another checkout is never opened, and is not a match.
+      try { return runSlugOf(JSON.parse(readRunText(fs, entry.file, runStoreDir(root))          ), root) === slug; } catch { return false; }
+    });
+    if (found) matches.push({ file: found.file, root });
+  }
   if (matches.length === 0) return missing;
-  if (matches.length > 1) return { ...missing, status: 'ambiguous', candidates: matches.map((root     ) => path.join(root, rel)) };
-  return { status: 'found', file: path.join(matches[0], rel), root: matches[0], origin: 'other', candidates: [] };
+  if (matches.length > 1) return { ...missing, status: 'ambiguous', candidates: matches.map((m) => m.file) };
+  return { status: 'found', file: matches[0].file, root: matches[0].root, origin: 'other', candidates: [] };
 }
 
 /** The slug a refusal's next command names: one whose feature folder exists in this checkout or in
@@ -231,7 +477,7 @@ function unusableDetail(record     , now     ) {
  * @param {string} options.template
  * @param {Date} [options.now]
  * @param {Function} [options.exec]
- * @returns {{ok: boolean, code: 'ready'|'missing'|'not-ready'|'wrong-template'|'unusable'|'ambiguous',
+ * @returns {{ok: boolean, code: 'ready'|'missing'|'not-ready'|'wrong-template'|'unusable'|'ambiguous'|'store-conflict',
  *   record: Object|null, file: string|null, origin: string|null, candidates: Array<string>,
  *   detail: string|null, nextSlug: string|null, message: string|null}}
  */
@@ -254,6 +500,7 @@ function checkReadiness({ stateRoot, taskId, slug = null, template, now = new Da
     }),
   });
   if (read.status === 'ambiguous') return result('ambiguous');
+  if (read.status === 'conflict') return result('store-conflict');
   if (read.status === 'missing') return result('missing');
   const detail = read.status === 'unreadable' ? read.detail : unusableDetail(read.record, now);
   if (detail) return result('unusable', detail);
@@ -284,7 +531,9 @@ function verifyReadinessCheck({ stateRoot, taskId, slug = null, now = new Date()
     };
   }
   if (found.status === 'missing') return { applies: false, reason: 'no-run' };
-  const run = readTaskState(fs, found.file);
+  // Reads only through the run store's safe reader; a run file that must not be read is refused by name.
+  const run = readRunRecord(fs, found.file, runStoreDir(found.root));
+  if (!run) return { applies: false, reason: 'no-run' };
   if (run.state === 'COMPLETED' || run.state === 'REJECTED') return { applies: false, reason: 'run-finished' };
   const stageNodes = (run.program || []).filter((n     ) => n.type === 'stage');
   const stage = gatedStage(stageNodes);
@@ -309,6 +558,7 @@ function verifyReadinessCheck({ stateRoot, taskId, slug = null, now = new Date()
 }
 
 module.exports = {
+  unusableDetail,
   gatedStage,
   heldClasses,
   refusalText,
@@ -317,5 +567,10 @@ module.exports = {
   verifyReadinessCheck,
   featureSlugFor,
   runSlugOf,
+  orchestrationRuns,
+  selectRunEntries,
   findRunFile,
+  RUN_STORE_REL,
+  runStoreDir,
+  readRunRecord,
 };

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,