@hone-ai/cli 1.4.0

package/lib/pipeline-config.js

@@ -0,0 +1,83 @@
+'use strict';
+/**
+ * pipeline-config.js — SC-003 (Phase 3 of SC family).
+ * Pure helper to read adopter-overridable thresholds from
+ * `.pipeline-config.yml`'s `story_classifier:` block.
+ *
+ * Reads from (in order):
+ *   1. <repoRoot>/.pipeline-config.yml
+ *   2. <repoRoot>/.github/.pipeline-config.yml
+ *
+ * Failure modes (all degrade gracefully — return empty object):
+ *   - file missing
+ *   - file unreadable / unparseable YAML
+ *   - story_classifier block absent
+ *   - block has unknown keys (passed through; helper just extracts)
+ *
+ * The 9 inputs to classifyStory are NOT read from config — those come
+ * per-story from the issue or --input-file. This config holds only
+ * adopter-team-level THRESHOLD DEFAULTS (estimate, recently-modified
+ * window) that apply across all stories.
+ *
+ * Safety-critical rules (R1/R2/R3 in story-classifier.js) are
+ * NOT configurable — adopter cannot downgrade bug+high-blast away
+ * from hot-fix, security away from full-sdlc, or first-of-its-kind
+ * away from full-sdlc, regardless of what they put in this config.
+ *
+ * Issue: user-request 2026-05-05 SC-003. Builds on SC-001/SC-002.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const KNOWN_THRESHOLD_KEYS = ['estimate_full_sdlc', 'recently_modified_window_days'];
+
+/**
+ * Read story-classifier thresholds from .pipeline-config.yml.
+ *
+ * @param {string} repoRoot
+ * @returns {{ estimate_full_sdlc?: string, recently_modified_window_days?: number }}
+ *          Empty object if config is missing, malformed, or has no story_classifier block.
+ */
+function readStoryClassifierConfig(repoRoot) {
+  if (!repoRoot || typeof repoRoot !== 'string') return {};
+
+  const candidates = [
+    path.join(repoRoot, '.pipeline-config.yml'),
+    path.join(repoRoot, '.github/.pipeline-config.yml'),
+  ];
+
+  for (const p of candidates) {
+    if (!fs.existsSync(p)) continue;
+    let raw;
+    try { raw = fs.readFileSync(p, 'utf8'); }
+    catch { continue; }
+
+    let parsed;
+    try {
+      const yaml = require('js-yaml');
+      parsed = yaml.load(raw);
+    } catch {
+      // Malformed YAML — silently skip (not a fatal error)
+      continue;
+    }
+
+    if (!parsed || typeof parsed !== 'object') continue;
+    const block = parsed.story_classifier;
+    if (!block || typeof block !== 'object') continue;
+
+    // Pick out only the known threshold keys; ignore unknowns
+    const out = {};
+    for (const key of KNOWN_THRESHOLD_KEYS) {
+      if (block[key] !== undefined) out[key] = block[key];
+    }
+    return out;
+  }
+
+  return {};
+}
+
+module.exports = {
+  readStoryClassifierConfig,
+  KNOWN_THRESHOLD_KEYS,
+};

package/lib/pipeline-status.js

