@khoavu882/doflow 2.0.1 → 2.0.2

package/src/runtime/lifecycle/release.js

@@ -39,6 +39,7 @@ const { isSafeSlug, invalidSlugRefusal } = require('../task-scope.js');
 const { appendEvents, readFold } = require('./event-store.js');
 const { deriveStatuses, readGitFacts, behindNote, subjectNames, readMerges, readBranchTips, readHistory } = require('./status.js');
 const { FollowupUsageError, oneLine, channelBy } = require('./followup.js');
+const { parseSemVer, compareSemVer } = require('../../helper/semver.js');
 
 /** The release-tag pattern of IC-020, the one `git-state` filters by. */
 const RELEASE_TAG = /^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$/;
@@ -125,13 +126,25 @@ function releaseFeatures({ root, tag, confirm = false, features, exclude, channe
     return refusal('release', 'untracked-feature', `${untracked.join(', ')} ${untracked.length === 1 ? 'is' : 'are'} not tracked, so ${untracked.length === 1 ? 'it' : 'they'} cannot be added to or excluded from a release; run doflow-run lifecycle --action init --slug <slug> first. Nothing was written.`);
   }
 
-  // DEC-030: containment in the tag being recorded never finishes a feature before its record exists.
-  const otherTags = { ...facts, release_tags: facts.release_tags.filter((name     ) => name !== tag) };
+  // DEC-030: containment in the tag being recorded never finishes a feature before its record exists. Of the
+  // other tags only an unrecorded one that is stable and earlier than `tag` (lower version, or a strict ancestor of it)
+  // may take a feature out of this release: a pre-release (v1.0.0-rc.1 before v1.0.0) or a later tag
+  // (v2.0.0 when recording v1.0.0) does not. A tag with a record is left in: status reads it by its record.
+  const tagCommit = commitOf(root, `refs/tags/${tag}`);
+  const recordedTags = new Set(fold.releases.map((r     ) => r.tag));
+  const shadows = (name     ) => {
+    const parsed = parseSemVer(name.slice(1));
+    if (!parsed || parsed.prerelease.length > 0) return false;
+    if (compareSemVer(name.slice(1), tag.slice(1)) < 0) return true;
+    // A strict ancestor only: a higher-versioned tag on the very same commit is not earlier.
+    const commit = tagCommit && commitOf(root, `refs/tags/${name}`);
+    return Boolean(commit) && commit !== tagCommit && isAncestor(root, commit, tagCommit);
+  };
+  const otherTags = { ...facts, release_tags: facts.release_tags.filter((name     ) => name !== tag && (recordedTags.has(name) || shadows(name))) };
   const derived = deriveStatuses({ root, fold, facts: otherTags });
   if (derived.releaseMode === 'unknown' || !derived.integrationSha) return refusal('release', 'no-integration-ref', `${derived.reason || `${facts.integration_ref} does not resolve to a commit`}. Nothing was written.`);
 
   // X: the tag's commit once it exists, else the commit the status view pinned the integration ref to (DEC-044).
-  const tagCommit = commitOf(root, `refs/tags/${tag}`);
   const bound = tagCommit || derived.integrationSha;
   const previousTag = previousTagOf(root, { tag, facts, bound });
   // A hotfix merged only into the tag's own history has no evidence on the integration chain: derive against the tag as well.

package/src/runtime/lifecycle/retention.js

@@ -18,7 +18,7 @@
 
 const nodeFs = require('node:fs');
 const { isDeepStrictEqual } = require('node:util');
-const { loadSettings } = require('../settings/resolve.js');
+const { loadSettings, registryOn } = require('../settings/resolve.js');
 const { foldInto, finalize, EVENT_TYPES } = require('./fold.js');
 
 const HOUR_MS = 3600000;
@@ -53,14 +53,7 @@ function retentionWindow({ env = process.env, projectRoot, fsImpl = nodeFs }
   const parsed = parseWindow(env);
   if (parsed.state === 'invalid') return parsed;
   try {
-    let settingsRegistry;
-    if (fsImpl !== nodeFs) {
-      const { loadSettingsRegistry } = require('../settings/registry.js');
-      const loaded = loadSettingsRegistry({ fsImpl });
-      if (!loaded.ok) throw new Error(loaded.detail);
-      settingsRegistry = loaded.registry;
-    }
-    const view = loadSettings({ projectRoot, env, fsImpl, ...(settingsRegistry ? { registry: settingsRegistry } : {}) });
+    const view = loadSettings({ projectRoot, env, fsImpl, ...registryOn(fsImpl) });
     const retention = view.get('storage.retentionHours', 'project');
     if (retention.state === 'invalid') return { state: 'invalid', raw: invalidRaw(retention, env) };
     if (retention.explicit) {
@@ -136,10 +129,12 @@ function unitsOf(events       , shouldStop                )               {
 }
 
 /**
- * Every string value and every object key in the data of the events whose type this version's fold
- * does not know (a newer DoFlow wrote them). The fold ignores them, so retention cannot tell what they change; a unit that
- * one of them names by id is kept whole rather than deleted from under it. Exact matches only:
- * keeping too little is a lost record, keeping too much only a file that stays.
+ * Every string value in the envelope, and every object key inside it, of the events whose type this
+ * version's fold does not know (a newer DoFlow wrote them). The fold ignores them, so retention
+ * cannot tell what they change; a unit that one of them names, by item id, event id or event file
+ * name, is kept whole rather than deleted from under it. The envelope's own field names are its
+ * shape, not references. Exact matches only: keeping too little is a lost record, keeping too much
+ * only a file that stays.
  * @returns {Set<string>|null} null when `shouldStop` fired
  */
 function unknownTypeStrings(events       , shouldStop                )                     {
@@ -148,7 +143,7 @@ function unknownTypeStrings(events       , shouldStop                )
   for (const event of events) {
     if (shouldStop?.()) return null;
     if (known.has(event.type)) continue;
-    const pending        = [event.data];
+    const pending        = Object.values(event);
     while (pending.length > 0) {
       if (shouldStop?.()) return null;
       const value = pending.pop();
@@ -260,7 +255,9 @@ function selectExpired(events       , { now, windowMs, shouldStop }      = {})
   };
   const baseSelected = safeSubset(candidates);
   if (!baseSelected) return incomplete();
-  const unprotected = baseSelected.filter((unit     ) => ![...unit.items].some((key        ) => mentioned.has(key.slice(key.indexOf(':') + 1))));
+  const namedByUnknown = (unit     )          => [...unit.items].some((key        ) => mentioned.has(key.slice(key.indexOf(':') + 1)))
+    || unit.events.some((event     ) => mentioned.has(event.id) || mentioned.has(`${event.id}.json`));
+  const unprotected = baseSelected.filter((unit     ) => !namedByUnknown(unit));
   // Dropping units can leave a set the refold no longer accepts; check it again, inside the subset.
   const selected = unprotected.length === baseSelected.length ? baseSelected : safeSubset(unprotected);
   if (!selected) return incomplete();

package/src/runtime/lifecycle/store-upkeep.js

@@ -342,9 +342,9 @@ function retainLocked(root     , options      = {}) {
   if (!release) return outcome(0, [], true);
   try {
     const swept = sweepStaleTmp(fsImpl, root, now, staleTmpMs, { maxFiles, shouldStop });
-    if (swept.partial) return outcome(0, [], true);
+    if (swept.partial) return outcome(swept.removed, [], true);
     const result = retain(fsImpl, root, window, now, { maxFiles: Math.max(0, maxFiles - swept.removed), shouldStop });
-    return outcome(result.removedCount, result.warning, result.partial, result.selected, result.code);
+    return outcome(swept.removed + result.removedCount, result.warning, result.partial, result.selected, result.code);
   } finally {
     release();
   }
@@ -358,6 +358,16 @@ function needsPrune(fsImpl     , root     , window     , now     ) {
   return selectExpired(readEvents(root, { fsImpl }).events, { now, windowMs: window.ms }).files.length > 0;
 }
 
+/**
+ * Whether the old `agent-docs/lifecycle` copy still waits to be copied. Read-only (no lock, no
+ * write, `DOFLOW_UPKEEP` not consulted), for `doctor`; an unreadable folder counts as not pending.
+ */
+function migrationPending(root        , { fsImpl = nodeFs }      = {}) {
+  try {
+    return !hasMarker(fsImpl, root) && !storeHasEvents(fsImpl, root) && legacyEventFiles(fsImpl, root).length > 0;
+  } catch { return false; }
+}
+
 /**
  * Prepares the project store for one verb invocation.
  * @param {string} root projectRoot() result
@@ -439,4 +449,4 @@ function prepareStore(root        , { env = process.env, now = new Date(), fsImp
   }
 }
 
-module.exports = { prepareStore, retainLocked, removedLine, STALE_TMP_MS, LEGACY_LIFECYCLE_REL, LEGACY_EVENTS_REL, MARKER_REL };
+module.exports = { prepareStore, migrationPending, retainLocked, removedLine, STALE_TMP_MS, LEGACY_LIFECYCLE_REL, LEGACY_EVENTS_REL, MARKER_REL };

package/src/runtime/mask.js

@@ -12,8 +12,8 @@
  * Rules run in the table's order. Normalisation (rules 10 to 13) is a separate step applied to
  * failure messages only, after masking.
  *
- * The module has no I/O and no state; the home directory is read from `HOME` unless the caller
- * passes one.
+ * The module has no I/O and no state; the home directory is read from `HOME` (`USERPROFILE` when
+ * `HOME` is absent or empty, as on Windows) unless the caller passes one.
  */
 
 const MASKED = '<masked>';
@@ -152,7 +152,7 @@ function escapeRegExp(text        )         { return text.replace(/[.*+?^${}()|[
 
 /** The home directory to abbreviate: an absolute path other than the file system root. */
 function homeOf(options      )                {
-  const raw = options && 'home' in options ? options.home : process.env.HOME;
+  const raw = options && 'home' in options ? options.home : (process.env.HOME || process.env.USERPROFILE);
   if (typeof raw !== 'string' || !(raw.startsWith('/') || /^[A-Za-z]:[\\/]/.test(raw))) return null;
   const home = raw.replace(/[\\/]+$/, '');
   return home.length > 1 ? home : null;

package/src/runtime/mcp-consultations.js

@@ -230,14 +230,15 @@ const bySortKey = (a     , b     )         => (a < b ? -1 : a > b ? 1 : 0);
  * Injected readers (all optional; a missing one contributes nothing):
  * - `ledger.queryEvidence({taskId})` -> evidence items (active ones count)
  * - `requests.list(taskId)` -> research requests
- * - `briefRecords` -> IC-018 records already parsed, each `{ runTaskId, stage, tasks, expected }`
+ * - `briefRecords` -> IC-018 records already parsed, each `{ runTaskId, stage, createdAt, tasks, expected }`
  * - `readReport(path)` -> report text, or null when the file is missing
  * - `reach.anyHarnessHas(server)` -> true | false | null (unknown); never decides an outcome
  * - `reach.harnessWith(server)` -> the display name of a harness that has the server, or null
  * - `harnessName(id)` -> a harness id's display name (for a brief record's `harness`)
- * - `addCommand(server)` -> the text after "add it:" in the unavailable notice
+ * - `addCommand(server, harnessId)` -> the text after "add it:" in the unavailable notice; `harnessId` is the harness
+ *   of the brief that found the server unreachable, or null when no brief names one
  * - `since` -> ISO time of the previous stage's completion (or the run start); rule 3 counts only
- *   evidence observed after it
+ *   evidence observed after it, and only brief records created after it
  *
  * @returns {{ record: object, warnings: object[], notices: object[], evidenceToAdd: object[] }}
  */
@@ -266,8 +267,11 @@ function resolveConsultations({
   // ingested (design A6).
   const toolsUsed        = [];
   const fromReports = new Map               ();
+  // A stage visited twice leaves briefs from the earlier visit: when `since` is known only a brief created
+  // after it counts, and a record with no creation time (written before it was stamped) cannot be placed.
   const records = (Array.isArray(briefRecords) ? briefRecords : [])
-    .filter((record     ) => record && stageId && taskId && record.stage === stageId && record.runTaskId === taskId);
+    .filter((record     ) => record && stageId && taskId && record.stage === stageId && record.runTaskId === taskId
+      && (since === null || (typeof record.createdAt === 'string' && record.createdAt > since)));
   const reports                                        = [];
   for (const record of records) {
     for (const task of record.tasks || []) {
@@ -347,10 +351,12 @@ function resolveConsultations({
   // brief writes `unreachable` only where every config the harness merges was read (IC-017).
   const unreachable = new Map             ();
   const reachableOn = new Map             ();
+  const unreachableOn = new Map             ();
   for (const record of records) {
     for (const expected of record.expected || []) {
       if (!expected || typeof expected.server !== 'string') continue;
       if (expected.reach === 'unreachable' && !unreachable.has(expected.server)) unreachable.set(expected.server, record.tasks?.[0]?.id);
+      if (expected.reach === 'unreachable' && !unreachableOn.has(expected.server)) unreachableOn.set(expected.server, record.harness ?? null);
       if (expected.reach === 'reachable' && !reachableOn.has(expected.server)) reachableOn.set(expected.server, record.harness ?? null);
     }
   }
@@ -415,7 +421,7 @@ function resolveConsultations({
           text: `[WARN] mcp: ${server} reported unavailable but ${has} has it configured`,
         });
       }
-      const add = !has && typeof addCommand === 'function' ? addCommand(server) : null;
+      const add = !has && typeof addCommand === 'function' ? addCommand(server, unreachableOn.get(server) ?? null) : null;
       notices.push({
         kind: 'unavailable', server,
         text: `[INFO] mcp: ${server} unavailable to ${skill}${add ? `; add it: ${add}` : ''}`,

package/src/runtime/research-request.js

@@ -95,7 +95,9 @@ class ResearchRequestStore {
   }
 
   stageFor(taskId     , stageId     ) {
-    const run = readTaskState(this.fsImpl, this.runFile(taskId));
+    // The run is read the way every run read is: no link followed, no FIFO or device opened (FU-d88kp0).
+    const { readRunRecord } = require('./implementation-gate.js');
+    const run = readRunRecord(this.fsImpl, this.runFile(taskId), path.join(this.projectRoot, '.doflow', 'state', 'orchestration'));
     if (!run || run.taskClass !== 'feature' || run.state !== 'RUNNING') {
       throw new Error(`Task '${taskId}' has no active feature stage`);
     }

package/src/runtime/review/command.js

@@ -25,15 +25,10 @@ const TELEMETRY_COUNT_KEYS = Object.freeze([
   'plausible', 'unverified_blockers', 'bug_classes',
 ]);
 
-// Inherited location variables would point the check at another repository (C-8).
-const GIT_LOCATION_KEYS = Object.freeze([
-  'GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_OBJECT_DIRECTORY', 'GIT_COMMON_DIR',
-  'GIT_ALTERNATE_OBJECT_DIRECTORIES',
-]);
-
 function defaultGit(args          , cwd        , env     )                            {
   const gitEnv = { ...env };
-  for (const key of GIT_LOCATION_KEYS) delete gitEnv[key];
+  // Inherited location variables would point the check at another repository (C-8); the list is verification's.
+  for (const key of require('../dispatch/verify-run.js').REPO_ENV) delete gitEnv[key];
   return spawnSync('git', ['-C', cwd, ...args], { cwd, env: gitEnv, stdio: 'ignore' });
 }
 
@@ -112,6 +107,7 @@ function handleReviewCommand({
     }
     return handleReviewStart({ slug: hasValue(slug) ? slug : null, base: hasValue(base) ? base : null, preset: hasValue(preset) ? preset : null, json, cwd, env, resolve, adviceClient, out });
   }
+  if (Array.isArray(recordPath)) return usage('--path may be given only once', json, out);
   if (hasValue(base)) return usage('--base is valid only with --action start', json, out);
   if (hasValue(preset)) return usage('--preset is valid only with --action start', json, out);
   if (hasValue(slug) && hasValue(recordPath)) return usage('use either --slug or --path, not both', json, out);

package/src/runtime/review/start.js

@@ -109,15 +109,16 @@ function readBounded(file        , maxBytes        )
   }
 }
 
-function parseRecordLines(file        )                                         {
+function parseRecordLines(file        )                                                       {
   const read = readBounded(file, MAX_RECORD_BYTES);
   if ('error' in read) return { error: read.error };
+  const text = 'text' in read ? read.text : '';
   const records        = [];
-  for (const [index, line] of ('text' in read ? read.text : '').split('\n').entries()) {
+  for (const [index, line] of text.split('\n').entries()) {
     if (!line.trim()) continue;
     try { records.push(JSON.parse(line)); } catch (error     ) { return { error: `line ${index + 1}: ${error.message}` }; }
   }
-  return { records };
+  return { records, text };
 }
 
                                                                                             
@@ -243,20 +244,23 @@ function loadGatePolicy(cwd               )
  * is on, so the class seat floor binds; maint-thin), the gate policy (the shipped gates.json narrowed by the
  * project's `.doflow/gates.override.json`, read as roadmap gate-b reads it, 119 IC-005; null when there is no task class, so
  * no floor), the protocols registry and the enforcement inputs (`loadEnforcementInputs`). A base, override or registry the loaders reject is a refusal carrying the loader's
- * reason (and the override file). Shared with the `protocol` verb.
+ * reason (and the override file). Shared with the `protocol` verb. `replaced` names the settings a prepared run
+ * (`config validate --prepared-run`) writes to the project layer: an invalid project candidate of such a key is
+ * replaced by it, so it does not refuse here.
  */
-function loadProtocolInputs(taskClass               , cwd        , env                                     = process.env) 
+function loadProtocolInputs(taskClass               , cwd        , env                                     = process.env, replaced                      = new Set()) 
                                                                                                                                                                                                                             {
   const settingsView                                                    = {};
   try {
     const settings = require('../settings/resolve.js').loadSettings({ projectRoot: path.resolve(cwd), env });
     for (const key of PROTOCOL_SETTINGS) {
       const resolution = settings.get(key);
-      // C-6: an invalid project or local review.* candidate would silently fall back to the default: refuse instead.
-      // A preset key refuses an invalid user candidate too.
-      const invalid = key.endsWith('.preset') ? invalidPresetCandidate(resolution)
-        : key.startsWith('review.') ? invalidProjectCandidate(resolution) : undefined;
-      if (invalid) return { error: 'settings-unavailable', message: `${key} in ${invalid.source}: ${invalid.reason}` };
+      // C-6: an invalid project or local review.* candidate would silently fall back to the default: refuse instead,
+      // except a project candidate that a prepared run replaces. A preset key refuses an invalid user candidate too.
+      const judged = replaced.has(key) ? { ...resolution, candidates: (resolution.candidates ?? []).filter((c     ) => c.layer !== 'project') } : resolution;
+      const stands = key.endsWith('.preset') ? invalidPresetCandidate(judged)
+        : key.startsWith('review.') ? invalidProjectCandidate(judged) : undefined;
+      if (stands) return { error: 'settings-unavailable', message: `${key} in ${stands.source}: ${stands.reason}` };
       settingsView[key] = { value: resolution.value, layer: resolution.origin.layer };
     }
   } catch (error     ) {
@@ -429,12 +433,14 @@ async function handleReviewStart({ slug, base, preset, json = false, cwd, env, r
     result.applicable = result.notApplicable === null;
 
     let nextCommand                = null;
+    let seen                                                               = null;
     if (result.applicable) {
       const state = readHeadState(cwd, env);
       result.head = state.head;
       result.clean = state.clean;
       const parsed = parseRecordLines(verificationRunRecordFile(verificationRunsRoot(cwd), verifyId          ));
       if ('error' in parsed) return refuse('records-unreadable', parsed.error);
+      seen = { head: state.head, clean: state.clean, text: parsed.text };
       result.reasons = reviewPrecondition({ records: parsed.records, head: state.head, clean: state.clean, slug: verifyId });
       if (result.reasons.length) {
         result.ok = false;
@@ -507,6 +513,14 @@ async function handleReviewStart({ slug, base, preset, json = false, cwd, env, r
     const decided = resolveProtocol({ ...facts, advicePick: null });
     if (!decided.ok) return refuseResolution(decided.reason);
     const advice = await askAdvice({ decision: { depth: decided.protocol.depth, scope }, risk: result.risk, taskClass, slug: resolvedSlug, files: paths ? paths.length : null, cwd, env, adviceClient });
+    // The advice await can take a while: what the precondition and the risk were read from must still stand.
+    if (seen && advice.status !== 'off') {
+      const now = readHeadState(cwd, env);
+      const records = parseRecordLines(verificationRunRecordFile(verificationRunsRoot(cwd), verifyId          ));
+      if (now.head !== seen.head || now.clean !== seen.clean || 'error' in records || records.text !== seen.text) {
+        return refuse('state-moved', 'HEAD, the working tree or the verification records changed while the advice was asked; run review start again');
+      }
+    }
     const resolved = resolveProtocol({ ...facts, advicePick: advice.pick });
     if (!resolved.ok) return refuseResolution(resolved.reason);
     const { protocol } = resolved;

package/src/runtime/roadmap/loop.js

@@ -15,6 +15,7 @@ const path = require('node:path');
 const crypto = require('node:crypto');
 const { execFileSync: defaultExecFileSync } = require('node:child_process');
 const { listCheckouts } = require('../checkouts.js');
+const { readRegularFileText } = require('../task-scope.js');
 const { withGitMemo } = require('../git-memo.js');
 const {
   parseSeed,
@@ -661,11 +662,17 @@ const tripwireFile = (ctx     )         => path.join(ctx.dir, 'tripwire', 'event
 function readTripwire(ctx     )      {
   const file = tripwireFile(ctx);
   try {
-    const value = JSON.parse(ctx.fsImpl.readFileSync(file, 'utf8'));
+    try { ctx.fsImpl.lstatSync(file); } catch (error     ) {
+      if (error.code === 'ENOENT') return { schema: 1, reverts: [], unverified: [] };
+      throw error;
+    }
+    // A bounded read: a link, a FIFO or a file over the record cap is never opened as the record.
+    const text = readRegularFileText(file, ctx.fsImpl);
+    if (text === null) throw new Error('not a regular file within the record size cap');
+    const value = JSON.parse(text);
     if (!value || value.schema !== 1 || !Array.isArray(value.reverts) || !Array.isArray(value.unverified)) throw new Error('not a schema 1 tripwire record');
     return value;
   } catch (error     ) {
-    if (error.code === 'ENOENT') return { schema: 1, reverts: [], unverified: [] };
     throw new Unreadable(['tripwire'], error.message);
   }
 }
@@ -808,7 +815,9 @@ function orchestrationFor(ctx     , row     , worktree        )
   // artifactRootOf finds it (the feature checkout, else the main one).
   const planExitCheck = () => require('../plan-content.js').planStageExit({ roots: [...new Set([worktree, runRoot, ctx.root])], slug: row.slug });
   const orch = new WorkflowOrchestrator({ repoRoot: ctx.repoRoot, projectRoot: runRoot, sourceRoot: worktree,
-    stateDir: path.join(runRoot, '.doflow', 'state', 'orchestration'), featureSlug: row.slug, fsImpl: ctx.fsImpl, env: ctx.env, cwd: worktree, planExitCheck });
+    stateDir: path.join(runRoot, '.doflow', 'state', 'orchestration'), featureSlug: row.slug, fsImpl: ctx.fsImpl, env: ctx.env, cwd: worktree, planExitCheck,
+    // FR-006, as the orchestrate verb wires it: the ledger is found from any checkout of the row.
+    taskAttemptCheck: () => require('../task-attempts.js').checkCompletion({ slug: row.slug, cwd: worktree, fsImpl: ctx.fsImpl }) });
   let run     ;
   try { run = orch.readRun(row.slug); } catch (error     ) { throw new Unreadable([source], error.message); }
   if (run && (!Array.isArray(run.program) || !Number.isInteger(run.cursor) || typeof run.state !== 'string' || !Array.isArray(run.history))) {
@@ -1716,4 +1725,6 @@ module.exports = {
   // The lease primitive, exported for its interleaving test (C8).
   acquireLease,
   releaseLease, resolveMainRoot, noPsAlive,
+  // The orchestrator the loop builds for a row, exported for its wiring test (FU-e4yr45).
+  orchestrationFor,
 };

package/src/runtime/roadmap/rows.js

@@ -864,7 +864,8 @@ function render(
   for (const row of rows) {
     const info = getInfo(row.id);
     const needsStr = row.needs && row.needs.length > 0 ? row.needs.join(', ') : '-';
-    const statusStr = info.status;
+    // A not-started row of a class the loop does not run waits for a person, not for time: `manual`.
+    const statusStr = info.status === 'not-started' && !LOOP_CLASSES.includes(row.class) ? 'manual' : info.status;
 
     let evidenceStr = '-';
     if (info.evidence) {

package/src/runtime/settings/files.js

@@ -35,6 +35,8 @@ const BOM = '\uFEFF';
                 
                                                                                   
                                      
+                                                                                           
+                  
  
 
 function isObject(value         )                                   {
@@ -265,7 +267,7 @@ function readLayerFile(file        , { registry, fsImpl = nodeFs, includeDocumen
     values.set(key, { raw, value: error ? null : raw, error });
   }
   return { status: 'ok', code: null, offset: null, reason: null, values, notes,
-    ...(includeDocument ? { document: parsed                            } : {}) };
+    ...(includeDocument ? { document: parsed                           , source: text } : {}) };
 }
 
 module.exports = { MAX_BYTES, jsonFailure, validateValue, readLayerFile };

package/src/runtime/settings/prepared-run.js

@@ -188,6 +188,7 @@ function validatePrepared(doc                     , ctx     )          {
   if (Object.hasOwn(doc, 'presets') && !isObject(doc.presets)) errors.push(entry('presets', null, 'type', 'presets must be an object with review and debate preset ids'));
   let loaded      = null; // the start verb's inputs, loaded once and only when a preset is checked
   const inputs = ()      => (loaded ??= ctx.inputs(taskClass));
+  let settingsFault                = null; // a live settings fault the prepared values do not replace: one entry per preset
   for (const kind of ['review', 'debate']) {
     if (!Object.hasOwn(presets, kind)) continue;
     const order           = presetIds(protocols, kind); // the effective core order: the only ids that have a rank
@@ -201,6 +202,10 @@ function validatePrepared(doc                     , ctx     )          {
     // The effective preset setting (C-3): the user/project/local layers `review --action start` reads, with this
     // file's own entry as the project layer, applied by the resolver's rule (settingsPick) to the loosest preset.
     const settingKey = `${kind}.preset`;
+    if (settingsFault === null) {
+      try { inputs(); } catch (error     ) { if (!error.settings) throw error; settingsFault = error.message; }
+    }
+    if (settingsFault !== null) { errors.push(entry(key, null, 'settings-unavailable', settingsFault)); continue; }
     const view                      = { ...inputs().settingsView };
     const current = view[settingKey];
     if (typeof settings[settingKey] === 'string' && (!current || ['default', 'user', 'project'].includes(current.layer))) {
@@ -239,6 +244,11 @@ function report(file        , errors         , json         , notes           =
   return finishRuntime(errors.length === 0 ? 0 : 1);
 }
 
+/** The settings keys the prepared run writes to the project layer: applied before the live settings are judged. */
+function replaced(doc                     )              {
+  return new Set(isObject(doc.settings) ? Object.keys(doc.settings).filter((key) => doc.settings[key] !== null) : []);
+}
+
 function handlePreparedRun({ file, json, registry, repoRoot, projectRoot, env, fsImpl = nodeFs }     )         {
   let text        ;
   try { text = fsImpl.readFileSync(path.resolve(file), 'utf8'); } catch { return usageError('config', `cannot read the prepared run ${file}`, json); }
@@ -255,8 +265,8 @@ function handlePreparedRun({ file, json, registry, repoRoot, projectRoot, env, f
       registry, protocols: protocols.registry, classes: taskClasses(repoRoot, fsImpl), env, projectRoot: root, repoRoot, fsImpl, notes,
       // what `review --action start` loads: the protocol settings view and gates.json narrowed by the project's override
       inputs: (taskClass               )      => {
-        const inputs = require('../review/start.js').loadProtocolInputs(taskClass, root, env);
-        if ('error' in inputs) throw Object.assign(new Error(inputs.message), { usage: true });
+        const inputs = require('../review/start.js').loadProtocolInputs(taskClass, root, env, replaced(doc));
+        if ('error' in inputs) throw Object.assign(new Error(inputs.message), inputs.error === 'settings-unavailable' ? { settings: true } : { usage: true });
         return inputs;
       },
     };

package/src/runtime/settings/resolve.js

@@ -214,6 +214,18 @@ function loadSettings({ projectRoot = null, global = false, env = process.env, r
   return view;
 }
 
+/**
+ * The registry to pass `loadSettings` with `fsImpl`: none for the real file system (the shipped one),
+ * else the registry read through that file system. Throws when it is unusable (callers fail closed).
+ */
+function registryOn(fsImpl     )                     {
+  if (fsImpl === nodeFs) return {};
+  const { loadSettingsRegistry } = require('./registry.js');
+  const loaded = loadSettingsRegistry({ fsImpl });
+  if (!loaded.ok) throw new Error(loaded.detail);
+  return { registry: loaded.registry };
+}
+
 function buildView(registry     , home     , root               , global         , env     , fsImpl     , protocols     , only                 )      {
   const { REGISTRY_FILE } = require('./registry.js');
   const { REF_META } = require('./refs.js');
@@ -710,4 +722,4 @@ function buildView(registry     , home     , root               , global
   return view;
 }
 
-module.exports = { loadSettings, clearSettingsCache };
+module.exports = { loadSettings, registryOn, clearSettingsCache };

package/src/runtime/settings/write.js

@@ -189,10 +189,74 @@ function writeLayer({ file, set = {}, unset = [], scrubKeys = [], force = false,
   }
 }
 
+/**
+ * Where a write to `file` lands. A symlinked settings file (a dotfile manager's link) is written
+ * through to its target so the link survives; a project or local file whose link leads outside the
+ * project, or leads nowhere, is refused rather than read through or copied.
+ */
+function writeTarget(file        , fsImpl     )                                                            {
+  let stat     ;
+  try { stat = fsImpl.lstatSync(file); } catch { return { ok: true, target: file }; }
+  if (!stat.isSymbolicLink()) return { ok: true, target: file };
+  let real        ;
+  try { real = fsImpl.realpathSync(file); } catch {
+    return { ok: false, result: invalid(file, 'is a symbolic link that does not resolve to a file; nothing was written', 'scope') };
+  }
+  const directory = path.dirname(file);
+  if (path.basename(directory) === '.doflow') {
+    try {
+      const rel = path.relative(fsImpl.realpathSync(path.dirname(directory)), real);
+      if (!rel || rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) throw new Error('outside');
+    } catch {
+      return { ok: false, result: invalid(file, 'is a symbolic link to a path outside the project; nothing was written', 'scope') };
+    }
+  }
+  return { ok: true, target: real };
+}
+
+/** The most significant digits a JSON number keeps exactly when it is read as a double and written back. */
+const EXACT_DIGITS = 15;
+const NUMBER_AT = /-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/y;
+
+/**
+ * The first top-level key of `text` (a JSON document) holding a number that `JSON.parse` followed by
+ * `JSON.stringify` would change in value: more than 15 digits and not a safe integer.
+ */
+function inexactNumberKey(text        )                {
+  let depth = 0;
+  let current                = null;
+  for (let i = 0; i < text.length;) {
+    const ch = text[i];
+    if (ch === '"') {
+      let end = i + 1;
+      while (end < text.length && text[end] !== '"') end += text[end] === '\\' ? 2 : 1;
+      if (depth === 1) {
+        let after = end + 1;
+        while (after < text.length && /\s/.test(text[after])) after++;
+        if (text[after] === ':') { try { current = JSON.parse(text.slice(i, end + 1)); } catch { current = null; } }
+      }
+      i = end + 1;
+    } else if (ch === '{' || ch === '[') { depth++; i++; }
+    else if (ch === '}' || ch === ']') { depth--; i++; }
+    else if (ch === '-' || (ch >= '0' && ch <= '9')) {
+      NUMBER_AT.lastIndex = i;
+      const match = NUMBER_AT.exec(text);
+      if (!match) { i++; continue; }
+      const token = match[0];
+      const digits = token.replace(/[eE].*$/, '').replace(/[-.]/g, '').replace(/^0+/, '').replace(/0+$/, '');
+      if (digits.length > EXACT_DIGITS && !(/^-?\d+$/.test(token) && Number.isSafeInteger(Number(token))) && current !== null) return current;
+      i += token.length;
+    } else i++;
+  }
+  return null;
+}
+
 const INVALID = Symbol('invalid layer');
 
 /** The read, merge and rename of `writeLayer`, run while it holds the layer's lock. */
 function replaceLayer({ file, registry, set, unsetKeys, scrubKeys, force, expect, backup, fsImpl }     )      {
+  const landing = writeTarget(file, fsImpl);
+  if (!landing.ok) return landing.result;
   let before                                 = null;
   let existing                          = {};
   let layer     ;
@@ -231,6 +295,13 @@ function replaceLayer({ file, registry, set, unsetKeys, scrubKeys, force, expect
   for (const [key, value] of Object.entries(set)) values[key] = value;
   for (const key of unsetKeys) delete values[key];
 
+  if (layer?.status === 'ok' && typeof layer.source === 'string') {
+    const kept = inexactNumberKey(layer.source);
+    if (kept !== null && Object.hasOwn(values, kept) && !Object.hasOwn(set, kept)) {
+      return invalid(file, `key '${kept}' holds a number with more digits than JSON can rewrite exactly; nothing was written; edit the file by hand`, 'number-precision');
+    }
+  }
+
   const after = layerDocument(registry, values);
   const bytes = serializeLayer(after);
   const tooLarge = oversize(file, bytes);
@@ -244,7 +315,7 @@ function replaceLayer({ file, registry, set, unsetKeys, scrubKeys, force, expect
   const directory = path.dirname(file);
   let temporary                = null;
   try {
-    temporary = path.join(directory, `.${path.basename(file)}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`);
+    temporary = path.join(path.dirname(landing.target), `.${path.basename(landing.target)}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`);
     fsImpl.writeFileSync(temporary, bytes, { flag: 'wx', mode: 0o600 });
     fsImpl.chmodSync(temporary, 0o600);
     if (path.basename(directory) === '.doflow') {
@@ -253,7 +324,7 @@ function replaceLayer({ file, registry, set, unsetKeys, scrubKeys, force, expect
         return invalid(file, '.doflow symlink points outside the project', 'scope');
       }
     }
-    fsImpl.renameSync(temporary, file);
+    fsImpl.renameSync(temporary, landing.target);
     temporary = null;
     clearSettingsCache();
     return { ok: true, file, before, after };

package/src/runtime/storage/registry.js

@@ -13,7 +13,7 @@ const RULES                        = new Map([
   ['date-partition', ['maxAgeDays']],
   ['recovery', ['keepNewest']],
   ['lifecycle-settled', ['defaultHours']],
-  ['report-orphan', ['orphanGraceHours', 'foreignMaxAgeDays']],
+  ['report-orphan', ['orphanGraceHours']],
   ['age', ['maxAgeDays']],
   ['existing', []],
   ['control', []],
@@ -132,7 +132,7 @@ function formatBound(store     )         {
     case 'date-partition': return `prune partitions older than ${bound.maxAgeDays} days`;
     case 'recovery': return `keep newest ${bound.keepNewest}, plus the snapshot named by the ledger`;
     case 'lifecycle-settled': return `retain settled events for ${bound.defaultHours} hours`;
-    case 'report-orphan': return `prune orphan bodies after ${bound.orphanGraceHours} hours; foreign folders after ${bound.foreignMaxAgeDays} days`;
+    case 'report-orphan': return `prune orphan bodies after ${bound.orphanGraceHours} hours; foreign folders are kept`;
     case 'age': return `prune inactive directories after ${bound.maxAgeDays} days`;
     case 'existing':
     case 'control': return bound.text;