@hone-ai/cli 1.18.0 → 1.19.0

package/lib/architect-config.js

@@ -0,0 +1,121 @@
+'use strict';
+/**
+ * architect-config.js — HC-019b: read per-story architect flags from
+ * `.github/EXECUTION_PLAN.yml` so the CLI can plumb them into
+ * `workflow_runs.config` on POST /orchestrate (and POST /orchestrate/batch).
+ *
+ * The architect prompt (HC-019a) instructs the LLM to emit, per story:
+ *
+ *   stories:
+ *     - id: <STORY-ID>
+ *       config:
+ *         architect_consulted: true|false
+ *         checklist_b_completed: true|false
+ *
+ * The orchestrator's `validateStepPreConditions`
+ * (server/src/services/workflow-dag.js:340) BLOCKS step_1 when
+ * `architect_consulted=true` but `checklist_b_completed=false` — so
+ * without this plumbing, the HC-019a flag never reaches the server and
+ * every architect-engaged story would deadlock at step_1.
+ *
+ * Pure helper — caller wraps fs.readFileSync + path resolution so the
+ * helper is unit-testable with stubs.
+ */
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { parseExecutionPlan } = require('./fast-track-ratify');
+
+/**
+ * Default flag values when the EXECUTION_PLAN.yml file is absent, the
+ * story id is not found in it, or the per-story `config:` block is
+ * absent. False/false matches the behavior an operator would get from
+ * a story that bypassed the architect — `validateStepPreConditions`
+ * only blocks when `architect_consulted=true`, so the safer default
+ * is "architect was not consulted" (lets the story flow through; the
+ * operator's classifier decision determines whether engagement is
+ * required, not this helper).
+ */
+const DEFAULTS = Object.freeze({
+  architect_consulted: false,
+  checklist_b_completed: false,
+});
+
+/**
+ * Read the per-story architect flags from `.github/EXECUTION_PLAN.yml`.
+ *
+ * @param {string} repoRoot — absolute path to the repo root
+ * @param {string} storyId  — the story id to look up
+ * @returns {{ architect_consulted: boolean, checklist_b_completed: boolean }}
+ */
+function readArchitectConfig(repoRoot, storyId) {
+  if (typeof repoRoot !== 'string' || !repoRoot) return { ...DEFAULTS };
+  if (typeof storyId  !== 'string' || !storyId)  return { ...DEFAULTS };
+
+  const planPath = path.join(repoRoot, '.github', 'EXECUTION_PLAN.yml');
+  let text;
+  try {
+    if (!fs.existsSync(planPath)) return { ...DEFAULTS };
+    text = fs.readFileSync(planPath, 'utf8');
+  } catch {
+    return { ...DEFAULTS };
+  }
+
+  return readArchitectConfigFromText(text, storyId);
+}
+
+/**
+ * Same as `readArchitectConfig` but takes the YAML text directly
+ * (so tests don't need to write to disk).
+ *
+ * The optional second-return value is a `diagnostic` string that surfaces
+ * silent-bypass conditions the operator should know about (code-review
+ * F2/F3 — without these, malformed plan files or missing story entries
+ * silently disable the architect contract for every affected story).
+ * Callers can log it via `console.warn(diagnostic)` or ignore it.
+ *
+ * Returns: { architect_consulted, checklist_b_completed, diagnostic? }
+ *   - diagnostic === undefined → clean read, flags reflect reality
+ *   - diagnostic === string    → defaults returned for the reason given
+ */
+function readArchitectConfigFromText(text, storyId) {
+  if (typeof storyId !== 'string' || !storyId) return { ...DEFAULTS };
+
+  // Empty text is a legitimate "no plan file" path (most repos before
+  // architect adoption). NOT a diagnostic — defaults are intended.
+  if (typeof text !== 'string' || text.length === 0) return { ...DEFAULTS };
+
+  const parsed = parseExecutionPlan(text);
+  if (!parsed || parsed.error) {
+    // Code-review F2: malformed YAML silently disabled the contract for
+    // every story. Now we surface a diagnostic so the CLI can warn.
+    return {
+      ...DEFAULTS,
+      diagnostic: `EXECUTION_PLAN.yml ${parsed?.error || 'parse error'}: ${parsed?.message || ''} — defaulting to {false, false} for all stories`,
+    };
+  }
+
+  const stories = Array.isArray(parsed.stories) ? parsed.stories : [];
+  const story = stories.find(s => s && s.id === storyId);
+  if (!story) {
+    // Code-review F3: story-not-in-plan was silent. If the operator added
+    // the story but forgot to add an entry to EXECUTION_PLAN.yml, the
+    // architect contract is silently bypassed. Surface as a diagnostic.
+    return {
+      ...DEFAULTS,
+      diagnostic: `story id '${storyId}' not found in EXECUTION_PLAN.yml — defaulting to {false, false}`,
+    };
+  }
+
+  const cfg = story.config || {};
+  return {
+    architect_consulted:  cfg.architect_consulted  === true,
+    checklist_b_completed: cfg.checklist_b_completed === true,
+  };
+}
+
+module.exports = {
+  DEFAULTS,
+  readArchitectConfig,
+  readArchitectConfigFromText,
+};

