@khoavu882/doflow 2.0.0-beta.5 → 2.0.0

package/src/runtime/settings/legacy.js

@@ -0,0 +1,154 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * The 2.0 settings files, read as deprecated sources (086 IC-008, FR-010). The rules are the 2.0
+ * ones, copied from `advice/config.ts` (parseUserSetting, parseProjectSetting, readJson),
+ * `storage/roots.ts` (readSetting + existsSync) and `failure/home.ts` (the sentinel `isFile`), so an
+ * old file gives the result it gave in 2.0. Two departures, both in the safe direction: a JSON parse
+ * error names its offset only, never the file text (IC-002, `jsonFailure`); a path that is not a
+ * regular file is never opened, so a FIFO cannot block a read (2.0 would have waited on it).
+ *
+ * `../settings/resolve.js` requires this module only after a `stat` hit on a legacy path, so a
+ * machine with no old files never compiles it. Nothing here writes, and nothing returns file text.
+ */
+
+const nodeFs = require('node:fs');
+const { jsonFailure } = require('./files.js');
+
+const PROJECT_NOTE = 'a project cannot enable the decision model or choose its endpoint';
+const USER_KEYS = new Set(['schema', 'enabled', 'provider', 'endpoint', 'model']);
+const PROJECT_KEYS = ['schema', 'enabled', 'model', 'endpoint', 'provider'];
+/** The decision-model.json fields that carry a setting, in file order. */
+const FIELDS = ['enabled', 'provider', 'endpoint', 'model'];
+
+                                                                                                         
+                                             
+                                                                                          
+                        
+                                      
+                    
+                        
+                                                                                              
+                        
+                                                                  
+                               
+                      
+ 
+/** What the user file is checked against: the provider default and list, and each provider's default endpoint. */
+                                                                                                              
+
+function isObject(value     )          {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** 2.0 `parseUserSetting` (advice/config.ts): the whole file is valid or none of it is. */
+function parseUserSetting(value     , providers           )                                  {
+  if (!isObject(value)) return { error: 'user setting must be a JSON object', code: 'unparseable' };
+  if (value.schema !== 1) return { error: 'user setting schema must be 1', code: 'schema' };
+  if (typeof value.enabled !== 'boolean') return { error: 'user setting enabled must be a boolean', code: 'type' };
+
+  const providerId = value.provider === undefined ? providers.defaultProvider : value.provider;
+  if (typeof providerId !== 'string' || !providers.ids.includes(providerId)) {
+    return { error: `user setting provider '${providerId}' is not in advice.json providers`, code: 'enum' };
+  }
+  let endpoint         ;
+  if (value.endpoint !== undefined) {
+    if (typeof value.endpoint !== 'string' || !value.endpoint.trim()) return { error: 'user setting endpoint must be a URL string', code: 'url' };
+    try { new URL(value.endpoint); } catch { return { error: 'user setting endpoint must be a URL string', code: 'url' }; }
+    endpoint = value.endpoint;
+  } else {
+    endpoint = providers.defaultEndpoint(providerId);
+  }
+  if (typeof endpoint !== 'string' || !endpoint) return { error: `providers.${providerId}.defaultEndpoint is missing`, code: 'enum' };
+
+  if (value.model !== undefined && (typeof value.model !== 'string' || !value.model.trim())) {
+    return { error: 'user setting model must be a non-empty string', code: 'type' };
+  }
+  if (value.enabled && (typeof value.model !== 'string' || !value.model.trim())) {
+    return { error: 'user setting model is required when enabled is true', code: 'cross-key' };
+  }
+  const notes               = Object.keys(value)
+    .filter((key) => !USER_KEYS.has(key))
+    .map((key) => ({ code: 'unknown-key', field: null, text: `unknown user key '${key}' ignored` }));
+  return { notes };
+}
+
+/** 2.0 `parseProjectSetting`: a project may only disable and choose a model; the rest is noted, never applied. */
+function parseProjectSetting(value     )                                  {
+  if (!isObject(value)) return { error: 'project setting must be a JSON object', code: 'unparseable' };
+  if (value.schema !== 1) return { error: 'project setting schema must be 1', code: 'schema' };
+  if (value.enabled !== undefined && typeof value.enabled !== 'boolean') return { error: 'project setting enabled must be a boolean', code: 'type' };
+  if (value.model !== undefined && (typeof value.model !== 'string' || !value.model.trim())) return { error: 'project setting model must be a non-empty string', code: 'type' };
+
+  const notes               = [];
+  if (value.enabled === true) notes.push({ code: 'scope', field: 'enabled', text: `project key 'enabled' ignored: ${PROJECT_NOTE}` });
+  for (const key of ['endpoint', 'provider']) {
+    if (Object.hasOwn(value, key)) notes.push({ code: 'scope', field: key, text: `project key '${key}' ignored: ${PROJECT_NOTE}` });
+  }
+  for (const key of Object.keys(value)) {
+    if (!PROJECT_KEYS.includes(key)) {
+      const shown = JSON.stringify(key.length > 80 ? `${key.slice(0, 80)}...` : key);
+      notes.push({ code: 'unknown-key', field: null, text: `unknown project key ${shown} ignored` });
+    }
+  }
+  return { notes };
+}
+
+function failed(code      , reason        , offset                = null)               {
+  return { status: 'invalid', code, offset, reason, fields: new Map(), notes: [] };
+}
+
+/**
+ * `<config home>/doflow/decision-model.json` (flavour `user`) or `.doflow/decision-model.json`
+ * (`project`). A missing file is absent; any other fault is the whole file invalid with today's text.
+ * A valid file yields the fields it holds: a project's `enabled: true`, `endpoint` and `provider` are
+ * yielded too (the resolver's scope rules ignore them) with today's notes.
+ */
+function readDecisionModel(file        , flavour                    , providers                  , fsImpl      = nodeFs)               {
+  try {
+    if (!fsImpl.statSync(file).isFile()) return failed('not-file', 'is not a regular file');
+  } catch (error     ) {
+    if (error?.code === 'ENOENT') return { status: 'absent', code: null, offset: null, reason: null, fields: new Map(), notes: [] };
+    return failed('unreadable', String(error?.message ?? 'cannot be read'));
+  }
+  let text        ;
+  try { text = fsImpl.readFileSync(file, 'utf8'); }
+  catch (error     ) { return failed('unreadable', String(error?.message ?? 'cannot be read')); }
+  let value     ;
+  try { value = JSON.parse(text); }
+  catch (error     ) {
+    const failure = jsonFailure(error, text);
+    return failed('unparseable', failure.reason, failure.offset);
+  }
+  const parsed = flavour === 'user'
+    ? parseUserSetting(value, providers ?? { defaultProvider: undefined, ids: [], defaultEndpoint: () => null })
+    : parseProjectSetting(value);
+  if ('error' in parsed) return failed(parsed.code, parsed.error);
+  const fields = new Map                 ();
+  for (const field of FIELDS) if (Object.hasOwn(value, field)) fields.set(field, value[field]);
+  return { status: 'ok', code: null, offset: null, reason: null, fields, notes: parsed.notes };
+}
+
+/**
+ * The `prune` file (2.0 `readSetting` behind `existsSync`): absent → null; otherwise its first line,
+ * trimmed, any case, `on` or `off`; anything else, an empty file or a path that cannot be read as a
+ * file is `off`.
+ */
+function readLineOnOff(file        , fsImpl      = nodeFs)                      {
+  let stat     ;
+  try { stat = fsImpl.statSync(file); } catch { return null; }
+  if (!stat.isFile()) return 'off';
+  try {
+    const first = String(fsImpl.readFileSync(file, 'utf8')).split(/\r?\n/, 1)[0].trim().toLowerCase();
+    return first === 'on' || first === 'off' ? first : 'off';
+  } catch { return 'off'; }
+}
+
+/** A sentinel file (`failures/off`): present when the path is a regular file; its content is never read. */
+function readSentinel(file        , fsImpl      = nodeFs)          {
+  try { return fsImpl.statSync(file).isFile(); } catch { return false; }
+}
+
+module.exports = { PROJECT_NOTE, readDecisionModel, readLineOnOff, readSentinel };

package/src/runtime/settings/lexical.js

@@ -0,0 +1,56 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * The lexical `failure.capture` rule v1 (086 IC-004, DD-3, OI-1): the one line rule over the raw text
+ * of `settings.json` that the bash dispatcher, the bash policy, the JS hook runner and Node all apply,
+ * so a failing hook never needs `jq`, `node` or a JSON parser to know whether capture is off. The
+ * text is the file's bytes up to the first NUL. Every match of `"failure.capture"` + `:` + a value
+ * must capture exactly `"on"`; any other capture is `off`; no match is "no setting" (null). JSON
+ * validity is irrelevant and nothing here reports file text.
+ *
+ * The bare alternative excludes `"` (OI-1) so `{"failure.capture":"on"abc,}` reads the same in
+ * bash (leftmost-longest) and JS (leftmost-first). The whitespace class is the C-locale
+ * `[[:space:]]`, spelled out: JS `\s` would add Unicode spaces (U+00A0) that bash does not match.
+ * The file is read as `latin1`, one character per byte, as bash does under `LC_ALL=C`.
+ */
+
+const nodeFs = require('node:fs');
+
+                                   
+
+const WS = '[ \\t\\n\\v\\f\\r]';
+const CAPTURE_RE = new RegExp(`"failure\\.capture"${WS}*:${WS}*("[^"]*"|[^,}" \\t\\n\\v\\f\\r]*)`, 'g');
+
+/** @param text the file's bytes as a latin1 string */
+function lexicalCapture(text        )          {
+  let out          = null;
+  for (const m of text.split('\0', 1)[0].matchAll(CAPTURE_RE)) out = m[1] === '"on"' ? (out ?? 'on') : 'off';
+  return out;
+}
+
+/**
+ * A missing file is no setting; a path that is not a regular file, or cannot be read, is `off`.
+ * Never throws, never returns file text.
+ */
+function readLexicalCapture(file        , fsImpl      = nodeFs)          {
+  try {
+    if (!fsImpl.statSync(file).isFile()) return 'off';
+  } catch (error     ) {
+    const code = error?.code;
+    if (code === 'ENOENT' || code === 'ELOOP' || code === 'ENOTDIR') return null;
+    if (code === 'EACCES') {
+      try {
+        const parent = require('node:path').dirname(file);
+        if (!fsImpl.statSync(parent).isDirectory()) return null;
+        try { fsImpl.accessSync(parent, fsImpl.constants?.X_OK ?? nodeFs.constants.X_OK); return null; }
+        catch (accessError     ) { return accessError?.code === 'EACCES' ? 'off' : null; }
+      } catch { return null; }
+    }
+    return 'off';
+  }
+  try { return lexicalCapture(fsImpl.readFileSync(file, 'latin1')); } catch { return 'off'; }
+}
+
+module.exports = { lexicalCapture, readLexicalCapture };

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

@@ -0,0 +1,269 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * `doflow config validate --prepared-run <file>` (119 IC-010, FR-013, NFR-005). Checks a prepared-run file
+ * `{ schema: 1, taskClass, primary: { harness, model }, settings: { <key>: <value> }, presets: { review, debate } }`
+ * and returns one IC-009 entry per fault, keyed by JSON path. It starts no harness, calls no model, runs no git,
+ * opens no network connection and writes nothing. Each `settings` and `primary` entry is judged exactly as
+ * `config validate <key> <value> --layer project` (config-write.ts `keyEntry` + `layerEntry`), so no value
+ * rule is repeated here. The presets
+ * are checked against what a run can know before there is a diff (L-E1): the risk-policy step of the protocol
+ * resolution needs the diff and is not applied.
+ */
+
+const path = require('node:path');
+const nodeFs = require('node:fs');
+const { finishRuntime, usageError } = require('../cli-result.js');
+const { keyEntry, layerFile, layerEntry } = require('./config-write.js');
+const { loadProtocols, presetIds, contributedPresetIds } = require('../review/protocols.js');
+const { gateMinSeats, settingsPick, atLeastAsStrict } = require('../review/resolve-protocol.js');
+
+/** The worker fields are judged here, without applying them or launching a harness. */
+const KNOWN = new Set(['schema', 'taskClass', 'primary', 'workers', 'settings', 'presets']);
+
+                                                                                                                 
+
+function entry(key        , layer               , code        , message        , allowed          = null)        {
+  return { key, layer, ok: false, code, message, allowed };
+}
+
+function isObject(value         )                               {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** IC-018: qualified worker ids need JSON-path brackets; built-in ids stay readable. */
+function bindingKey(id        , tier        )         {
+  const worker = /^[a-z][a-z0-9-]*$/.test(id) ? `.${id}` : `[${JSON.stringify(id)}]`;
+  return `workers.models${worker}.${tier}`;
+}
+
+/** The task classes of the workflow registry, the one `doflow classify` validates against. */
+function taskClasses(repoRoot        , fsImpl     )           {
+  const { WorkflowEngine } = require('../workflow-engine.js');
+  return new WorkflowEngine({ repoRoot, fsImpl }).listClasses();
+}
+
+function validatePrepared(doc                     , ctx     )          {
+  const { registry, protocols, classes } = ctx;
+  const errors          = [];
+  const notes           = ctx.notes;
+
+  if (!Object.hasOwn(doc, 'schema')) errors.push(entry('schema', null, 'type', 'schema is required and must be 1'));
+  else if (doc.schema !== 1) errors.push(entry('schema', null, 'enum', 'schema must be 1', [1]));
+
+  let taskClass                = null;
+  if (typeof doc.taskClass !== 'string') {
+    errors.push(entry('taskClass', null, 'type', Object.hasOwn(doc, 'taskClass') ? 'taskClass must be a string' : 'taskClass is required'));
+  } else if (!classes.includes(doc.taskClass)) {
+    errors.push(entry('taskClass', null, 'enum', `${doc.taskClass} is not a task class in core/registry/workflows.yaml`, classes));
+  } else taskClass = doc.taskClass;
+
+  const settings                      = isObject(doc.settings) ? doc.settings : {};
+  if (Object.hasOwn(doc, 'settings') && !isObject(doc.settings)) errors.push(entry('settings', null, 'type', 'settings must be an object of setting keys to values'));
+  let where      = null;
+  for (const key of Object.keys(settings)) {
+    const named = (e       )        => ({ ...e, key: `settings.${e.key}` });
+    const keyFault = keyEntry(registry, key, 'project', true);
+    if (keyFault) { errors.push(named(keyFault)); continue; }
+    if (settings[key] === null) { errors.push(entry(`settings.${key}`, 'project', 'type', `${key} cannot be null; leave the key out`)); continue; }
+    where ??= layerFile('project', ctx.env, ctx.projectRoot, ctx.fsImpl);
+    if ('error' in where) throw Object.assign(new Error(where.error), { usage: true });
+    const fault = layerEntry(registry, key, 'project', where.file, { ok: true, value: settings[key] },
+      { env: ctx.env, projectRoot: ctx.projectRoot, fsImpl: ctx.fsImpl, siblings: settings });
+    if (fault) errors.push(named(fault));
+  }
+
+  const primary                      = isObject(doc.primary) ? doc.primary : {};
+  if (Object.hasOwn(doc, 'primary') && !isObject(doc.primary)) {
+    errors.push(entry('primary', null, 'type', 'primary must be an object with harness and model'));
+  } else if (Object.hasOwn(doc, 'primary')) {
+    for (const field of Object.keys(primary)) {
+      const key = `primary.${field}`;
+      if (field !== 'harness' && field !== 'model') {
+        errors.push(entry(key, null, 'unknown-key', `${field} is not a primary field; expected harness, model`));
+        continue;
+      }
+      const keyFault = keyEntry(registry, key, 'project', true);
+      if (keyFault) { errors.push(keyFault); continue; }
+      if (primary[field] === null) {
+        errors.push(entry(key, 'project', 'type', `${key} cannot be null; leave the key out`));
+        continue;
+      }
+      where ??= layerFile('project', ctx.env, ctx.projectRoot, ctx.fsImpl);
+      if ('error' in where) throw Object.assign(new Error(where.error), { usage: true });
+      const fault = layerEntry(registry, key, 'project', where.file, { ok: true, value: primary[field] },
+        { env: ctx.env, projectRoot: ctx.projectRoot, fsImpl: ctx.fsImpl, siblings: primary });
+      if (fault) errors.push(fault);
+    }
+  }
+
+  if (Object.hasOwn(doc, 'workers')) {
+    const { validateValue } = require('./files.js');
+    const workers                      = isObject(doc.workers) ? doc.workers : {};
+    if (!isObject(doc.workers)) {
+      errors.push(entry('workers', null, 'type', 'workers must be an object with enabled and models'));
+    } else {
+      for (const field of Object.keys(workers)) {
+        if (field !== 'enabled' && field !== 'models') {
+          errors.push(entry(`workers.${field}`, null, 'unknown-key', `${field} is not a workers field; expected enabled, models`));
+        }
+      }
+
+      if (Object.hasOwn(workers, 'enabled')) {
+        const key = 'workers.enabled';
+        const value = workers.enabled;
+        const spec = registry.keys.get(key);
+        const allowed = registry.enumValues(key);
+        if (value === null) {
+          errors.push(entry(key, null, 'type', `${key} cannot be null; leave the key out`));
+        } else {
+          const fault = validateValue(spec, value, allowed);
+          if (fault) {
+            let index = -1;
+            if (Array.isArray(value)) {
+              for (let i = 0; i < value.length; i += 1) {
+                if (validateValue(spec, value.slice(0, i + 1), allowed)) { index = i; break; }
+              }
+            }
+            if (index >= 0) {
+              const prefixFault = validateValue(spec, value.slice(0, index + 1), allowed);
+              errors.push(entry(`${key}[${index}]`, null, prefixFault.code, prefixFault.reason, allowed));
+            } else errors.push(entry(key, null, fault.code, fault.reason, allowed));
+          } else {
+            where ??= layerFile('project', ctx.env, ctx.projectRoot, ctx.fsImpl);
+            if ('error' in where) throw Object.assign(new Error(where.error), { usage: true });
+            const fault = layerEntry(registry, key, 'project', where.file, { ok: true, value },
+              { env: ctx.env, projectRoot: ctx.projectRoot, fsImpl: ctx.fsImpl, notes, siblings: {} });
+            if (fault) {
+              if (fault.code === 'not-narrower') {
+                const match = fault.message.match(/\('([^']*)' is not in the value below\)/);
+                const index = match ? value.indexOf(match[1]) : -1;
+                if (index >= 0) fault.key = `${key}[${index}]`;
+              }
+              errors.push(fault);
+            }
+          }
+        }
+      }
+
+      if (Object.hasOwn(workers, 'models')) {
+        const key = 'workers.models';
+        const value = workers.models;
+        const spec = registry.keys.get(key);
+        const allowed = registry.enumValues(key);
+        if (value === null) {
+          errors.push(entry(key, null, 'type', `${key} cannot be null; leave the key out`));
+        } else {
+          const fault = validateValue(spec, value, allowed);
+          if (fault) {
+            errors.push(entry(key, null, fault.code, fault.reason, allowed));
+          } else {
+            const { loadRegistry } = require('../../registry/index.js');
+            const { workerCatalogue } = require('../worker/catalogue.js');
+            const workerRegistry = loadRegistry({ repoRoot: ctx.repoRoot, fsImpl: ctx.fsImpl });
+            const catalogue = workerCatalogue({ registry: workerRegistry });
+            const byId = new Map             (catalogue.map((worker     ) => [worker.id, worker]));
+            for (const id of Object.keys(value)) {
+              const worker = byId.get(id);
+              if (!worker) {
+                notes.push(`note: ${key}: worker '${id}' is not installed (ignored)`);
+                continue;
+              }
+              const status = worker.worker.model?.status || 'absent';
+              if (status === 'supported') continue;
+              for (const tier of Object.keys(value[id])) {
+                errors.push(entry(bindingKey(id, tier), null, 'model-flag-unevidenced',
+                  `${id} has no evidenced model flag (descriptor model is ${status}); dispatch would skip the worker for this binding`));
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  const presets                      = isObject(doc.presets) ? doc.presets : {};
+  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));
+  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
+    const named           = [...order, ...contributedPresetIds(protocols, kind)]; // selectable by name (122 IC-014)
+    const key = `presets.${kind}`;
+    const id = presets[kind];
+    if (typeof id !== 'string' || !named.includes(id)) {
+      errors.push(entry(key, null, 'enum', `${typeof id === 'string' ? id : JSON.stringify(id)} is not a ${kind} preset`, named));
+      continue;
+    }
+    // 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`;
+    const view                      = { ...inputs().settingsView };
+    const current = view[settingKey];
+    if (typeof settings[settingKey] === 'string' && (!current || ['default', 'user', 'project'].includes(current.layer))) {
+      view[settingKey] = { value: settings[settingKey], layer: 'project' };
+    }
+    const pick = settingsPick({ kind, pick: { id: order[order.length - 1], origin: 'registry' }, settingsView: view, registry: protocols });
+    // Two core ids compare by their place in the order; a pair with a contributed id by dominance (never an indexOf of -1).
+    if (!atLeastAsStrict(protocols, kind, id, pick.id)) {
+      errors.push(entry(key, null, 'not-narrower', `${id} is looser than settings["${settingKey}"] ${pick.id} (${pick.origin} layer)`));
+      continue;
+    }
+    if (kind !== 'review') continue;
+    if (taskClass === null) continue;
+    // maint-thin: the seat floor binds unless autopilot is verifiably off (reviewUnattended), as in review start.
+    const floor         = inputs().unattended === false ? 0 : gateMinSeats(inputs().gatePolicy, taskClass);
+    const seats         = protocols.presets[id].seats.length;
+    if (seats < floor) { // the seat floor (L-E1); the E.1-control-floor mutation targets this line
+      errors.push(entry(key, null, 'not-narrower', `${id} has ${seats} seat${seats === 1 ? '' : 's'}; the gate-b floor for ${taskClass} is ${floor} seats`));
+    }
+  }
+
+  for (const key of Object.keys(doc)) {
+    if (KNOWN.has(key)) continue;
+    errors.push(entry(key, null, 'unknown-key', `${key} is not a prepared-run field; expected schema, taskClass, primary, workers, settings, presets`));
+  }
+  return errors;
+}
+
+function report(file        , errors         , json         , notes           = [])         {
+  if (json) console.log(JSON.stringify({ ok: errors.length === 0, errors, ...(notes.length ? { notes } : {}) }, null, 2));
+  else {
+    if (errors.length === 0) console.log(`prepared run: valid (${file})`);
+    else for (const error of errors) console.error(`${error.key}: ${error.message}`);
+    for (const note of notes) console.log(note);
+  }
+  return finishRuntime(errors.length === 0 ? 0 : 1);
+}
+
+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); }
+  let doc         ;
+  try { doc = JSON.parse(text); } catch { return report(file, [entry('$', null, 'type', 'the prepared run is not valid JSON')], json); }
+  if (!isObject(doc)) return report(file, [entry('$', null, 'type', 'the prepared run must be a JSON object')], json);
+
+  try {
+    const protocols = loadProtocols({ repoRoot, fsImpl });
+    if (!protocols.ok) throw new Error(protocols.errors.join('; '));
+    const root = path.resolve(projectRoot);
+    const notes           = [];
+    const ctx = {
+      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 });
+        return inputs;
+      },
+    };
+    return report(file, validatePrepared(doc, ctx), json, notes);
+  } catch (error     ) {
+    return usageError('config', error?.message || String(error), json, error.usage ? undefined : error);
+  }
+}
+
+module.exports = { handlePreparedRun, bindingKey };

