@hone-ai/cli 1.4.0

package/lib/derive-domain.js

@@ -0,0 +1,185 @@
+'use strict';
+/**
+ * derive-domain.js — HC-004 (first per-adopter skill scaffolder).
+ *
+ * Pure helper that scaffolds a per-adopter `<name>-domain/SKILL.md` from
+ * the 7-section template documented in pipeline-integrity §13 (Per-adopter
+ * `<domain>-domain/SKILL.md` slot, OptionsFlow E26-A-L1).
+ *
+ * Marker discipline (per HC-001-L1):
+ *   - Frontmatter `managed_by: hone-derive-domain` marks the file as
+ *     framework-scaffolded
+ *   - Three states: absent → write; managed → no-op; unmanaged → SKIP
+ *     unless --force
+ *
+ * Uses static template at cli/lib/domain-skill-template.md (per HC-001's
+ * static-file precedent — auditable, previewable, lintable).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const TEMPLATE_PATH = path.join(__dirname, 'domain-skill-template.md');
+const MANAGED_MARKER = 'managed_by: hone-derive-domain';
+
+const DOMAIN_SKILL_SECTIONS = [
+  'Vocabulary',
+  'Architectural Contracts',
+  'Review Rules',
+  'Anti-Hallucination Rules',
+  'Calibration & Empirical Unknowns',
+  'Known Asymmetries / Bugs',
+  'References',
+];
+
+const RESERVED_NAMES = new Set([
+  'domain',     // would produce 'domain-domain' — silly
+  'skill',      // could be confused with skill itself
+  'skills',
+  'core',
+  'common',
+  'global',
+]);
+
+/**
+ * @param {string} name
+ * @returns {{ ok: boolean, error?: string }}
+ */
+function validateDomainName(name) {
+  if (!name || typeof name !== 'string') {
+    return { ok: false, error: 'domainName is required (non-empty string)' };
+  }
+  if (name.length < 2) {
+    return { ok: false, error: `domainName too short: "${name}" (min 2 chars)` };
+  }
+  if (name.length > 50) {
+    return { ok: false, error: `domainName too long: "${name}" (max 50 chars)` };
+  }
+  if (!/^[a-z0-9][a-z0-9-]*[a-z0-9]$/.test(name)) {
+    return {
+      ok: false,
+      error: `domainName must be kebab-case (lowercase a-z + 0-9 + hyphens; start and end with alphanumeric): "${name}"`,
+    };
+  }
+  if (RESERVED_NAMES.has(name)) {
+    return { ok: false, error: `domainName is reserved: "${name}"` };
+  }
+  return { ok: true };
+}
+
+/**
+ * Scaffold a per-adopter domain skill.
+ *
+ * @param {object} args
+ * @param {string} args.repoRoot
+ * @param {string} args.domainName
+ * @param {boolean} [args.force]
+ * @param {Function} [args.now]   () => new Date()
+ * @returns {{
+ *   findings: Array,
+ *   summary: { total, errors, warnings, info },
+ *   created: string[],
+ *   skipped: Array<{path, reason}>,
+ * }}
+ */
+function deriveDomain(args) {
+  const { repoRoot, domainName, force = false } = args || {};
+  const now = args && args.now ? args.now : () => new Date();
+  const findings = [];
+  const created = [];
+  const skipped = [];
+
+  if (!repoRoot || typeof repoRoot !== 'string') {
+    return wrap(
+      [{ severity: 'ERROR', code: 'invalid-args', message: 'repoRoot is required' }],
+      created, skipped,
+    );
+  }
+
+  const valid = validateDomainName(domainName);
+  if (!valid.ok) {
+    return wrap(
+      [{ severity: 'ERROR', code: 'invalid-domain-name', message: valid.error }],
+      created, skipped,
+    );
+  }
+
+  if (!fs.existsSync(TEMPLATE_PATH)) {
+    return wrap(
+      [{ severity: 'ERROR', code: 'template-missing', message: `template not found: ${TEMPLATE_PATH}` }],
+      created, skipped,
+    );
+  }
+
+  const targetDir = path.join(repoRoot, '.github/skills', `${domainName}-domain`);
+  const targetFile = path.join(targetDir, 'SKILL.md');
+
+  // Three states per HC-001-L1
+  if (fs.existsSync(targetFile)) {
+    const existing = fs.readFileSync(targetFile, 'utf8');
+    const isManaged = existing.includes(MANAGED_MARKER);
+    if (isManaged && !force) {
+      skipped.push({
+        path: targetFile,
+        reason: 'already-managed — re-run is a no-op (idempotent); pass --force to overwrite',
+      });
+      return wrap(findings, created, skipped);
+    }
+    if (!isManaged && !force) {
+      skipped.push({
+        path: targetFile,
+        reason: 'unmanaged-existing-file — refusing to overwrite adopter customization',
+        userAction: 'pass --force to overwrite, or remove the file manually first',
+      });
+      return wrap(findings, created, skipped);
+    }
+  }
+
+  // Render template
+  let template;
+  try {
+    template = fs.readFileSync(TEMPLATE_PATH, 'utf8');
+  } catch (e) {
+    return wrap(
+      [{ severity: 'ERROR', code: 'template-read-failed', message: e.message }],
+      created, skipped,
+    );
+  }
+
+  const derivedAt = now().toISOString();
+  const content = template
+    .replace(/\{\{DOMAIN_NAME\}\}/g, domainName)
+    .replace(/\{\{DERIVED_AT\}\}/g, derivedAt);
+
+  // Write
+  try {
+    fs.mkdirSync(targetDir, { recursive: true });
+    fs.writeFileSync(targetFile, content, 'utf8');
+    created.push(targetFile);
+  } catch (e) {
+    return wrap(
+      [{ severity: 'ERROR', code: 'write-failed', message: `failed to write ${targetFile}: ${e.message}` }],
+      created, skipped,
+    );
+  }
+
+  return wrap(findings, created, skipped);
+}
+
+function wrap(findings, created, skipped) {
+  const summary = {
+    total: findings.length,
+    errors: findings.filter(f => f.severity === 'ERROR').length,
+    warnings: findings.filter(f => f.severity === 'WARN').length,
+    info: findings.filter(f => f.severity === 'INFO').length,
+  };
+  return { findings, summary, created, skipped };
+}
+
+module.exports = {
+  deriveDomain,
+  validateDomainName,
+  DOMAIN_SKILL_SECTIONS,
+  MANAGED_MARKER,
+  RESERVED_NAMES,
+};

