@hone-ai/cli 1.4.0

package/lib/editor-detect.js

@@ -0,0 +1,169 @@
+'use strict';
+/**
+ * editor-detect.js — H-081 detect which editor(s) drive the SDLC pipeline.
+ *
+ * Pure helper with injected I/O (same shape as platform-detect.js,
+ * compliance-check.js). Caller passes `fileExists` callback + optional
+ * `envVar` value; helper returns array of detected editors.
+ *
+ * Detection signals (in order):
+ *   1. HONE_EDITOR env var (comma-separated explicit override)
+ *   2. File-system fingerprints at repo root
+ *   3. .vscode/settings.json `github.copilot.enable` (Copilot opt-in)
+ *
+ * Closes silent-drop class of bugs where Hone scaffolds files in editor-
+ * specific paths that the adopter's actual editor doesn't read. Per #81.
+ */
+
+/**
+ * Editor → fingerprint files at repo root that signal "this editor is in use."
+ * Multiple fingerprints per editor: any one match counts.
+ */
+const EDITOR_FINGERPRINTS = Object.freeze({
+  'claude-code': {
+    files: ['CLAUDE.md', '.claude/agents'],
+    description: 'Claude Code (Anthropic CLI)',
+  },
+  copilot: {
+    files: ['.github/copilot-instructions.md'],
+    description: 'GitHub Copilot',
+    additional_signal: 'vscode_copilot_enabled',
+  },
+  cursor: {
+    files: ['.cursorrules', '.cursor'],
+    description: 'Cursor (Anysphere)',
+  },
+  windsurf: {
+    files: ['.windsurfrules', '.windsurf'],
+    description: 'Windsurf (Codeium)',
+  },
+  aider: {
+    files: ['.aider.conf.yml', 'CONVENTIONS.md'],
+    description: 'Aider (paul-gauthier)',
+  },
+  continue: {
+    files: ['.continue', '.continuerc.json'],
+    description: 'Continue.dev',
+  },
+});
+
+/**
+ * Detect editors from file-system probes + env var override.
+ *
+ * #119 concern 2 (over-detection): Without `opts.listDir`, this is
+ * filesystem-PRESENCE detection — a stale empty `.cursor/` directory
+ * registers as Cursor present. Pass `opts.listDir` to upgrade to
+ * filesystem-CONTENT detection: directory fingerprints (those ending
+ * in `/`, like `.cursor`) require at least one file inside to count.
+ *
+ * @param {object} [opts]
+ * @param {(relativePath: string) => boolean} [opts.fileExists] - filesystem check
+ * @param {string} [opts.envVar] - HONE_EDITOR value (comma-separated list)
+ * @param {(relativePath: string) => string|null} [opts.readFile] - for vscode/settings.json
+ * @param {(relativePath: string) => string[]} [opts.listDir] - #119: optional
+ *   directory listing. When provided, directory fingerprints (.cursor/,
+ *   .continue/, .claude/agents/) require at least one entry to count as
+ *   detected. Without listDir, falls back to presence-only.
+ * @returns {string[]} - editor keys from EDITOR_FINGERPRINTS, sorted by table order
+ */
+function detectEditors(opts = {}) {
+  const { fileExists, envVar, readFile, listDir } = opts;
+
+  // 1. Explicit env var override wins
+  if (typeof envVar === 'string' && envVar.trim().length > 0) {
+    const requested = envVar.split(',').map((s) => s.trim()).filter(Boolean);
+    const out = [];
+    for (const key of Object.keys(EDITOR_FINGERPRINTS)) {
+      if (requested.includes(key)) out.push(key);
+    }
+    return out;
+  }
+
+  // 2. File-system probes
+  if (typeof fileExists !== 'function') return [];
+
+  const detected = new Set();
+  for (const [editor, { files }] of Object.entries(EDITOR_FINGERPRINTS)) {
+    if (files.some((f) => {
+      try {
+        if (fileExists(f) !== true) return false;
+        // #119: if listDir is provided, use the RETURN-SHAPE to distinguish
+        // directory vs file (avoids unreliable name-heuristics — `.cursor`
+        // looks like a file by extension but is actually a directory).
+        //   - listDir(dir) → array of entries; empty array means dir is empty
+        //   - listDir(file) → throws (fs.readdirSync semantics)
+        // Empty directory → exclude (stale scaffolding shouldn't count as
+        // the editor being in use).
+        if (typeof listDir === 'function') {
+          let entries;
+          try {
+            entries = listDir(f);
+          } catch {
+            // listDir threw → it's a file (or unreadable) → presence-only OK
+            return true;
+          }
+          if (Array.isArray(entries)) {
+            return entries.length > 0;  // dir: require non-empty
+          }
+          return true;  // listDir returned non-array → presence-only fallback
+        }
+        return true;  // no listDir → presence-only (backward compat)
+      } catch {
+        return false;
+      }
+    })) {
+      detected.add(editor);
+    }
+  }
+
+  // 3. .vscode/settings.json Copilot opt-in
+  if (!detected.has('copilot') && typeof readFile === 'function') {
+    try {
+      const settings = readFile('.vscode/settings.json');
+      if (settings && /["']github\.copilot\.enable["']\s*:\s*(?:true|\{)/.test(settings)) {
+        detected.add('copilot');
+      }
+    } catch { /* defensive */ }
+  }
+
+  return [...detected];
+}
+
+/**
+ * Editor → expected projection surfaces (where the editor reads from).
+ * Used by pipeline-validate.js to assert each editor's expected files exist.
+ */
+const EDITOR_PROJECTIONS = Object.freeze({
+  'claude-code': {
+    project_doc: 'CLAUDE.md',
+    agents_dir: '.claude/agents',
+    agent_file_pattern: '*.agent.md',
+  },
+  copilot: {
+    project_doc: '.github/copilot-instructions.md',
+    agents_dir: null,  // Copilot uses inline doc; no per-agent files
+  },
+  cursor: {
+    project_doc: '.cursorrules',
+    agents_dir: '.cursor/rules',
+    agent_file_pattern: '*.mdc',
+  },
+  windsurf: {
+    project_doc: '.windsurfrules',
+    agents_dir: null,
+  },
+  aider: {
+    project_doc: 'CONVENTIONS.md',
+    agents_dir: null,
+  },
+  continue: {
+    project_doc: '.continuerc.json',
+    agents_dir: null,
+  },
+});
+
+module.exports = {
+  EDITOR_FINGERPRINTS,
+  EDITOR_PROJECTIONS,
+  detectEditors,
+};

package/lib/fast-track-ratify.js

@@ -0,0 +1,133 @@
+'use strict';
+/**
+ * fast-track-ratify.js — H-027 ratify fast-track at the epic level.
+ *
+ * Pure helpers — no I/O. Caller (hone-cli.js) reads + writes
+ * .github/EXECUTION_PLAN.yml and runs the readline prompt.
+ *
+ * Closes #50 sub-tasks (a) classifier + (b/c/d) CLI machinery. Sub-tasks
+ * (e) agent prompt wiring + (f) doc updates deferred to a follow-up
+ * story (separate PR — narrower blast radius).
+ *
+ * 10th instance of pure-helpers + thin-CLI-shell pattern in cli/lib/
+ * after H-018, H-035, H-009, H-008, H-021, H-061, H-010, H-015, H-013.
+ */
+
+const yaml = require('js-yaml');
+
+// ─────────────────────────────────────────────────────────────────────
+// HIGH_TOUCH_RULES — codified from issue #50 §Proposed design point 2
+// ─────────────────────────────────────────────────────────────────────
+//   Each rule is a (story) → bool predicate. ANY rule matching means the
+//   story is high-touch and must be excluded from epic ratification.
+const HIGH_TOUCH_RULES = [
+  // 1. Migration: schema-change keywords, but NOT explicit "no schema changes"
+  (s) => {
+    if (!s.migration) return false;
+    if (/\bno schema changes\b/i.test(s.migration)) return false;
+    return /\b(table|column|schema|alter|drop|migration)\b/i.test(s.migration);
+  },
+  // 2. Data model: schema/table/column/migration/breaking
+  (s) => s.data_model && /\b(schema|table|column|migration|breaking)\b/i.test(s.data_model),
+  // 3. Security: auth/secret/token/org-isolation/encryption/credential
+  (s) => s.security && /\b(auth|secret|token|org.isolation|encryption|credential)\b/i.test(s.security),
+  // 4. Estimate: ≥5 points
+  (s) => typeof s.estimate === 'number' && s.estimate >= 5,
+  // 5. Breaking change flag
+  (s) => s.breaking === true,
+];
+
+// ─────────────────────────────────────────────────────────────────────
+// isHighTouch — pure boolean classifier
+// ─────────────────────────────────────────────────────────────────────
+function isHighTouch(story) {
+  if (!story || typeof story !== 'object') return false;
+  return HIGH_TOUCH_RULES.some(rule => rule(story));
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// parseExecutionPlan — yaml.load wrapper with graceful fallback
+// ─────────────────────────────────────────────────────────────────────
+function parseExecutionPlan(text) {
+  if (typeof text !== 'string' || text.length === 0) {
+    return { error: 'empty', stories: [] };
+  }
+  try {
+    const parsed = yaml.load(text) || {};
+    return parsed;
+  } catch (e) {
+    return { error: 'malformed', message: e.message, stories: [] };
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// addRatifiedBlock — surgical APPEND (or REPLACE if exists) of
+// `fast_track_ratified:` block. Preserves all comments + content.
+// ─────────────────────────────────────────────────────────────────────
+//   opts: { by, at, mode, highTouchExcluded[] }
+//   Returns { text, updated }
+function addRatifiedBlock(text, opts = {}) {
+  if (typeof text !== 'string') return { text, updated: false };
+  const by = opts.by || 'unknown';
+  const at = opts.at || new Date().toISOString();
+  const mode = opts.mode || 'epic';
+  const highTouchExcluded = Array.isArray(opts.highTouchExcluded) ? opts.highTouchExcluded : [];
+
+  // Render the block
+  const lines = [
+    `fast_track_ratified:`,
+    `  by: ${by}`,
+    `  at: ${at}`,
+    `  mode: ${mode}`,
+  ];
+  if (highTouchExcluded.length > 0) {
+    lines.push(`  high_touch_excluded:`);
+    for (const id of highTouchExcluded) lines.push(`    - ${id}`);
+  } else {
+    lines.push(`  high_touch_excluded: []`);
+  }
+  const block = lines.join('\n');
+
+  // If an existing block exists, REPLACE it surgically
+  // Match `fast_track_ratified:` block at column 0 + its 2-space-indented children
+  const existingRe = /^fast_track_ratified:[\s\S]*?(?=^\S|\Z)/m;
+  if (existingRe.test(text)) {
+    return {
+      text: text.replace(existingRe, block + '\n\n'),
+      updated: true,
+    };
+  }
+
+  // Otherwise APPEND at end (with one blank line separator)
+  const sep = text.length === 0 || text.endsWith('\n\n') ? '' : (text.endsWith('\n') ? '\n' : '\n\n');
+  return {
+    text: text + sep + block + '\n',
+    updated: true,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// getRatificationStatus — read current state of fast_track_ratified
+// ─────────────────────────────────────────────────────────────────────
+function getRatificationStatus(text) {
+  const parsed = parseExecutionPlan(text);
+  const block = parsed.fast_track_ratified;
+  if (!block || typeof block !== 'object') {
+    return { ratified: false };
+  }
+  return {
+    ratified: true,
+    by: block.by || null,
+    at: block.at || null,
+    mode: block.mode || 'epic',
+    highTouchExcluded: Array.isArray(block.high_touch_excluded) ? block.high_touch_excluded : [],
+  };
+}
+
+module.exports = {
+  HIGH_TOUCH_RULES,
+  isHighTouch,
+  parseExecutionPlan,
+  addRatifiedBlock,
+  getRatificationStatus,
+};

package/lib/git-helpers.js

@@ -0,0 +1,109 @@
+'use strict';
+/**
+ * git-helpers.js — LC-004 (#143): shared git-log helpers for CLI shells.
+ *
+ * Extracted from cli/hone-cli.js's inline `getSkillLastModifiedDays`
+ * (which was added inline for LC-003 — `hone audit-learnings`). LC-004
+ * adds a sibling `getFirstCommitDateMs` for the captured_at-fallback
+ * path — both helpers share the same execSync error-handling shape.
+ *
+ * Pure-helper-with-injected-IO style: each helper accepts `repoRoot`
+ * + the relative file path, returns a primitive (number-of-days,
+ * Unix milliseconds, or null on any failure mode). Callers (CLI
+ * shells) inject these helpers into pure pipeline-status / audit-
+ * learnings logic.
+ *
+ * Why a separate module: cli/hone-cli.js is 3000+ lines and adding more
+ * inline git-log helpers each iteration creates the wrong module
+ * boundary. Architect's gap-finding for LC-004 said extract first.
+ *
+ * Issue: #143 (LC-004) — captured_at fallback to git log file mtime.
+ */
+const { execSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Last-modified Unix timestamp (seconds) for a tracked file, via
+ * `git log -1 --format=%ct -- <path>`. Returns null if:
+ *   - path doesn't exist on disk
+ *   - git log returns empty (file has never been committed)
+ *   - git is unavailable / repo is not a git repo
+ *   - any other error
+ *
+ * Used by LC-003 (audit-learnings: skill freshness signal).
+ */
+function getLastCommitTimestampSeconds(repoRoot, relativePath) {
+  if (!repoRoot || !relativePath) return null;
+  const abs = path.join(repoRoot, relativePath);
+  if (!fs.existsSync(abs)) return null;
+  try {
+    const out = execSync(
+      `git log -1 --format=%ct -- ${JSON.stringify(relativePath)}`,
+      { cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }
+    ).trim();
+    if (!out) return null;
+    const seconds = Number(out);
+    return Number.isFinite(seconds) ? seconds : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * First-commit Unix timestamp (milliseconds) for a tracked file, via
+ * `git log --diff-filter=A --follow --format=%at -- <path>`. The
+ * `--diff-filter=A` clause restricts to ADD events; `--follow` follows
+ * file renames so a learnings file moved between paths still resolves.
+ * Returns null on any failure (same modes as getLastCommitTimestampSeconds).
+ *
+ * Architect's gap-finding for LC-004: captured_at semantically wants
+ * "when was this learning first WRITTEN" — which is the FIRST commit
+ * that added the file, not the last commit that modified it. Different
+ * git log flag from getLastCommitTimestampSeconds.
+ *
+ * Returned as MILLISECONDS for consistency with Date.parse() / Date.now()
+ * — caller can format to ISO string via new Date(ms).toISOString().
+ *
+ * Used by LC-004 (audit-learnings: captured_at fallback when YAML
+ * field is absent).
+ */
+function getFirstCommitDateMs(repoRoot, relativePath) {
+  if (!repoRoot || !relativePath) return null;
+  const abs = path.join(repoRoot, relativePath);
+  if (!fs.existsSync(abs)) return null;
+  try {
+    const out = execSync(
+      `git log --diff-filter=A --follow --format=%at -- ${JSON.stringify(relativePath)}`,
+      { cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }
+    ).trim();
+    if (!out) return null;
+    // Multiple ADD events possible (file renames); take the OLDEST (last line)
+    const lines = out.split('\n').filter(Boolean);
+    const oldestLine = lines[lines.length - 1];
+    const seconds = Number(oldestLine);
+    return Number.isFinite(seconds) ? seconds * 1000 : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Convenience wrapper: how many days ago was the file last modified?
+ * Returns Math.max(0, round((now - lastCommit) / day_ms)) or null.
+ *
+ * Same shape as the original getSkillLastModifiedDays inlined in
+ * cli/hone-cli.js, just relocated for shared use across CLI commands.
+ */
+function getLastModifiedDays(repoRoot, relativePath, nowMs) {
+  const seconds = getLastCommitTimestampSeconds(repoRoot, relativePath);
+  if (seconds === null) return null;
+  const ref = (typeof nowMs === 'number' && Number.isFinite(nowMs)) ? nowMs : Date.now();
+  return Math.max(0, Math.round((ref - seconds * 1000) / 86400000));
+}
+
+module.exports = {
+  getLastCommitTimestampSeconds,
+  getFirstCommitDateMs,
+  getLastModifiedDays,
+};

package/lib/hook-templates/pre-commit.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# managed-by: hone — DO NOT EDIT (run `hone install-hooks --uninstall` to remove)
+#
+# Hone pre-commit hook (HC-001).
+# Validates any staged metadata.yml under .github/pipeline/<STORY>/ against
+# the framework JSON schema (per SC-011). Skips on develop/main/release branches.
+#
+# Bypass: HONE_PRECOMMIT_SKIP=1 git commit ...   (use sparingly; this defeats the gate per E13-A-L3)
+
+set -euo pipefail
+
+# Skip toggle for emergency commits (still emits a warning so it can't be silent)
+if [ "${HONE_PRECOMMIT_SKIP:-0}" = "1" ]; then
+  echo "⚠ hone pre-commit: HONE_PRECOMMIT_SKIP=1 — skipping (per E13-A-L3, bypass should be rare and tracked)" >&2
+  exit 0
+fi
+
+# Skip on non-story branches
+BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)"
+SKIP_BRANCHES_RE="${HONE_PRECOMMIT_SKIP_BRANCHES:-^(develop|main|master|release/.*)$}"
+if echo "$BRANCH" | grep -qE "$SKIP_BRANCHES_RE"; then
+  exit 0
+fi
+
+# Find staged metadata.yml files under .github/pipeline/<STORY>/
+STAGED_METADATA="$(git diff --cached --name-only --diff-filter=ACMR | grep -E '^\.github/pipeline/[^/]+/metadata\.yml$' || true)"
+
+if [ -z "$STAGED_METADATA" ]; then
+  exit 0
+fi
+
+# Validate each staged metadata.yml via `hone validate-metadata`
+EXIT_CODE=0
+SCHEMA_PATH="${HONE_METADATA_SCHEMA:-.github/schema/metadata.schema.json}"
+# Fallback to canonical (hone-server's own dev mode) if the adopter copy is missing
+if [ ! -f "$SCHEMA_PATH" ] && [ -f enterprise-assets/.github/schema/metadata.schema.json ]; then
+  SCHEMA_PATH="enterprise-assets/.github/schema/metadata.schema.json"
+fi
+
+while IFS= read -r meta; do
+  STORY_ID="$(echo "$meta" | sed -E 's|^\.github/pipeline/([^/]+)/metadata\.yml$|\1|')"
+  echo "hone pre-commit: validating $meta (story: $STORY_ID)" >&2
+  if ! hone validate-metadata "$STORY_ID" --schema "$SCHEMA_PATH" 2>&1; then
+    EXIT_CODE=1
+  fi
+done <<< "$STAGED_METADATA"
+
+if [ "$EXIT_CODE" -ne 0 ]; then
+  echo "" >&2
+  echo "✗ hone pre-commit: metadata.yml validation failed. Fix the findings above OR run with HONE_PRECOMMIT_SKIP=1 (tracked per E13-A-L3)." >&2
+  exit 1
+fi
+
+exit 0

package/lib/hook-templates/pre-push.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# managed-by: hone — DO NOT EDIT (run `hone install-hooks --uninstall` to remove)
+#
+# Hone pre-push hook (HC-001).
+# For the current branch's story (if any), assert that for every step marked
+# `completed` in metadata.yml, the corresponding step-N artifact file exists.
+# Catches the failure mode where a step is marked done in metadata but the
+# artifact wasn't committed (would block PR review).
+#
+# Bypass: HONE_PREPUSH_SKIP=1 git push   (use sparingly per E13-A-L3)
+# Thorough: HONE_PREPUSH_THOROUGH=1 git push   (also runs the story's regression tests)
+
+set -euo pipefail
+
+if [ "${HONE_PREPUSH_SKIP:-0}" = "1" ]; then
+  echo "⚠ hone pre-push: HONE_PREPUSH_SKIP=1 — skipping (per E13-A-L3, bypass should be rare and tracked)" >&2
+  exit 0
+fi
+
+BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)"
+SKIP_BRANCHES_RE="${HONE_PREPUSH_SKIP_BRANCHES:-^(develop|main|master|release/.*)$}"
+if echo "$BRANCH" | grep -qE "$SKIP_BRANCHES_RE"; then
+  exit 0
+fi
+
+# Extract story ID from branch name (matches SC-NNN, H-NNN, RP-NNN, AU-NNN, SR-NNN, HC-NNN, E-NNN-X)
+STORY_ID="$(echo "$BRANCH" | grep -oE '(SC|H|RP|AU|SR|HC|LC|SA)-[0-9]+[A-Z]?|E[0-9]+-[A-Z]' | head -1 || true)"
+if [ -z "$STORY_ID" ]; then
+  exit 0  # Not a story branch
+fi
+
+META=".github/pipeline/$STORY_ID/metadata.yml"
+if [ ! -f "$META" ]; then
+  exit 0  # Story branch but no metadata yet; pre-commit warned
+fi
+
+# Walk completed steps; assert artifact files exist
+EXIT_CODE=0
+# Read step IDs whose status is "completed" (or "complete")
+COMPLETED_STEPS="$(grep -oE 'step_[0-9]+[a-z]?:[[:space:]]*\{[[:space:]]*status:[[:space:]]*(completed|complete)' "$META" | grep -oE 'step_[0-9]+[a-z]?' || true)"
+
+for STEP in $COMPLETED_STEPS; do
+  # Find the artifact path: artifact: <name>.md
+  ARTIFACT_LINE="$(grep -E "^[[:space:]]+${STEP}:[[:space:]]*\{" "$META" || true)"
+  ARTIFACT="$(echo "$ARTIFACT_LINE" | grep -oE 'artifact:[[:space:]]*[a-zA-Z0-9_.-]+' | sed -E 's|artifact:[[:space:]]*||' || true)"
+  if [ -n "$ARTIFACT" ]; then
+    ARTIFACT_PATH=".github/pipeline/$STORY_ID/$ARTIFACT"
+    if [ ! -f "$ARTIFACT_PATH" ]; then
+      echo "✗ hone pre-push: $STEP marked completed but artifact $ARTIFACT_PATH is missing" >&2
+      EXIT_CODE=1
+    fi
+  fi
+done
+
+# Thorough mode: run the story's regression tests
+if [ "${HONE_PREPUSH_THOROUGH:-0}" = "1" ]; then
+  TEST_PATTERN="tests/regression/${STORY_ID}-*.test.js"
+  if compgen -G "$TEST_PATTERN" > /dev/null; then
+    echo "hone pre-push (thorough): running $TEST_PATTERN" >&2
+    if ! node --test $TEST_PATTERN 2>&1 | tail -10; then
+      EXIT_CODE=1
+    fi
+  fi
+fi
+
+if [ "$EXIT_CODE" -ne 0 ]; then
+  echo "" >&2
+  echo "✗ hone pre-push: artifact / test gate failed. Fix above OR run with HONE_PREPUSH_SKIP=1 (tracked per E13-A-L3)." >&2
+  exit 1
+fi
+
+exit 0