@hone-ai/cli 1.4.0

package/lib/doctor-docs.js

@@ -0,0 +1,205 @@
+'use strict';
+/**
+ * doctor-docs.js — Hone doctor's documentation-freshness subcheck (H-017).
+ *
+ * Pure module: parses a README's test-count badge + inline mentions, compares
+ * against an actual test count from the project's test runner. Returns a
+ * structured result. Caller (hone-cli.js) does the I/O.
+ *
+ * H-016 / E20-A-L1 / E22-C pattern: pure function + thin shell.
+ *
+ * The OptionsFlow pilot wrote a Python equivalent (scripts/doc_freshness_check.py)
+ * before this CLI version existed. Logic and regex literals match that script
+ * so behavior is identical across the two implementations.
+ */
+
+// Matches shields.io badge variations:
+//   /tests-260%20passing-/    (URL-encoded space)
+//   /tests-260-passing-/      (single hyphen)
+//   /tests--260--passing-/    (double hyphen)
+const BADGE_RE = /tests-{1,2}(\d+)(?:%20|-{1,2})passing/i;
+
+// Matches inline prose like "260 tests passing" or "**260 tests passing**".
+// Used to catch drifted counts in the README body, not just the badge.
+const INLINE_RE = /\*{0,2}(\d+)\s+tests?\s+passing\*{0,2}/i;
+
+
+/**
+ * @param {string} readmeText — full contents of README.md
+ * @returns {number|null} the test count from the badge, or null if not found
+ */
+function extractBadgeCount(readmeText) {
+  const m = (readmeText || '').match(BADGE_RE);
+  return m ? parseInt(m[1], 10) : null;
+}
+
+/**
+ * @param {string} readmeText
+ * @returns {number[]} all inline test-count mentions in prose (excluding the badge)
+ */
+function extractInlineCounts(readmeText) {
+  const stripped = (readmeText || '').replace(BADGE_RE, '');
+  const matches = [];
+  let m;
+  const re = new RegExp(INLINE_RE, 'gi');
+  while ((m = re.exec(stripped)) !== null) {
+    matches.push(parseInt(m[1], 10));
+  }
+  return matches;
+}
+
+
+/**
+ * Evaluate the docs-freshness rule.
+ *
+ * @param {object} input
+ * @param {string|null} input.readmeText — README.md contents (null if missing)
+ * @param {number|null} input.actualTestCount — test count from runner (null if runner unavailable)
+ * @returns {{
+ *   status: 'ok' | 'drift' | 'skip',
+ *   reason: string,
+ *   badge: number|null,
+ *   inline: number[],
+ *   actual: number|null,
+ *   suggestedFix: string|null,
+ * }}
+ */
+function checkDocsFreshness(input) {
+  const { readmeText, actualTestCount } = input || {};
+
+  if (readmeText == null) {
+    return {
+      status: 'skip',
+      reason: 'No README.md found at repo root.',
+      badge: null,
+      inline: [],
+      actual: actualTestCount ?? null,
+      suggestedFix: null,
+    };
+  }
+
+  const badge = extractBadgeCount(readmeText);
+  const inline = extractInlineCounts(readmeText);
+
+  if (badge == null && inline.length === 0) {
+    return {
+      status: 'skip',
+      reason: 'README.md has no test-count badge or inline mention; nothing to check.',
+      badge: null,
+      inline: [],
+      actual: actualTestCount ?? null,
+      suggestedFix: null,
+    };
+  }
+
+  if (actualTestCount == null) {
+    return {
+      status: 'skip',
+      reason:
+        'Could not determine actual test count (test runner unavailable or returned no count). ' +
+        'README mentions a count but cannot be verified.',
+      badge,
+      inline,
+      actual: null,
+      suggestedFix: null,
+    };
+  }
+
+  // Compare badge + every inline mention against actual.
+  const mismatches = [];
+  if (badge != null && badge !== actualTestCount) {
+    mismatches.push(`badge says ${badge}`);
+  }
+  for (const c of inline) {
+    if (c !== actualTestCount) {
+      mismatches.push(`inline says ${c}`);
+    }
+  }
+
+  if (mismatches.length === 0) {
+    return {
+      status: 'ok',
+      reason: `README test count matches actual (${actualTestCount}).`,
+      badge,
+      inline,
+      actual: actualTestCount,
+      suggestedFix: null,
+    };
+  }
+
+  return {
+    status: 'drift',
+    reason:
+      `README test count drifted: ${mismatches.join(', ')}, ` +
+      `but the test runner reports ${actualTestCount}.`,
+    badge,
+    inline,
+    actual: actualTestCount,
+    suggestedFix:
+      `Update README.md so every test-count mention reads ${actualTestCount}, or ` +
+      `re-run the check after the next test suite changes settle.`,
+  };
+}
+
+
+/**
+ * Build the command to count tests for a given stack. Returns a shell command
+ * string that, when executed, prints "<N> tests collected" or similar — caller
+ * parses the output. Pure function — no I/O.
+ *
+ * Stacks with no known runner return null; caller should skip with a "skip" result.
+ */
+function testCounterCommand(stack) {
+  switch (stack) {
+    case 'python':
+      // pytest works for any Python project that has pytest installed
+      return 'python3 -m pytest --collect-only -q 2>&1 | tail -3';
+    case 'node':
+    case 'javascript':
+    case 'typescript':
+      // jest --listTests outputs one path per line; vitest is similar
+      // Use a generic strategy: try jest first, fall back to vitest list
+      return null; // explicit skip — Node test counts vary too much by toolchain
+    case 'go':
+      return "go test -list '.*' ./... 2>&1 | grep -cE '^(Test|Benchmark)'";
+    case 'rust':
+      return "cargo test -- --list 2>&1 | grep -cE '^test '";
+    default:
+      return null;
+  }
+}
+
+
+/**
+ * Parse the output of a test-counter command into an integer count.
+ * Stack-specific because each runner formats output differently.
+ */
+function parseTestCount(stack, stdout) {
+  if (!stdout) return null;
+  switch (stack) {
+    case 'python': {
+      const m = stdout.match(/(\d+)\s+tests?\s+(?:collected|selected)/);
+      return m ? parseInt(m[1], 10) : null;
+    }
+    case 'go':
+    case 'rust': {
+      // Output is a count from grep -c
+      const n = parseInt(stdout.trim(), 10);
+      return Number.isFinite(n) && n > 0 ? n : null;
+    }
+    default:
+      return null;
+  }
+}
+
+
+module.exports = {
+  checkDocsFreshness,
+  extractBadgeCount,
+  extractInlineCounts,
+  testCounterCommand,
+  parseTestCount,
+  // Exported for tests
+  BADGE_RE,
+  INLINE_RE,
+};

