@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/context-pack.js

@@ -0,0 +1,326 @@
+#!/usr/bin/env node
+// context-pack.js — the claim-time "you are here" pack (V4.R04 / #942).
+//
+// Criterion: sessions-start-knowing. The June 2026 BFG corpus showed sessions
+// burning turns RE-DISCOVERING things that are knowable up front:
+//   - which tree to edit in (the wrong-path class — 84 hits, #1 error class):
+//     edits/git ops landing in the MAIN checkout instead of the session's
+//     worktree (feedback_edit_under_worktree_path).
+//   - the GDS API path prefix + task field enums (the BAD_KIND / P2 guess-and-
+//     retry class — e.g. kind=chore burned a turn in session #506).
+//   - OS toolchain gotchas (no `timeout` on macOS; where psql lives).
+//
+// So we PUSH that context at /builder-claim (and a compact form at
+// /builder-start) instead of letting each session hunt for it.
+//
+// DESIGN (mirrors next-number.js / R26):
+//   - The enums are GENERATED FROM THE LIVE VALIDATORS — VALID_KINDS,
+//     VALID_DISCIPLINES, TASK_FIELD_BOUNDS imported from src/bongos/task-classifier,
+//     the exact same module POST /tasks validates against. They cannot drift
+//     from what the server accepts, and nothing here is hand-maintained.
+//   - Pure core (buildContextPack/formatContextPack) takes injected runners so
+//     tests are hermetic (tests/context_pack.mjs). The facade contextPack()
+//     wires the real git/which/process.
+//   - FAIL-OPEN: every probe degrades to a safe default; this is a UX surface
+//     and must NEVER throw or block a claim.
+
+const { execFileSync } = require('node:child_process');
+const path = require('node:path');
+
+// The live validators. task-classifier is a pure module (no DB, no network),
+// so importing it from a CLI is safe — same precedent as next-number.js reading
+// the repo tree directly. This is the "not hand-maintained" guarantee.
+//
+// OPTIONAL, because the file may not be ON DISK (task 1003085). A sparse checkout
+// can lack modules/lifecycle, and when it did this require threw
+// MODULE_NOT_FOUND at import time. That killed /builder-start AND /builder-claim
+// — the two commands a builder needs to recover — leaving a deadlock escapable
+// only by calling POST /claims with curl. The header's FAIL-OPEN promise ("must NEVER throw or
+// block a claim") was already the right rule; this require was the line that did
+// not keep it.
+//
+// Degrade by OMITTING the enums, NEVER by hard-coding a copy. A local list of
+// kinds is precisely the drift the "generated from the live validators" design
+// exists to prevent, and it would be WORSE than absence: absence costs the
+// planner one /docs lookup, while a stale list reads as authoritative and is
+// discovered only when POST /tasks rejects it — the guess-and-retry turn this
+// whole pack was built to save.
+let classifier = null;
+try {
+  // eslint-disable-next-line global-require
+  classifier = require('../../modules/lifecycle/task-classifier');
+} catch (_) {
+  // Not materialized on this box. apiContract() reports it honestly below.
+}
+
+// Single source of truth for the API prefix (src/bongos/api-prefix.js) so the URL
+// rename (Part B) flips one constant and this pack follows. Importing a pure src
+// constant from a CLI is safe — same precedent as task-classifier above.
+const { API_PREFIX } = require('../../src/bongos/api-prefix');
+
+// ---- pure core -------------------------------------------------------------
+
+// The API contract a planner needs to file/claim without guessing. 'unclassified'
+// is dropped from both enums: it's the classifier's fallback bucket, never a
+// value a human should pick.
+//
+// The SHAPE is the same either way — empty arrays and null bounds, never missing
+// keys — because every consumer here and in start.js reads these fields
+// positionally. Returning a short object instead would move the crash from the
+// require to the formatter and fix nothing. `enums_available` is what the
+// formatters branch on, so "we don't know" is said once, in words, rather than
+// rendered as an empty list that looks like "there are none".
+function apiContract() {
+  const base = {
+    api_prefix: API_PREFIX,
+    docs_url: '/docs',
+    openapi_url: '/docs/openapi.json',
+    enums_available: Boolean(classifier),
+    task_kinds: [],
+    disciplines: [],
+    priority: null,
+    manual_degree: null,
+  };
+  if (!classifier) return base;
+  return {
+    ...base,
+    task_kinds: [...classifier.VALID_KINDS].filter((k) => k !== 'unclassified'),
+    disciplines: [...classifier.VALID_DISCIPLINES].filter((d) => d !== 'unclassified'),
+    priority: classifier.TASK_FIELD_BOUNDS.priority,
+    manual_degree: classifier.TASK_FIELD_BOUNDS.manual_degree,
+  };
+}
+
+// Resolve the absolute worktree root. runGit throws → fall back to cwd (which is
+// still better than nothing; the builder at least sees the directory they're in).
+//
+// task 1002573: also resolve WHICH KIND of tree this is. The pack used to print
+// the root and then assert "this is the session's tree, not the main checkout"
+// unconditionally — so claiming from the main checkout produced a sentence that
+// was flatly false, and the tooling told the builder to do the one thing that
+// makes the ship unmergeable (ship.js's local auto-merge has nowhere to merge
+// INTO when the receiving tree is the one holding the branch — task 1002572).
+//
+// The signal is the same one claim.js detectWorktreeName() already uses: in the
+// main checkout `--git-dir` and `--git-common-dir` resolve to the same path; in a
+// linked worktree they diverge. isMainCheckout is TRI-STATE — null means "could
+// not tell", and the guidance hedges rather than guessing, because this is a UX
+// surface that must never block a claim.
+function resolveWorktreeRoot({ runGit, cwd }) {
+  let root = null;
+  let degraded = false;
+  try {
+    root = runGit(['rev-parse', '--show-toplevel']).trim() || null;
+  } catch {
+    /* fall through */
+  }
+  if (!root) {
+    root = cwd;
+    degraded = true;
+  }
+  let isMainCheckout = null;
+  try {
+    const gitDir = runGit(['rev-parse', '--git-dir']).trim();
+    const commonDir = runGit(['rev-parse', '--git-common-dir']).trim();
+    if (gitDir && commonDir) {
+      // Both can come back RELATIVE ('.git' in the main checkout), so resolve
+      // against the tree we are describing rather than the process cwd.
+      const base = degraded ? cwd : root;
+      isMainCheckout = path.resolve(base, gitDir) === path.resolve(base, commonDir);
+    }
+  } catch {
+    /* unknown — the guidance hedges */
+  }
+  return { root, degraded, isMainCheckout };
+}
+
+// task 1002573: the guidance line(s) for the resolved tree. Pure, and exported so
+// the "these two must not read the same" property is unit-tested rather than
+// eyeballed. Returns an array of lines (the warning needs more than one).
+function worktreeGuidance(worktree) {
+  const isMain = worktree ? worktree.isMainCheckout : null;
+  if (isMain === true) {
+    return [
+      '    ⚠ THIS IS THE MAIN CHECKOUT — not a per-claim worktree.',
+      '      Working the claim here parks the main checkout off `main`, and the local',
+      '      auto-merge then has nowhere to merge INTO: the ship strands at `confirmed`',
+      '      until the server reconciler (or /merge-mode) catches it. Automation that',
+      '      resets this tree mid-session can also take your uncommitted work with it.',
+      '      Prefer a worktree:  git worktree add .claude/worktrees/<name> -b <branch>',
+    ];
+  }
+  if (isMain === false) {
+    return ['    → edit files + run git HERE. This is the session\'s tree, not the main checkout (the #1 wrong-path footgun).'];
+  }
+  return [
+    '    → edit files + run git HERE.',
+    '    ⚠ Could not tell whether this is the main checkout or a linked worktree. If it is',
+    '      the main checkout, prefer a per-claim worktree — see the warning in /builder-claim.',
+  ];
+}
+
+// OS toolchain facts the corpus showed sessions tripping over. `which` returns a
+// path or throws (command absent) — we only care presence/absence + the path.
+function osFacts({ platform, runWhich }) {
+  const isMac = platform === 'darwin';
+  const isWindows = platform === 'win32';
+  const probe = (cmd) => {
+    try {
+      const p = runWhich(cmd).trim();
+      return p || null;
+    } catch {
+      return null;
+    }
+  };
+  return {
+    platform,
+    isMac,
+    isWindows,
+    timeoutPath: probe('timeout'),   // absent on stock macOS (BSD ships `gtimeout` via coreutils)
+    psqlPath: probe('psql'),
+    nodeVersion: process.version,
+  };
+}
+
+// Normalize active claims (from /api/bongos/me) into {id, title, current} rows.
+// currentTaskId marks the one just claimed so the print can say "(this one)".
+function normalizeClaims(activeClaims, currentTaskId) {
+  const rows = Array.isArray(activeClaims) ? activeClaims : [];
+  return rows.map((c) => ({
+    id: c.task_id,
+    title: c.title || '',
+    current: currentTaskId != null && String(c.task_id) === String(currentTaskId),
+  }));
+}
+
+// Assemble the whole pack. Pure given its injected runners.
+function buildContextPack({
+  activeClaims = [],
+  currentTaskId = null,
+  cwd,
+  platform,
+  runGit,
+  runWhich,
+} = {}) {
+  return {
+    worktree: resolveWorktreeRoot({ runGit, cwd }),
+    claims: normalizeClaims(activeClaims, currentTaskId),
+    api: apiContract(),
+    os: osFacts({ platform, runWhich }),
+  };
+}
+
+// ---- formatting ------------------------------------------------------------
+
+function formatClaims(claims) {
+  if (!claims.length) return '(none held)';
+  return claims
+    .map((c) => `#${c.id}${c.current ? ' (this one)' : ''}`)
+    .join(', ');
+}
+
+function formatOs(os) {
+  const bits = [os.platform];
+  if (os.timeoutPath) bits.push('`timeout` available');
+  else bits.push('no `timeout`' + (os.isMac ? ' (macOS — use `gtimeout` or omit)' : ''));
+  bits.push(os.psqlPath ? `psql at ${os.psqlPath}` : 'psql NOT on PATH');
+  bits.push(`node ${os.nodeVersion}`);
+  return bits.join(' · ');
+}
+
+// Render the pack as terminal lines. Returns a string (no trailing newline) so
+// callers control spacing. ASCII-friendly labels; the one emoji header matches
+// the existing claim.js voice (📚 learnings, etc.).
+function formatContextPack(pack) {
+  const { worktree, claims, api, os } = pack;
+  const lines = [];
+  lines.push('🧭 Context pack (so this session starts knowing, not hunting):');
+  lines.push(`  Worktree root:  ${worktree.root}`);
+  lines.push(...worktreeGuidance(worktree)); // task 1002573 — tells the TRUTH about which tree this is
+  if (worktree.degraded) {
+    lines.push('    ⚠ git toplevel unreadable — showing cwd; double-check before writing.');
+  }
+  lines.push(`  Held claims:    ${formatClaims(claims)}`);
+  lines.push(`  API prefix:     ${api.api_prefix}   (e.g. POST ${api.api_prefix}/tasks, GET ${api.api_prefix}/me)`);
+  lines.push(`  API reference:  ${api.docs_url} (rendered) · ${api.openapi_url} (OpenAPI 3.1)`);
+  if (api.enums_available) {
+    lines.push(`  Task kinds:     ${api.task_kinds.join(', ')}`);
+    lines.push(`  Disciplines:    ${api.disciplines.join(', ')}`);
+    const conv = api.priority.convention;
+    lines.push(
+      `  Numeric fields: priority int ${api.priority.min}–${api.priority.max} ` +
+      `(use ${conv.label}) · manual_degree int ${api.manual_degree.min}–${api.manual_degree.max}`
+    );
+  } else {
+    // Say WHY and WHERE to look. The one thing this line must not do is imply the
+    // enums are empty — a planner who reads "kinds:" with nothing after it will
+    // invent one.
+    lines.push(`  Task kinds:     unavailable here — modules/lifecycle is not on this box; see ${api.docs_url}`);
+  }
+  lines.push(`  OS:             ${formatOs(os)}`);
+  return lines.join('\n');
+}
+
+// Compact form for /builder-start, which already prints the version/cost rows,
+// the "You:" line, and held claims. We add only what start.js DOESN'T already
+// say: the worktree root (the wrong-path footgun) + a one-line enum reminder
+// (the full enum list + OS facts stay on /builder-claim). Two lines, no emoji
+// noise beyond the shared compass.
+function formatContextPackCompact(pack) {
+  const { worktree, api } = pack;
+  const kinds = api.enums_available
+    ? api.task_kinds.slice(0, 4).join(', ') + (api.task_kinds.length > 4 ? ', …' : '')
+    : `see ${api.docs_url}`;
+  return [
+    `🧭 Worktree: ${worktree.root}  (edit + git here, not the main checkout)`,
+    `   API ${api.api_prefix} · kinds: ${kinds} · full pack on /builder-claim`,
+  ].join('\n');
+}
+
+// ---- real-runner facade ----------------------------------------------------
+
+const defaultRunGit = (args) =>
+  execFileSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+
+// Cross-platform "where is this command": `which` on POSIX, `where` on Windows.
+const defaultRunWhich = (cmd) =>
+  execFileSync(process.platform === 'win32' ? 'where' : 'which', [cmd], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+
+// Build the pack with the real environment. Best-effort — never throws.
+function contextPack({ activeClaims = [], currentTaskId = null } = {}) {
+  return buildContextPack({
+    activeClaims,
+    currentTaskId,
+    cwd: process.cwd(),
+    platform: process.platform,
+    runGit: defaultRunGit,
+    runWhich: defaultRunWhich,
+  });
+}
+
+// CLI: `node scripts/bongos/context-pack.js` prints the static pack (no claims —
+// it's an env probe). Handy for `doctor`-style checks.
+function main() {
+  const pack = contextPack();
+  console.log(formatContextPack(pack));
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  API_PREFIX,
+  apiContract,
+  resolveWorktreeRoot,
+  worktreeGuidance, // task 1002573
+  osFacts,
+  normalizeClaims,
+  buildContextPack,
+  formatClaims,
+  formatOs,
+  formatContextPack,
+  formatContextPackCompact,
+  contextPack,
+};

package/scripts/bongos/control-manifest.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+// scripts/bongos/control-manifest.js — the assurance-of-assurance check (task
+// 1003131, goal 1000076; docs/audits/ai-dev-redteam-baseline.md §0).
+//
+// The audit's HEADLINE finding: ADR 0022 named three enforcement controls
+// (a pre-commit secret hook, a secrets-scan CI workflow, a security-baseline
+// doc) that DID NOT EXIST in this repo — they never survived the core
+// extraction, and nothing noticed for releases. A control that can silently
+// stop existing is not a control.
+//
+// This module is the manifest of controls goal 1000076 shipped, plus the
+// predicate each must satisfy. It runs as a fitness check (fitness.js): delete
+// or unwire any control and the merge gate goes red. The manifest is the ONE
+// list — a control added later without a manifest row, or a manifest row whose
+// file is gone, both fail.
+//
+// Predicates are deliberately shallow (existence + one wiring substring), not
+// deep behavior tests — the control's own unit test proves behavior; THIS proves
+// the control is still present and connected. Cheap, hermetic (fs only), and
+// exactly the check whose absence the audit flagged.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const read = (rel) => fs.readFileSync(path.join(ROOT, rel), 'utf8');
+const exists = (rel) => fs.existsSync(path.join(ROOT, rel));
+
+// Each control: a file that must exist, and optionally a `wiredIn` (file, needle)
+// proving it is CONNECTED, not just present on disk. `label` names it in failures.
+const CONTROLS = [
+  {
+    label: 'prevent: secret-gate PreToolUse hook',
+    file: '.claude/hooks/secret-gate.js',
+    wiredIn: { file: '.claude/settings.json', needle: 'secret-gate.js' },
+  },
+  {
+    label: 'prevent: settings deny-rules for env/key lanes',
+    file: '.claude/settings.json',
+    wiredIn: { file: '.claude/settings.json', needle: '"deny"' },
+  },
+  {
+    label: 'gate: gitleaks secret scan in the unit workflow',
+    file: '.gitleaks.toml',
+    wiredIn: { file: '.github/workflows/unit.yml', needle: 'gitleaks' },
+  },
+  {
+    label: 'gate: dependency audit gate + baseline',
+    file: 'scripts/bongos/audit-gate.js',
+    wiredIn: { file: '.github/workflows/unit.yml', needle: 'audit-gate.js' },
+    alsoExists: ['config/audit-baseline.json'],
+  },
+  {
+    label: 'gate: install-lifecycle scripts disabled',
+    file: '.npmrc',
+    wiredIn: { file: '.npmrc', needle: 'ignore-scripts=true' },
+  },
+  {
+    label: 'gate: quality ratchets registered in fitness',
+    file: 'scripts/bongos/fitness-ratchets.js',
+    wiredIn: { file: 'scripts/bongos/fitness.js', needle: 'fitness-ratchets' },
+    alsoExists: ['config/fitness-baselines.json'],
+  },
+  {
+    label: 'gate: knip dead-code ratchet step in the unit workflow',
+    file: 'scripts/bongos/fitness-ratchets.js',
+    wiredIn: { file: '.github/workflows/unit.yml', needle: '--knip' },
+  },
+  {
+    // Task 1003209 re-pointed this row. It used to prove the routine mentioned
+    // its own scanner — a wiring substring satisfied by the SKILL.md talking
+    // about itself, which is why the manifest read GREEN for months while the
+    // patrol never ran once (follow-up audit §7). "Wired" for a scheduled
+    // control has to mean SOMETHING FIRES IT, so the needle now lives in the
+    // scheduler. The period itself is checked relationally, where a substring
+    // can't reach: scripts/bongos/routine-schedule.js (fitness Check 25).
+    label: 'patrol: weekly red-team routine is actually scheduled',
+    file: '.claude/scheduled-tasks/redteam-weekly/SKILL.md',
+    wiredIn: { file: '.github/workflows/redteam-patrol.yml', needle: 'run-routine.js redteam-weekly' },
+    alsoExists: ['scripts/bongos/redteam-patrol.js', 'scripts/bongos/routine-schedule.js', 'tests/routine_schedule.mjs'],
+  },
+
+  {
+    // Task 1003210. The ratchet (above) makes a metric unable to REGRESS; this
+    // makes it unable to sit still unnoticed. Both are needed — the audit measured
+    // the whole file at "every metric equal to baseline, 0 reduced", a state the
+    // ratchet reports as a clean pass. Wired in BOTH directions on purpose: the
+    // merge gate catches rot in a floor DECLARATION (hermetic, caused by the diff),
+    // and the weekly patrol files the time-based half, which is nobody's diff.
+    label: 'assurance: a frozen baseline cannot silently become permanent',
+    file: 'scripts/bongos/baseline-staleness.js',
+    wiredIn: { file: 'scripts/bongos/fitness.js', needle: 'baseline-staleness' },
+    alsoExists: ['config/fitness-baselines.json', 'tests/baseline_staleness.mjs'],
+  },
+  {
+    label: 'assurance: the staleness check is filed weekly, not only on merge',
+    file: 'scripts/bongos/baseline-staleness.js',
+    wiredIn: { file: 'scripts/bongos/redteam-patrol.js', needle: 'stalenessFindings' },
+    alsoExists: ['.github/workflows/redteam-patrol.yml'],
+  },
+
+  // ── goal 1000077's four guards (task 1003169 / G05) ──────────────────────
+  //
+  // Same reasoning as the goal-1000076 controls above, applied to the goal that
+  // exists BECAUSE prose documented four failure modes and nothing refused them.
+  // A guard that can silently stop existing is not a guard — and these four are
+  // exactly the kind that can: three are one line in fitness.js's CHECKS array
+  // (delete the line and the check simply never runs, with nothing red), and the
+  // fourth is a module the ship pipeline requires.
+  //
+  // `alsoExists` names each guard's TEST on purpose. A check whose test is gone
+  // still runs, but nothing then proves it can still fail — and this session
+  // produced three tests that were green for the wrong reason, so an untested
+  // guard is a guard on trust.
+  {
+    label: 'guard: a doc that names a CLI matches the real CLI (G01)',
+    file: 'scripts/bongos/doc-cli-guard.js',
+    wiredIn: { file: 'scripts/bongos/fitness.js', needle: 'doc-cli-guard' },
+    alsoExists: ['tests/doc_cli_guard.mjs'],
+  },
+  {
+    label: 'guard: no ops script hardcodes a version id (G02)',
+    file: 'scripts/bongos/version-literal-guard.js',
+    wiredIn: { file: 'scripts/bongos/fitness.js', needle: 'version-literal-guard' },
+    alsoExists: ['tests/version_literals.mjs', 'scripts/bongos/version-select.js'],
+  },
+  {
+    label: 'guard: an ops skill declares the machine it needs (G03)',
+    file: 'scripts/bongos/skill-preflight.js',
+    wiredIn: { file: 'scripts/bongos/fitness.js', needle: 'skill-preflight' },
+    alsoExists: ['tests/skill_preflight.mjs'],
+  },
+  {
+    // Not a fitness check: a module the ship pipeline requires. Wired in
+    // ship-flow.js, which is where the carve left the resume path — and where a
+    // missing import silently broke every regrade until task 1003166 hit it.
+    label: 'guard: a ship cannot lie about how far it got (G04)',
+    file: 'scripts/bongos/ship-honesty.js',
+    wiredIn: { file: 'scripts/bongos/ship-flow.js', needle: 'ship-honesty' },
+    alsoExists: ['tests/ship_cannot_lie.mjs'],
+  },
+  {
+    // Task 1003418 (audit A14). The manifest's own blind spot: it covers the rows
+    // someone listed. This guard derives claims from the docs instead, so a
+    // described-but-absent control reds the gate with no row to add.
+    label: 'guard: a doc cannot describe a control that does not exist (A14)',
+    file: 'scripts/bongos/doc-control-claims.js',
+    wiredIn: { file: 'scripts/bongos/fitness.js', needle: 'doc-control-claims' },
+    alsoExists: ['tests/doc_control_claims.mjs'],
+  },
+];
+
+// Pure evaluation — exported for the test. deps.exists/deps.read override fs.
+function evaluate(controls = CONTROLS, deps = {}) {
+  const ex = deps.exists || exists;
+  const rd = deps.read || read;
+  const missing = [];
+  for (const c of controls) {
+    if (!ex(c.file)) { missing.push(`${c.label}: control file missing (${c.file})`); continue; }
+    for (const extra of c.alsoExists || []) {
+      if (!ex(extra)) missing.push(`${c.label}: companion file missing (${extra})`);
+    }
+    if (c.wiredIn) {
+      let hay = '';
+      try { hay = ex(c.wiredIn.file) ? rd(c.wiredIn.file) : ''; } catch { hay = ''; }
+      if (!hay.includes(c.wiredIn.needle)) {
+        missing.push(`${c.label}: not wired in — "${c.wiredIn.needle}" absent from ${c.wiredIn.file}`);
+      }
+    }
+  }
+  return missing;
+}
+
+// The fitness.js check.
+function checkControlsExist() {
+  const violations = evaluate();
+  return {
+    name: 'controls assert their own existence — goal 1000076 enforcement manifest (task 1003131)',
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: violations.length
+      ? 'a shipped security/quality control disappeared or came unwired — restore it or update control-manifest.js in the same change'
+      : `all ${CONTROLS.length} controls present and wired — goal 1000076's plus goal 1000077's four guards (task 1003169). The assurance-of-assurance the ADR 0022 audit found missing.`,
+  };
+}
+
+function main() {
+  const r = checkControlsExist();
+  for (const v of r.violations) console.error(`✗ ${v}`);
+  console.log(`${r.hardFail ? 'FAIL' : 'PASS'}  ${r.note}`);
+  process.exit(r.hardFail ? 1 : 0);
+}
+
+if (require.main === module) main();
+
+module.exports = { checkControlsExist, evaluate, CONTROLS };