runlist 0.0.0 → 0.94.1

package/src/config.mjs

@@ -0,0 +1,705 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { die, warn } from './util.mjs';
+import { CONFIG_FILENAMES } from './naming.mjs';
+import { validateStageDefinitions } from './stages.mjs';
+import { validateFilingConfig } from './filing.mjs';
+import { validateYardstickConfig } from './yardstick.mjs';
+
+// Keys where user config replaces defaults entirely (not deep-merged).
+// These are flat maps or config sections where the user's version is authoritative —
+// default keys that the user omitted should NOT survive the merge.
+const REPLACE_KEYS = new Set([
+  'statuses.staleDays',
+  'statuses.rootStatuses',
+  'lifecycle.filedStatuses',
+  'presets',
+  'context',
+]);
+
+const DEFAULTS = {
+  root: '.',
+  archiveDir: 'archived',
+  excludeDirs: [],
+  externalBodyLinkRoots: [],
+  records: null,
+  filing: null,
+  yardstick: null,
+  // Floor under the scan surface; null = off. See `applyScanFloor` in validate.mjs.
+  minDocs: null,
+
+  // Reference repair outside the doc roots (`runlist refs`). An empty
+  // `codeRoots` is off, which is the behaviour before this key existed: the
+  // doc-root repair archive and rename already run is unchanged either way.
+  // Paths are repo-relative. `null` on the two lists means "the built-in
+  // list", which lives in code-refs.mjs so config.mjs stays a leaf.
+  codeRoots: [],
+  codeExtensions: null,
+  codeExcludes: null,
+  // Files whose content is data keyed on document paths — a guard baseline
+  // whose keys are plan paths, for instance. Reported, never written.
+  codeRefsUntouched: [],
+
+  types: {
+    plan: {
+      statuses: ['in-session', 'active', 'planned', 'blocked', 'partial', 'paused', 'awaiting', 'queued-after', 'archived'],
+      context: {
+        expanded: ['in-session', 'active', 'partial'],
+        listed: ['planned', 'blocked', 'paused', 'awaiting'],
+        counted: ['queued-after', 'archived'],
+      },
+      staleDays: { 'in-session': 1, active: 14, planned: 30, blocked: 30, paused: 3, awaiting: 14 },
+    },
+    doc: {
+      statuses: ['draft', 'active', 'review', 'reference', 'deprecated', 'archived'],
+      context: { expanded: ['active'], listed: ['draft', 'review'], counted: ['reference', 'deprecated', 'archived'] },
+      staleDays: { draft: 30, active: 14, review: 14 },
+    },
+    // A prompt has two states and no third. It is pending — the next session
+    // should consume it — or it is archived, consumed, body kept under the
+    // archive directory. `held`, `shelved` and `claimed` were removed 2026-08-30:
+    // a prompt directs work, so parking one instead of archiving it leaves work
+    // state sitting outside the plan that owns it, where it fights with the
+    // plan's own status and neither one is the truth. If a prompt should not be
+    // consumed, its content belongs in the plan and the prompt should be
+    // archived. See lifecycle.filedStatuses — prompts file nowhere.
+    prompt: {
+      statuses: ['pending', 'archived'],
+      context: { expanded: ['pending'], counted: ['archived'] },
+      staleDays: { pending: 30 },
+    },
+  },
+
+  statuses: {
+    order: ['active', 'ready', 'planned', 'scoping', 'blocked', 'reference', 'archived'],
+    staleDays: {
+      active: 14,
+      ready: 14,
+      planned: 30,
+      blocked: 30,
+      scoping: 30,
+    },
+  },
+
+  lifecycle: {
+    startableStatuses: ['active', 'planned'],
+    archiveStatuses: ['archived'],
+    skipStaleFor: ['archived', 'reference', 'partial', 'queued-after'],
+    skipWarningsFor: ['archived', 'partial', 'queued-after'],
+    terminalStatuses: ['archived', 'deprecated', 'reference'],
+    // F15: per-status filing buckets (status → dirName). Built-in held/paused
+    // statuses file under the owning type folder; archive remains a separate
+    // primitive untouched.
+    // Plans only. A paused plan files under <plansDir>/held/ so the live plan
+    // list stays readable. Prompts were removed from this map 2026-08-30 along
+    // with their held/shelved statuses — `archived` is the only directory a
+    // prompt ever moves into.
+    filedStatuses: { paused: 'held' },
+    // Types whose archive nests under their own type dir (<typeDir>/<archiveDir>,
+    // e.g. docs/prompts/archived/) instead of the shared <root>/<archiveDir>.
+    // Prompts are session-local churn — keeping their archive out of the shared
+    // docs/archived/ stops them from burying plans/docs there. Set to [] to send
+    // every type to the shared archive.
+    archiveNestedTypes: ['prompt'],
+  },
+
+  taxonomy: {
+    surfaces: null,
+    // Ordered delivery stages; null leaves the repository vocabulary unrestricted.
+    milestones: null,
+    // modules: when null (default), the project doesn't enumerate product
+    // modules — the modules-required validator silently skips. When set to
+    // an array, modules are taxonomy-enforced AND moduleRequiredFor activates.
+    // Mirrors the long-standing semantics of `taxonomy.surfaces`.
+    modules: null,
+    moduleRequiredFor: ['partial', 'paused', 'awaiting', 'queued-after'],
+  },
+
+  index: null,
+
+  context: {
+    expanded: ['active'],
+    listed: ['ready', 'planned'],
+    counted: ['blocked', 'scoping', 'reference', 'archived'],
+    recentDays: 3,
+    recentStatuses: ['active', 'ready', 'planned'],
+    recentLimit: 10,
+    truncateNextStep: 80,
+  },
+
+  display: {
+    lineWidth: 0,
+    truncateTitle: 30,
+    truncateNextStep: 80,
+  },
+
+  referenceFields: {
+    // Defaults match the fields the built-in `plan`, `doc`, and `prompt`
+    // templates scaffold, so graph / deps / unblocks / pickup's Related:
+    // resolver work without config. Override by setting `referenceFields`
+    // in your config — your value fully replaces (no per-field merge).
+    bidirectional: ['related_plans', 'related_docs'],
+    unidirectional: ['parent_plan', 'runlist'],
+  },
+
+  templates: {},
+
+  glossary: null,
+  // `runlist new decision`: { section, prefix, register: { file, statusLine } }.
+  decisions: null,
+  // `runlist flag` / `runlist flags`: { file } moves the log from .runlist/flags.jsonl.
+  flags: null,
+
+  // Opt-in JSONL command journal at .runlist/journal.jsonl. Default off — agents
+  // and users who want usage observability flip this on (or set RUNLIST_JOURNAL=1).
+  journal: false,
+
+  // PreToolUse guard behavior. `deny: false` drops status edits to warnings;
+  // `promptReads: 'deny'` blocks direct reads of existing pending prompts.
+  guard: { deny: true, promptReads: 'warn' },
+
+  presets: {
+    stale: ['--status', 'active,ready,planned,blocked,scoping', '--stale', '--sort', 'updated', '--all'],
+    actionable: ['--status', 'active,ready', '--has-next-step', '--sort', 'updated', '--all'],
+  },
+};
+
+const VALID_CONTEXT_VALUES = new Set(['expanded', 'listed', 'counted']);
+
+/**
+ * Normalize rich status definitions (object form) into array form + derived config.
+ * When types.<type>.statuses is an object like:
+ *   { 'active': { context: 'expanded', staleDays: 14, requiresModule: true }, ... }
+ * this extracts all behavioral properties, converts statuses to an array for
+ * downstream processing, and returns derived values for lifecycle/taxonomy/context.
+ *
+ * Returns null if no types use object-form statuses.
+ */
+function normalizeRichStatuses(config, userConfig) {
+  const derived = {
+    startableStatuses: [],
+    archiveStatuses: [],
+    skipStaleFor: [],
+    skipWarningsFor: [],
+    // Same membership as `skipWarningsFor`, but kept per declaring type. The flat
+    // list is a union of status NAMES, so a name any type marks quiet suppresses
+    // warnings for every other type that happens to share it — `journey.active`
+    // silencing every `active` plan in the repo. Statuses are type-scoped
+    // everywhere else (`typeStatuses`, `isValidStatus`), so the suppression that
+    // reads them has to be too.
+    skipWarningsForByType: {},
+    terminalStatuses: [],
+    terminalStatusesByType: {},
+    moduleRequiredFor: [],
+    // F15: status-name → directory-name (defaults to the status name verbatim).
+    // Filed statuses move docs into <root>/<dirName>/ on transition INTO the
+    // status, and back to flat <root>/ on transition OUT. Separate from
+    // archive: true to avoid touching that long-standing primitive's
+    // semantics.
+    filedStatuses: {},
+    staleDays: {},
+    statusOrder: [],
+    context: { expanded: [], listed: [], counted: [] },
+  };
+
+  let hasRich = false;
+
+  for (const [typeName, typeDef] of Object.entries(config.types ?? {})) {
+    if (!typeDef.statuses || Array.isArray(typeDef.statuses)) continue;
+    if (typeof typeDef.statuses !== 'object') continue;
+
+    hasRich = true;
+    // Claim the key even when no status is quiet: an empty list means "this type
+    // declared its statuses and suppresses nothing", which must not fall back to
+    // the global union. Absent entirely means "type never declared rich statuses".
+    derived.skipWarningsForByType[typeName] ??= [];
+    derived.terminalStatusesByType[typeName] ??= [];
+    const statusNames = [];
+    const typeContext = { expanded: [], listed: [], counted: [] };
+    const typeStaleDays = {};
+
+    for (const [name, props] of Object.entries(typeDef.statuses)) {
+      const p = props ?? {};
+      statusNames.push(name);
+
+      const ctx = p.context ?? 'counted';
+      if (typeContext[ctx]) typeContext[ctx].push(name);
+      // Global context: only add if not already in any bucket (first type wins)
+      const inGlobal = derived.context.expanded.includes(name) ||
+        derived.context.listed.includes(name) || derived.context.counted.includes(name);
+      if (!inGlobal && derived.context[ctx]) derived.context[ctx].push(name);
+
+      if (p.staleDays != null) {
+        typeStaleDays[name] = p.staleDays;
+        derived.staleDays[name] = p.staleDays;
+      }
+
+      // `quiet: true` is sugar for skipStale + skipWarnings unless those are explicitly false.
+      const quietImpliesSkipStale = p.quiet && p.skipStale !== false;
+      const quietImpliesSkipWarnings = p.quiet && p.skipWarnings !== false;
+
+      // Contradiction diagnostics — emit at load so dead config doesn't fail silently.
+      const skipStaleEffective = p.skipStale === true || quietImpliesSkipStale;
+      const skipWarningsEffective = p.skipWarnings === true || quietImpliesSkipWarnings;
+      if (skipStaleEffective && p.staleDays != null) {
+        warn(`runlist config: status "${typeName}.${name}" has skipStale: true and staleDays: ${p.staleDays} — staleDays is ignored. Drop one to silence this warning.`);
+      }
+      if (skipWarningsEffective && p.requiresModule) {
+        warn(`runlist config: status "${typeName}.${name}" has skipWarnings: true and requiresModule: true — the module requirement can never fire. Drop one to silence this warning.`);
+      }
+
+      if (p.archive && !derived.archiveStatuses.includes(name)) derived.archiveStatuses.push(name);
+      if (p.startable && !derived.startableStatuses.includes(name)) derived.startableStatuses.push(name);
+      if ((p.skipStale || quietImpliesSkipStale) && !derived.skipStaleFor.includes(name)) derived.skipStaleFor.push(name);
+      if (p.skipWarnings || quietImpliesSkipWarnings) {
+        if (!derived.skipWarningsFor.includes(name)) derived.skipWarningsFor.push(name);
+        (derived.skipWarningsForByType[typeName] ??= []).push(name);
+      }
+      if (p.terminal) {
+        if (!derived.terminalStatuses.includes(name)) derived.terminalStatuses.push(name);
+        derived.terminalStatusesByType[typeName].push(name);
+      }
+      if (p.requiresModule && !derived.moduleRequiredFor.includes(name)) derived.moduleRequiredFor.push(name);
+      if (p.filed && !derived.filedStatuses[name]) {
+        // dirName defaults to the status name; users can override with
+        // `filed: 'custom-dir'` (string form) instead of `filed: true`.
+        derived.filedStatuses[name] = typeof p.filed === 'string' ? p.filed : name;
+      }
+
+      if (!derived.statusOrder.includes(name)) derived.statusOrder.push(name);
+    }
+
+    // Convert to array form for downstream pipeline
+    typeDef.statuses = statusNames;
+
+    // Derive type-level context/staleDays unless user explicitly provided them
+    const userTypeDef = userConfig.types?.[typeName];
+    if (!userTypeDef?.context) typeDef.context = typeContext;
+    if (!userTypeDef?.staleDays) typeDef.staleDays = typeStaleDays;
+  }
+
+  if (!hasRich) return null;
+  return derived;
+}
+
+/**
+ * Apply derived values from rich status definitions into the merged config.
+ * Explicit user config always wins over derived values.
+ */
+function applyDerivedConfig(config, userConfig, derived) {
+  // statuses.order — derive from types if user didn't explicitly set
+  if (!userConfig.statuses?.order && derived.statusOrder.length) {
+    config.statuses.order = derived.statusOrder;
+  }
+
+  // statuses.staleDays — merge derived as base, user overrides
+  if (!userConfig.statuses?.staleDays && Object.keys(derived.staleDays).length) {
+    config.statuses.staleDays = derived.staleDays;
+  }
+
+  // lifecycle — each sub-key independently
+  if (!userConfig.lifecycle?.startableStatuses && derived.startableStatuses.length) {
+    config.lifecycle.startableStatuses = derived.startableStatuses;
+  }
+  if (!userConfig.lifecycle?.archiveStatuses && derived.archiveStatuses.length) {
+    config.lifecycle.archiveStatuses = derived.archiveStatuses;
+  }
+  if (!userConfig.lifecycle?.skipStaleFor && derived.skipStaleFor.length) {
+    config.lifecycle.skipStaleFor = derived.skipStaleFor;
+  }
+  // Assigned on BOTH branches, never conditionally: `config.lifecycle` can be the
+  // module-level DEFAULTS.lifecycle object itself (deepMerge shallow-copies, so a
+  // user config with no `lifecycle` key shares the reference), and a conditional
+  // write would leave a previous resolveConfig call's map in place.
+  if (!userConfig.lifecycle?.skipWarningsFor && derived.skipWarningsFor.length) {
+    config.lifecycle.skipWarningsFor = derived.skipWarningsFor;
+    config.lifecycle.skipWarningsForByType = derived.skipWarningsForByType;
+  } else {
+    // An explicit `lifecycle.skipWarningsFor` is a deliberate repo-wide statement
+    // and stays type-blind.
+    config.lifecycle.skipWarningsForByType = {};
+  }
+  if (!userConfig.lifecycle?.terminalStatuses && derived.terminalStatuses.length) {
+    config.lifecycle.terminalStatuses = derived.terminalStatuses;
+    config.lifecycle.terminalStatusesByType = derived.terminalStatusesByType;
+  } else {
+    // An explicit lifecycle list is intentionally repo-wide.
+    config.lifecycle.terminalStatusesByType = {};
+  }
+  if (!userConfig.lifecycle?.filedStatuses && Object.keys(derived.filedStatuses).length) {
+    config.lifecycle.filedStatuses = derived.filedStatuses;
+  }
+
+  // taxonomy.moduleRequiredFor
+  if (!userConfig.taxonomy?.moduleRequiredFor && derived.moduleRequiredFor.length) {
+    config.taxonomy.moduleRequiredFor = derived.moduleRequiredFor;
+  }
+
+  // context — only the status-related arrays, not recentDays/recentLimit/etc
+  if (!userConfig.context?.expanded) config.context.expanded = derived.context.expanded;
+  if (!userConfig.context?.listed) config.context.listed = derived.context.listed;
+  if (!userConfig.context?.counted) config.context.counted = derived.context.counted;
+}
+
+function findConfigFile(startDir) {
+  let dir = path.resolve(startDir);
+  const root = path.parse(dir).root;
+
+  while (dir !== root) {
+    for (const filename of CONFIG_FILENAMES) {
+      const candidate = path.join(dir, filename);
+      if (existsSync(candidate)) return candidate;
+    }
+    dir = path.dirname(dir);
+  }
+
+  return null;
+}
+
+const VALID_CONFIG_KEYS = new Set(Object.keys(DEFAULTS));
+
+function validateConfig(userConfig, config, validStatuses, indexPath) {
+  const warnings = validateStageDefinitions(config);
+  warnings.push(...validateFilingConfig(config.filing));
+  warnings.push(...validateYardstickConfig(config.yardstick));
+
+  // statuses.order must be array
+  if (config.statuses && config.statuses.order !== undefined && !Array.isArray(config.statuses.order)) {
+    warnings.push('Config: statuses.order must be an array.');
+  }
+
+  // archiveDir must be string
+  if (config.archiveDir !== undefined && typeof config.archiveDir !== 'string') {
+    warnings.push('Config: archiveDir must be a string.');
+  }
+
+  // Lifecycle status lists must reference configured statuses.
+  if (config.lifecycle?.startableStatuses) {
+    for (const s of config.lifecycle.startableStatuses) {
+      if (!validStatuses.has(s)) {
+        warnings.push(`Config: lifecycle.startableStatuses contains unknown status '${s}'.`);
+      }
+    }
+  }
+
+  // lifecycle.archiveStatuses values must exist in validStatuses
+  if (config.lifecycle?.archiveStatuses) {
+    for (const s of config.lifecycle.archiveStatuses) {
+      if (!validStatuses.has(s)) {
+        warnings.push(`Config: lifecycle.archiveStatuses contains unknown status '${s}'.`);
+      }
+    }
+  }
+
+  // staleDays keys must exist in validStatuses — but only validate the map when
+  // the user actually wrote `statuses.staleDays`. When it's inherited from
+  // defaults (user overrode `statuses.order` but left staleDays unset), the
+  // default map is keyed by default statuses (`ready`, `scoping`, …) that the
+  // user's order may not include — warning there blames the user for keys they
+  // never authored and makes brownfield repos noisy on every command, hook
+  // included. Real typos in a user-provided map are still caught.
+  if (userConfig.statuses?.staleDays && config.statuses?.staleDays) {
+    for (const key of Object.keys(config.statuses.staleDays)) {
+      if (!validStatuses.has(key)) {
+        warnings.push(`Config: statuses.staleDays contains unknown status '${key}'.`);
+      }
+    }
+  }
+
+  // taxonomy.surfaces must be null or array
+  if (config.taxonomy?.surfaces !== undefined && config.taxonomy.surfaces !== null && !Array.isArray(config.taxonomy.surfaces)) {
+    warnings.push('Config: taxonomy.surfaces must be null or an array.');
+  }
+
+  // index path file exists (if configured)
+  if (indexPath && !existsSync(indexPath)) {
+    warnings.push(`Config: index path does not exist: ${indexPath}`);
+  }
+
+  if (config.index?.snapshot !== undefined && !['status', 'state'].includes(config.index.snapshot)) {
+    warnings.push("Config: index.snapshot must be 'status' or 'state'.");
+  }
+
+  for (const key of ['codeRoots', 'codeRefsUntouched']) {
+    if (config[key] !== undefined && !Array.isArray(config[key])) {
+      warnings.push(`Config: ${key} must be an array.`);
+    }
+  }
+  for (const key of ['codeExtensions', 'codeExcludes']) {
+    if (config[key] != null && !Array.isArray(config[key])) {
+      warnings.push(`Config: ${key} must be an array.`);
+    }
+  }
+
+  if (userConfig.decisions != null) {
+    const d = userConfig.decisions;
+    if (typeof d !== 'object' || Array.isArray(d)) warnings.push('Config: decisions must be an object.');
+    else if (d.register != null && (typeof d.register?.file !== 'string' || typeof d.register?.statusLine !== 'string')) {
+      warnings.push('Config: decisions.register needs a file and a statusLine.');
+    }
+  }
+
+  // Unknown top-level user config keys
+  for (const key of Object.keys(userConfig)) {
+    if (!VALID_CONFIG_KEYS.has(key)) {
+      warnings.push(`Config: unknown key '${key}'.`);
+    }
+  }
+
+  return warnings;
+}
+
+function deepMerge(defaults, overrides, parentPath = '') {
+  const result = { ...defaults };
+  for (const [key, value] of Object.entries(overrides)) {
+    const keyPath = parentPath ? `${parentPath}.${key}` : key;
+    if (value != null && typeof value === 'object' && !Array.isArray(value) &&
+        result[key] != null && typeof result[key] === 'object' && !Array.isArray(result[key]) &&
+        !REPLACE_KEYS.has(keyPath)) {
+      result[key] = deepMerge(result[key], value, keyPath);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+export async function resolveConfig(cwd, explicitConfigPath) {
+  const configPath = explicitConfigPath
+    ? path.resolve(cwd, explicitConfigPath)
+    : findConfigFile(cwd);
+
+  let userConfig = {};
+  let hooks = {};
+  let configDir = cwd;
+
+  if (configPath && existsSync(configPath)) {
+    const configUrl = pathToFileURL(configPath).href;
+    let mod;
+    try {
+      mod = await import(configUrl);
+    } catch (err) {
+      die('Failed to load config: ' + configPath + '\n' + err.message + '\nCheck for syntax errors in your config file.');
+    }
+
+    configDir = path.dirname(configPath);
+
+    for (const [key, value] of Object.entries(mod)) {
+      if (key === 'default') continue;
+      if (typeof value === 'function') {
+        hooks[key] = value;
+      } else {
+        userConfig[key] = value;
+      }
+    }
+  }
+
+  // Backwards compat: `readme` config key maps to `index`
+  if (userConfig.readme && !userConfig.index) {
+    userConfig.index = userConfig.readme;
+    delete userConfig.readme;
+  }
+
+  const config = deepMerge(DEFAULTS, userConfig);
+  // Replacement links remain repairable even with custom reference-field lists
+  // or after the repository turns off goal display.
+  config.referenceFields.unidirectional = [...new Set([
+    ...(config.referenceFields.unidirectional ?? []), 'yardstick_into',
+  ])];
+
+  // Normalize rich status definitions (object form → array + derived config)
+  const derived = normalizeRichStatuses(config, userConfig);
+  if (derived) applyDerivedConfig(config, userConfig, derived);
+
+  const rootPaths = Array.isArray(config.root) ? config.root : [config.root];
+  const docsRoots = rootPaths.map(r => path.resolve(configDir, r));
+  const docsRoot = docsRoots[0]; // primary root for backwards compat
+
+  const earlyWarnings = [];
+  for (const dr of docsRoots) {
+    if (!existsSync(dr)) {
+      earlyWarnings.push('Config: docs root does not exist: ' + dr);
+    }
+  }
+
+  // Find repo root by walking up looking for .git
+  let repoRoot = configDir;
+  {
+    let dir = configDir;
+    const fsRoot = path.parse(dir).root;
+    while (dir !== fsRoot) {
+      if (existsSync(path.join(dir, '.git'))) {
+        repoRoot = dir;
+        break;
+      }
+      dir = path.dirname(dir);
+    }
+  }
+
+  // Resolve document types
+  const typesConfig = config.types ?? {};
+  const validTypes = new Set(Object.keys(typesConfig));
+  const typeStatuses = new Map();
+  const typeContextConfig = new Map();
+  for (const [typeName, typeDef] of Object.entries(typesConfig)) {
+    typeStatuses.set(typeName, new Set(typeDef.statuses ?? []));
+    if (typeDef.context) typeContextConfig.set(typeName, typeDef.context);
+  }
+
+  const statusOrder = config.statuses.order;
+  const validStatuses = new Set(statusOrder);
+  // Merge all type-specific statuses into the global valid set
+  for (const typeSet of typeStatuses.values()) {
+    for (const s of typeSet) validStatuses.add(s);
+  }
+  const staleDaysByStatus = {};
+  for (const status of statusOrder) {
+    staleDaysByStatus[status] = config.statuses.staleDays?.[status] ?? null;
+  }
+  // Merge type-specific staleDays
+  for (const typeDef of Object.values(typesConfig)) {
+    if (typeDef.staleDays) {
+      for (const [status, days] of Object.entries(typeDef.staleDays)) {
+        if (!(status in staleDaysByStatus)) staleDaysByStatus[status] = days;
+      }
+    }
+  }
+
+  // Per-root additional statuses (merged with global validStatuses)
+  const rootStatusesRaw = config.statuses.rootStatuses ?? {};
+  const rootLabels = new Set(rootPaths.map(r => path.relative(configDir, path.resolve(configDir, r)).split(path.sep).join('/')));
+  const rootValidStatuses = new Map();
+  for (const [rootKey, extraStatuses] of Object.entries(rootStatusesRaw)) {
+    const merged = new Set(validStatuses);
+    for (const s of extraStatuses) merged.add(s);
+    rootValidStatuses.set(rootKey, merged);
+  }
+
+  const validSurfaces = config.taxonomy.surfaces
+    ? new Set(config.taxonomy.surfaces)
+    : null;
+  const validModules = config.taxonomy.modules
+    ? new Set(config.taxonomy.modules)
+    : null;
+  const moduleRequiredStatuses = new Set(config.taxonomy.moduleRequiredFor);
+
+  const indexPath = config.index?.path
+    ? path.resolve(repoRoot, config.index.path)
+    : null;
+
+  // Compute docs root relative path for index link stripping
+  const docsRootRelative = path.relative(repoRoot, docsRoot).split(path.sep).join('/');
+  const docsRootPrefix = docsRootRelative ? docsRootRelative + '/' : '';
+
+  // Lifecycle config
+  const lifecycle = config.lifecycle;
+  const archiveStatuses = new Set(lifecycle.archiveStatuses);
+  const startableStatuses = new Set(lifecycle.startableStatuses ?? ['active', 'planned']);
+  const skipStaleFor = new Set(lifecycle.skipStaleFor);
+  const skipWarningsFor = new Set(lifecycle.skipWarningsFor);
+  const skipWarningsForByType = new Map(
+    Object.entries(lifecycle.skipWarningsForByType ?? {}).map(([type, names]) => [type, new Set(names)]),
+  );
+  // Does `status` suppress warning-only checks for a doc of this type? A type that
+  // declared rich statuses answers for itself — including answering "no" for a
+  // name some other type marked quiet. Everything else (no rich statuses, an
+  // explicit global `skipWarningsFor`, a doc with no type) reads the flat set.
+  const skipsWarnings = (status, type) => {
+    const own = type != null ? skipWarningsForByType.get(type) : undefined;
+    return own ? own.has(status) : skipWarningsFor.has(status);
+  };
+  const terminalStatuses = new Set(lifecycle.terminalStatuses);
+  const terminalStatusesByType = new Map(
+    Object.entries(lifecycle.terminalStatusesByType ?? {}).map(([type, names]) => [type, new Set(names)]),
+  );
+  const isTerminal = (status, type) => {
+    const own = type != null ? terminalStatusesByType.get(type) : undefined;
+    return own ? own.has(status) : terminalStatuses.has(status);
+  };
+  // F15: filedStatuses keyed by status name, value = directory name. Empty
+  // object when no status opts in via `filed: true` (or `filed: '<dirname>'`).
+  const filedStatuses = new Map(Object.entries(lifecycle.filedStatuses ?? {}));
+  // Types that archive into their own <typeDir>/<archiveDir> rather than the
+  // shared <root>/<archiveDir> (default: prompt).
+  const archiveNestedTypes = new Set(lifecycle.archiveNestedTypes ?? []);
+
+  // Warn if rootStatuses keys don't match any configured root
+  for (const rootKey of Object.keys(rootStatusesRaw)) {
+    if (!rootLabels.has(rootKey)) {
+      earlyWarnings.push(`Config: statuses.rootStatuses key '${rootKey}' does not match any configured root.`);
+    }
+  }
+
+  // A floor under the scan surface. Unset (the default) is off, so no existing
+  // repo changes behavior. See `applyScanFloor` in src/validate.mjs for why a
+  // silent zero-doc pass is the failure mode worth spending a config key on.
+  let minDocs = null;
+  if (config.minDocs !== undefined && config.minDocs !== null) {
+    if (!Number.isInteger(config.minDocs) || config.minDocs < 1) {
+      earlyWarnings.push(`Config: minDocs must be a positive integer; ignoring \`${config.minDocs}\`.`);
+    } else {
+      minDocs = config.minDocs;
+    }
+  }
+
+  const configWarnings = [...earlyWarnings, ...validateConfig(userConfig, config, validStatuses, indexPath)];
+
+  return {
+    raw: config,
+
+    docsRoot,
+    docsRoots,
+    repoRoot,
+    configDir,
+    configPath: configPath ?? null,
+    configFound: Boolean(configPath),
+    archiveDir: config.archiveDir,
+    excludeDirs: new Set(config.excludeDirs),
+    externalBodyLinkRoots: Array.isArray(config.externalBodyLinkRoots) ? config.externalBodyLinkRoots : [],
+    docsRootPrefix,
+    minDocs,
+
+    codeRefs: {
+      roots: Array.isArray(config.codeRoots) ? config.codeRoots : [],
+      extensions: Array.isArray(config.codeExtensions) ? config.codeExtensions : null,
+      excludes: Array.isArray(config.codeExcludes) ? config.codeExcludes : null,
+      untouched: Array.isArray(config.codeRefsUntouched) ? config.codeRefsUntouched : [],
+    },
+
+    statusOrder,
+    validStatuses,
+    validTypes,
+    typeStatuses,
+    typeContextConfig,
+    rootValidStatuses,
+    staleDaysByStatus,
+
+    lifecycle: { archiveStatuses, startableStatuses, skipStaleFor, skipWarningsFor, skipWarningsForByType, skipsWarnings, terminalStatuses, terminalStatusesByType, isTerminal, filedStatuses, archiveNestedTypes },
+
+    validSurfaces,
+    validModules,
+    moduleRequiredStatuses,
+
+    indexPath,
+    indexStartMarker: config.index?.startMarker ?? '<!-- GENERATED:runlist:start -->',
+    indexEndMarker: config.index?.endMarker ?? '<!-- GENERATED:runlist:end -->',
+    indexSnapshot: config.index?.snapshot ?? 'status',
+    archivedHighlightLimit: config.index?.archivedLimit ?? 8,
+
+    context: config.context,
+    display: config.display,
+    referenceFields: config.referenceFields,
+    filing: config.filing,
+    yardstick: config.yardstick,
+    presets: config.presets,
+    configuredPresetNames: new Set(Object.keys(userConfig.presets ?? {})),
+    journal: config.journal === true,
+    guard: {
+      deny: config.guard?.deny !== false,
+      promptReads: config.guard?.promptReads === 'deny' ? 'deny' : 'warn',
+    },
+    hooks,
+    configWarnings,
+  };
+}