package/lib/ci-gate-chooser.js

@@ -0,0 +1,267 @@
+'use strict';
+/**
+ * HC-RC-004: interactive ci.gate chooser for `hone setup`.
+ *
+ * Closes the adopter discoverability gap left by HC-101-followup-2/3.
+ * Before this story:
+ *   - `hone setup` defaults to `github` (or auto-detects `local` when
+ *     a Makefile with `ci:` target already exists at the repo root)
+ *   - `hone setup-local-ci` flips to `local` — but only adopters who
+ *     read the docs know this command exists
+ *
+ * After: `hone setup` presents the 4-mode choice WITH cost trade-offs at
+ * setup time so adopters who care about GitHub Actions minutes (almost all
+ * of them) discover the local-CI option without having to know its name.
+ *
+ * Modes:
+ *   - github (default): GitHub Actions runs every gate, billed per minute
+ *   - local: `make ci` runs every gate locally, $0 CI cost, requires
+ *     HC-101 Makefile + compose stack (this helper scaffolds it on choice)
+ *   - mixed: local for fast feedback, github for final gate (defense in
+ *     depth, costs less than github-only)
+ *   - none: no CI verification — NOT recommended; setup-local-ci's
+ *     X-Hone-Recommendation nudge fires on every /orchestrate request
+ *
+ * Non-blocking guarantees:
+ *   - Non-TTY (CI / piped / Claude Code) skips the prompt entirely —
+ *     adopter CI scripts don't break
+ *   - HONE_SETUP_NONINTERACTIVE=1 forces auto-detect path (env-var escape
+ *     hatch for scripted setups)
+ *   - --ci-gate=<mode> CLI flag overrides the prompt entirely
+ *   - Any prompt failure (EOF, signal, error) falls back to auto-detect
+ *     so a flaky terminal never blocks setup
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const readline = require('node:readline');
+
+// Canonical mode names MUST match cli/lib/pipeline-config.js CI_GATE_MODES
+// — that module's normalizeCIGate() rejects anything else with a stderr
+// warning and silently downgrades to 'github'. HC-RC-004 pass-1 code
+// review CRIT-1: pre-fix this list said 'mixed' (a marketing-friendly
+// label) which downstream consumers (run-story, queue-stories, the
+// setup-ai-pipeline.sh CI_GATE allowlist) all reject. Adopters picking
+// option [3] silently got github-only mode. 'both' is the contract.
+// 'mixed' / 'hybrid' are accepted as input aliases via normalizeMode.
+const VALID_MODES = Object.freeze(['github', 'local', 'both', 'none']);
+
+const MODE_DESCRIPTIONS = Object.freeze({
+  github: 'GitHub Actions runs every gate. Billed per CI minute. (default)',
+  local:  'Run `make ci` locally. $0 CI cost. Scaffolds HC-101 Makefile + compose.',
+  both:   'Local for fast feedback, GitHub for the final gate. Defense in depth.',
+  none:   'NO CI verification. NOT recommended — gates are advisory only.',
+});
+
+/**
+ * Normalize a raw mode string (from --ci-gate flag, env var, or prompt
+ * answer). Returns one of VALID_MODES or null on unrecognized.
+ *
+ * @param {string|undefined|null} raw
+ * @returns {string|null}
+ */
+function normalizeMode(raw) {
+  if (raw === undefined || raw === null) return null;
+  const v = String(raw).toLowerCase().trim();
+  if (VALID_MODES.includes(v)) return v;
+  // Aliases the adopter might type — map to the canonical names that
+  // downstream consumers (pipeline-config.js CI_GATE_MODES, the bash
+  // setup script's allowlist) actually understand.
+  if (v === 'gh') return 'github';
+  if (v === 'off' || v === 'disabled' || v === 'no') return 'none';
+  if (v === 'mixed' || v === 'hybrid') return 'both';
+  return null;
+}
+
+/**
+ * Detect whether the auto-detect path should pick `local` (Makefile with
+ * `ci:` target already at repo root) or `github`.
+ *
+ * Mirrors the same check setup-ai-pipeline.sh's detected_ci_default logic
+ * does, but in JS so the CLI doesn't have to fork-and-grep. The
+ * `^ci:[\s$|^=]` shape rejects Make variable assignments (`ci:=`).
+ *
+ * @param {{repoRoot: string, readFileSync?: Function, existsSync?: Function}} opts
+ * @returns {string} 'local' | 'github'
+ */
+function detectAutoMode(opts = {}) {
+  const repoRoot = opts.repoRoot || process.cwd();
+  const exists = opts.existsSync || fs.existsSync;
+  const read = opts.readFileSync || fs.readFileSync;
+  const makefilePath = path.join(repoRoot, 'Makefile');
+  if (!exists(makefilePath)) return 'github';
+  try {
+    const content = read(makefilePath, 'utf8');
+    // Match a real `ci:` target — exclude Make variable assignments.
+    if (/^ci:(?:[ \t]|$|[^=])/m.test(content)) return 'local';
+  } catch { /* fall through to github */ }
+  return 'github';
+}
+
+/**
+ * Decide whether to skip the interactive prompt entirely.
+ *
+ * Returns true (skip prompt) when ANY of:
+ *   - --ci-gate flag was passed
+ *   - --non-interactive was passed
+ *   - HONE_SETUP_NONINTERACTIVE env var is truthy
+ *   - stdin is not a TTY (CI / piped / Claude Code)
+ *   - stdout is not a TTY (piped output — prompt would garble)
+ *
+ * @param {{flagMode?: string, nonInteractive?: boolean, env?: object, stdin?: any, stdout?: any}} opts
+ * @returns {boolean}
+ */
+function shouldSkipPrompt(opts = {}) {
+  const env = opts.env || process.env;
+  const stdin = opts.stdin || process.stdin;
+  const stdout = opts.stdout || process.stdout;
+  if (opts.flagMode && normalizeMode(opts.flagMode)) return true;
+  if (opts.nonInteractive) return true;
+  // HC-RC-004 pass-1 (LOW-1): tolerant truthy check so adopters who set
+  // HONE_SETUP_NONINTERACTIVE=yes / true / TRUE / 2 also get the
+  // documented escape hatch. Exact-string match silently fell through
+  // for every spelling but '1' and 'true'.
+  if (env.HONE_SETUP_NONINTERACTIVE && /^(1|true|yes|on)$/i.test(String(env.HONE_SETUP_NONINTERACTIVE))) return true;
+  if (stdin && stdin.isTTY === false) return true;
+  if (stdout && stdout.isTTY === false) return true;
+  // Defensive: missing isTTY at all (some test rigs) → treat as non-TTY
+  if (stdin && stdin.isTTY === undefined) return true;
+  return false;
+}
+
+/**
+ * Resolve the mode WITHOUT prompting. Used when shouldSkipPrompt() returns
+ * true. Priority:
+ *   1. --ci-gate flag (already validated)
+ *   2. HONE_CI_GATE env var (alias for adopter CI scripts)
+ *   3. Auto-detect from Makefile presence
+ *
+ * @param {{flagMode?: string, env?: object, repoRoot?: string, existsSync?: Function, readFileSync?: Function}} opts
+ * @returns {{mode: string, source: string}}
+ */
+function resolveNonInteractive(opts = {}) {
+  const env = opts.env || process.env;
+  const flagMode = normalizeMode(opts.flagMode);
+  if (flagMode) return { mode: flagMode, source: 'flag' };
+  const envMode = normalizeMode(env.HONE_CI_GATE);
+  if (envMode) return { mode: envMode, source: 'env' };
+  return { mode: detectAutoMode(opts), source: 'auto-detect' };
+}
+
+/**
+ * Render the prompt's banner. Pulled out so tests can pin the exact lines
+ * adopters see — accidental UX regressions (e.g. dropping the cost
+ * trade-off line that drives the choice) get caught at PR time.
+ *
+ * @returns {string[]} lines to print (caller does console.log per line)
+ */
+function renderPromptBanner() {
+  return [
+    '',
+    'HC-RC-004: How should CI run for this repo?',
+    '',
+    '  [1] github  — ' + MODE_DESCRIPTIONS.github,
+    '  [2] local   — ' + MODE_DESCRIPTIONS.local,
+    '  [3] both    — ' + MODE_DESCRIPTIONS.both,
+    '  [4] none    — ' + MODE_DESCRIPTIONS.none,
+    '',
+    'Default is `github`. Pick `local` if you want to save GitHub Actions minutes.',
+    '',
+  ];
+}
+
+/**
+ * Run the interactive prompt. Returns the chosen mode or null on EOF /
+ * signal / any error.
+ *
+ * @param {{stdin?: any, stdout?: any, write?: Function, banner?: Function}=} opts
+ * @returns {Promise<string|null>}
+ */
+async function runPrompt(opts = {}) {
+  const stdin = opts.stdin || process.stdin;
+  const stdout = opts.stdout || process.stdout;
+  const write = opts.write || ((line) => stdout.write(line + '\n'));
+  const banner = opts.banner || ((lines) => lines.forEach(l => stdout.write(l + '\n')));
+
+  banner(renderPromptBanner());
+
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  // HC-RC-004 pass-1 (HIGH-3): the readline question() callback persists
+  // after the timeout fires; a late keypress would resolve a dead Promise
+  // and emit a 'line' event into a closed rl. Wrap with a single-shot
+  // settle guard + remove the question's line listener in the timeout
+  // branch so the rl can be closed cleanly.
+  let settled = false;
+  let questionTimer = null;
+  try {
+    const answer = await new Promise((resolve) => {
+      const settle = (v) => {
+        if (settled) return;
+        settled = true;
+        if (questionTimer) clearTimeout(questionTimer);
+        resolve(v);
+      };
+      rl.question('Pick [1-4] or mode name (default: github): ', (a) => settle(a));
+      // Defensive: timeout the prompt after 60s so a hung terminal doesn't
+      // wedge setup forever. Adopters who need >60s should set --ci-gate
+      // or HONE_SETUP_NONINTERACTIVE.
+      questionTimer = setTimeout(() => {
+        // Drop the pending line listener so a late keypress can't fire
+        // into the closed interface.
+        rl.removeAllListeners('line');
+        settle(null);
+      }, 60_000);
+      questionTimer.unref?.();
+    });
+    if (answer === null) {
+      write('  ⚠ prompt timed out after 60s — falling back to auto-detect');
+      return null;
+    }
+    const trimmed = String(answer).trim();
+    if (trimmed.length === 0) return 'github';
+    // Numeric shortcut
+    const numeric = { '1': 'github', '2': 'local', '3': 'both', '4': 'none' };
+    if (numeric[trimmed]) return numeric[trimmed];
+    // Otherwise normalize as mode name
+    const norm = normalizeMode(trimmed);
+    if (norm) return norm;
+    write(`  ⚠ unknown answer "${trimmed}" — falling back to auto-detect`);
+    return null;
+  } catch (e) {
+    write(`  ⚠ prompt error (${e.message}) — falling back to auto-detect`);
+    return null;
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * Top-level entry point. Decides whether to prompt, resolves the mode,
+ * returns it plus the source so the caller can log how it was chosen.
+ *
+ * @param {{flagMode?: string, nonInteractive?: boolean, env?: object, repoRoot?: string, stdin?: any, stdout?: any}=} opts
+ * @returns {Promise<{mode: string, source: string}>}
+ */
+async function chooseCIGate(opts = {}) {
+  if (shouldSkipPrompt(opts)) {
+    return resolveNonInteractive(opts);
+  }
+  const answer = await runPrompt(opts);
+  if (answer === null) {
+    // Prompt failed / timed out / unknown answer — fall back to auto-detect.
+    return resolveNonInteractive(opts);
+  }
+  return { mode: answer, source: 'prompt' };
+}
+
+module.exports = {
+  chooseCIGate,
+  normalizeMode,
+  detectAutoMode,
+  shouldSkipPrompt,
+  resolveNonInteractive,
+  renderPromptBanner,
+  runPrompt,
+  VALID_MODES,
+  MODE_DESCRIPTIONS,
+};

package/lib/doctor-admin-merge.js

@@ -23,6 +23,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { execSync } = require('node:child_process');
+const { gitEnv } = require('./git-env');
 
 // HC-005-A: ambiguous pattern named explicitly so the ambiguity-guard
 // doesn't depend on array index ordering. Adding new patterns to
@@ -65,7 +66,7 @@ function checkAdminMerge(args) {
   let log;
   try {
     log = execSync(`git log -n ${lookback} --pretty=format:'%H%x09%s%x09%b%x1e'`, {
-      cwd: repoRoot,
+      cwd: repoRoot, env: gitEnv(),
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'pipe'],
     });
@@ -166,7 +167,7 @@ function checkAdminMerge(args) {
 function isShallowClone(repoRoot) {
   try {
     const out = execSync('git rev-parse --is-shallow-repository', {
-      cwd: repoRoot,
+      cwd: repoRoot, env: gitEnv(),
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'pipe'],
     }).trim();

package/lib/doctor-architecture.js

@@ -0,0 +1,213 @@
+'use strict';
+/**
+ * doctor-architecture.js — HC-020e architecture-staleness check.
+ *
+ * Surfaces stale architecture docs in `hone doctor`. Mirrors the
+ * doctor-skill-staleness shape: returns a `{name, status, reason,
+ * suggestedFix}` object the hone-cli renderer consumes.
+ *
+ * What it checks:
+ *   1. Look for `docs/sdlc/ARCHITECTURE.md` (the canonical living-
+ *      architecture summary file the CLI writes via `hone derive`).
+ *      Memory: hone-cli.js:1438 confirms this is the target path.
+ *   2. If file is missing → `skip` (adopter hasn't run derive yet).
+ *   3. Try to parse `<!-- Generated by derive-domain-skills on
+ *      YYYY-MM-DD -->` marker from the file body. This is the
+ *      authoritative signal: git checkout resets file mtimes to
+ *      checkout time, so mtime alone gives false-fresh results on
+ *      every CI build.
+ *   4. If marker absent → `skip` with a note that the prompt should
+ *      be emitting it (HC-020e's companion change updates the
+ *      prompt's Living Architecture Summary section to do so).
+ *   5. If marker present + parses → compare against threshold
+ *      (default 90 days, matching `refresh_interval_days`).
+ *      > threshold → `drift` with `Run hone derive --refresh` fix.
+ *      ≤ threshold → `ok`.
+ *
+ * Pure helper. No I/O outside `args.repoRoot`. Never throws.
+ *
+ * Why this ships in the same PR as the prompt change (defer-with-hooks
+ * pattern from HC-010d/e): pass-1 reviews on those stories established
+ * that "doctor check exists but its data source isn't emitted yet" is
+ * the same dead-data class as "schema with no runtime consumer." The
+ * companion prompt update closes the loop in the same PR.
+ */
+
+const fs   = require('node:fs');
+const path = require('node:path');
+
+const DEFAULT_AGE_THRESHOLD_DAYS = 90;
+const ARCHITECTURE_PATH = 'docs/sdlc/ARCHITECTURE.md';
+// Pass-2 review LOW: cap file read size so a runaway ARCHITECTURE.md
+// (or symlink to a huge log) can't OOM the doctor. 1MB matches the
+// `bundleDirectory` defaults used elsewhere in the CLI. Files above
+// the cap → skip with reason (no signal worse than wrong signal).
+const MAX_FILE_BYTES = 1024 * 1024;
+
+// Marker emitted by the derive prompt at the top of the Living
+// Architecture Summary section. Matches `<!-- Generated by
+// derive-domain-skills on 2026-06-07 -->` (or any 10-char ISO date).
+// Capturing group #1 is the date string. Whitespace inside the comment
+// delimiters is tolerated; the wording itself is exact-match.
+const GENERATED_MARKER_RE =
+  /<!--\s*Generated by derive-domain-skills on (\d{4}-\d{2}-\d{2})\s*-->/;
+
+// Anchored variant: matches the marker ONLY inside the Living
+// Architecture Summary section (so an example marker pasted elsewhere
+// in the file — e.g., inside a code fence or a docs reference — can't
+// pollute the parse). Pass-1 review MED #3 caught this.
+// Pass-2 review MED: the gap between the heading and the marker uses
+// a negative-lookahead loop `(?:(?!\n##\s)[\s\S])*?` instead of the
+// unbounded `[\s\S]*?`, so the inter-marker scan STOPS at the next
+// `## ` heading. Otherwise a stray marker in a LATER section (e.g.
+// "## Anti-Pattern Report" with a pasted example) would be falsely
+// attributed to the Living Architecture Summary section.
+const SECTION_ANCHORED_MARKER_RE =
+  /##\s+Living Architecture Summary(?:(?!\n##\s)[\s\S])*?<!--\s*Generated by derive-domain-skills on (\d{4}-\d{2}-\d{2})\s*-->/i;
+
+/**
+ * @param {object} args
+ * @param {string} args.repoRoot
+ * @param {number} [args.ageThresholdDays=90]
+ * @param {Date|number}   [args.now]    — injected for tests
+ * @returns {{ name: 'architecture',
+ *             status: 'ok'|'drift'|'skip',
+ *             reason: string,
+ *             suggestedFix?: string }}
+ */
+function checkArchitectureStaleness(args) {
+  const {
+    repoRoot,
+    ageThresholdDays = DEFAULT_AGE_THRESHOLD_DAYS,
+    now,
+  } = args || {};
+  const name = 'architecture';
+
+  if (!repoRoot || typeof repoRoot !== 'string') {
+    return { name, status: 'skip', reason: 'no repoRoot supplied' };
+  }
+  if (!Number.isFinite(ageThresholdDays) || ageThresholdDays <= 0) {
+    return { name, status: 'skip',
+             reason: `invalid ageThresholdDays: ${ageThresholdDays}` };
+  }
+
+  const archPath = path.join(repoRoot, ARCHITECTURE_PATH);
+  if (!fs.existsSync(archPath)) {
+    return {
+      name,
+      status: 'skip',
+      reason: `${ARCHITECTURE_PATH} not found (run \`hone derive\` to generate it)`,
+    };
+  }
+
+  // Pass-2 review LOW: cap file size before read. A runaway
+  // ARCHITECTURE.md (or a symlink target) bigger than the cap would
+  // both waste memory and indicate the file isn't what the helper
+  // expects — skip with a clear reason rather than load it.
+  try {
+    const st = fs.statSync(archPath);
+    if (st.size > MAX_FILE_BYTES) {
+      return {
+        name,
+        status: 'skip',
+        reason:
+          `${ARCHITECTURE_PATH} is ${st.size} bytes (> ${MAX_FILE_BYTES} cap); ` +
+          'refusing to load. Inspect the file or split it.',
+      };
+    }
+  } catch (e) {
+    return { name, status: 'skip',
+             reason: `failed to stat ${ARCHITECTURE_PATH}: ${e.message}` };
+  }
+
+  let content;
+  try {
+    content = fs.readFileSync(archPath, 'utf8');
+  } catch (e) {
+    return { name, status: 'skip',
+             reason: `failed to read ${ARCHITECTURE_PATH}: ${e.message}` };
+  }
+
+  // Prefer the section-anchored match — only counts a marker INSIDE
+  // the Living Architecture Summary section. Falls back to unanchored
+  // match for files that lack the section heading (legacy / pre-prompt
+  // ARCHITECTURE.md files) so existing adopter setups still get a
+  // staleness signal.
+  let m = content.match(SECTION_ANCHORED_MARKER_RE);
+  if (!m) m = content.match(GENERATED_MARKER_RE);
+  if (!m) {
+    // No marker — can't trust file mtime (git checkout resets it).
+    // Skip with action item.
+    return {
+      name,
+      status: 'skip',
+      reason:
+        `${ARCHITECTURE_PATH} has no \`<!-- Generated by derive-domain-skills on YYYY-MM-DD -->\` ` +
+        'marker; can\'t reliably measure staleness (git checkout resets file mtime). ' +
+        'Re-run `hone derive --refresh` so the new prompt instruction emits the marker (HC-020e).',
+    };
+  }
+
+  const dateStr = m[1];
+  const generatedAt = new Date(`${dateStr}T00:00:00Z`);
+  if (Number.isNaN(generatedAt.getTime())) {
+    return {
+      name,
+      status: 'skip',
+      reason: `invalid generated-on date: ${dateStr}`,
+    };
+  }
+
+  const nowMs = now instanceof Date ? now.getTime()
+              : typeof now === 'number' ? now
+              : Date.now();
+  const ageDays = Math.floor((nowMs - generatedAt.getTime()) / (1000 * 60 * 60 * 24));
+
+  // Pass-1 review LOW: if the LLM hallucinated a future date (model
+  // believes it's 2027), ageDays is negative and the staleness check
+  // silently reports "ok". Treat future dates as untrusted → skip with
+  // a clear reason so the operator notices the hallucination.
+  if (ageDays < 0) {
+    return {
+      name,
+      status: 'skip',
+      reason:
+        `${ARCHITECTURE_PATH} marker date ${dateStr} is in the future (now: ` +
+        `${new Date(nowMs).toISOString().slice(0, 10)}); treating as untrusted. ` +
+        'Re-run `hone derive` to regenerate with a correct date.',
+    };
+  }
+
+  if (ageDays > ageThresholdDays) {
+    return {
+      name,
+      // Pass-1 review HIGH #2: use 'warn' (matches doctor-skill-staleness
+      // precedent — same semantic of "regenerated artifact aged past
+      // threshold", same CI-pass-through exit code). The earlier
+      // 'drift' status would have silently flipped existing adopter CI
+      // builds red on first stale-arch detection.
+      status: 'warn',
+      reason:
+        `${ARCHITECTURE_PATH} is ${ageDays} days old ` +
+        `(generated ${dateStr}; threshold ${ageThresholdDays} days). ` +
+        'Architecture may have drifted from the canonical view.',
+      suggestedFix: 'Run `hone derive --refresh` to regenerate from the current codebase.',
+    };
+  }
+  return {
+    name,
+    status: 'ok',
+    reason:
+      `${ARCHITECTURE_PATH} is ${ageDays} days old ` +
+      `(generated ${dateStr}; threshold ${ageThresholdDays} days).`,
+  };
+}
+
+module.exports = {
+  checkArchitectureStaleness,
+  DEFAULT_AGE_THRESHOLD_DAYS,
+  ARCHITECTURE_PATH,
+  MAX_FILE_BYTES,
+  GENERATED_MARKER_RE,
+  SECTION_ANCHORED_MARKER_RE,
+};