package/src/runtime/settings/project-layers.js

@@ -0,0 +1,118 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * 086 IC-007, DD-9: where the project layer of the settings lives. Locates files only; both project
+ * files are untrusted (D-16) and the resolver reads them. A linked worktree with no settings of its
+ * own falls back to the main checkout's `.doflow/` (OI-4, a declared change in this release), found by reading
+ * `.git` (`gitdir: <g>`), `<g>/gitdir` (the back-pointer to this worktree, so a forged or stale `.git`
+ * inherits nothing) and `<g>/commondir`: three small reads, no process (no `git worktree list` per
+ * verb). A sandbox (`.doflow-worktree-base`, which every dispatch worktree under
+ * `<root>/.doflow/state/dispatch-worktrees/<id>` carries) stays isolated and uses only its own.
+ *
+ * The root is the caller's, authoritative: nothing walks up to a nearer `.git`, so a folder with its own
+ * `.doflow` inside a repository gets its own layers, as 2.0 read them. Every fault yields the checkout's
+ * own `.doflow`, never a throw. A `.doflow` that is a symlink out of its checkout is not followed: the own
+ * one yields no project layer, a main checkout's falls back to the own. Pure data: the same tree gives the same answer, so the caller may memoize per process.
+ */
+
+const nodeFs = require('node:fs');
+const path = require('node:path');
+
+const MARKER = '.doflow-worktree-base';
+const SETTINGS_FILES = Object.freeze(['settings.json', 'settings.local.json', 'decision-model.json', 'prune']);
+const MAX_POINTER_BYTES = 4096;
+const GITDIR_LINE = /^gitdir:[ \t]*([^\r\n]+?)[ \t]*\r?\n?$/;
+
+                                           
+                              
+                                                                                                       
+                            
+                            
+                                                                                                       
+                  
+ 
+
+function lstatOrNull(p        , fsImpl     )      {
+  try { return fsImpl.lstatSync(p); } catch { return null; }
+}
+
+/** True when `<root>/.doflow` may serve as a layer folder: absent is fine (the files are absent
+ * too), a real folder is fine, a symlink must resolve inside `root`. */
+function containedDoflow(root        , fsImpl     )          {
+  const dir = path.join(root, '.doflow');
+  const stat = lstatOrNull(dir, fsImpl);
+  if (!stat || !stat.isSymbolicLink()) return true;
+  try {
+    const rel = path.relative(fsImpl.realpathSync(root), fsImpl.realpathSync(dir));
+    return !!rel && rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel);
+  } catch { return false; }
+}
+
+function holdsSettings(root        , fsImpl     )          {
+  return SETTINGS_FILES.some((name) => lstatOrNull(path.join(root, '.doflow', name), fsImpl) !== null);
+}
+
+/** A small regular file's text, or null (missing, not a file, over the bound, unreadable). */
+function readPointer(file        , fsImpl     )                {
+  try {
+    const stat = fsImpl.statSync(file);
+    if (!stat.isFile() || stat.size > MAX_POINTER_BYTES) return null;
+    const text = String(fsImpl.readFileSync(file, 'utf8'));
+    return text.includes('\0') ? null : text;
+  } catch { return null; }
+}
+
+/** The main checkout a linked worktree at `root` belongs to, from `.git` and `commondir`; null on any fault. */
+function mainCheckoutOf(root        , fsImpl     )                {
+  const pointer = readPointer(path.join(root, '.git'), fsImpl);
+  const match = pointer === null ? null : GITDIR_LINE.exec(pointer);
+  if (!match) return null;
+  const gitdir = path.resolve(root, match[1]);
+  // git writes `<gitdir>/gitdir` pointing back at this worktree's `.git` file; a `.git` file that names
+  // some other worktree's admin dir (hostile or stale after a move) fails this and inherits nothing
+  const back = readPointer(path.join(gitdir, 'gitdir'), fsImpl);
+  const backLine = back === null ? '' : back.replace(/\r?\n$/, '');
+  if (!backLine || /[\r\n]/.test(backLine)) return null;
+  try {
+    if (fsImpl.realpathSync(path.resolve(gitdir, backLine)) !== fsImpl.realpathSync(path.join(root, '.git'))) return null;
+  } catch { return null; }
+  const common = readPointer(path.join(gitdir, 'commondir'), fsImpl);
+  const line = common === null ? '' : common.replace(/\r?\n$/, '');
+  if (!line || /[\r\n]/.test(line)) return null;
+  const commonDir = path.resolve(gitdir, line);
+  return path.basename(commonDir) === '.git' ? path.dirname(commonDir) : null;
+}
+
+function located(root        , checkout          , fsImpl     )                     {
+  if (!containedDoflow(root, fsImpl)) return { layersFrom: null, checkout: 'own', files: [] };
+  const layersFrom = path.join(root, '.doflow');
+  return { layersFrom, checkout, files: [path.join(layersFrom, 'settings.local.json'), path.join(layersFrom, 'settings.json')] };
+}
+
+/**
+ * @param projectRoot the checkout root, authoritative: the caller's own root, with no walk-up
+ * @param fsImpl `lstatSync`, `statSync`, `readFileSync`, `realpathSync`
+ * @returns the `.doflow` folder and the ordered layer files, with which checkout they belong to
+ */
+function projectLayerSource(projectRoot                           , fsImpl      = nodeFs)                     {
+  if (!projectRoot) return { layersFrom: null, checkout: null, files: [] };
+  try {
+    const root = path.resolve(projectRoot);
+    const git = lstatOrNull(path.join(root, '.git'), fsImpl);
+    if (git && git.isDirectory()) return located(root, 'own', fsImpl);
+    if (lstatOrNull(path.join(root, MARKER), fsImpl)) return located(root, 'sandbox', fsImpl);
+    if (!git) {
+      return lstatOrNull(path.join(root, '.doflow'), fsImpl) ? located(root, 'own', fsImpl) : { layersFrom: null, checkout: 'own', files: [] };
+    }
+    if (holdsSettings(root, fsImpl)) return located(root, 'own', fsImpl);
+    const main = mainCheckoutOf(root, fsImpl);
+    if (main && lstatOrNull(path.join(main, '.doflow'), fsImpl) && containedDoflow(main, fsImpl)) return located(main, 'main', fsImpl);
+    return located(root, 'own', fsImpl);
+  } catch {
+    return { layersFrom: null, checkout: null, files: [] };
+  }
+}
+
+module.exports = { projectLayerSource, containedDoflow, MARKER };