@hone-ai/cli 1.4.0

package/lib/story-classifier.js

@@ -0,0 +1,282 @@
+'use strict';
+/**
+ * story-classifier.js — SC-001 (#user-request 2026-05-05): pure helper
+ * that recommends SDLC track + agent invocation per story.
+ *
+ * Inputs (9 fields per architect plan):
+ *   - type:                      bug | enhancement | feature | refactor | docs | chore | meta-epic
+ *   - adopter_blast_radius:      zero | low | medium | high | critical
+ *   - surface_area:              single-file | single-module | multi-module | cross-package | external-dep
+ *   - estimate:                  XS | S | M | L | XL
+ *   - design_options:            "1" | "2-3" | "many"
+ *   - recently_modified_overlap: bool
+ *   - cross_repo_dependency:     bool
+ *   - has_test_matrix:           simple | parametrized | exhaustive
+ *   - has_security_implications: bool
+ *   - is_first_of_its_kind:      bool
+ *
+ * Output:
+ *   { track, architect: { engage, axes }, agents, artifacts, rationale, inputs_echo }
+ *
+ * Pipeline-of-rules architecture (per AU-001-L1):
+ *   Pass 1: shouldEngageArchitect
+ *   Pass 2: determineTrack
+ *   Pass 3: recommendAgents
+ *
+ * Pure-helper-with-injected-IO style (Category B per cli/lib/README.md):
+ *   - No filesystem, no network, no process.exit
+ *   - All inputs explicit; no environment lookups
+ *   - Same shape as cli/lib/skill-audit.js, cli/lib/learnings-audit.js
+ *
+ * Issue: user-request 2026-05-05 (SC-001 family — Phase 1).
+ */
+
+// ─── Enums (frozen, exported for test-shape assertions) ───
+
+const TRACKS = Object.freeze({
+  HOT_FIX:    'hot-fix',
+  FULL_SDLC:  'full-sdlc',
+  FAST_TRACK: 'fast-track',
+});
+
+const ARCHITECT_AXES = Object.freeze({
+  CROSS_PACKAGE:           'cross-package',
+  MULTIPLE_DESIGN_OPTIONS: 'multiple-design-options',
+  META_OR_EPIC:            'meta-or-epic',
+  RECENTLY_MODIFIED:       'recently-modified-overlap',
+  FIRST_OF_ITS_KIND:       'first-of-its-kind',
+  EXTERNAL_COORDINATION:   'external-coordination',
+  CROSS_REPO_DEPENDENCY:   'cross-repo-dependency',
+  SECURITY_IMPLICATIONS:   'security-implications',
+});
+
+// Estimate ordering for threshold comparisons
+const ESTIMATE_ORDER = ['XS', 'S', 'M', 'L', 'XL'];
+function estimateGreaterOrEqual(a, b) {
+  const ai = ESTIMATE_ORDER.indexOf(String(a || '').toUpperCase());
+  const bi = ESTIMATE_ORDER.indexOf(String(b || '').toUpperCase());
+  if (ai < 0 || bi < 0) return false;
+  return ai >= bi;
+}
+
+// Default thresholds (some configurable via opts; SAFETY-CRITICAL ones not)
+const DEFAULT_THRESHOLDS = Object.freeze({
+  estimate_full_sdlc:           'L',  // configurable; team risk tolerance
+  recently_modified_window_days: 14,  // configurable
+});
+
+// ─── Pass 1: Architect engagement (any-of) ───
+
+function shouldEngageArchitect(input) {
+  const axes = [];
+  // Cross-package or external-dep surface → architect for sequencing
+  if (input.surface_area === 'cross-package' || input.surface_area === 'external-dep') {
+    axes.push(ARCHITECT_AXES.CROSS_PACKAGE);
+  }
+  // Multiple design options → architect for tradeoff analysis
+  if (input.design_options === 'many' || input.design_options === '2-3') {
+    axes.push(ARCHITECT_AXES.MULTIPLE_DESIGN_OPTIONS);
+  }
+  // Meta / epic → architect for decomposition
+  if (input.type === 'meta-epic') {
+    axes.push(ARCHITECT_AXES.META_OR_EPIC);
+  }
+  // Recently-modified file overlap → architect for gap analysis vs prior PR
+  if (input.recently_modified_overlap === true) {
+    axes.push(ARCHITECT_AXES.RECENTLY_MODIFIED);
+  }
+  // First-of-its-kind pattern → architect for novel-pattern review
+  if (input.is_first_of_its_kind === true) {
+    axes.push(ARCHITECT_AXES.FIRST_OF_ITS_KIND);
+  }
+  // Cross-repo dependency → architect for upstream coordination
+  if (input.cross_repo_dependency === true) {
+    axes.push(ARCHITECT_AXES.CROSS_REPO_DEPENDENCY);
+  }
+  // Security implications → architect for risk review
+  if (input.has_security_implications === true) {
+    axes.push(ARCHITECT_AXES.SECURITY_IMPLICATIONS);
+  }
+  return { engage: axes.length > 0, axes };
+}
+
+// ─── Pass 2: Track determination (priority order) ───
+
+function determineTrack(input, thresholds) {
+  const reasons = [];
+
+  // ── SAFETY-CRITICAL RULES (not configurable) ──
+
+  // R1: security implications → full-sdlc, never fast-track or hot-fix.
+  // HC-009: moved above the hot-fix rule. Security bugs need full-sdlc
+  // review even when blast radius + surface area would qualify for hot-fix.
+  if (input.has_security_implications === true) {
+    return {
+      track: TRACKS.FULL_SDLC,
+      reason: 'has_security_implications=true → full-sdlc (safety-critical, framework-fixed)',
+    };
+  }
+
+  // R2: bug + high-or-critical adopter blast + single surface → hot-fix path.
+  // Architect's "100% on hot-fix safety axis" target.
+  // HC-009: now checked AFTER R1 (security). A security bug always gets
+  // full-sdlc regardless of blast radius or surface area.
+  if (input.type === 'bug'
+      && (input.adopter_blast_radius === 'high' || input.adopter_blast_radius === 'critical')
+      && (input.surface_area === 'single-file' || input.surface_area === 'single-module')) {
+    return {
+      track: TRACKS.HOT_FIX,
+      reason: `bug + adopter_blast_radius=${input.adopter_blast_radius} + ${input.surface_area} → hot-fix path (safety-critical, framework-fixed)`,
+    };
+  }
+
+  // R3: first-of-its-kind → full-sdlc.
+  if (input.is_first_of_its_kind === true) {
+    return {
+      track: TRACKS.FULL_SDLC,
+      reason: 'is_first_of_its_kind=true → full-sdlc (architect engagement axis)',
+    };
+  }
+
+  // ── CONFIGURABLE RULES ──
+
+  // R4: large estimate → full-sdlc (configurable threshold)
+  const fullSdlcEstimate = thresholds.estimate_full_sdlc || DEFAULT_THRESHOLDS.estimate_full_sdlc;
+  if (estimateGreaterOrEqual(input.estimate, fullSdlcEstimate)) {
+    return {
+      track: TRACKS.FULL_SDLC,
+      reason: `estimate=${input.estimate} ≥ ${fullSdlcEstimate} → full-sdlc (configurable threshold)`,
+    };
+  }
+
+  // R5: recently-modified overlap → full-sdlc, BUT ONLY when the work
+  // has real blast radius. Tiny framework-tooling iterations
+  // (RP-002..005 style: XS, blast_radius=zero, no adopter impact) get
+  // multiple sequential PRs touching the same file but don't need full
+  // SDLC ceremony each time. Calibration finding from SC-001 corpus.
+  // Architect engagement still triggers (axes include "recently-modified");
+  // the team just doesn't need full step-0..5 artifacts for an XS iteration.
+  if (input.recently_modified_overlap === true
+      && input.adopter_blast_radius !== 'zero'
+      && input.estimate !== 'XS') {
+    return {
+      track: TRACKS.FULL_SDLC,
+      reason: 'recently_modified_overlap=true (with non-zero blast or non-XS estimate) → full-sdlc (parametrized regression coverage)',
+    };
+  }
+
+  // R6: exhaustive test matrix → full-sdlc
+  if (input.has_test_matrix === 'exhaustive') {
+    return {
+      track: TRACKS.FULL_SDLC,
+      reason: 'has_test_matrix=exhaustive → full-sdlc',
+    };
+  }
+
+  // R7: cross-package surface area + non-trivial → full-sdlc
+  if (input.surface_area === 'cross-package' && input.type !== 'chore') {
+    return {
+      track: TRACKS.FULL_SDLC,
+      reason: 'surface_area=cross-package + non-chore → full-sdlc',
+    };
+  }
+
+  // R8 (default): fast-track
+  return {
+    track: TRACKS.FAST_TRACK,
+    reason: 'no escalation rules matched → fast-track (default)',
+  };
+}
+
+// ─── Pass 3: Per-step agent + artifact recommendation ───
+
+function recommendAgents(input, track) {
+  const agents = [];
+  const artifacts = [];
+
+  // HC-013b: hot-fix is MINIMAL — speed is critical, skip grooming + plan.
+  if (track === TRACKS.HOT_FIX) {
+    agents.push('unit-test-writer', 'code-builder', 'code-reviewer');
+    artifacts.push('step-2-tests.md', 'step-4-implementation.md', 'step-5-review.md');
+    return { agents, artifacts };
+  }
+
+  // HC-013b: fast-track gets LIGHTWEIGHT grooming + plan (not skip them).
+  // Without a plan, the test-writer doesn't know WHAT to test. Without
+  // grooming, acceptance criteria are implicit. The cost of a lightweight
+  // plan (30 seconds) is far less than the cost of rework from skipping it.
+  //
+  // full-sdlc gets FULL grooming + plan (unchanged).
+  agents.push('story-groomer', 'implementation-planner', 'unit-test-writer');
+  artifacts.push('step-0-grooming.md', 'step-1-plan.md', 'step-2-tests.md');
+
+  // Skip E2E for CLI-internal / pure-helper / single-module surfaces.
+  // Add E2E for cross-package + non-doc/chore types.
+  const surface = input && input.surface_area;
+  const type = input && input.type;
+  if ((surface === 'multi-module' || surface === 'cross-package')
+      && type !== 'docs' && type !== 'chore') {
+    agents.push('e2e-qa-planner');
+    artifacts.push('step-3-e2e-plan.md');
+  }
+
+  agents.push('code-builder', 'code-reviewer');
+  artifacts.push('step-4-implementation.md', 'step-5-review.md');
+
+  return { agents, artifacts };
+}
+
+// ─── Public API ───
+
+/**
+ * Classify a story by SDLC track + architect engagement axes.
+ *
+ * @param {object} input - 9 classification fields (see file header)
+ * @param {object} [thresholds] - optional adopter overrides (estimate_full_sdlc,
+ *                                recently_modified_window_days). SAFETY-CRITICAL
+ *                                rules ignore overrides.
+ * @returns {{
+ *   track: string,
+ *   architect: { engage: boolean, axes: string[] },
+ *   agents: string[],
+ *   artifacts: string[],
+ *   rationale: string,
+ *   inputs_echo: object,
+ * }}
+ */
+function classifyStory(input, thresholds) {
+  // Defensive: handle null/undefined/non-object inputs
+  const safeInput = (input && typeof input === 'object') ? input : {};
+  const safeThresholds = (thresholds && typeof thresholds === 'object') ? thresholds : {};
+
+  const architect = shouldEngageArchitect(safeInput);
+  const trackResult = determineTrack(safeInput, safeThresholds);
+  const { agents, artifacts } = recommendAgents(safeInput, trackResult.track);
+
+  // Build rationale: combine track decision + architect axes
+  const rationaleParts = [trackResult.reason];
+  if (architect.engage) {
+    rationaleParts.push(`architect engagement axes: [${architect.axes.join(', ')}]`);
+  }
+  const rationale = rationaleParts.join(' | ');
+
+  return {
+    track: trackResult.track,
+    architect,
+    agents,
+    artifacts,
+    rationale,
+    inputs_echo: { ...safeInput },
+  };
+}
+
+module.exports = {
+  classifyStory,
+  shouldEngageArchitect,
+  determineTrack,
+  recommendAgents,
+  TRACKS,
+  ARCHITECT_AXES,
+  DEFAULT_THRESHOLDS,
+  estimateGreaterOrEqual,
+};