package/lib/doctor-placeholders.js

@@ -0,0 +1,144 @@
+'use strict';
+/**
+ * doctor-placeholders.js — HC-002.
+ *
+ * Scans CI workflows + adopter config files for unsubstituted placeholders
+ * (per E21-A-L1, absorbed into pr-review-standards/SKILL.md §Adoption-time
+ * placeholder substitution is silent-disable vector).
+ *
+ * Detects placeholder formats:
+ *   - {{PLACEHOLDER}} (Jinja / Handlebars-style)
+ *   - <PLACEHOLDER> (XML-style, used in some YAML scaffolds)
+ *   - __PLACEHOLDER__ (underscore-wrap, used in some shell scaffolds)
+ *
+ * Scans only the files where adopter substitution actually happens:
+ *   - .github/workflows/*.yml
+ *   - .github/.pipeline-config.yml
+ *   - scripts/*.sh
+ *   - copilot-instructions.md / CLAUDE.md (rare but possible)
+ *
+ * Returns conventional doctor result shape. Never throws.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const PLACEHOLDER_PATTERNS = [
+  // {{NAME}} — jinja-style
+  { re: /\{\{([A-Z_][A-Z0-9_]*)\}\}/g, format: '{{NAME}}' },
+  // <PLACEHOLDER_NAME> — XML-bracketed (only when ALL_CAPS to avoid HTML / XML false positives)
+  { re: /<([A-Z_][A-Z0-9_]{2,})>/g, format: '<NAME>' },
+  // __PLACEHOLDER_NAME__ — underscore-wrapped
+  { re: /__([A-Z_][A-Z0-9_]{2,})__/g, format: '__NAME__' },
+];
+
+const SCAN_PATHS = [
+  '.github/workflows',
+  '.github/.pipeline-config.yml',
+  '.github/copilot-instructions.md',
+  'CLAUDE.md',
+  'scripts',
+];
+
+// Known false positives to ignore (legitimate uses of <X> / __NAME__ / etc.)
+const ALLOW_LIST = [
+  '<NAME>',
+  '<URL>',
+  '<EMAIL>',
+  '<USER>',
+  '<TOKEN>',
+  '<PROJECT>',
+  '<BRANCH>',
+  '<STORY-ID>',  // doc syntax: paths like .github/pipeline/<STORY-ID>/...
+  '<id>',
+  '<n>',
+  '__init__',
+  '__main__',
+  '__name__',
+  '__future__',
+  '__file__',
+  '__dict__',
+  '__doc__',
+  '__class__',
+  '__version__',
+  '__all__',
+  '__future__',
+  '__pycache__',
+  '__future__',
+];
+
+/**
+ * @param {object} args
+ * @param {string} args.repoRoot
+ * @returns {{ name: 'placeholders', status: 'ok'|'drift'|'skip', reason: string, suggestedFix?: string }}
+ */
+function checkPlaceholders(args) {
+  const { repoRoot } = args || {};
+  const name = 'placeholders';
+
+  if (!repoRoot || typeof repoRoot !== 'string') {
+    return { name, status: 'skip', reason: 'no repoRoot supplied' };
+  }
+  if (!fs.existsSync(repoRoot)) {
+    return { name, status: 'skip', reason: `repoRoot does not exist: ${repoRoot}` };
+  }
+
+  const offenders = [];
+  for (const relPath of SCAN_PATHS) {
+    const fullPath = path.join(repoRoot, relPath);
+    if (!fs.existsSync(fullPath)) continue;
+
+    const stat = fs.statSync(fullPath);
+    if (stat.isFile()) {
+      scanFile(fullPath, relPath, offenders);
+    } else if (stat.isDirectory()) {
+      // Recurse one level deep into known dirs
+      for (const entry of fs.readdirSync(fullPath)) {
+        const ep = path.join(fullPath, entry);
+        if (fs.statSync(ep).isFile()) {
+          scanFile(ep, path.join(relPath, entry), offenders);
+        }
+      }
+    }
+  }
+
+  if (offenders.length === 0) {
+    return {
+      name,
+      status: 'ok',
+      reason: 'no unsubstituted placeholders found in scanned paths',
+    };
+  }
+
+  const detail = offenders.slice(0, 5)
+    .map(o => `${o.file}:${o.line} (${o.placeholder})`)
+    .join(', ');
+  return {
+    name,
+    status: 'drift',
+    reason: `Unsubstituted placeholders detected — ${offenders.length} violation(s): ${detail}${offenders.length > 5 ? ` (+${offenders.length - 5} more)` : ''}. Adoption-time placeholder substitution is a silent-disable vector (per E21-A-L1).`,
+    suggestedFix: 'Re-run `hone setup` or `hone adopt` to substitute, or hand-edit the files. See pr-review-standards/SKILL.md §Adoption-time placeholder substitution.',
+  };
+}
+
+function scanFile(absPath, relPath, offenders) {
+  let content;
+  try { content = fs.readFileSync(absPath, 'utf8'); }
+  catch { return; }
+
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const { re, format } of PLACEHOLDER_PATTERNS) {
+      re.lastIndex = 0;
+      let m;
+      while ((m = re.exec(line)) !== null) {
+        const placeholder = m[0];
+        if (ALLOW_LIST.includes(placeholder)) continue;
+        offenders.push({ file: relPath, line: i + 1, placeholder, format });
+      }
+    }
+  }
+}
+
+module.exports = { checkPlaceholders, PLACEHOLDER_PATTERNS, SCAN_PATHS };

