@hone-ai/cli 1.4.0

package/lib/stack-detect.js

@@ -0,0 +1,170 @@
+'use strict';
+/**
+ * stack-detect.js — H-002a pure helpers for source-file counting and the
+ * Node-vs-Python rebalance tie-breaker invoked by `setup-ai-pipeline.sh`
+ * after greedy stack detection.
+ *
+ * The bash detection block in `server/scripts/setup-ai-pipeline.sh` is
+ * order-sensitive: when a repo has BOTH `package.json` AND a Python
+ * manifest (e.g. an OptionsFlow-style backend with a tiny `package.json`
+ * for husky / lint-staged tooling), `DETECTED_STACK` lands on `node`
+ * because the Node block runs first. That writes the wrong
+ * `stack.primary` and `stack.test_framework` to `.pipeline-config.yml`.
+ *
+ * This module provides the file-count tie-breaker. The bash function
+ * `rebalance_node_python` shells out to `node -e` to call
+ * `rebalanceNodePython({ root })` — so the counting logic has a single
+ * source of truth, is unit-testable, and is reusable by H-028
+ * (application_type detection) which wants the same primitives.
+ *
+ * Exports:
+ *   - LANG_EXTENSIONS  : map of language → array of extensions
+ *   - countSourceFiles : pure(ish) counter, walks dirs at bounded depth
+ *   - rebalanceNodePython : returns 'python' or 'node' based on counts
+ *
+ * Closes #11 (H-002 / H-002a). Stacked under by #54 (H-002b — install
+ * path + CLAUDE.md substitution). Reused by H-028 (#51).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// ─────────────────────────────────────────────────────────────────────
+// Public constants
+// ─────────────────────────────────────────────────────────────────────
+
+const LANG_EXTENSIONS = Object.freeze({
+  python:     ['.py'],
+  javascript: ['.js', '.jsx'],
+  typescript: ['.ts', '.tsx'],
+});
+
+// Directory names whose contents must NEVER be counted, even if a caller
+// passes them in `dirs`. These are build artifacts / vendored deps that
+// would skew the file-count rebalance toward whichever language they ship.
+const SKIP_DIR_NAMES = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  '.next',
+  '.nuxt',
+  'out',
+  'coverage',
+  '__pycache__',
+  '.venv',
+  'venv',
+  '.tox',
+  '.pytest_cache',
+  'target',           // Java/Rust build dir
+  '.gradle',
+]);
+
+// When the caller does NOT pass `dirs`, we walk the repo root once at
+// `maxDepth`. The skip-list (SKIP_DIR_NAMES + dotdirs) keeps us out of
+// node_modules, .git, dist, build, __pycache__, .venv, etc., which is the
+// only restriction that matters for the file-count rebalance.
+//
+// Walking root once (instead of `['src','app','lib','.']`) avoids the
+// double-counting bug — `src/main.py` would otherwise be counted twice:
+// once via the explicit `'src'` walker, and again via the `'.'` walker
+// recursing into `src/`.
+//
+// DEFAULT_DIRS is exported so callers (and H-028) can build on the same
+// canonical list when they want to explicitly restrict — but the default
+// branch in countSourceFiles() does NOT use it.
+const DEFAULT_DIRS = Object.freeze(['src', 'app', 'lib', '.']);
+const DEFAULT_MAX_DEPTH = 5;
+
+// ─────────────────────────────────────────────────────────────────────
+// countSourceFiles({ root, dirs?, maxDepth? })
+// Returns { python, javascript, typescript } counts.
+//   - default (no `dirs`): walk `root` once at maxDepth, skip-list aware
+//   - explicit `dirs`:    walk only the named sub-dirs (each at maxDepth)
+// ─────────────────────────────────────────────────────────────────────
+
+function countSourceFiles({ root, dirs, maxDepth = DEFAULT_MAX_DEPTH } = {}) {
+  if (!root || typeof root !== 'string') {
+    throw new TypeError('countSourceFiles: { root } must be a non-empty string');
+  }
+
+  const counts = { python: 0, javascript: 0, typescript: 0 };
+
+  // Build a flat reverse map: extension → language key so each filename
+  // costs exactly one O(1) lookup in the inner walker.
+  const extToLang = Object.create(null);
+  for (const [lang, exts] of Object.entries(LANG_EXTENSIONS)) {
+    for (const ext of exts) extToLang[ext] = lang;
+  }
+
+  if (Array.isArray(dirs)) {
+    // Explicit caller-restricted walk. Each named dir is walked
+    // independently — caller is responsible for not passing an
+    // overlapping list (e.g. ['.', 'src']).
+    for (const dir of dirs) {
+      const absDir = dir === '.' ? root : path.join(root, dir);
+      walk(absDir, 0, maxDepth, extToLang, counts);
+    }
+  } else {
+    // Default: single walk from root, skip-list filters out the dirs
+    // that would otherwise pollute counts.
+    walk(root, 0, maxDepth, extToLang, counts);
+  }
+
+  return counts;
+}
+
+// Walker — bounded-depth, skip-list aware, swallows EACCES/ENOENT so a
+// missing optional dir like `app/` on a `src/`-only repo isn't fatal.
+function walk(absDir, depth, maxDepth, extToLang, counts) {
+  if (depth > maxDepth) return;
+
+  let entries;
+  try {
+    entries = fs.readdirSync(absDir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT' || err.code === 'EACCES' || err.code === 'ENOTDIR') return;
+    throw err;
+  }
+
+  for (const ent of entries) {
+    const name = ent.name;
+    if (ent.isDirectory()) {
+      if (SKIP_DIR_NAMES.has(name)) continue;
+      if (name.startsWith('.') && name !== '.' && name !== '..') {
+        // Skip dotdirs by default (.github, .vscode, .idea, etc.) —
+        // these aren't application source.
+        continue;
+      }
+      walk(path.join(absDir, name), depth + 1, maxDepth, extToLang, counts);
+    } else if (ent.isFile()) {
+      const ext = path.extname(name);
+      const lang = extToLang[ext];
+      if (lang) counts[lang] += 1;
+    }
+    // Symlinks intentionally not followed — avoids cycles and fs traversal
+    // into vendored dirs that link back into node_modules.
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// rebalanceNodePython({ root })
+// Returns 'python' if .py files outnumber .js/.jsx/.ts/.tsx files.
+// Returns 'node' on tie or empty repo (preserves current default).
+// ─────────────────────────────────────────────────────────────────────
+
+function rebalanceNodePython({ root } = {}) {
+  const counts = countSourceFiles({ root });
+  const nodeCount = counts.javascript + counts.typescript;
+  const pythonCount = counts.python;
+  return pythonCount > nodeCount ? 'python' : 'node';
+}
+
+module.exports = {
+  LANG_EXTENSIONS,
+  SKIP_DIR_NAMES,
+  DEFAULT_DIRS,
+  DEFAULT_MAX_DEPTH,
+  countSourceFiles,
+  rebalanceNodePython,
+};

package/lib/stack-paths.js

@@ -0,0 +1,285 @@
+'use strict';
+/**
+ * stack-paths.js — Framework-agnostic path classifier (H-028).
+ *
+ * Replaces the Next.js-centric path heuristic in
+ * `scripts/seed-agent-prompts.js` (HONE-011) with a table covering 9
+ * frameworks: Next.js, Vue, Angular, Django, Flask, Rails, FastAPI,
+ * Express, and Salesforce LWC/Apex.
+ *
+ * The classifier returns one of:
+ *   - BROWSER  : files match only browser/UI paths
+ *   - API      : files match only server/API paths
+ *   - HYBRID   : both browser AND api signals present (mixed-stack —
+ *                preserves the HONE-011 contract for fullstack repos)
+ *   - UNKNOWN  : no recognized signal (or invalid/empty input)
+ *
+ * Pure helper. No side effects. Consumed by:
+ *   - agent prompts (E2E QA Planner) for scenario tagging
+ *   - future story: setup-ai-pipeline.sh stack.application_type derivation
+ *
+ * Issue: https://github.com/subbareddyvani/hone-server/issues/51
+ */
+
+// Patterns are anchored by file extension where overlapping paths between
+// frameworks would otherwise produce false positives. For example:
+//   - `app/views.py` is Django (a `.py` file at module root) — must NOT
+//     match Next.js's `app/` router or Rails's `app/views/`.
+//   - `app/views/users.py` is Flask (`.py` under `app/views/`) — must NOT
+//     match Rails's `app/views/` (Rails uses `.erb`/`.haml`).
+const STACK_PATH_TABLE = {
+  nextjs: {
+    // Next.js sources are .ts/.tsx/.js/.jsx/.css/.scss only — anchor by ext
+    browser: [
+      /^src\/pages\//,
+      /^src\/components\//,
+      /^app\/.*\.(tsx?|jsx?|css|scss)$/,
+      /^pages\/.*\.(tsx?|jsx?)$/,
+    ],
+    api: [/^server\//, /^src\/api\//, /^app\/api\/.*\.(tsx?|jsx?)$/, /^pages\/api\//],
+  },
+  vue: {
+    // .vue is the canonical disambiguator
+    browser: [/\.vue$/],
+    api: [],
+  },
+  angular: {
+    browser: [/\.component\.ts$/, /^src\/app\/components\//, /^src\/app\/pages\//],
+    api: [],
+  },
+  django: {
+    browser: [/templates\/.*\.html$/],
+    api: [/(^|\/)views\.py$/, /(^|\/)urls\.py$/, /(^|\/)api\.py$/],
+  },
+  flask: {
+    browser: [/app\/templates\/.*\.html$/],
+    api: [/^app\/(views|api|routes)\/.*\.py$/],
+  },
+  rails: {
+    // Rails views are .erb/.haml; controllers and routes are .rb
+    browser: [/^app\/views\/.*\.(erb|haml)$/, /^app\/javascript\//],
+    api: [/^app\/controllers\/.*\.rb$/, /^config\/routes\.rb$/],
+  },
+  fastapi: {
+    browser: [],
+    api: [/^app\/routers\/.*\.py$/, /^app\/api\/.*\.py$/, /(^|\/)main\.py$/],
+  },
+  express: {
+    browser: [],
+    api: [/^routes\/.*\.(j|t)s$/, /^controllers\/.*\.(j|t)s$/, /^api\/.*\.(j|t)s$/],
+  },
+  salesforce: {
+    browser: [/^force-app\/main\/default\/(lwc|aura)\//],
+    api: [/^force-app\/main\/default\/(classes|triggers)\//],
+    // Declarative metadata (SFDX) — XML files deployed via `sf project deploy`.
+    // CONFIG-only stories test via sandbox deploy + UI smoke + metadata API
+    // round-trip; do NOT generate Playwright/API specs.
+    config: [
+      /^force-app\/main\/default\/objects\//,
+      /^force-app\/main\/default\/(profiles|permissionsets|permissionsetgroups)\//,
+      /^force-app\/main\/default\/(flows|workflows)\//,
+      /^force-app\/main\/default\/(layouts|flexipages|compactLayouts)\//,
+      /^force-app\/main\/default\/(customMetadata|customSettings|globalValueSets)\//,
+      /^force-app\/main\/default\/(applications|tabs)\//,
+      /^force-app\/main\/default\/(email|reports|dashboards)\//,
+      /^force-app\/main\/default\/(sharingRules|approvalProcesses)\//,
+      /^force-app\/main\/default\/staticresources\//,
+    ],
+  },
+  // NetSuite SuiteScript (SDF projects). Scripts live under
+  // src/FileCabinet/SuiteScripts/<feature>/<ScriptType>/ but adopters use
+  // varied roots — patterns match the script-type directory anywhere in the
+  // path, and tolerate both "ClientScripts" and "Client Scripts" naming.
+  // Suitelets are classified as API even though they may render UI: the
+  // testable surface is HTTP-handler logic (same precedent as Salesforce Apex).
+  netsuite: {
+    browser: [
+      /\/(ClientScripts|Client Scripts|Portlets)\//,
+      /\.ssp$/,
+    ],
+    api: [
+      /\/(RESTlets|Suitelets|UserEventScripts|User Event Scripts|MapReduce|Map Reduce|ScheduledScripts|Scheduled Scripts|WorkflowActions|Workflow Actions|WorkflowActionScripts|MassUpdate|Mass Update)\//,
+    ],
+    // Declarative metadata (SDF) — XML files deployed via `suitecloud
+    // project:deploy`. Same CONFIG strategy as Salesforce.
+    config: [
+      /^src\/Objects\//,
+      /^src\/AccountConfiguration\//,
+      /^src\/Translations\//,
+    ],
+  },
+};
+
+// Paths that should never count toward classification (test fixtures, deps,
+// docs, VCS metadata). The classifier filters these out before scanning.
+const IGNORED_PATH_PATTERNS = [
+  /^tests?\//,
+  /^node_modules\//,
+  /^\.git\//,
+  /^docs\//,
+  /^dist\//,
+  /^build\//,
+];
+
+/**
+ * Coerce an array of patterns (mix of RegExp and strings) into RegExp[].
+ * Invalid string patterns are silently dropped — they neither crash nor
+ * spuriously match. This is the H-028d defensive behavior for adopter-
+ * supplied `extraConfigPaths`.
+ *
+ * @param {Array<RegExp|string>} patterns
+ * @returns {RegExp[]}
+ */
+function coerceToRegexArray(patterns) {
+  if (!Array.isArray(patterns)) return [];
+  const out = [];
+  for (const p of patterns) {
+    if (p instanceof RegExp) {
+      out.push(p);
+    } else if (typeof p === 'string' && p.length > 0) {
+      try { out.push(new RegExp(p)); } catch { /* invalid regex — skip */ }
+    }
+  }
+  return out;
+}
+
+/**
+ * Classify a list of file paths into one of: BROWSER / API / HYBRID / CONFIG / UNKNOWN.
+ *
+ * Categories:
+ *   - BROWSER : client-side / UI code (test via Playwright UI specs)
+ *   - API     : server-side handlers (test via Playwright `request` /
+ *               pytest-httpx / node:test + fetch)
+ *   - HYBRID  : both code signals OR (any code signal + CONFIG metadata) —
+ *               needs mixed test strategy
+ *   - CONFIG  : declarative metadata only (Salesforce SFDX, NetSuite SDF,
+ *               or adopter-supplied via opts.extraConfigPaths). Test via
+ *               sandbox deploy + UI smoke + metadata API round-trip.
+ *               Do NOT generate Playwright/API specs.
+ *   - UNKNOWN : no recognized signal (or invalid/empty input)
+ *
+ * H-028d adds the optional `opts` argument with `extraConfigPaths` —
+ * lets adopters union custom regex/string patterns with the built-in
+ * config table (e.g., `^infra/`, `^helm/`, `^k8s/`). Default empty →
+ * backward-compatible with H-028c callers.
+ *
+ * @param {string[]} paths - file paths from a step-1-plan.md or git diff.
+ * @param {object} [opts]
+ * @param {Array<RegExp|string>} [opts.extraConfigPaths] - additional
+ *   patterns to count as CONFIG. Strings are coerced to RegExp; invalid
+ *   patterns are silently skipped.
+ * @returns {'BROWSER'|'API'|'HYBRID'|'CONFIG'|'UNKNOWN'}
+ */
+function classifyPathsForStack(paths, opts = {}) {
+  if (!Array.isArray(paths) || paths.length === 0) return 'UNKNOWN';
+
+  const extraConfigPatterns = coerceToRegexArray(opts && opts.extraConfigPaths);
+
+  let hasBrowser = false;
+  let hasApi = false;
+  let hasConfig = false;
+
+  for (const p of paths) {
+    if (typeof p !== 'string') continue;
+    if (IGNORED_PATH_PATTERNS.some((rx) => rx.test(p))) continue;
+
+    for (const fw of Object.values(STACK_PATH_TABLE)) {
+      if (!hasBrowser && fw.browser.some((rx) => rx.test(p))) hasBrowser = true;
+      if (!hasApi && fw.api.some((rx) => rx.test(p))) hasApi = true;
+      if (!hasConfig && (fw.config || []).some((rx) => rx.test(p))) hasConfig = true;
+    }
+    // Adopter-supplied extras unioned with built-ins
+    if (!hasConfig && extraConfigPatterns.some((rx) => rx.test(p))) hasConfig = true;
+
+    if (hasBrowser && hasApi && hasConfig) break; // all signals settled
+  }
+
+  // CONFIG mixed with any code signal → HYBRID (sandbox deploy + code test).
+  // Pure CONFIG → CONFIG (sandbox + UI smoke only).
+  if ((hasBrowser && hasApi) || (hasConfig && (hasBrowser || hasApi))) return 'HYBRID';
+  if (hasBrowser) return 'BROWSER';
+  if (hasApi) return 'API';
+  if (hasConfig) return 'CONFIG';
+  return 'UNKNOWN';
+}
+
+/**
+ * Parse adopter-supplied `platform.config_paths:` patterns from a
+ * `.pipeline-config.yml` text. Minimal regex-based scan — keeps the
+ * helper dep-free (no js-yaml). Adopters with esoteric YAML can fall
+ * back to calling `classifyPathsForStack(paths, { extraConfigPaths })`
+ * directly with their own loader.
+ *
+ * @param {string} yamlText
+ * @returns {string[]} pattern strings (NOT yet coerced to regex)
+ */
+function parsePlatformConfigPaths(yamlText) {
+  if (typeof yamlText !== 'string' || yamlText.length === 0) return [];
+  // Find the `platform:` block (top-level key, ignoring leading whitespace
+  // sensitivity by anchoring to start of line).
+  const blockMatch = yamlText.match(/^platform:\s*\n((?:[ \t]+.*\n?)*)/m);
+  if (!blockMatch) return [];
+  const block = blockMatch[1];
+  // Look for `config_paths:` then collect `- "..."` items at the same indent
+  const cpStart = block.search(/^\s*config_paths:\s*$/m);
+  if (cpStart < 0) return [];
+  const after = block.slice(cpStart);
+  const out = [];
+  // Match list items: `    - "pattern"` or `    - 'pattern'` or `    - pattern`
+  const re = /^\s*-\s*(?:"([^"]*)"|'([^']*)'|([^\s].*?))\s*$/gm;
+  let m;
+  while ((m = re.exec(after)) !== null) {
+    const v = m[1] || m[2] || m[3];
+    if (v) out.push(v.trim());
+  }
+  return out;
+}
+
+/**
+ * Higher-level classifier composing platform fingerprint detection +
+ * adopter-supplied `.pipeline-config.yml platform.config_paths` + the
+ * pure `classifyPathsForStack` core.
+ *
+ * Pure-helper-with-injected-I/O shape (same as compliance-check.js):
+ * caller wraps `fs.existsSync` and `fs.readFileSync` so the helper can
+ * be unit-tested with stubs.
+ *
+ * @param {object} [opts]
+ * @param {string[]} opts.paths - file paths to classify
+ * @param {string} opts.repoRoot - absolute path to repo root
+ * @param {(relativePath: string) => boolean} [opts.fileExists] - filesystem check
+ * @param {(relativePath: string) => string|null} [opts.readFile] - file reader
+ * @returns {{ category: string, detectedPlatforms: string[], configPathsUsed: string[] }}
+ */
+function classifyPathsForRepo(opts = {}) {
+  const { paths, repoRoot, fileExists, readFile } = opts;
+
+  // Platform fingerprint detection (H-028d helper)
+  let detectedPlatforms = [];
+  try {
+    const { detectPlatforms } = require('./platform-detect');
+    detectedPlatforms = detectPlatforms({ repoRoot, fileExists });
+  } catch { /* defensive — if the module is unavailable, treat as no platforms */ }
+
+  // Read adopter-supplied platform.config_paths from .pipeline-config.yml (best-effort)
+  let configPathsUsed = [];
+  try {
+    if (typeof readFile === 'function') {
+      const yamlText = readFile('.pipeline-config.yml');
+      if (typeof yamlText === 'string' && yamlText.length > 0) {
+        configPathsUsed = parsePlatformConfigPaths(yamlText);
+      }
+    }
+  } catch { /* defensive — bad YAML / missing file is a no-op */ }
+
+  const category = classifyPathsForStack(paths, { extraConfigPaths: configPathsUsed });
+  return { category, detectedPlatforms, configPathsUsed };
+}
+
+module.exports = {
+  STACK_PATH_TABLE,
+  IGNORED_PATH_PATTERNS,
+  classifyPathsForStack,
+  classifyPathsForRepo,
+  parsePlatformConfigPaths,
+};

package/lib/story-classifier-extract.js

@@ -0,0 +1,203 @@
+'use strict';
+/**
+ * story-classifier-extract.js — SC-002 (Phase 2 of SC family).
+ * Heuristic extractors that infer 4 of the 9 classifyStory() inputs from
+ * a GitHub issue's labels + body + title + the repo's git history.
+ *
+ * The other 5 inputs (adopter_blast_radius, surface_area, estimate,
+ * design_options, has_test_matrix, is_first_of_its_kind) are JUDGMENT
+ * fields that the CLI prompts for OR accepts via --input-file. They
+ * cannot reliably be heuristically extracted from text alone.
+ *
+ * Pure-helper-with-injected-IO style:
+ *   - Extractors take parsed inputs (labels array, body string, etc.)
+ *   - The git-log query is the one extractor that needs the repo path,
+ *     and shells out to git via execSync — same pattern as
+ *     cli/lib/git-helpers.js.
+ *
+ * Issue: user-request 2026-05-05 SC-002. Builds on SC-001's classifyStory().
+ */
+
+const { execSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+// ── Label-to-type canonical mapping ──
+// First-match-wins per label-array order.
+const LABEL_TO_TYPE = Object.freeze({
+  bug:                'bug',
+  enhancement:        'enhancement',
+  feature:            'feature',
+  refactor:           'refactor',
+  refactoring:        'refactor',
+  documentation:      'docs',
+  docs:               'docs',
+  chore:              'chore',
+  epic:               'meta-epic',
+  meta:               'meta-epic',
+  'meta-epic':        'meta-epic',
+});
+
+// Title-prefix patterns (case-insensitive) → type
+const TITLE_PREFIXES = [
+  { re: /^\s*\[(meta|epic|meta-epic)\]/i, type: 'meta-epic' },
+  { re: /^\s*(fix|bug):/i,                 type: 'bug' },
+  { re: /^\s*(feat|feature):/i,            type: 'feature' },
+  { re: /^\s*(docs|doc):/i,                type: 'docs' },
+  { re: /^\s*(chore):/i,                   type: 'chore' },
+  { re: /^\s*(refactor):/i,                type: 'refactor' },
+];
+
+// Body keywords → type (tested word-boundary)
+const BODY_TYPE_KEYWORDS = [
+  { re: /\bregression\b/i,                  type: 'bug' },
+  { re: /\bproduction failure\b/i,          type: 'bug' },
+  { re: /\bbroken in\b/i,                   type: 'bug' },
+  { re: /\bbroke (the|a|something)\b/i,     type: 'bug' },
+];
+
+// Security keywords (case-insensitive, word-boundary)
+const SECURITY_KEYWORDS = [
+  /\bauth\b/i,
+  /\btoken\b/i,
+  /\bcredential[s]?\b/i,
+  /\bsecret[s]?\b/i,
+  /\bCVE-\d{4}-\d+\b/i,
+  /\bXSS\b/i,
+  /\bCSRF\b/i,
+  /\binjection\b/i,
+  /\bsanitize\b/i,
+  /\bencrypt\b/i,
+  /\bdecrypt\b/i,
+  /\bpassword[s]?\b/i,
+  /\bOAuth\b/i,
+  /\bJWT\b/i,
+];
+
+// Cross-repo phrases (signal that something OUTSIDE this repo is a dependency)
+const CROSS_REPO_PHRASES = [
+  /\bblocked\s+by\b/i,
+  /\bblocked-by\b/i,
+  /\bdepends\s+on\b/i,
+  /\bdepends-on\b/i,
+  /\bupstream\b/i,
+  /\brequires\s+#/i,
+  /\bafter\s+#/i,
+];
+
+// Cross-repo URL/ref patterns
+const CROSS_REPO_REF = /\b([\w.-]+\/[\w.-]+)#\d+\b/;            // owner/repo#NN
+const CROSS_REPO_URL = /https?:\/\/github\.com\/[^\s\/]+\/[^\s\/]+\/(issues|pull)\/\d+/;
+
+// ── Public API ──
+
+/**
+ * Infer story type from labels + title + body.
+ *
+ * @param {string[]|null} labels
+ * @param {string|null} body
+ * @param {string} [title]
+ * @returns {'bug'|'enhancement'|'feature'|'refactor'|'docs'|'chore'|'meta-epic'}
+ */
+function extractType(labels, body, title) {
+  // 1. Labels (most authoritative)
+  const safeLabels = Array.isArray(labels) ? labels : [];
+  for (const label of safeLabels) {
+    const key = String(label || '').toLowerCase();
+    if (LABEL_TO_TYPE[key]) return LABEL_TO_TYPE[key];
+  }
+  // 2. Title prefix
+  const safeTitle = typeof title === 'string' ? title : '';
+  for (const { re, type } of TITLE_PREFIXES) {
+    if (re.test(safeTitle)) return type;
+  }
+  // 3. Body keywords
+  const safeBody = typeof body === 'string' ? body : '';
+  for (const { re, type } of BODY_TYPE_KEYWORDS) {
+    if (re.test(safeBody)) return type;
+  }
+  // 4. Default
+  return 'enhancement';
+}
+
+/**
+ * Detect whether a story has security implications.
+ *
+ * @param {string[]|null} labels
+ * @param {string|null} body
+ * @returns {boolean}
+ */
+function extractSecurityImplications(labels, body) {
+  const safeLabels = Array.isArray(labels) ? labels : [];
+  // 1. Label
+  for (const label of safeLabels) {
+    if (String(label || '').toLowerCase() === 'security') return true;
+  }
+  // 2. Keywords in body
+  const safeBody = typeof body === 'string' ? body : '';
+  for (const re of SECURITY_KEYWORDS) {
+    if (re.test(safeBody)) return true;
+  }
+  return false;
+}
+
+/**
+ * Detect whether a story depends on work in a different repo.
+ *
+ * @param {string|null} body
+ * @returns {boolean}
+ */
+function extractCrossRepoDependency(body) {
+  const safeBody = typeof body === 'string' ? body : '';
+  if (!safeBody) return false;
+  // 1. Cross-repo ref form (owner/repo#NN)
+  if (CROSS_REPO_REF.test(safeBody)) return true;
+  // 2. Cross-repo URL
+  if (CROSS_REPO_URL.test(safeBody)) return true;
+  // 3. Phrase-based (depends on, blocked by, upstream, etc.)
+  for (const re of CROSS_REPO_PHRASES) {
+    if (re.test(safeBody)) return true;
+  }
+  return false;
+}
+
+/**
+ * Detect whether any of the touched files has a recent commit within the
+ * configured window. Indicates same-file overlap with recent prior work.
+ *
+ * @param {string} repoRoot
+ * @param {string[]} touchedFiles
+ * @param {number} [windowDays=14]
+ * @returns {boolean}
+ */
+function extractRecentlyModifiedOverlap(repoRoot, touchedFiles, windowDays) {
+  const w = (typeof windowDays === 'number' && windowDays > 0) ? windowDays : 14;
+  if (!repoRoot || typeof repoRoot !== 'string') return false;
+  if (!Array.isArray(touchedFiles) || touchedFiles.length === 0) return false;
+  for (const rel of touchedFiles) {
+    if (typeof rel !== 'string' || !rel) continue;
+    const abs = path.join(repoRoot, rel);
+    if (!fs.existsSync(abs)) continue;
+    try {
+      const out = execSync(
+        `git log --since="${w} days ago" --format=%H -- ${JSON.stringify(rel)}`,
+        { cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }
+      ).trim();
+      if (out) return true;
+    } catch {
+      // Git unavailable / not a repo — silently continue
+    }
+  }
+  return false;
+}
+
+module.exports = {
+  extractType,
+  extractSecurityImplications,
+  extractCrossRepoDependency,
+  extractRecentlyModifiedOverlap,
+  // Exported for test-shape assertions + future extension
+  LABEL_TO_TYPE,
+  SECURITY_KEYWORDS,
+  CROSS_REPO_PHRASES,
+};