package/lib/sync-overwrite.js

@@ -0,0 +1,47 @@
+'use strict';
+/**
+ * sync-overwrite.js — H-024 pure helper for `hone sync`.
+ *
+ * Detects whether a local file has been edited away from the
+ * server-delivered version, so we can warn before overwriting and
+ * silently destroying local additions (the OPS-2 / E13-A case).
+ *
+ * Pure function — no I/O. The CLI shell handles fs reads + writes.
+ */
+
+/**
+ * @param {string} serverContent  — what `hone sync` is about to write
+ * @param {string|null} localContent  — current file contents, or null if file doesn't exist
+ * @returns {{ kind: 'new'|'identical'|'modified', hasLocalEdits: boolean }}
+ */
+function detectLocalEdits(serverContent, localContent) {
+  if (localContent === null || localContent === undefined) {
+    return { kind: 'new', hasLocalEdits: false };
+  }
+  if (normalize(serverContent) === normalize(localContent)) {
+    return { kind: 'identical', hasLocalEdits: false };
+  }
+  return { kind: 'modified', hasLocalEdits: true };
+}
+
+/**
+ * Normalize line endings + trailing whitespace so we don't false-positive
+ * on CRLF↔LF or editor-stripped trailing spaces. Keep it simple: this is
+ * a "should we warn" gate, not a content-equality contract.
+ */
+function normalize(s) {
+  return String(s).replace(/\r\n/g, '\n').replace(/[ \t]+$/gm, '').trimEnd();
+}
+
+/**
+ * Build a single-line warning the CLI prints when refusing to overwrite.
+ *
+ * @param {string} relPath  — relative path the user will recognize
+ * @returns {string}
+ */
+function formatSkipMessage(relPath) {
+  return `  ⚠ skipping ${relPath} — local edits not on server. ` +
+         `Use \`hone promote\` to upstream them, or pass \`--force\` to overwrite.`;
+}
+
+module.exports = { detectLocalEdits, formatSkipMessage, normalize };