package/lib/doctor-skill-staleness.js

@@ -0,0 +1,122 @@
+'use strict';
+/**
+ * doctor-skill-staleness.js — HC-002.
+ *
+ * Surfaces skill staleness in the `hone doctor` summary (per E16-A-L4,
+ * absorbed into observability/SKILL.md §11 Skill-staleness disclosure).
+ *
+ * Reads `.github/.pipeline-config.yml` for `skill_refresh.last_derived`,
+ * compares against age threshold (default 30 days). Optional growth check:
+ * if .github/skills/ source-file count grew >50% since last_derived, flag
+ * as stale even if within age threshold.
+ *
+ * Existing `hone check-refresh` command already does similar work; this
+ * helper mirrors its logic so doctor's summary includes the staleness
+ * signal alongside other health checks.
+ *
+ * Returns conventional doctor result shape. Never throws.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * @param {object} args
+ * @param {string} args.repoRoot
+ * @param {number} [args.ageThresholdDays=30]
+ * @param {number} [args.growthPctThreshold=50]
+ * @returns {{ name: 'skill-staleness', status: 'ok'|'warn'|'skip', reason: string, suggestedFix?: string }}
+ */
+function checkSkillStaleness(args) {
+  const { repoRoot, ageThresholdDays = 30, growthPctThreshold = 50 } = args || {};
+  const name = 'skill-staleness';
+
+  if (!repoRoot || typeof repoRoot !== 'string') {
+    return { name, status: 'skip', reason: 'no repoRoot supplied' };
+  }
+
+  // Try both .github/.pipeline-config.yml and .pipeline-config.yml (per SC-003 dual-location)
+  const candidates = [
+    path.join(repoRoot, '.github/.pipeline-config.yml'),
+    path.join(repoRoot, '.pipeline-config.yml'),
+  ];
+  const cfgPath = candidates.find(p => fs.existsSync(p));
+  if (!cfgPath) {
+    return { name, status: 'skip', reason: 'no .pipeline-config.yml found (skipping staleness check)' };
+  }
+
+  let cfg;
+  try {
+    const yaml = require('js-yaml');
+    cfg = yaml.load(fs.readFileSync(cfgPath, 'utf8'), { schema: yaml.JSON_SCHEMA });
+  } catch (e) {
+    return { name, status: 'skip', reason: `failed to parse ${cfgPath}: ${e.message}` };
+  }
+
+  const lastDerived = cfg?.skill_refresh?.last_derived;
+  if (!lastDerived) {
+    return {
+      name,
+      status: 'skip',
+      reason: 'no skill_refresh.last_derived recorded (run `hone derive` to initialize)',
+    };
+  }
+
+  // Age check
+  const lastDerivedDate = new Date(lastDerived);
+  if (isNaN(lastDerivedDate.getTime())) {
+    return { name, status: 'skip', reason: `invalid skill_refresh.last_derived: ${lastDerived}` };
+  }
+  const ageDays = Math.floor((Date.now() - lastDerivedDate.getTime()) / (1000 * 60 * 60 * 24));
+
+  // Growth check (optional — count files in .github/skills/)
+  let growthPct = null;
+  const skillsDir = path.join(repoRoot, '.github/skills');
+  if (fs.existsSync(skillsDir)) {
+    const fileCount = countFiles(skillsDir);
+    const recordedCount = cfg?.skill_refresh?.source_file_count;
+    if (typeof recordedCount === 'number' && recordedCount > 0) {
+      growthPct = Math.round(((fileCount - recordedCount) / recordedCount) * 100);
+    }
+  }
+
+  const ageStale = ageDays > ageThresholdDays;
+  const growthStale = growthPct !== null && growthPct > growthPctThreshold;
+
+  if (!ageStale && !growthStale) {
+    return {
+      name,
+      status: 'ok',
+      reason: `skills derived ${ageDays} days ago (within ${ageThresholdDays}-day threshold)${growthPct !== null ? `; source dir growth ${growthPct}%` : ''}`,
+    };
+  }
+
+  const reasons = [];
+  if (ageStale) reasons.push(`derived ${ageDays} days ago (>${ageThresholdDays})`);
+  if (growthStale) reasons.push(`source dir grew ${growthPct}% (>${growthPctThreshold}%)`);
+
+  return {
+    name,
+    status: 'warn',
+    reason: `Skills are stale: ${reasons.join('; ')}`,
+    suggestedFix: 'Run `hone derive` to refresh domain skills (or `hone refresh-knowledge` once HC-003 ships). See observability/SKILL.md §11 Skill-staleness disclosure.',
+  };
+}
+
+function countFiles(dir) {
+  let count = 0;
+  try {
+    for (const entry of fs.readdirSync(dir)) {
+      const ep = path.join(dir, entry);
+      const stat = fs.statSync(ep);
+      if (stat.isDirectory()) {
+        count += countFiles(ep);
+      } else if (entry === 'SKILL.md') {
+        count += 1;
+      }
+    }
+  } catch {}
+  return count;
+}
+
+module.exports = { checkSkillStaleness };

