@hone-ai/cli 1.4.0

package/lib/README.md

@@ -0,0 +1,119 @@
+# `cli/lib/` — Pure Helpers Convention
+
+> Last updated: 2026-05-04 (#119 helper-shape taxonomy)
+
+All helpers in `cli/lib/` are PURE (no I/O, no `process.exit`, no console
+output) and accept dependency-injection callbacks (`fileExists`, `readFile`,
+`listDir`) so they're unit-testable with stubs. The CLI shell in
+`cli/hone-cli.js` provides the actual filesystem callbacks.
+
+## Helper-shape taxonomy (#119)
+
+A code review (2026-05-04) flagged "inconsistent error shape across the 4
+editor-integrity helpers" as a minor concern. The honest read after audit:
+**different helper categories LEGITIMATELY use different shapes.** Forcing
+all into one shape would harm clarity. This document codifies the taxonomy.
+
+### Category A: Detection helpers
+**Return:** `string[]` (array of detected platforms / editors / etc.)
+**Examples:**
+- `cli/lib/platform-detect.js` → `string[]` of platform IDs
+- `cli/lib/editor-detect.js` → `string[]` of editor IDs
+
+**Why:** "Detect what's here" maps cleanly to a list. No findings/diagnostics
+needed at this layer; failures are just an empty array.
+
+### Category B: Validation helpers
+**Return:** `{ findings: Array<{severity, category, ...}>, summary: object }`
+**Examples:**
+- `cli/lib/skill-audit.js` → `{ findings, summary }`
+  (AU-001 / #159 — also exports `classifyPathCandidate(p, ctx)` →
+  `{ verdict, reason }` as a pure-helper sub-function. Verdicts:
+  `is_file_path`, `is_url`, `is_python_dotted`, `is_code_block`,
+  `is_inline_prose`, `unclassified`. Accepts `ignoreList: string[]`
+  for adopter-supplied allow-list at `.hone/audit-skills.ignore.yml`.)
+- `cli/lib/pipeline-validate.js` → `{ findings, summary }`
+- `cli/lib/adversarial-negative-lint.js` → `{ findings, summary }`
+- `cli/lib/skill-assertions.js` → `{ findings, scannedSkills, skipped, warnings }`
+- `cli/lib/story-classifier.js` → `{ track, architect, agents, artifacts, rationale, inputs_echo }`
+  (SC-001 / 2026-05-05 — `classifyStory(input, thresholds?)` recommends SDLC
+  track + architect engagement axes + per-step agent list per story. Pure
+  helper; pipeline-of-rules architecture per AU-001-L1. Sub-exports:
+  `TRACKS`, `ARCHITECT_AXES`, `DEFAULT_THRESHOLDS`. Validated against 41-story
+  corpus at .github/pipeline/SC-001/classifier-corpus.yml — 100% match
+  overall.)
+- `cli/lib/story-classifier-extract.js` — heuristic extractors (SC-002).
+  Pure helpers: `extractType(labels, body, title)`,
+  `extractSecurityImplications(labels, body)`,
+  `extractCrossRepoDependency(body)`,
+  `extractRecentlyModifiedOverlap(repoRoot, touchedFiles, windowDays)`.
+  Used by `hone classify-story` to infer 4 of the 9 classifyStory inputs
+  from a GitHub issue. Other 5 fields are user-supplied (judgment).
+- `cli/lib/publish-learning.js` — SC-005 publish framework-canonical
+  learning to `server/seeds/learnings/<ID>.yml` + flip source's
+  `status: pending → promoted` + stamp `promoted_at`. Eligibility:
+  `share_enterprise: true` AND `enterprise_candidate: true` (top-level
+  or per-learning). Idempotent (`already-promoted` on repeat); `--force`
+  re-publishes. Returns `{ status, copiedTo?, error? }`.
+- `cli/lib/pipeline-config.js` — adopter-overridable thresholds (SC-003).
+  `readStoryClassifierConfig(repoRoot)` returns
+  `{ estimate_full_sdlc?, recently_modified_window_days? }` from
+  `.pipeline-config.yml`'s `story_classifier:` block. Returns empty `{}`
+  on any failure. Safety-critical rules (R1/R2/R3) are NOT readable
+  from config — framework-fixed.
+  (SA-001 / #137 — `runAssertions()`. Carries scope diagnostics — `scannedSkills`,
+  `skipped` — alongside findings, since Step 5b reports per-skill coverage.
+  Severity values: `BLOCKER`, `WARN`, `INFO` — Step 5b's BLOCKER ≈ Category B's
+  `ERROR` semantically; named differently because gating happens in the CLI
+  shell, not the helper.)
+
+**Why:** Validation produces a heterogeneous list of issues at varying
+severities. The findings array + summary counts is the canonical shape.
+**Severity values:** `ERROR`, `WARN`, `INFO` (Category B canonical) — or
+domain-equivalent names where the deployment context calls for them.
+**Summary fields:** `error_count`, `warn_count`, `info_count`, plus
+domain-specific (`files_scanned`, `editors_validated`, etc.).
+
+### Category C: Transformation helpers
+**Return:** `{ <output>: <transformed_value>, applied: [], errors: [], <diagnostics>: ... }`
+**Examples:**
+- `cli/lib/overlay-merge.js` → `{ merged, applied, errors, conflicts }`
+- `cli/lib/config-update.js` → `{ updated_text, fields_changed }`
+
+**Why:** Transformation produces NEW content. The shape carries the
+content + per-input diagnostics + accumulated errors. Forcing this into
+the validation shape would lose the content output.
+
+### Category D: Verification helpers
+**Return:** `{ passed: boolean, results: Array<{found, ...}> }`
+**Examples:**
+- `cli/lib/synthetic-pipeline.js` `verifyMarkers()` → `{ passed, results }`
+
+**Why:** Verification answers a yes/no question with per-check evidence.
+The pass/fail is the headline result; the results array is for diagnostics.
+
+### Category E: Composition / resolution helpers
+**Return:** `{ <resolved_inputs>, <derived_view>, _error?: string }`
+**Examples:**
+- `cli/lib/rule-resolver.js` `resolveRules()` → `{ canonical, overlays, merged }`
+
+**Why:** Composition pulls from multiple sources and returns a unified view.
+The shape names each input layer + the derived output. Defensive `_error`
+field for callback failures.
+
+## Defensive conventions across all categories
+
+- **Missing required callback** → return early with `_error` field or empty
+  result. Never throw.
+- **Malformed input** → log via the appropriate diagnostic field
+  (errors / findings / _error). Never throw.
+- **Path traversal** → reject paths starting with `/`, `..`, or outside the
+  expected directory.
+- **Frozen tables** → deep-copy before returning if caller might mutate
+  (see RR-003-L1 learning).
+
+## When to add a new helper category
+
+If a new helper truly doesn't fit any of A-E, propose a new category here
+with rationale. Don't silently invent a 6th shape — that's the inconsistency
+this doc exists to prevent.

package/lib/adversarial-negative-lint.js

@@ -0,0 +1,149 @@
+'use strict';
+/**
+ * adversarial-negative-lint.js — HS-005 lint enforcing the META-Q2-L2 rule:
+ * "for every positive assertion, write at least one adversarial-negative test."
+ *
+ * Pure helper that takes test file content + path, parses test() declarations,
+ * categorizes by name (positive / negative), and flags files that lack any
+ * negative-asserting test if an allow-list comment is absent.
+ *
+ * Designed for node:test conventions (assert.equal/ok). Not a full AST parser
+ * — uses regex over `test('...')` declarations because that's what node:test
+ * uses and it's vastly lighter than @babel/parser.
+ *
+ * Allow-list mechanism: a comment matching
+ *   // hs005-allowlist: <reason>
+ * at the top of the file (within first 30 lines) exempts the file with the
+ * given justification.
+ *
+ * Initial release: warn-only mode. Returns findings; caller decides
+ * exit code. After 1-week soak + audit of existing tests, promote to
+ * required CI check.
+ *
+ * Closes architect plan #121 HS-005.
+ */
+
+// Negative-assertion keywords in test names. If a test() declaration's name
+// includes any of these, the test is considered to assert a NEGATIVE case.
+const NEGATIVE_KEYWORDS = [
+  'rejects',         // "REJECTS gameable input"
+  'fails',           // "fails when X"
+  'does not',        // "does not match"
+  'doesn\'t',        // "doesn't accept"
+  'must not',        // "must not pass"
+  'should not',      // "should not match"
+  'no match',        // "no match for X"
+  'no findings',     // "no findings when Y"
+  'invalid',         // "invalid input → error"
+  'malformed',       // "malformed YAML → []"
+  'missing',         // "missing fileExists callback"
+  'defensive',       // "defensive on missing X"
+  'bad input',       // "bad input → []"
+  'gameable',        // "gameable input"
+  'adversarial',     // "adversarial-negative"
+  'empty',           // "empty array → ..."
+];
+
+const ALLOWLIST_PATTERN = /\/\/\s*hs005-allowlist:\s*(.+?)$/im;
+
+/**
+ * Lint one test file.
+ *
+ * @param {string} filePath - relative path (for reporting)
+ * @param {string} content - file content
+ * @returns {{
+ *   filePath: string,
+ *   totalTests: number,
+ *   negativeTests: number,
+ *   positiveTests: number,
+ *   hasAllowlist: boolean,
+ *   allowlistReason?: string,
+ *   needsAdversarial: boolean,  // true if positive-only AND no allow-list
+ * }}
+ */
+function lintTestFile(filePath, content) {
+  if (typeof content !== 'string') {
+    return { filePath, totalTests: 0, negativeTests: 0, positiveTests: 0, hasAllowlist: false, needsAdversarial: false };
+  }
+
+  // Allow-list check (must be in top-of-file comment block, first ~30 lines)
+  const top = content.split('\n').slice(0, 30).join('\n');
+  const allowlistMatch = top.match(ALLOWLIST_PATTERN);
+  const hasAllowlist = !!allowlistMatch;
+  const allowlistReason = hasAllowlist ? allowlistMatch[1].trim() : undefined;
+
+  // Find all test() declarations: `test('name', ...)` or `test("name", ...)`
+  // Skip skipped/todo (test('name', { skip: ... } or test.skip)
+  const testRe = /(?:^|\n)\s*test(?:\.skip|\.only)?\s*\(\s*['"`]([^'"`]+)['"`]/gm;
+  let m;
+  let totalTests = 0;
+  let negativeTests = 0;
+  while ((m = testRe.exec(content)) !== null) {
+    totalTests++;
+    const name = m[1].toLowerCase();
+    if (NEGATIVE_KEYWORDS.some((kw) => name.includes(kw))) {
+      negativeTests++;
+    }
+  }
+  const positiveTests = totalTests - negativeTests;
+  const needsAdversarial = totalTests > 0 && negativeTests === 0 && !hasAllowlist;
+
+  return {
+    filePath,
+    totalTests,
+    negativeTests,
+    positiveTests,
+    hasAllowlist,
+    allowlistReason,
+    needsAdversarial,
+  };
+}
+
+/**
+ * Lint a set of test files.
+ *
+ * @param {Array<{filePath, content}>} files
+ * @returns {{ findings: Array, summary: object }}
+ */
+function lintTestFiles(files) {
+  if (!Array.isArray(files)) return { findings: [], summary: { files_scanned: 0 } };
+
+  const findings = [];
+  let totalFlagged = 0;
+  let totalScanned = 0;
+  let totalAllowlisted = 0;
+
+  for (const file of files) {
+    if (!file || typeof file.filePath !== 'string') continue;
+    totalScanned++;
+    const result = lintTestFile(file.filePath, file.content);
+    if (result.hasAllowlist) totalAllowlisted++;
+    if (result.needsAdversarial) {
+      totalFlagged++;
+      findings.push({
+        severity: 'WARN',  // warn-only initial release
+        category: 'MISSING_ADVERSARIAL_NEGATIVE',
+        file: result.filePath,
+        message: `${result.totalTests} test(s) all assert positive cases. Per HS-005 / META-Q2-L2: add ≥1 adversarial-negative test (REJECTS / does not / must fail / etc.) OR add allow-list comment "// hs005-allowlist: <reason>" within first 30 lines.`,
+        positiveTests: result.positiveTests,
+        negativeTests: result.negativeTests,
+      });
+    }
+  }
+
+  const summary = {
+    files_scanned: totalScanned,
+    files_flagged: totalFlagged,
+    files_allowlisted: totalAllowlisted,
+    files_compliant: totalScanned - totalFlagged - totalAllowlisted,
+  };
+
+  return { findings, summary };
+}
+
+module.exports = {
+  NEGATIVE_KEYWORDS,
+  ALLOWLIST_PATTERN,
+  lintTestFile,
+  lintTestFiles,
+};

package/lib/audit.js

@@ -0,0 +1,156 @@
+'use strict';
+/**
+ * audit.js — H-020 pure helpers for `hone audit`.
+ *
+ * Walks the in-memory representation of `.github/pipeline/<STORY>/` and
+ * scorecards each story against required + optional step artifacts.
+ *
+ * No I/O happens here — the CLI shell (hone-cli.js) is responsible for
+ * reading the directory tree and passing { storyId, files[] } objects in.
+ * That keeps everything synchronous, deterministic, and unit-testable
+ * without touching the filesystem.
+ */
+
+const DEFAULT_REQUIRED_STEPS = [
+  'step-0-grooming.md',
+  'step-1-plan.md',
+  'step-2-tests.md',
+  'step-4-implementation.md',
+  'step-5-review.md',
+];
+
+const DEFAULT_OPTIONAL_STEPS = [
+  'step-3-e2e-plan.md',
+];
+
+// Some adopters store artifacts as STEP2_TESTS.md / step_2_tests.md.
+// Normalize before comparing so we don't false-positive missing.
+function normalize(name) {
+  return String(name).toLowerCase().replace(/_/g, '-');
+}
+
+/**
+ * Score a single story.
+ *
+ * @param {object}   story
+ * @param {string}   story.storyId   e.g. "E20-A"
+ * @param {string[]} story.files     basename list of files in that story dir
+ * @param {object}   [opts]
+ * @param {string[]} [opts.requiredSteps]
+ * @param {string[]} [opts.optionalSteps]
+ * @returns {{ storyId, status, present, missing, optionalPresent, score }}
+ */
+function scoreStory(story, opts = {}) {
+  const required = opts.requiredSteps || DEFAULT_REQUIRED_STEPS;
+  const optional = opts.optionalSteps || DEFAULT_OPTIONAL_STEPS;
+  const have = new Set((story.files || []).map(normalize));
+
+  const present = required.filter((r) => have.has(normalize(r)));
+  const missing = required.filter((r) => !have.has(normalize(r)));
+  const optionalPresent = optional.filter((o) => have.has(normalize(o)));
+
+  let status;
+  if (present.length === 0 && missing.length === required.length && have.size === 0) {
+    status = 'EMPTY';
+  } else if (missing.length === 0) {
+    status = 'COMPLETE';
+  } else if (missing.length <= 1) {
+    status = 'NEAR_COMPLETE';
+  } else {
+    status = 'INCOMPLETE';
+  }
+
+  const score = `${present.length}/${required.length}`;
+
+  return {
+    storyId: story.storyId,
+    status,
+    present,
+    missing,
+    optionalPresent,
+    score,
+  };
+}
+
+/**
+ * Score every story in the pipeline.
+ *
+ * @param {Array<{storyId:string, files:string[]}>} stories
+ * @param {object} [opts]
+ * @returns {{ stories: object[], summary: { total, complete, nearComplete, incomplete, empty, percentComplete } }}
+ */
+function auditPipeline(stories, opts = {}) {
+  const filterStory = opts.story || null;
+  const filtered = filterStory
+    ? stories.filter((s) => s.storyId === filterStory)
+    : stories;
+
+  const scored = filtered.map((s) => scoreStory(s, opts));
+  const total = scored.length;
+  const complete = scored.filter((s) => s.status === 'COMPLETE').length;
+  const nearComplete = scored.filter((s) => s.status === 'NEAR_COMPLETE').length;
+  const incomplete = scored.filter((s) => s.status === 'INCOMPLETE').length;
+  const empty = scored.filter((s) => s.status === 'EMPTY').length;
+  const percentComplete = total === 0 ? 0 : Math.round((complete / total) * 100);
+
+  return {
+    stories: scored,
+    summary: { total, complete, nearComplete, incomplete, empty, percentComplete },
+  };
+}
+
+/**
+ * Render a human-readable table for terminal output.
+ */
+function renderTable(audit) {
+  const { stories, summary } = audit;
+  if (stories.length === 0) {
+    return 'No pipeline stories found under .github/pipeline/';
+  }
+
+  const lines = [];
+  lines.push('Scanning .github/pipeline/ ...');
+  lines.push('');
+  lines.push('Story        | Steps | Missing                              | Status');
+  lines.push('-------------|-------|--------------------------------------|----------------');
+  for (const s of stories) {
+    const id = s.storyId.padEnd(12);
+    const score = s.score.padEnd(5);
+    const missing = (s.missing.join(', ') || '').padEnd(36);
+    const tag = statusTag(s.status);
+    lines.push(`${id} | ${score} | ${missing} | ${tag}`);
+  }
+  lines.push('');
+  lines.push(
+    `Pipeline compliance: ${summary.complete}/${summary.total} (${summary.percentComplete}%)`
+  );
+  if (summary.nearComplete > 0) lines.push(`Near-complete:       ${summary.nearComplete}`);
+  if (summary.incomplete > 0) lines.push(`Incomplete:          ${summary.incomplete}`);
+  if (summary.empty > 0) lines.push(`Empty:               ${summary.empty}`);
+  return lines.join('\n');
+}
+
+function statusTag(status) {
+  switch (status) {
+    case 'COMPLETE':
+      return 'OK COMPLETE';
+    case 'NEAR_COMPLETE':
+      return '~ NEAR-COMPLETE';
+    case 'INCOMPLETE':
+      return 'X INCOMPLETE';
+    case 'EMPTY':
+      return 'X EMPTY';
+    default:
+      return status;
+  }
+}
+
+module.exports = {
+  scoreStory,
+  auditPipeline,
+  renderTable,
+  statusTag,
+  normalize,
+  DEFAULT_REQUIRED_STEPS,
+  DEFAULT_OPTIONAL_STEPS,
+};

package/lib/auto-detect.js

@@ -0,0 +1,213 @@
+'use strict';
+/**
+ * auto-detect.js — H-018 pure helpers for stack/convention detection.
+ *
+ * The CLI shell collects filesystem signals (file lists, branch names,
+ * pipeline dir names, package.json) and passes them in. We return
+ * recommended `story_id_pattern` and `e2e_spec_pattern` plus a
+ * confidence tag so the caller can decide whether to (a) write straight
+ * to .pipeline-config.yml, (b) print a "we detected X — confirm?"
+ * summary, or (c) fail loud if ambiguous.
+ *
+ * Why pure: detection is pattern-matching over inputs. Keeping all I/O
+ * in the CLI shell makes the rules unit-testable without temp dirs.
+ */
+
+// ── Story-ID detection ─────────────────────────────────────────────
+
+const HONE_SHAPE = /^E\d+-[A-Z]+/;     // E20-A, E22-H, E1-AB
+const JIRA_SHAPE = /^[A-Z]+-\d+/;      // ABC-123, OPS-42
+const WIDEST_PATTERN = 'E[0-9]+-[A-Z]+|[A-Z]+-[0-9]+';
+
+/**
+ * Look at observed story IDs (from branch names + .github/pipeline/ dir
+ * names) and decide which shape this repo uses.
+ *
+ * @param {string[]} samples — strings like ["feature/E20-A-add-foo", "ABC-123-fix"]
+ * @returns {{ pattern: string, shape: 'hone'|'jira'|'mixed'|'unknown', confidence: 'high'|'medium'|'low', samples: string[] }}
+ */
+function detectStoryIdShape(samples) {
+  const hits = { hone: 0, jira: 0 };
+  const matched = [];
+  for (const s of samples || []) {
+    // Strip common branch prefixes before matching.
+    const stripped = String(s).replace(/^(feature|fix|chore|feat|hotfix)\//, '');
+    if (HONE_SHAPE.test(stripped)) {
+      hits.hone++;
+      matched.push(stripped.match(HONE_SHAPE)[0]);
+    } else if (JIRA_SHAPE.test(stripped)) {
+      hits.jira++;
+      matched.push(stripped.match(JIRA_SHAPE)[0]);
+    }
+  }
+
+  const total = hits.hone + hits.jira;
+  if (total === 0) {
+    return { pattern: WIDEST_PATTERN, shape: 'unknown', confidence: 'low', samples: [] };
+  }
+
+  if (hits.hone > 0 && hits.jira === 0) {
+    return {
+      pattern: 'E[0-9]+-[A-Z]+',
+      shape: 'hone',
+      confidence: hits.hone >= 3 ? 'high' : 'medium',
+      samples: matched.slice(0, 5),
+    };
+  }
+  if (hits.jira > 0 && hits.hone === 0) {
+    return {
+      pattern: '[A-Z]+-[0-9]+',
+      shape: 'jira',
+      confidence: hits.jira >= 3 ? 'high' : 'medium',
+      samples: matched.slice(0, 5),
+    };
+  }
+  // Mixed → use the widest pattern that catches both.
+  return {
+    pattern: WIDEST_PATTERN,
+    shape: 'mixed',
+    confidence: 'medium',
+    samples: matched.slice(0, 5),
+  };
+}
+
+// ── E2E convention detection ───────────────────────────────────────
+
+/**
+ * Decide which E2E spec pattern fits this repo.
+ *
+ * Inputs are coarse-grained signals the CLI collects:
+ *   hasPyproject     — pyproject.toml exists
+ *   hasRequirements  — requirements.txt exists
+ *   hasPlaywrightDep — package.json mentions @playwright/test or playwright
+ *   testsDir         — true if tests/ exists (plural)
+ *   testDir          — true if test/ exists (singular)
+ *   sampleE2EFiles   — list of basenames found under tests?/e2e/ (or [])
+ *
+ * @returns {{ pattern: string, framework: 'pytest'|'playwright-ts'|'playwright-js'|'unknown'|'mixed', confidence, dir: 'tests'|'test'|'unknown' }}
+ */
+function detectE2EConvention(signals) {
+  const s = signals || {};
+  const isPython = !!(s.hasPyproject || s.hasRequirements);
+  const isPlaywright = !!s.hasPlaywrightDep;
+  const dir = s.testsDir ? 'tests' : s.testDir ? 'test' : 'unknown';
+
+  // Look at observed E2E filenames first — most reliable signal.
+  const observedPy = (s.sampleE2EFiles || []).some((f) => /^test_.*\.py$/i.test(f));
+  const observedTs = (s.sampleE2EFiles || []).some((f) => /\.spec\.ts$/i.test(f));
+  const observedJs = (s.sampleE2EFiles || []).some((f) =>
+    /\.spec\.js$/i.test(f) && !/\.spec\.ts$/i.test(f)
+  );
+
+  // Mixed = both python and TS/JS specs in the same E2E dir.
+  if (observedPy && (observedTs || observedJs)) {
+    return {
+      pattern: `${dir === 'unknown' ? 'tests?' : dir}/e2e/(test_.*\\.py|.*\\.spec\\.(ts|js))$`,
+      framework: 'mixed',
+      confidence: 'high',
+      dir,
+    };
+  }
+  if (observedPy) {
+    return {
+      pattern: `${dir === 'unknown' ? 'tests?' : dir}/e2e/test_.*\\.py$`,
+      framework: 'pytest',
+      confidence: 'high',
+      dir,
+    };
+  }
+  if (observedTs) {
+    return {
+      pattern: `${dir === 'unknown' ? 'tests?' : dir}/e2e/.*\\.spec\\.ts$`,
+      framework: 'playwright-ts',
+      confidence: 'high',
+      dir,
+    };
+  }
+  if (observedJs) {
+    return {
+      pattern: `${dir === 'unknown' ? 'tests?' : dir}/e2e/.*\\.spec\\.js$`,
+      framework: 'playwright-js',
+      confidence: 'high',
+      dir,
+    };
+  }
+
+  // No observed files — fall back to dependency / manifest signals.
+  if (isPython && !isPlaywright) {
+    return {
+      pattern: `${dir === 'unknown' ? 'tests?' : dir}/e2e/test_.*\\.py$`,
+      framework: 'pytest',
+      confidence: 'medium',
+      dir,
+    };
+  }
+  if (isPlaywright && !isPython) {
+    return {
+      pattern: `${dir === 'unknown' ? 'tests?' : dir}/e2e/.*\\.spec\\.(ts|js)$`,
+      framework: 'playwright-ts',
+      confidence: 'medium',
+      dir,
+    };
+  }
+  if (isPython && isPlaywright) {
+    return {
+      pattern: `tests?/e2e/(test_.*\\.py|.*\\.spec\\.(ts|js))$`,
+      framework: 'mixed',
+      confidence: 'medium',
+      dir,
+    };
+  }
+  // Nothing detected — widest possible pattern.
+  return {
+    pattern: `tests?/e2e/(test_.*\\.py|.*\\.spec\\.(ts|js))$`,
+    framework: 'unknown',
+    confidence: 'low',
+    dir,
+  };
+}
+
+// ── Drift checker (used by `hone doctor --check patterns`) ─────────
+
+/**
+ * Compare the patterns currently in .pipeline-config.yml against what
+ * we recommend. Returns either status:'ok' or status:'drift' with an
+ * actionable suggested fix.
+ */
+function checkPatternDrift({ configured, recommended }) {
+  const findings = [];
+  if (configured?.story_id_pattern && configured.story_id_pattern !== recommended.story.pattern) {
+    findings.push({
+      key: 'story_id_pattern',
+      configured: configured.story_id_pattern,
+      recommended: recommended.story.pattern,
+      reason: `repo looks like ${recommended.story.shape} (${recommended.story.confidence} confidence)`,
+    });
+  }
+  if (configured?.e2e_spec_pattern && configured.e2e_spec_pattern !== recommended.e2e.pattern) {
+    findings.push({
+      key: 'e2e_spec_pattern',
+      configured: configured.e2e_spec_pattern,
+      recommended: recommended.e2e.pattern,
+      reason: `detected ${recommended.e2e.framework} under ${recommended.e2e.dir}/e2e/ (${recommended.e2e.confidence} confidence)`,
+    });
+  }
+
+  if (findings.length === 0) {
+    return { status: 'ok', findings: [], reason: 'patterns match detected conventions' };
+  }
+  return {
+    status: 'drift',
+    findings,
+    reason: `${findings.length} pattern(s) drift from detected conventions`,
+    suggestedFix:
+      'Update .github/.pipeline-config.yml ci.* and the inlined regex in .github/workflows/ai-review.yml to the recommended values above.',
+  };
+}
+
+module.exports = {
+  detectStoryIdShape,
+  detectE2EConvention,
+  checkPatternDrift,
+  WIDEST_PATTERN,
+};