package/lib/synthetic-pipeline.js

@@ -0,0 +1,299 @@
+'use strict';
+/**
+ * synthetic-pipeline.js — H-086 synthetic SDLC verification fixtures + verifier.
+ *
+ * The CI-grade harness for "did the editor actually APPLY rule X" verification.
+ * Pure helper: generates synthetic story fixtures with expected rule-applied
+ * markers, and verifies captured pipeline output against them.
+ *
+ * M scope:
+ *   - SYNTHETIC_FIXTURES — library of synthetic stories, each with known
+ *     properties + expected markers per pipeline step
+ *   - generateFixture(scenario) — produces { story, expectedMarkers }
+ *   - verifyMarkers({ capturedOutputs, expectedMarkers }) — asserts each
+ *     expected marker appears in the matching step's captured output
+ *
+ * L scope deferred:
+ *   - Per-editor runtime drivers (Claude CLI invocation, Copilot probe, etc.)
+ *   - CI workflow cron template
+ *   - Slack/issue notification on regression
+ *   - enterprise/SDLC_VERIFICATION.md doc
+ *
+ * Closes #86 (M scope).
+ */
+
+/**
+ * Library of synthetic story fixtures. Each fixture exercises a SPECIFIC
+ * rule that should fire when the story is run through the pipeline.
+ *
+ * Fixture shape:
+ *   {
+ *     name: string,
+ *     description: string,
+ *     story_metadata: object  // gets serialized into step-0 grooming
+ *     expected_markers: {
+ *       [step_name]: string[]  // patterns (case-insensitive substrings) that should appear in that step's output
+ *     }
+ *   }
+ */
+const SYNTHETIC_FIXTURES = Object.freeze({
+  'fix-with-regression-policy': {
+    name: 'fix-with-regression-policy',
+    description: 'Fix story with fix_for set — Step 5 must apply E24-A regression policy + capture learning',
+    story_metadata: {
+      story_id: 'SYN-001',
+      story_type: 'bug_fix',
+      fix_for: 'SYN-prior-001',
+      files_touched: ['src/handler.js', 'tests/regression/SYN-001.test.js'],
+    },
+    // HS-002: structural assertions (was: substring 'regression' / 'learnings')
+    // Empirically verified against real shipped step-5-review.md files:
+    //   - "regression: 7/7" / "5/5 pass" count pattern (proves TDD-Green)
+    //   - "1 enterprise-candidate (...)" bullet (proves Capture Learnings)
+    // Prose-only "we wrote regression tests" without count/structure → REJECTED.
+    expected_markers: {
+      'step-5-review': [
+        '(regression|tests?)\\b.*\\d+\\s*\\/\\s*\\d+|\\d+\\s*\\/\\s*\\d+.*(regression|tests?)\\b',
+        '\\b\\d+\\s+enterprise[-\\s]candidate',
+      ],
+      'step-1-plan': [
+        'tests/regression',  // explicit path, not just word "regression"
+      ],
+    },
+  },
+  'feature-touching-source': {
+    name: 'feature-touching-source',
+    description: 'Feature story touching source — Step 5 should not require regression test BUT must still capture learnings',
+    story_metadata: {
+      story_id: 'SYN-002',
+      story_type: 'feature_add',
+      files_touched: ['src/feature.js', 'tests/regression/SYN-002.test.js'],
+    },
+    // HS-002: structural assertion (was: substring 'learnings').
+    // Real convention: "N enterprise-candidate (X-LN: title)" bullet.
+    expected_markers: {
+      'step-5-review': [
+        '\\b\\d+\\s+enterprise[-\\s]candidate',
+      ],
+    },
+  },
+  'pure-config-change': {
+    name: 'pure-config-change',
+    description: 'Pure declarative metadata story — Step 3a should tag scenario as CONFIG (not BROWSER/API)',
+    story_metadata: {
+      story_id: 'SYN-003',
+      story_type: 'feature_add',
+      files_touched: ['force-app/main/default/profiles/Admin.profile-meta.xml'],
+    },
+    // HS-002: structural assertions (was: bare 'CONFIG' + 'sandbox|deploy').
+    // CONFIG must appear in a tagging context (table/list/category), not prose.
+    // Strategy must co-locate sandbox-or-metadata with deploy/smoke/round-trip.
+    expected_markers: {
+      'step-3-e2e-plan': [
+        '(tag|type|category|classify|scenario|test.type).{0,40}\\bCONFIG\\b|\\bCONFIG\\b.{0,40}(tag|type|category|test.type)',
+        '(sandbox|metadata\\s*API).{0,80}(deploy|smoke|round.?trip|verify)|(deploy|smoke).{0,80}(sandbox|metadata)',
+      ],
+    },
+  },
+  'agent-prompt-edit-needs-step-5c': {
+    name: 'agent-prompt-edit-needs-step-5c',
+    description: 'Story editing agent prompt — Step 5c CI Gate Verification must be invoked after PR creation',
+    story_metadata: {
+      story_id: 'SYN-004',
+      story_type: 'feature_add',
+      files_touched: ['scripts/seed-agent-prompts.js'],
+    },
+    // HS-004 RESOLUTION (chicken-and-egg fixed):
+    // Per the agent prompt at scripts/seed-agent-prompts.js:775, Step 5c
+    // writes its gate matrix to `.github/pipeline/<STORY-ID>/step-5c-ci.md`
+    // — a SEPARATE artifact, not step-5-review.md. The previous fixture
+    // (HS-001) asserted against the wrong file (step-5-review.md), which
+    // is why no shipped artifact ever satisfied it. Per architect plan #121,
+    // HS-004: convention establishment + backfill before re-asserting.
+    //
+    // Backfill: H-076's `.github/pipeline/H-076/step-5c-ci.md` was created
+    // (the story that introduced Step 5c per its own convention).
+    //
+    // Markers (all 3 required, structural):
+    //   1. `## Gate matrix` heading (anchored, line-start via /m flag) —
+    //      the canonical artifact section per the agent-prompt template
+    //   2. `gh pr checks` polling command must be referenced
+    //   3. Concrete gate result in either word order
+    expected_markers: {
+      'step-5c-ci': [
+        '^##\\s+Gate matrix',                                        // Canonical artifact heading (anchored via /m flag)
+        'gh pr checks',                                              // Polling command must be referenced
+        // Concrete gate result, accepting either word order:
+        //   "- gate: PASS" / "Regression suite | ✅ PASS" — gate-first
+        //   "- PASS gates" — result-first (artificial but valid)
+        '(PASS|FAIL)\\b.*\\b(gate|gates|check|checks)\\b|\\b(gate|gates|check|checks)\\b.*(PASS|FAIL)\\b',
+      ],
+    },
+  },
+  // SA-001 / #137 (architect plan, story 1/2): synthetic story whose implementation
+  // deliberately violates a skill assertion. Used by the Step 5b runtime
+  // harness regression once Story 2 wires the runner. Today: Story 1 ships
+  // the engine only; this fixture is the contract that Story 2 will satisfy.
+  //
+  // Assertion shape (versioned `version: 1`):
+  //   - id: NO-CONSOLE-LOG-IN-SRC
+  //     applies_to: "^src/"
+  //     forbid_added: "console\\.log"
+  //
+  // The story metadata's `referenced_skill` lets the runner scope which
+  // skill's assertions to evaluate (LC-001 cross-reference field).
+  'story-that-violates-skill': {
+    name: 'story-that-violates-skill',
+    description: 'Story that violates a referenced skill — Step 5b must emit a BLOCKER finding tied to the skill+assertion id',
+    story_metadata: {
+      story_id: 'SYN-005',
+      story_type: 'feature_add',
+      files_touched: ['src/handler.js'],
+      referenced_skill: 'error-handling',
+    },
+    // Markers (all 3 required, structural) — what Story 2's
+    // step-5b-skill-audit.md MUST contain when this fixture is run:
+    //   1. `## Skill audit` heading (the canonical artifact section)
+    //   2. The skill id that was scanned, paired with the assertion id
+    //   3. A concrete finding block with severity + matched file path
+    expected_markers: {
+      'step-5b-skill-audit': [
+        '^##\\s+Skill audit',                                        // Canonical artifact heading
+        '\\berror-handling\\b.*\\bNO-CONSOLE-LOG-IN-SRC\\b|\\bNO-CONSOLE-LOG-IN-SRC\\b.*\\berror-handling\\b',
+        '(BLOCKER|WARN|INFO)\\b.*\\bsrc/handler\\.js\\b',
+      ],
+    },
+  },
+});
+
+/**
+ * Generate a fixture for a named scenario. Returns the synthetic story +
+ * the expected-markers manifest the verifier will check.
+ *
+ * RR-003 (architect plan #117 story 3/4): when opts.includeOverlays is true
+ * and rule-resolver inputs are provided, adopter overlay rule_ids are added
+ * as additional markers in step-5-review (where the agent reports rules
+ * applied). Default behavior unchanged — backward compat for all existing
+ * callers.
+ *
+ * @param {string} scenarioName - key from SYNTHETIC_FIXTURES
+ * @param {object} [opts]
+ * @param {boolean} [opts.includeOverlays=false] - if true, add adopter overlay
+ *   rule_ids to the fixture's expected_markers (requires repoRoot + fileExists
+ *   + readFile + overlayPaths)
+ * @param {string} [opts.repoRoot]
+ * @param {(p:string)=>boolean} [opts.fileExists]
+ * @param {(p:string)=>string|null} [opts.readFile]
+ * @param {string[]} [opts.overlayPaths]
+ * @returns {{ story: object, expectedMarkers: object, description: string,
+ *   adopterRulesIncluded?: string[] } | null}
+ */
+function generateFixture(scenarioName, opts = {}) {
+  const fixture = SYNTHETIC_FIXTURES[scenarioName];
+  if (!fixture) return null;
+
+  // Deep-copy expected_markers so the caller can't mutate the frozen table
+  const expectedMarkers = {};
+  for (const [step, markers] of Object.entries(fixture.expected_markers)) {
+    expectedMarkers[step] = [...markers];
+  }
+
+  const result = {
+    story: { ...fixture.story_metadata },
+    expectedMarkers,
+    description: fixture.description,
+  };
+
+  // RR-003: extend with adopter overlay rule_ids if requested
+  if (opts.includeOverlays && typeof opts.fileExists === 'function' && typeof opts.readFile === 'function') {
+    try {
+      const { resolveRules } = require('./rule-resolver');
+      const resolved = resolveRules({
+        repoRoot: opts.repoRoot,
+        fileExists: opts.fileExists,
+        readFile: opts.readFile,
+        overlayPaths: Array.isArray(opts.overlayPaths) ? opts.overlayPaths : [],
+      });
+      const adopterRuleIds = resolved.overlays.map((o) => o.ruleId);
+      if (adopterRuleIds.length > 0) {
+        // Adopter rules should appear in step-5-review when the agent reports
+        // which rules it applied. Each rule_id becomes a substring marker.
+        const stepKey = 'step-5-review';
+        if (!expectedMarkers[stepKey]) expectedMarkers[stepKey] = [];
+        for (const ruleId of adopterRuleIds) {
+          // Don't duplicate if already present
+          if (!expectedMarkers[stepKey].includes(ruleId)) {
+            expectedMarkers[stepKey].push(ruleId);
+          }
+        }
+        result.adopterRulesIncluded = adopterRuleIds;
+      } else {
+        result.adopterRulesIncluded = [];
+      }
+    } catch {
+      // Defensive — resolveRules failure → silent fallback to canonical fixture
+      result.adopterRulesIncluded = [];
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Verify that captured outputs contain all expected markers.
+ *
+ * @param {object} opts
+ * @param {object} opts.capturedOutputs - map: step_name → captured text
+ * @param {object} opts.expectedMarkers - map: step_name → array of regex/substring patterns
+ * @returns {{ passed: boolean, results: Array<{step, marker, found, capturedSample}> }}
+ */
+function verifyMarkers(opts = {}) {
+  const { capturedOutputs = {}, expectedMarkers = {} } = opts;
+  const results = [];
+
+  for (const [step, markers] of Object.entries(expectedMarkers)) {
+    const captured = capturedOutputs[step];
+    if (typeof captured !== 'string') {
+      // No output captured for this step — every marker counts as not found
+      for (const marker of markers) {
+        results.push({
+          step,
+          marker,
+          found: false,
+          reason: `no captured output for step "${step}"`,
+        });
+      }
+      continue;
+    }
+    for (const marker of markers) {
+      // marker may be a regex string (with | alternation) or a literal substring.
+      // Flags: i = case-insensitive; m = ^/$ anchor to line-start/line-end (multiline).
+      // The /m flag is REQUIRED for markers like `^##\s+Step 5c` to match a heading
+      // that appears on a non-first line of a multiline file. Without /m, ^ anchors
+      // to string-start, which only matches if the heading starts at byte 0.
+      // Bug fix in PR following PR #120 (which forgot the /m flag).
+      let found;
+      try {
+        const re = new RegExp(marker, 'im');
+        found = re.test(captured);
+      } catch {
+        found = captured.toLowerCase().includes(marker.toLowerCase());
+      }
+      results.push({
+        step,
+        marker,
+        found,
+        capturedSample: found ? '(present)' : captured.slice(0, 100) + '...',
+      });
+    }
+  }
+
+  const passed = results.every((r) => r.found);
+  return { passed, results };
+}
+
+module.exports = {
+  SYNTHETIC_FIXTURES,
+  generateFixture,
+  verifyMarkers,
+};