@hone-ai/cli 1.18.0 → 1.20.0

package/lib/ci-gate-chooser.js

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

package/lib/doctor-admin-merge.js

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

package/lib/doctor-architecture.js

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

package/lib/emit-pr.js

@@ -0,0 +1,167 @@
+'use strict';
+/**
+ * emit-pr.js — HC-019n-followup-25 (pipeline-recovery condition 7).
+ *
+ * Condition 6 proved step_4's diff APPLIES and its tests PASS in isolation.
+ * Condition 7 turns that verified diff into the reviewable artifact: a branch
+ * and (opt-in) a draft PR a human can review. Today the pipeline's terminal
+ * output is a markdown file; this is the first step that produces something a
+ * reviewer opens.
+ *
+ * This module is the PURE half — branch-name / commit-message / PR-body
+ * construction, the idempotency decision, and the exit-code map. The worktree
+ * lifecycle, git writes, push, and `gh pr create` live in the CLI command and
+ * call these builders. Keeping it I/O-free makes the naming + honest-limit
+ * wording unit-testable without a repo or a network.
+ *
+ * See .github/pipeline/HC-019n-followup-25/architect.md. Publishing is opt-in
+ * and staged (tier 1 dry-run by default; --push, then --open-pr). NOTE the
+ * honest limit, carried verbatim into every PR body: a green verify means the
+ * change "does not regress the existing suite", NOT that the story is correctly
+ * implemented.
+ */
+
+/**
+ * Exit codes. 0–4 are byte-for-byte verify-patch's EXIT map, so a caller that
+ * already branches on verify-patch keeps working; 5 and 6 are the new
+ * outward-facing failures (branch conflict, publish failure).
+ */
+const EXIT = {
+  PASS: 0,            // plan built (dry run) | branch pushed | PR opened | PR already open
+  NO_DIFF: 1,         // step_4 produced no changes / fetch failed
+  DOES_NOT_APPLY: 2,  // diff did not apply in the worktree
+  TESTS_FAILED: 3,    // --verify ran and tests failed (no commit made)
+  TIMEOUT: 4,         // --verify test command timed out
+  BRANCH_CONFLICT: 5, // local branch already exists (not overwritten)
+  PUBLISH_FAILED: 6,  // push or gh pr create failed (no remote / no auth / rejected)
+};
+
+/**
+ * Sanitize an arbitrary string into a valid git ref path segment.
+ * Keeps [A-Za-z0-9._-], turns everything else into '-', collapses runs, and
+ * trims leading/trailing separators (git rejects a segment that starts with a
+ * dot or ends with '.lock', and a ref may not contain '..' or '@{').
+ */
+function slugifyRef(s) {
+  return String(s == null ? '' : s)
+    .replace(/[^A-Za-z0-9._-]+/g, '-')
+    .replace(/\.+/g, '.')       // no '..' (git forbids it in refs)
+    .replace(/-+/g, '-')
+    .replace(/^[-.]+|[-.]+$/g, '');
+}
+
+/** First 8 chars of a workflow/run id, for a short, traceable branch suffix. */
+function short8(workflowId) {
+  return String(workflowId == null ? '' : workflowId).replace(/[^A-Za-z0-9]/g, '').slice(0, 8);
+}
+
+/**
+ * Branch name for an emitted PR: `hone/<storyId>-<short8(workflowId)>`.
+ * An explicit override wins (still slugified, so a caller can't inject a bad
+ * ref). The workflowId suffix keeps re-runs of the same story from colliding.
+ */
+function buildBranchName({ storyId, workflowId, override }) {
+  if (override && override.trim()) {
+    // Preserve intentional path structure (`hone/foo`) in an override.
+    const cleaned = override.trim().split('/').map(slugifyRef).filter(Boolean).join('/');
+    if (cleaned) return cleaned;
+  }
+  const story = slugifyRef(storyId) || 'story';
+  const suffix = short8(workflowId) || 'run';
+  return `hone/${story}-${suffix}`;
+}
+
+/**
+ * Commit message. Provenance lives in the body/trailer — authorship is NOT
+ * spoofed (the commit is authored by the adopter's own git identity).
+ *
+ * @param {{storyId:string, summary?:string, workflowId:string, headSha:string,
+ *          verifyState:'pass'|'skipped'}} o
+ */
+function buildCommitMessage({ storyId, summary, workflowId, headSha, verifyState }) {
+  const subjectStory = storyId || 'story';
+  const subjectText = (summary && summary.trim().split('\n')[0].trim()) || 'apply generated changes';
+  const verifyLine = verifyState === 'pass'
+    ? `Verified by \`hone verify-patch\` against HEAD ${headSha}: pass.`
+    : `Diff applies against HEAD ${headSha}; verify skipped.`;
+  return [
+    `${subjectStory}: ${subjectText}`,
+    '',
+    `Generated by Hone step_4 (code-builder), workflow ${workflowId}.`,
+    'Diff materialized by `hone` from ## Changed Files (git-authored hunks).',
+    verifyLine,
+    '',
+    'Co-Authored-By: Hone Pipeline <noreply@hone.ai>',
+    '',
+  ].join('\n');
+}
+
+/**
+ * The mandatory honest-limit paragraph. Exported so a test can assert it is
+ * present in every PR body — it is the "must not overclaim" rule made concrete.
+ */
+const HONEST_LIMIT = [
+  '## Honest limit',
+  '`verify-patch` proves this change **does not regress the existing test suite**.',
+  'It does **not** prove the story is correctly or completely implemented — the',
+  'existing tests may not cover the new behavior. Review accordingly.',
+].join('\n');
+
+/**
+ * PR body. Always a draft's body; always carries HONEST_LIMIT verbatim.
+ *
+ * @param {{storyId:string, workflowId:string, headSha:string,
+ *          verifyState:'pass'|'skipped', command?:string, runUrl?:string}} o
+ */
+function buildPrBody({ storyId, workflowId, headSha, verifyState, command, runUrl }) {
+  const verification = verifyState === 'pass'
+    ? `- Verification: \`hone verify-patch\` — tests PASSED against HEAD \`${headSha}\`` +
+      (command ? ` using \`${command}\`` : '')
+    : `- Verification: SKIPPED — diff applies against HEAD \`${headSha}\`, tests not run at emit time`;
+  const lines = [
+    '## Summary',
+    `Automated change for ${storyId || 'a story'}, generated by the Hone SDLC pipeline.`,
+    '',
+    '## Provenance',
+    `- Source: step_4 (code-builder) output of workflow \`${workflowId}\``,
+    '- Diff: materialized CLI-side from `## Changed Files` (hunks computed by `git diff`, applicable by construction)',
+    verification,
+    '',
+    HONEST_LIMIT,
+  ];
+  if (runUrl) {
+    lines.push('', `Run: ${runUrl}`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * Idempotency decision, given the observed remote/local state. Pure: the CLI
+ * does the git/gh probes and hands the results here.
+ *
+ * @param {{branchExists:boolean, openPrUrl:string|null}} state
+ * @returns {{action:'branch_conflict'|'already_open'|'proceed', exitCode:number, prUrl?:string}}
+ */
+function decidePublish({ branchExists, openPrUrl }) {
+  // An already-open PR for this head is idempotent success — never open a
+  // duplicate. Checked before the branch-conflict guard: if the PR is already
+  // up, the branch necessarily exists, and reporting the URL is the useful move.
+  if (openPrUrl) {
+    return { action: 'already_open', exitCode: EXIT.PASS, prUrl: openPrUrl };
+  }
+  if (branchExists) {
+    return { action: 'branch_conflict', exitCode: EXIT.BRANCH_CONFLICT };
+  }
+  return { action: 'proceed', exitCode: EXIT.PASS };
+}
+
+module.exports = {
+  EXIT,
+  HONEST_LIMIT,
+  slugifyRef,
+  short8,
+  buildBranchName,
+  buildCommitMessage,
+  buildPrBody,
+  decidePublish,
+};