@@ -0,0 +1,207 @@
+'use strict';
+/**
+ * pipeline-status.js — H-009 pure helpers for the `hone status` and
+ * `hone next` CLI commands. No I/O — callers (hone-cli.js) do all
+ * filesystem reads and pass parsed inputs in. Keeps all rules
+ * unit-testable without temp dirs.
+ *
+ * Same shape as cli/lib/auto-detect.js (H-018) and cli/lib/learnings-parse.js
+ * (H-035) — pure helpers, all I/O at the CLI shell.
+ *
+ * Closes #18.
+ */
+
+const yaml = require('js-yaml');
+
+// ── Canonical step file naming convention (H-009/A2) ───────────────
+// Verified across .github/pipeline/H-001/, H-014/, H-029/, H-035/, H-076/.
+// step_3b is conditional (manual E2E mode only).
+// step_5b is conditional (SA-002 skill audit, present when story consults skills).
+// step_5c is conditional (H-076 CI gate, present after PR creation).
+//
+// SR-002 (#160): added step_5b + step_5c. Single STEPS table consolidates
+// the 4 prior parallel objects (file/display/agent maps + order array)
+// into one declaration so the "add a new step" affordance is a single edit.
+// Future steps go here without touching the helpers below.
+const STEPS = [
+  { key: 'step_0',  file: 'step-0-grooming.md',         display: 'Step 0 — Grooming',         agent: 'story-groomer',         conditional: false },
+  { key: 'step_1',  file: 'step-1-plan.md',             display: 'Step 1 — Plan',             agent: 'implementation-planner', conditional: false },
+  { key: 'step_2',  file: 'step-2-tests.md',            display: 'Step 2 — Unit Tests',       agent: 'unit-test-writer',      conditional: false },
+  { key: 'step_3a', file: 'step-3-e2e-plan.md',         display: 'Step 3a — E2E Plan',        agent: 'e2e-qa-planner',        conditional: false },
+  { key: 'step_3b', file: 'step-3b-spec.md',            display: 'Step 3b — E2E Spec',        agent: 'e2e-test-spec-writer',  conditional: true  },
+  { key: 'step_4',  file: 'step-4-implementation.md',   display: 'Step 4 — Implementation',   agent: 'code-builder',          conditional: false },
+  { key: 'step_5',  file: 'step-5-review.md',           display: 'Step 5 — Review',           agent: 'code-reviewer',         conditional: false },
+  { key: 'step_5b', file: 'step-5b-skill-audit.md',     display: 'Step 5b — Skill Audit',     agent: 'code-reviewer',         conditional: true  },
+  { key: 'step_5c', file: 'step-5c-ci.md',              display: 'Step 5c — CI Gate',         agent: 'code-reviewer',         conditional: true  },
+];
+
+// Derived maps preserved for back-compat — same shape, same exports.
+// Existing callers (cli/hone-cli.js + tests + downstream tooling) read
+// STEP_FILE_MAP / STEP_DISPLAY_NAME / STEP_AGENT / STEP_ORDER unchanged.
+const STEP_FILE_MAP    = Object.fromEntries(STEPS.map(s => [s.key, s.file]));
+const STEP_DISPLAY_NAME = Object.fromEntries(STEPS.map(s => [s.key, s.display]));
+const STEP_AGENT       = Object.fromEntries(STEPS.map(s => [s.key, s.agent]));
+const STEP_ORDER       = STEPS.map(s => s.key);
+const CONDITIONAL_STEPS = new Set(STEPS.filter(s => s.conditional).map(s => s.key));
+
+// SR-001 (#142): canonical STORY_ID_PATTERN — UNION of two adopter
+// conventions. The single-alternative form documented in H-005 silently
+// failed to match the second alternative's inputs (e.g., it claimed to
+// match "E13-A" but actually returned the wrong substring of any
+// branch like "feature/E34-A-...").
+//
+// Now matches:
+//   1. E[0-9]+-[A-Z]<rest>   — OptionsFlow's "E<num>-<letter>" convention
+//                              (E13-A, E34-A, E29-H, etc.)
+//   2. [A-Z]+[-_]<alphanum>  — Jira (ABC-123), Hone (H-009), LC-001,
+//                              SA-001, RP-001, underscore variants
+//                              (STORY_123)
+//
+// Alternation order matters: the E-prefix alternative is tried first
+// so digits-in-middle stories (E34-A) match correctly even when the
+// second alternative would also greedily-match a later substring
+// (A-resolve in "feature/E34-A-resolve-...").
+//
+// Substituted into ai-review.yml at install time via
+// server/scripts/setup-ai-pipeline.sh (which still ships the OLD
+// single-alt default for back-compat with existing .pipeline-config.yml
+// files; updating that default is a separate PR).
+//
+// Reused here for branch → STORY-ID extraction in:
+//   - `hone status` / `hone next` (existing)
+//   - `hone step-5b` (SA-002, this is what surfaced the bug — when run
+//     against OptionsFlow's feature/E34-A-* branches, story id was
+//     mis-extracted as "A-resolve")
+const STORY_ID_PATTERN = /(E[0-9]+-[A-Z][A-Za-z0-9]*|[A-Z]+[-_][A-Za-z0-9]+)/;
+
+// ─────────────────────────────────────────────────────────────────────
+// extractStoryIdFromBranch — pure regex on branch name
+// ─────────────────────────────────────────────────────────────────────
+function extractStoryIdFromBranch(branchName) {
+  if (!branchName || typeof branchName !== 'string') return null;
+  const m = branchName.match(STORY_ID_PATTERN);
+  return m ? m[0] : null;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// parseMetadata — YAML parse + shape validation, graceful catch on errors
+// ─────────────────────────────────────────────────────────────────────
+function parseMetadata(yamlText) {
+  let parsed;
+  try { parsed = yaml.load(yamlText); }
+  catch (e) { return { error: 'malformed', message: e.message }; }
+  if (!parsed || typeof parsed !== 'object') {
+    return { error: 'empty' };
+  }
+  return {
+    storyId: parsed.story_id || null,
+    title:   parsed.title    || null,
+    branch:  parsed.branch   || null,
+    base:    parsed.base     || null,
+    steps:   parsed.steps    || {},
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// getStepIcon — 5-state icon for one step
+// ─────────────────────────────────────────────────────────────────────
+//   '⏭️' if status is skipped (HC-007: intentional skip overrides file presence)
+//   '✓'  if metadata says completed/approved AND artifact exists
+//   '⏳' if status is in_progress|pending AND artifact exists
+//   '✗'  if status is failed AND artifact exists (SR-002: surface step_5c failures)
+//   '⬜' otherwise (filesystem wins on disagreement — AC-5)
+//
+// Filesystem-as-source-of-truth: even when metadata says completed, if
+// the underlying .md file is missing, return ⬜. Otherwise we'd lie to
+// the operator about pipeline state.
+//
+// SR-002 (#160): added 'approved' as a "done" status (used by step_5b /
+// step_5c for human-approved gates) and 'failed' as a distinct icon
+// (so a CI gate failure doesn't masquerade as in-progress).
+//
+// HC-007 (#163): added 'skipped' — boundary-below-threshold stories
+// legitimately skip step_3b; rendering ⬜ (gap) is a false alarm.
+// Skipped overrides file presence because the decision is recorded in
+// metadata, not in the filesystem.
+const DONE_STATUSES = new Set(['completed', 'approved']);
+const IN_PROGRESS_STATUSES = new Set(['in_progress', 'pending']);
+function getStepIcon(metadataStatus, artifactExists) {
+  if (metadataStatus === 'skipped') return '⏭️';
+  if (!artifactExists) return '⬜';
+  if (DONE_STATUSES.has(metadataStatus)) return '✓';
+  if (IN_PROGRESS_STATUSES.has(metadataStatus)) return '⏳';
+  if (metadataStatus === 'failed') return '✗';
+  return '⬜';
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// computeStepStates — combine parsed metadata with filesystem presence
+// ─────────────────────────────────────────────────────────────────────
+function computeStepStates(parsedMetadata, artifactPresence) {
+  const result = [];
+  const steps = parsedMetadata.steps || {};
+  for (const key of STEP_ORDER) {
+    const meta = steps[key] || {};
+    const fileExists = !!artifactPresence[key];
+    // SR-002 (#160): conditional steps (step_3b, step_5b, step_5c) skip
+    // when neither metadata nor file exists. Same convention as step_3b
+    // pre-SR-002 — generalized to all conditional steps now that we have
+    // 3 of them.
+    if (CONDITIONAL_STEPS.has(key) && !meta.status && !fileExists) continue;
+    const entry = {
+      key,
+      displayName:  STEP_DISPLAY_NAME[key],
+      agent:        STEP_AGENT[key],
+      icon:         getStepIcon(meta.status, fileExists),
+      status:       meta.status || 'not_started',
+      artifactPath: STEP_FILE_MAP[key],
+    };
+    // HC-007 (#163): surface skip reason so tracker/CLI can display it
+    if (meta.status === 'skipped' && meta.reason) {
+      entry.reason = meta.reason;
+    }
+    result.push(entry);
+  }
+  return result;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// findNextIncompleteStep — first step where icon !== '✓' and not skipped
+// HC-007: skipped steps are intentionally not done — don't report them as
+// "next incomplete" in `hone next`.
+// ─────────────────────────────────────────────────────────────────────
+function findNextIncompleteStep(stepStates) {
+  return stepStates.find(s => s.icon !== '✓' && s.icon !== '⏭️') || null;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// summarizeForAll — one-line summary for `hone status --all`
+// ─────────────────────────────────────────────────────────────────────
+function summarizeForAll(parsedMetadata, artifactPresence) {
+  const states = computeStepStates(parsedMetadata, artifactPresence);
+  const next = findNextIncompleteStep(states);
+  const summary = next
+    ? `${next.displayName} ${next.icon === '⏳' ? 'in progress' : 'not started'}`
+    : 'pipeline complete';
+  return {
+    storyId: parsedMetadata.storyId,
+    branch:  parsedMetadata.branch,
+    summary,
+  };
+}
+
+module.exports = {
+  // Constants (testable shape)
+  STEP_FILE_MAP,
+  STEP_DISPLAY_NAME,
+  STEP_AGENT,
+  STEP_ORDER,
+  STORY_ID_PATTERN,
+  // Pure helpers
+  extractStoryIdFromBranch,
+  parseMetadata,
+  getStepIcon,
+  computeStepStates,
+  findNextIncompleteStep,
+  summarizeForAll,
+};

package/lib/pipeline-validate.js

@@ -0,0 +1,322 @@
+'use strict';
+/**
+ * pipeline-validate.js — H-081 editor-aware pipeline validation.
+ *
+ * Performs the per-editor + cross-editor checks proposed in #81 component 3:
+ *   a. Discovery: agent files exist at the editor's expected paths
+ *   b. Step coverage: every pipeline step has an agent prompt or inline section
+ *   c. Rule presence: each canonical enforcement rule appears in editor surface
+ *   d. Format validity: per-editor format expectations met
+ *   e. Drift detection: every canonical rule appears in EVERY editor projection
+ *   f. Skill referenced: every skill is referenced by ≥1 agent prompt
+ *
+ * Pure helper with injected I/O. Returns findings + summary.
+ *
+ * ─── HS-003 Audit (PR-this) ────────────────────────────────────────────
+ * Use case distinction vs synthetic-pipeline.js:
+ *   - synthetic-pipeline.js asserts "did the agent APPLY the rule when
+ *     running this story?" → execution-level evidence; substring match
+ *     is gameable.
+ *   - pipeline-validate.js asserts "does the editor's PROMPT/scaffolding
+ *     teach the rule?" → adopter-scaffolding-level coverage check;
+ *     substring match is appropriate IF the rule is "topic is covered."
+ *
+ * Per-rule audit categorization (added in HS-003):
+ *   - 'step-5c-ci-gate' (a) — "is Step 5c covered in the prompt?"; mention is sufficient
+ *   - 'capture-learnings' (a) — "is the learnings substep documented?"; mention is sufficient
+ *   - 'no-bypass-no-verify' (c) — UPGRADED: rule is FORBID, not MENTION. Substring
+ *     match passed "you may use --no-verify in emergencies" (gameable). Now uses a
+ *     structural check verifying negative-context proximity (forbidden/never/MUST NOT).
+ *   - 'fast-track-protocol' (a) — "is the fast-track protocol explained?"; mention is sufficient
+ *
+ * Categories: (a) substring-acceptable-because-scaffolding; (b) prose-only-OK;
+ * (c) gameable-and-must-fix.
+ */
+
+const { EDITOR_PROJECTIONS } = require('./editor-detect');
+
+// Pipeline steps that should be covered by an agent prompt or inline section
+const PIPELINE_STEPS = ['story-groomer', 'implementation-planner', 'unit-test-writer',
+  'e2e-qa-planner', 'e2e-test-spec-writer', 'code-builder', 'code-reviewer'];
+
+// Canonical enforcement rules that should appear in EVERY editor's surface.
+// Two shapes supported:
+//   - string: case-insensitive regex/substring; rule is "topic is covered"
+//   - { positive: <regex>, forbidden: <regex> }: positive must appear AND
+//     it must NOT appear in a permissive context (e.g., "you may use X")
+const CANONICAL_RULES = Object.freeze({
+  'step-5c-ci-gate': 'Step 5c',                       // category (a): mention is sufficient
+  'capture-learnings': 'Capture Learnings',           // category (a)
+  'no-bypass-no-verify': {                            // category (c): UPGRADED for HS-003
+    // Must mention the flag AND in a forbidding context (NEVER, forbidden,
+    // MUST NOT, do not). Permissive phrasings ("you may use --no-verify")
+    // fail the rule.
+    positive: '--no-verify',
+    forbidden_context: '(may|allowed|sometimes|emergency|emergencies|except|escape hatch).{0,30}--no-verify|--no-verify.{0,30}(allowed|may be used|emergency|escape hatch)',
+    // Must mention --no-verify in a forbidding context:
+    required_context: '(NEVER|never|forbidden|MUST NOT|must not|do not|don\'t|prohibited|banned).{0,80}--no-verify|--no-verify.{0,80}(forbidden|never|prohibited|banned|MUST NOT|must not)',
+  },
+  'fast-track-protocol': 'fast.?track',               // category (a)
+});
+
+/**
+ * Validate the SDLC pipeline scaffolding for the given editors.
+ *
+ * @param {object} opts
+ * @param {string[]} opts.editors - detected editor keys
+ * @param {Map<string, string>} opts.surfaceContents - map: file path → content
+ * @param {(relativePath: string) => boolean} opts.fileExists
+ * @param {string[]} [opts.skillNames] - known skill names (for orphan check)
+ * @returns {{ findings: Array<{severity, category, editor?, rule?, message}>, summary }}
+ */
+function validatePipeline(opts = {}) {
+  const {
+    editors = [],
+    surfaceContents = new Map(),
+    fileExists,
+    skillNames = [],
+    // RR-002 + RR-004 (architect plan #117 stories 2 & 4): rule-baseline source.
+    //
+    // RR-002 default was 'canonical' (always) with warning when overlays
+    // detected. RR-004 promotes the default behavior:
+    //
+    //   - source explicitly set → use it (canonical or merged)
+    //   - source omitted + overlays present → default 'merged' (was: warn)
+    //   - source omitted + no overlays → default 'canonical' (unchanged)
+    //
+    // The promotion eliminates the OVERLAYS_PRESENT_BUT_CANONICAL_BASELINE
+    // warning by removing the underlying gap. Adopters who previously got
+    // the warning now get correct merged validation by default.
+    //
+    // Backward compat: adopters who passed source: 'canonical' explicitly
+    // are unaffected. Adopters who relied on the implicit canonical default
+    // when overlays exist (silent canonical mode) get behavior change —
+    // this is documented in CHANGELOG.md and was the architect's risk R1.
+    repoRoot,        // required when source = 'merged'
+    readFile,        // required when source = 'merged'
+    overlayPaths = [],  // optional list of overlay file paths
+  } = opts;
+  const sourceWasExplicit = ('source' in opts);
+  // Compute effective source AFTER destructuring (need fileExists to detect overlays)
+  let source = opts.source;
+  if (!sourceWasExplicit && typeof opts.fileExists === 'function') {
+    // RR-004 default-flip: implicit + overlays present → 'merged'
+    if (opts.fileExists('.hone-local/rule-overlays') || (opts.overlayPaths || []).length > 0) {
+      source = 'merged';
+    } else {
+      source = 'canonical';
+    }
+  }
+  if (source === undefined) source = 'canonical';
+  const findings = [];
+
+  // ─── RR-002: derive effective rule set ───
+  // CANONICAL_RULES is the framework's hardcoded list. When source = 'merged',
+  // each adopter overlay's rule_id is added as an additional substring rule
+  // (the rule_id should appear in the editor surface so the agent knows about
+  // adopter-specific enforcement).
+  let effectiveRules = { ...CANONICAL_RULES };
+  if (source === 'merged' && typeof fileExists === 'function' && typeof readFile === 'function') {
+    try {
+      const { resolveRules } = require('./rule-resolver');
+      const resolved = resolveRules({ repoRoot, fileExists, readFile, overlayPaths });
+      for (const overlay of resolved.overlays) {
+        // Adopter overlay rule_ids become additional checks. Use the rule_id
+        // string as the substring marker — adopters expecting custom enforcement
+        // should reference the rule_id in their editor projections.
+        if (!effectiveRules[overlay.ruleId]) {
+          effectiveRules[overlay.ruleId] = overlay.ruleId;
+        }
+      }
+    } catch { /* defensive — resolveRules failure → fall back to canonical */ }
+  }
+  // RR-004: removed OVERLAYS_PRESENT_BUT_CANONICAL_BASELINE warning since the
+  // default-flip above already routes implicit + overlays-present to 'merged'.
+  // Adopters who explicitly set source: 'canonical' with overlays present are
+  // making an informed choice and don't need a warning.
+
+  if (editors.length === 0) {
+    findings.push({
+      severity: 'WARN',
+      category: 'NO_EDITORS_DETECTED',
+      message: 'No editors detected — set HONE_EDITOR env var or add editor fingerprint files',
+    });
+  }
+
+  if (typeof fileExists !== 'function') {
+    return {
+      findings: [{ severity: 'ERROR', category: 'BAD_INPUT', message: 'fileExists callback missing' }],
+      summary: { error: 'missing fileExists' },
+    };
+  }
+
+  // ─── Per-editor: a. Discovery + d. Format ───
+  for (const editor of editors) {
+    const proj = EDITOR_PROJECTIONS[editor];
+    if (!proj) {
+      findings.push({
+        severity: 'WARN',
+        category: 'UNKNOWN_EDITOR',
+        editor,
+        message: `editor "${editor}" has no entry in EDITOR_PROJECTIONS table`,
+      });
+      continue;
+    }
+
+    // a. Discovery — project_doc exists?
+    if (proj.project_doc && !fileExists(proj.project_doc)) {
+      findings.push({
+        severity: 'ERROR',
+        category: 'DISCOVERY',
+        editor,
+        message: `${editor} expects project_doc "${proj.project_doc}" but it doesn't exist`,
+      });
+    }
+
+    // a. Discovery — agents_dir has at least one agent file?
+    if (proj.agents_dir && !fileExists(proj.agents_dir)) {
+      findings.push({
+        severity: 'ERROR',
+        category: 'DISCOVERY',
+        editor,
+        message: `${editor} expects agents_dir "${proj.agents_dir}" but it doesn't exist`,
+      });
+    }
+  }
+
+  // ─── Per-editor: c. Rule presence ───
+  // For each editor's project_doc surface, verify each canonical rule appears.
+  // HS-003: rule may be a string (substring/regex) OR an object
+  //   { positive, forbidden_context?, required_context? } for structural checks
+  //   (e.g., "no-bypass-no-verify" — must mention --no-verify in a forbidding
+  //   context; permissive phrasing fails the rule).
+  for (const editor of editors) {
+    const proj = EDITOR_PROJECTIONS[editor];
+    if (!proj || !proj.project_doc) continue;
+    const content = surfaceContents.get(proj.project_doc);
+    if (typeof content !== 'string') {
+      // #119 concern 3: don't silently skip when fileExists says yes but
+      // surfaceContents has nothing. That mismatch is a real gap (caller
+      // failed to read a file the validator was told existed).
+      if (fileExists(proj.project_doc)) {
+        findings.push({
+          severity: 'ERROR',
+          category: 'SURFACE_UNREADABLE',
+          editor,
+          message: `${editor} project_doc "${proj.project_doc}" exists per fileExists but no content provided in surfaceContents — caller should read this file before calling validatePipeline`,
+        });
+      }
+      continue;
+    }
+
+    for (const [ruleId, ruleSpec] of Object.entries(effectiveRules)) {
+      const passes = evaluateRule(ruleSpec, content);
+      if (!passes.matched) {
+        findings.push({
+          severity: 'WARN',
+          category: 'RULE_MISSING',
+          editor,
+          rule: ruleId,
+          message: passes.reason
+            ? `rule "${ruleId}" not satisfied in ${editor}'s project_doc (${proj.project_doc}): ${passes.reason}`
+            : `rule "${ruleId}" not found in ${editor}'s project_doc (${proj.project_doc})`,
+        });
+      }
+    }
+  }
+
+  // ─── Cross-editor: e. Drift detection ───
+  if (editors.length >= 2) {
+    // For each rule, count how many editors' surfaces have it
+    for (const [ruleId, ruleSpec] of Object.entries(effectiveRules)) {
+      const editorsWithRule = [];
+      const editorsWithoutRule = [];
+      for (const editor of editors) {
+        const proj = EDITOR_PROJECTIONS[editor];
+        if (!proj || !proj.project_doc) continue;
+        const content = surfaceContents.get(proj.project_doc);
+        if (typeof content !== 'string') continue;
+        if (evaluateRule(ruleSpec, content).matched) editorsWithRule.push(editor);
+        else editorsWithoutRule.push(editor);
+      }
+      // Drift: some editors have it, some don't
+      if (editorsWithRule.length > 0 && editorsWithoutRule.length > 0) {
+        findings.push({
+          severity: 'ERROR',
+          category: 'DRIFT',
+          rule: ruleId,
+          message: `rule "${ruleId}" present in [${editorsWithRule.join(',')}] but missing from [${editorsWithoutRule.join(',')}] — drift between editor projections`,
+        });
+      }
+    }
+  }
+
+  // ─── Cross-editor: f. Skill referenced ───
+  // For each skill, verify ≥1 surface mentions it.
+  for (const skillName of skillNames) {
+    let mentioned = false;
+    for (const content of surfaceContents.values()) {
+      if (typeof content === 'string' && content.includes(skillName)) {
+        mentioned = true;
+        break;
+      }
+    }
+    if (!mentioned) {
+      findings.push({
+        severity: 'INFO',
+        category: 'ORPHAN_SKILL',
+        message: `skill "${skillName}" not referenced by any editor surface — possibly orphaned`,
+      });
+    }
+  }
+
+  const summary = {
+    editors_validated: editors.length,
+    surfaces_scanned: surfaceContents.size,
+    error_count: findings.filter((f) => f.severity === 'ERROR').length,
+    warn_count: findings.filter((f) => f.severity === 'WARN').length,
+    info_count: findings.filter((f) => f.severity === 'INFO').length,
+  };
+
+  return { findings, summary };
+}
+
+/**
+ * Evaluate one CANONICAL_RULES entry against a content string.
+ * (HS-003) Handles both shapes:
+ *   - string: case-insensitive regex/substring match
+ *   - object { positive, forbidden_context?, required_context? }: structural
+ *     check requiring positive AND (if specified) required context AND
+ *     no forbidden context.
+ *
+ * @param {string|object} ruleSpec
+ * @param {string} content
+ * @returns {{ matched: boolean, reason?: string }}
+ */
+function evaluateRule(ruleSpec, content) {
+  if (typeof ruleSpec === 'string') {
+    return { matched: new RegExp(ruleSpec, 'i').test(content) };
+  }
+  if (!ruleSpec || typeof ruleSpec !== 'object') {
+    return { matched: false, reason: 'invalid rule spec' };
+  }
+  // Structural rule
+  const { positive, forbidden_context, required_context } = ruleSpec;
+  if (positive && !new RegExp(positive, 'i').test(content)) {
+    return { matched: false, reason: 'positive marker missing' };
+  }
+  if (forbidden_context && new RegExp(forbidden_context, 'i').test(content)) {
+    return { matched: false, reason: 'rule appears in a permissive context (e.g., "may use" or "emergency"); rule is FORBID, not MENTION' };
+  }
+  if (required_context && !new RegExp(required_context, 'i').test(content)) {
+    return { matched: false, reason: 'rule mentioned but not in a forbidding context (NEVER, forbidden, MUST NOT, prohibited)' };
+  }
+  return { matched: true };
+}
+
+module.exports = {
+  evaluateRule,
+  PIPELINE_STEPS,
+  CANONICAL_RULES,
+  validatePipeline,
+};