package/lib/doc-registry.js

@@ -0,0 +1,63 @@
+'use strict';
+/**
+ * doc-registry.js — Platform doc registry URL selection helper (HC-011).
+ *
+ * Pure helper (no I/O). Takes a parsed registry YAML object and a list
+ * of discovered metadata types, returns an ordered list of URLs filtered
+ * by relevance.
+ *
+ * Architecture: docs/architecture/platform-auto-discovery-v1.md (Tier 2)
+ */
+
+const MAX_URLS = 40; // 40 × 10K chars = 400K max context
+
+/**
+ * Select registry URLs relevant to the discovered metadata types.
+ *
+ * @param {object|null} registry - parsed platform doc registry YAML
+ * @param {string[]|null} discoveredTypes - metadata type names from platform-discover.js
+ * @returns {Array<{url: string, title: string, category: string, priority: number}>}
+ */
+function selectRegistryUrls(registry, discoveredTypes) {
+  if (!registry || typeof registry !== 'object') return [];
+  const categories = registry.doc_categories;
+  if (!categories || typeof categories !== 'object') return [];
+
+  const types = Array.isArray(discoveredTypes) ? discoveredTypes : [];
+  const typesSet = new Set(types);
+  const selected = [];
+
+  for (const [category, entries] of Object.entries(categories)) {
+    if (!Array.isArray(entries)) continue;
+
+    for (const entry of entries) {
+      if (!entry || !entry.url || !entry.title) continue;
+
+      const relevance = entry.relevance;
+      let relevant = false;
+
+      if (relevance === 'always') {
+        relevant = true;
+      } else if (Array.isArray(relevance)) {
+        relevant = relevance.some(r => typesSet.has(r));
+      }
+
+      if (relevant) {
+        selected.push({
+          url: entry.url,
+          title: entry.title,
+          category,
+          priority: entry.priority || 2,
+        });
+      }
+    }
+  }
+
+  // Sort: priority 1 first, then by category order (stable sort preserves insertion order)
+  selected.sort((a, b) => a.priority - b.priority);
+
+  // Cap at MAX_URLS
+  return selected.slice(0, MAX_URLS);
+}
+
+module.exports = { selectRegistryUrls, MAX_URLS };