package/lib/domain-skill-template.md

@@ -0,0 +1,114 @@
+---
+name: {{DOMAIN_NAME}}-domain
+description: >
+  Per-adopter domain skill for {{DOMAIN_NAME}}. Encodes vocabulary,
+  architectural contracts, review rules, anti-hallucination guards,
+  and calibration unknowns specific to this domain. Hand-edit the
+  sections below; the framework will not overwrite this file unless
+  you remove the `managed_by` line and re-run with --force.
+autoLoad: false
+managed_by: hone-derive-domain
+derived_at: "{{DERIVED_AT}}"
+---
+
+<!-- HC-004-MANAGED-MARKER — DO NOT EDIT this comment; it lets `hone derive-domain` detect this is a framework-scaffolded file -->
+
+# {{DOMAIN_NAME}} Domain Skill
+
+> Generated by `hone derive-domain {{DOMAIN_NAME}}` (HC-004) using the
+> 7-section template documented in `pipeline-integrity §13` (Per-adopter
+> `<domain>-domain/SKILL.md` slot, OptionsFlow E26-A-L1).
+>
+> Each section below ships with a placeholder + a guidance comment.
+> Replace placeholders with your domain's actual content; keep the
+> 7-section structure so cross-references from agent prompts work.
+>
+> When you're satisfied with content, set `autoLoad: true` in the
+> frontmatter so this skill loads automatically alongside the
+> generic-engineering skills.
+
+## §1 Vocabulary
+
+<!-- guidance: list domain terms with their PRECISE meaning. Distinguish overloaded terms (e.g., "delta" in options has 3 meanings: greek, change-amount, status indicator). Disambiguate at first use; cross-reference where the definition lives. -->
+
+- **<TERM-1>** — <one-line precise meaning. Note any overload with other domains>
+- **<TERM-2>** — <...>
+- **<TERM-N>** — <...>
+
+## §2 Architectural Contracts
+
+<!-- guidance: list MUST-DO rules domain-specific to this domain. Data flow, calculation conventions (e.g., dealer-gamma sign), regulatory constraints (e.g., HIPAA logging), trade-cutoff times, etc. Each rule should be testable AND have a Code Reviewer-actionable enforcement. -->
+
+- **Contract 1**: <e.g., "All position-sizing calculations MUST use the trading-day calendar, never the calendar day">
+- **Contract 2**: <...>
+- **Contract N**: <...>
+
+## §3 Review Rules
+
+<!-- guidance: what does Code Reviewer flag in domain code? Map each Architectural Contract above to a concrete review check. Use prescriptive language (per pr-review-standards/SKILL.md §Make hallucination IMPOSSIBLE) — "MUST NOT", "Never", "Forbid". -->
+
+For any PR that modifies <domain> code, Code Reviewer flags:
+
+- **<Rule 1>**: <e.g., "Position sizing without trading-day calendar import → HIGH">
+- **<Rule 2>**: <...>
+- **<Rule N>**: <...>
+
+## §4 Anti-Hallucination Rules
+
+<!-- guidance: per SC-009 §Make hallucination IMPOSSIBLE not discouraged (E20-A-L3), AI/scoring features in this domain MUST cite traceable sources. Every non-zero score / claim / inference must reference a source field (API response, paid-feed row, ground-truth lookup). Rule the rule prescriptively in the language. -->
+
+For any AI / ML / scoring feature in <domain>:
+
+- **MUST cite traceable source**: every non-zero score / claim / inference references a field in the input (e.g., `whales[symbol].volume`, `compliance_record.id`, `lab_result.timestamp`)
+- **NEVER emit ungrounded claims**: stub functions return deterministic empty (`score: 0`, `direction: None`); only follow-up implementation activates real signals
+- **<Domain-specific anti-hallucination rule>**: <...>
+
+Cross-reference: `pr-review-standards/SKILL.md` §Make hallucination IMPOSSIBLE not discouraged.
+
+## §5 Calibration & Empirical Unknowns
+
+<!-- guidance: per pipeline-integrity §14 calibration unknowns documented in domain skills (E26-A-L2), every tunable threshold MUST be flagged as UNKNOWN until measured. List each constant with its current value, status (UNKNOWN / MEASURED / EVIDENCE-BACKED), and a deferred-work tracker. -->
+
+The constants below are CURRENT VALUES, not EVIDENCE-BACKED. PRs that
+change a value MUST cite the measurement that justifies the new value.
+
+| Constant | Current value | Status | Deferred work |
+|---|---|---|---|
+| <e.g. confidence_threshold> | 0.65 | UNKNOWN | <ticket-id>: backtest 90 days → tune |
+| <e.g. consensus_rule> | 3-of-5 | UNKNOWN | <ticket-id>: simulate alternatives |
+| ... | ... | UNKNOWN | ... |
+
+Cross-reference: `pipeline-integrity/SKILL.md` §14 Calibration unknowns documented in domain skills.
+
+## §6 Known Asymmetries / Bugs
+
+<!-- guidance: domain-specific gotchas + their workarounds. Sign-convention footguns (per architecture-patterns §Domain-convention-vs-intuition footgun), structural biases, edge cases that bit production once. Each item should explain the trap + the mitigation. -->
+
+- **<Asymmetry / Bug 1>**: <description>
+  - **Workaround**: <how to avoid it>
+- **<Asymmetry / Bug 2>**: <...>
+
+Cross-reference: `architecture-patterns/SKILL.md` §Symmetry in multi-layer scoring systems (and §Domain-convention-vs-intuition footgun for sign conventions).
+
+## §7 References
+
+<!-- guidance: canonical sources, regulators, papers, related domain skills, internal docs. Anything a future contributor needs to look up to understand this domain. -->
+
+- **Canonical source**: <URL or paper citation>
+- **Regulator**: <e.g., SEC Rule X, GDPR Article Y, HIPAA §...>
+- **Related domain skills**: <e.g., `compliance-domain/SKILL.md`, `risk-domain/SKILL.md`>
+- **Internal docs**: <e.g., `docs/architecture/<domain>-overview.md`>
+
+---
+
+> **Editing this file**:
+> - Hand-edit any section above. The `managed_by: hone-derive-domain`
+>   line keeps this file in framework-managed state; re-running
+>   `hone derive-domain {{DOMAIN_NAME}}` is a no-op while the marker
+>   is present.
+> - To take full ownership and prevent the framework from ever
+>   touching this file: remove the `managed_by` line. Future
+>   `hone derive-domain` runs (and `--force` runs) will refuse to
+>   overwrite without an explicit `--force` flag from you.
+> - To regenerate from the latest framework template: run
+>   `hone derive-domain {{DOMAIN_NAME}} --force` (your edits will be lost).