package/lib/doctor-admin-merge.js

@@ -0,0 +1,185 @@
+'use strict';
+/**
+ * doctor-admin-merge.js — HC-002 + HC-005-A.
+ *
+ * Scans recent git history for the admin-merge anti-pattern (per E13-A-L3,
+ * absorbed into pr-review-standards/SKILL.md §Block admin-merge).
+ *
+ * Detects commits whose message contains:
+ *   - --admin
+ *   - --no-verify
+ *   - "force merge" / "force push" / "force-merge"
+ *   - "bypass" (CI / hook / branch protection)
+ *
+ * HC-005-A self-referential check discipline (per pipeline-integrity §17.5):
+ *   - Subject-only scan by default; body fall-through gated by meta-words.
+ *   - `[doctor:meta]` marker exempts a commit (subject OR body) from scan.
+ *   - Shallow-clone detection → `info` instead of silent `ok`.
+ *
+ * Returns the conventional doctor result shape: {name, status, reason, suggestedFix}.
+ * Pure-helper-with-injected-IO style; never throws.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execSync } = require('node:child_process');
+
+// HC-005-A: ambiguous pattern named explicitly so the ambiguity-guard
+// doesn't depend on array index ordering. Adding new patterns to
+// ADMIN_MERGE_PATTERNS won't accidentally re-target the ambiguity guard.
+const BYPASS_PATTERN = /\bbypass(es|ed|ing|ing-)?\b/i;
+
+// Patterns that indicate admin-merge / hook-bypass behavior
+const ADMIN_MERGE_PATTERNS = [
+  /--admin\b/i,
+  /--no-verify\b/i,
+  /\bforce[ -]merge/i,
+  /\bforce push\b/i,
+  BYPASS_PATTERN,  // "bypassed CI", "bypass branch protection" — ambiguous; guarded
+];
+
+// HC-005-A: explicit marker exempts a commit (intended for meta-commits that
+// document / forbid the patterns being scanned for)
+const META_MARKER = '[doctor:meta]';
+
+// HC-005-A: words that strongly suggest a commit body is *discussing* the
+// patterns rather than *applying* them. Used to filter body-only hits.
+// Subject hits always count, regardless of these words.
+const META_DISCUSSION_RE = /\b(regex|patterns?|detects?|forbid(s|den)?|enforce(s|d)?|bans?|blocks?|prohibit(s|ed)?|documents?|rules?|prevent(s|ed)?|no-bypass|no-admin|no-no-verify)\b/i;
+
+/**
+ * @param {object} args
+ * @param {string} args.repoRoot
+ * @param {number} [args.lookback=50]   commits to scan
+ * @returns {{ name: 'admin-merge', status: 'ok'|'drift'|'skip'|'info', reason: string, suggestedFix?: string }}
+ */
+function checkAdminMerge(args) {
+  const { repoRoot, lookback = 50 } = args || {};
+  const name = 'admin-merge';
+
+  if (!repoRoot || typeof repoRoot !== 'string') {
+    return { name, status: 'skip', reason: 'no repoRoot supplied' };
+  }
+
+  // Verify it's a git repo
+  let log;
+  try {
+    log = execSync(`git log -n ${lookback} --pretty=format:'%H%x09%s%x09%b%x1e'`, {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch {
+    return { name, status: 'skip', reason: 'not a git repository (or no commits yet)' };
+  }
+
+  // Split on record separator
+  const commits = log.split('\x1e').filter(c => c.trim());
+
+  // HC-005-A: shallow-clone detection — adopters with `clone --depth N`
+  // would get a silent `ok` after scanning only N commits. Surface it as
+  // `info` so they know the audit is partial.
+  const isShallow = isShallowClone(repoRoot);
+
+  const offenders = [];
+  for (const c of commits) {
+    const [sha, subject = '', body = ''] = c.split('\t');
+    const cleanSubject = subject.trim();
+    const cleanBody = body.trim();
+
+    // HC-005-A (a): explicit meta-marker exemption
+    if (cleanSubject.includes(META_MARKER) || cleanBody.includes(META_MARKER)) {
+      continue;
+    }
+
+    // HC-005-A (b): two-stage filter
+    // Stage 1 — subject hit. Flag-form patterns (--admin, --no-verify,
+    // force-merge, force push) are unambiguous in subjects. The standalone
+    // `bypass` token is ambiguous (e.g., "no-bypass rule" describes a feature
+    // that BANS bypass). For ambiguous subject matches, apply the
+    // discussion-words filter; for unambiguous matches, count immediately.
+    let matchedRe = null;
+    for (const re of ADMIN_MERGE_PATTERNS) {
+      if (re.test(cleanSubject)) {
+        if (re === BYPASS_PATTERN && META_DISCUSSION_RE.test(cleanSubject)) {
+          // Subject discusses the pattern (e.g., "no-bypass rule") — skip this match
+          break;
+        }
+        matchedRe = re;
+        break;
+      }
+    }
+
+    // Stage 2 — body fall-through, but only if body lacks meta-discussion words
+    if (!matchedRe) {
+      for (const re of ADMIN_MERGE_PATTERNS) {
+        if (re.test(cleanBody)) {
+          if (!META_DISCUSSION_RE.test(cleanBody)) {
+            matchedRe = re;
+          }
+          break;
+        }
+      }
+    }
+
+    if (matchedRe) {
+      offenders.push({
+        sha: sha.trim().slice(0, 7),
+        pattern: matchedRe.source,
+        subject: cleanSubject.slice(0, 80),
+      });
+    }
+  }
+
+  if (offenders.length === 0) {
+    if (isShallow) {
+      return {
+        name,
+        status: 'info',
+        reason: `shallow clone — scanned only ${commits.length} commits; \`git fetch --unshallow\` for deeper audit`,
+      };
+    }
+    return {
+      name,
+      status: 'ok',
+      reason: `no admin-merge anti-patterns in last ${commits.length} commits`,
+    };
+  }
+
+  const detail = offenders.map(o => `${o.sha} (${o.pattern}): ${o.subject}`).join('; ');
+  return {
+    name,
+    status: 'drift',
+    reason: `Found ${offenders.length} admin-merge anti-pattern commit(s) in last ${commits.length}: ${detail.slice(0, 300)}${detail.length > 300 ? '…' : ''}`,
+    suggestedFix: 'Branch protection should block --admin (per E13-A-L3). See pr-review-standards/SKILL.md §Block admin-merge anti-pattern. For commits documenting the pattern (not applying it), add [doctor:meta] to the subject or body.',
+  };
+}
+
+/**
+ * Detect shallow clone via `git rev-parse --is-shallow-repository`.
+ * This handles regular repos, worktrees (where `.git` is a file), and
+ * submodules — all cases the path-based `.git/shallow` check would miss.
+ *
+ * Falls back to checking `.git/shallow` if git is unavailable / errors.
+ * Returns false on any error (skips the surfacing — better than false-positiving).
+ */
+function isShallowClone(repoRoot) {
+  try {
+    const out = execSync('git rev-parse --is-shallow-repository', {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+    return out === 'true';
+  } catch {
+    // Fallback to file-based detection
+    try {
+      const shallowPath = path.join(repoRoot, '.git', 'shallow');
+      return fs.existsSync(shallowPath);
+    } catch {
+      return false;
+    }
+  }
+}
+
+module.exports = { checkAdminMerge, ADMIN_MERGE_PATTERNS, META_MARKER, META_DISCUSSION_RE };

package/lib/doctor-bind-default.js

@@ -0,0 +1,118 @@
+'use strict';
+/**
+ * doctor-bind-default.js — HC-002.
+ *
+ * Greps source code for the literal `0.0.0.0` bind anti-pattern (per
+ * E13-A-L1, absorbed into reliability/SKILL.md §Bind to localhost +
+ * Hard Rules). Per SC-006-L1's prescriptive-language discipline, the
+ * `reason` field uses MUST NOT / never wording so the check itself
+ * models the rule it enforces.
+ *
+ * Filters out:
+ *   - Test fixtures (tests/, fixtures/, *.test.*)
+ *   - Documentation (docs/, *.md)
+ *   - Hook templates (cli/lib/hook-templates/)
+ *   - node_modules / .git / dist / build
+ *   - Lines containing env-var-driven binds (os.getenv / process.env)
+ *
+ * Returns conventional doctor result shape. Never throws.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execSync } = require('node:child_process');
+
+const DEFAULT_ALLOWED_PATH_PREFIXES = [
+  'tests/',
+  'test/',
+  'fixtures/',
+  'docs/',
+  'node_modules/',
+  '.git/',
+  'dist/',
+  'build/',
+  'cli/lib/hook-templates/',  // pre-commit/pre-push templates may reference 0.0.0.0 in comments
+  '.github/learnings/',  // narrative may quote the anti-pattern
+  '.github/pipeline/',   // story artifacts may quote the anti-pattern
+  'server/seeds/skills/',  // skill content may quote the rule
+  'server/seeds/learnings/',
+  'enterprise-assets/.github/learnings/',
+  '.github/skills/',
+];
+
+// Files to ALSO skip by extension
+const SKIP_EXT = ['.md', '.test.js', '.test.ts', '.test.py', '.spec.js'];
+
+/**
+ * @param {object} args
+ * @param {string} args.repoRoot
+ * @param {string[]} [args.allowedPaths]   path prefixes to skip (default: DEFAULT_ALLOWED_PATH_PREFIXES)
+ * @returns {{ name: 'bind-default', status: 'ok'|'drift'|'skip', reason: string, suggestedFix?: string }}
+ */
+function checkBindDefault(args) {
+  const { repoRoot, allowedPaths = DEFAULT_ALLOWED_PATH_PREFIXES } = args || {};
+  const name = 'bind-default';
+
+  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}` };
+  }
+
+  // grep -rE "0\.0\.0\.0" with file exclusions
+  let raw = '';
+  try {
+    raw = execSync(
+      `grep -rEn '0\\.0\\.0\\.0' . ` +
+      `--include='*.py' --include='*.js' --include='*.ts' --include='*.go' --include='*.rb' --include='*.java' --include='*.kt' ` +
+      `--include='*.yml' --include='*.yaml' --include='*.toml' --include='*.json' --include='*.sh' ` +
+      `2>/dev/null || true`,
+      { cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 4 * 1024 * 1024 },
+    );
+  } catch {
+    return { name, status: 'skip', reason: 'grep failed (or no source files matched)' };
+  }
+
+  const offenders = [];
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    // Format: ./path/to/file:LINENO:matched-line
+    const m = line.match(/^\.\/(.+?):(\d+):(.*)$/);
+    if (!m) continue;
+    const [, file, lineNo, content] = m;
+
+    // Filter out allowed paths
+    if (allowedPaths.some(p => file.startsWith(p))) continue;
+    // Filter out test/spec files by extension
+    if (SKIP_EXT.some(ext => file.endsWith(ext))) continue;
+    // Filter out env-var-driven binds (legitimate use)
+    if (/\bos\.getenv\b|\bprocess\.env\b|\bgetenv\(/.test(content)) continue;
+    // Filter out lines that are clearly comments mentioning the anti-pattern
+    if (/^\s*(#|\/\/|--).*0\.0\.0\.0/.test(content)) continue;
+
+    offenders.push({ file, line: lineNo, content: content.trim().slice(0, 100) });
+  }
+
+  if (offenders.length === 0) {
+    return {
+      name,
+      status: 'ok',
+      reason: 'no literal 0.0.0.0 binds found in production code',
+    };
+  }
+
+  // Prescriptive language per SC-006-L1
+  const detail = offenders.slice(0, 5).map(o => `${o.file}:${o.line}`).join(', ');
+  return {
+    name,
+    status: 'drift',
+    reason: `MUST NOT bind 0.0.0.0 from code (per E13-A-L1). Never default to a wildcard host; always read from BIND_HOST env-var with 127.0.0.1 fallback. Found ${offenders.length} violation(s): ${detail}${offenders.length > 5 ? ` (+${offenders.length - 5} more)` : ''}`,
+    suggestedFix: 'Use os.getenv("BIND_HOST", "127.0.0.1") or process.env.BIND_HOST || "127.0.0.1". See reliability/SKILL.md §Bind to localhost by default.',
+  };
+}
+
+module.exports = {
+  checkBindDefault,
+  DEFAULT_ALLOWED_PATH_PREFIXES,
+};