@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/category-advisory-guard.js

@@ -0,0 +1,206 @@
+'use strict';
+
+// scripts/bongos/category-advisory-guard.js — the fitness check that keeps a work
+// CATEGORY advisory (task 1003275, goal 1000072, criterion legibility-categories;
+// ADR 0192).
+//
+// WHY A CHECK AND NOT A COMMENT. The owner said it twice about this organisation:
+// it "has no hierarchical purpose", and these categories have "no effect on the
+// creation and agentic management of these elements". The risk is specific and
+// named in the goal's own prose: the system ALREADY has a real hierarchy
+// (Project → Version → Goal → Criteria → Task, ADR 0086) with real enforcement —
+// the scope_modules wall, per-task rank floors, goal membership — so a SECOND
+// thing that looks like a hierarchy "will be mistaken for one within a release".
+// The mistake does not arrive as a decision; it arrives as one plausible line in
+// a gate ("skip Legal goals in the feed"), and from then on work is refused
+// because of a label nobody meant as a permission. A comment cannot refuse that
+// line. This check can.
+//
+// WHAT IT ENFORCES, in two halves:
+//   1. NO GATE READS A CATEGORY. Every file that decides authority, claim
+//      eligibility, feed membership or dependency satisfaction is scanned with
+//      comments stripped; any surviving mention of a category is a hard failure.
+//      Comments are stripped rather than flagged so a gate may CITE this rule (the
+//      checkVocabularyWall precedent) — what it may not do is branch on it.
+//   2. THE FEATURE STILL EXISTS. A guard whose subject was renamed away passes
+//      silently and reads as proof (the ADR 0022 assurance-of-assurance finding
+//      that produced control-manifest.js). So the check also asserts the category
+//      surface is present; if the feature is gone, the guard must fail loudly
+//      rather than congratulate an empty repo.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+
+// Every file that DECIDES something: who may act, what may be claimed, what the
+// feed offers, when a dependency is satisfied. A category may not appear in any
+// of them. Add to this list when a new decision surface lands — that is the
+// maintenance cost, and it is the point.
+const GATE_FILES = [
+  'src/bongos/auth.js',
+  'src/bongos/auth-admission.js',
+  'src/bongos/permission-path-check.js',
+  'src/bongos/goal-scope-check.js',
+  'src/bongos/module-scope-map.js',
+  'src/bongos/stealth-gate.js',
+  'modules/lifecycle/claim-eligibility.js',
+  'modules/lifecycle/claim-feed.js',
+  'modules/lifecycle/goal-authz.js',
+  'modules/lifecycle/routes/goal-route-authz.js',
+  'modules/lifecycle/db-rank-authz.js',
+  'modules/lifecycle/db-deps-criteria.js',
+  'scripts/bongos/gating.js',
+];
+
+// DELIBERATELY NOT a gate: src/bongos/route-rank-check.js. It is the pin TABLE
+// the rank fitness check reads, so it names every route including the category
+// ones by design, and it decides nothing at runtime. Scanning it would force the
+// pins out of the registry that exists to hold them.
+
+// The category surface half 2 asserts still exists. Path + a token that must
+// appear in it, so a rename or a gutting is caught rather than a bare `existsSync`.
+const FEATURE_ANCHORS = [
+  { file: 'migrations/core_226_work_categories.sql', needle: 'CREATE TABLE IF NOT EXISTS work_categories' },
+  { file: 'modules/lifecycle/goal-category.js', needle: 'decorateGoalCategory' },
+  { file: 'modules/lifecycle/routes/goals.js', needle: "router.patch('/goals/:id/category'" },
+];
+
+// Word-bounded on purpose: `subcategory_id` in some unrelated module is not this
+// feature, and a guard that cries wolf gets suppressed rather than obeyed. The
+// table name needs no boundary — nothing else is called that.
+// A quoted path to a scripts/bongos/*.js file is a FILENAME, not a category read
+// (task 1003949). One of these guards is itself called category-advisory-guard.js,
+// so the moment any decision surface lists the enforcement tooling by path — which
+// module-scope-map.js must, to own it — this check fired on its own name.
+//
+// Blanked rather than exempted by file, and kept as narrow as it can be: only the
+// quoted path is removed, so the rest of the line is still scanned. A genuine
+// category read cannot hide inside a string that ends in .js.
+function withoutScriptPaths(line) {
+  return String(line).replace(/(['\"`])[^'\"`]*\.js\1/g, '""');
+}
+
+const CATEGORY_RE = /\bcategor(y|ies|ised|ized|isation|ization)\b|\bcategory_id\b|work_categories/i;
+
+// Strip // line comments and /* */ blocks so a citation of a rule is legal and only
+// executable text is judged.
+//
+// String-aware, and that is the whole point rather than a refinement. The direction
+// a stripper errs in is a safety property: keeping a comment only re-raises a false
+// alarm, which is LOUD and gets fixed, while dropping real code makes a guard report
+// clean over a live violation, which is indistinguishable from a tree that is
+// actually clean. So the scanner must never remove text it is not sure about.
+//
+// The previous regex pair claimed to err that way and did the opposite. `//` inside
+// an ordinary string literal — a protocol-relative URL, a path fragment — matched the
+// line-comment rule and erased the rest of the line, real code included:
+//
+//   router.post('//legacy', requirePermission('task.abandon.own'), handler);
+//
+// stripped to `router.post('`, so the guard scanning for that very call found nothing
+// (task 1003832; the equivalent hole in the ownership-scope scan in
+// tests/government_require_permission.mjs). Tracking quotes fixes it at the root, for
+// both callers, and makes the erring-toward-keeping promise above actually true.
+//
+// Unterminated constructs deliberately keep their text rather than swallowing to EOF.
+// A regex literal is not tracked: an unescaped `//` cannot appear in one (it would be
+// an empty regex), so the only way in is a `/`-delimited literal containing an escaped
+// pair, which reads as escaped here too.
+function stripComments(src) {
+  let out = '';
+  let quote = null; // ' " or ` — inside a string literal, nothing is a comment
+  for (let i = 0; i < src.length;) {
+    const c = src[i];
+    const d = src[i + 1];
+    if (quote) {
+      if (c === '\\') { out += c + (d ?? ''); i += 2; continue; }
+      if (c === quote) quote = null;
+      out += c; i += 1; continue;
+    }
+    if (c === '"' || c === "'" || c === '`') { quote = c; out += c; i += 1; continue; }
+    if (c === '/' && d === '/') {
+      while (i < src.length && src[i] !== '\n') i += 1; // stop AT the newline, never past it
+      continue;
+    }
+    if (c === '/' && d === '*') {
+      const end = src.indexOf('*/', i + 2);
+      if (end === -1) { out += src.slice(i); break; } // unterminated: keep it
+      out += ' ';
+      i = end + 2;
+      continue;
+    }
+    out += c; i += 1;
+  }
+  return out;
+}
+
+function readFromDisk(rel) {
+  try { return fs.readFileSync(path.join(ROOT, rel), 'utf8'); } catch { return null; }
+}
+
+// The scan, with its file list and its reader INJECTED. A guard tested only
+// against the live tree proves nothing about what it would refuse — the tree is
+// clean today by construction. `read(rel)` returns the source or null.
+function scanGates(files, read) {
+  const violations = [];
+  const warnings = [];
+  let scanned = 0;
+
+  for (const rel of files) {
+    const src = read(rel);
+    if (src == null) {
+      // A missing gate file is a warning, not a pass: the list has drifted from
+      // the repo and someone must re-point it.
+      warnings.push(`${rel} not found — the GATE_FILES list in scripts/bongos/category-advisory-guard.js has drifted; re-point it at the file that replaced it.`);
+      continue;
+    }
+    scanned += 1;
+    const code = stripComments(src);
+    const hits = code.split('\n')
+      .map((line, i) => ({ line: line.trim(), n: i + 1 }))
+      .filter(({ line }) => CATEGORY_RE.test(withoutScriptPaths(line)));
+    for (const { line, n } of hits) {
+      violations.push(
+        `${rel}:${n} reads a work CATEGORY inside a decision surface — \`${line.slice(0, 100)}\`. `
+        + 'A category is ADVISORY: it orients a human and steers Claude, and authorises nothing (task 1003275, ADR 0192). '
+        + 'The real hierarchy with real enforcement is ADR 0086 — gate on scope_modules, rank, membership or dependencies instead. '
+        + 'If this label genuinely must gate something, that is an owner decision and needs its own ADR before this check is relaxed.'
+      );
+    }
+  }
+
+  return { violations, warnings, scanned };
+}
+
+// Half 2: the feature this guard constrains must still be there, or the guard is
+// vacuous and its green tick is a lie (the ADR 0022 assurance-of-assurance finding).
+function scanAnchors(anchors, read) {
+  const violations = [];
+  for (const { file, needle } of anchors) {
+    const src = read(file);
+    if (src == null || !src.includes(needle)) {
+      violations.push(
+        `${file} no longer carries \`${needle}\` — the category feature this guard exists to constrain has moved or been removed, so the guard is now vacuous and would pass an empty repo. `
+        + 'Re-point FEATURE_ANCHORS in scripts/bongos/category-advisory-guard.js, or delete the guard along with the feature.'
+      );
+    }
+  }
+
+  return violations;
+}
+
+function checkCategoryIsAdvisory({ files = GATE_FILES, anchors = FEATURE_ANCHORS, read = readFromDisk } = {}) {
+  const { violations: gateViolations, warnings, scanned } = scanGates(files, read);
+  const violations = gateViolations.concat(scanAnchors(anchors, read));
+  return {
+    name: 'a work category is ADVISORY — no gate reads it (task 1003275 / ADR 0192)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings,
+    note: `${scanned} decision surface(s) scanned (authority, claim eligibility, claimable feed, dependency satisfaction) with comments stripped — a gate may CITE this rule, never branch on it. Plus ${anchors.length} feature anchor(s), so a renamed-away feature fails loudly instead of passing vacuously.`,
+  };
+}
+
+module.exports = { checkCategoryIsAdvisory, scanGates, scanAnchors, GATE_FILES, FEATURE_ANCHORS, stripComments };

package/scripts/bongos/ci-grade.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// scripts/bongos/ci-grade.js — run the quality grader IN CI as a fail-closed PR
+// gate (#855, ADR 0042). This is the security KEYSTONE for the ci deploy mode.
+//
+// WHY it must run in CI (not "read the recorded grade"):
+//   POST /api/bongos/tasks/:id/grade records the grader scores FROM THE REQUEST
+//   BODY — the server does not independently recompute them. In laptop mode the
+//   grader runs on the OPERATOR's trusted machine, so that's fine. In ci mode the
+//   merge trigger moves to an UNTRUSTED builder machine; a tampered local ship.js
+//   could POST a fake passing grade, so a gate that merely READS the recorded
+//   grade is theater. The only tamper-proof gate runs the grader where the
+//   builder can't touch it: here, in GitHub Actions, against the PR diff.
+//
+// It reuses the EXACT production grading path (ship.js runSubagentGrader → the
+// adversarial worker panel / trivial-diff shot), so a CI pass means the same
+// thing a ship-time pass means. Exit 0 = pass, non-zero = fail (FAIL-CLOSED: any
+// grader error also exits non-zero).
+//
+// SKIP-SAFE until armed: if no grader auth is wired (CLAUDE_CODE_OAUTH_TOKEN /
+// ANTHROPIC_API_KEY), it prints SKIP and exits 0 — so merging this workflow
+// changes nothing until the operator (a) adds the auth secret and (b) marks this
+// a REQUIRED check in branch protection. Mirrors the inert-until-cutover pattern
+// of .github/workflows/deploy-prod.yml (#597). See ADR 0042 cutover precondition #1.
+//
+// Inputs (from the workflow env):
+//   GRADE_BASE_REF      base ref to diff against (default origin/main)
+//   GRADE_TASK_ID       the PR's task id (context only; grading is diff-based)
+//   GRADE_TASK_TITLE    the PR title (context for the grader prompt)
+//   GRADE_VALUE_SUMMARY the PR value summary (context for the grader prompt)
+
+const { execFileSync } = require('node:child_process');
+const ship = require('./ship.js');
+
+function git(args) {
+  return execFileSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+}
+
+(async () => {
+  // Auth presence — the grader spawns the `claude` CLI; without auth it cannot
+  // run. Until the operator wires it, stay green-but-not-gating (see header).
+  const hasAuth = !!(process.env.CLAUDE_CODE_OAUTH_TOKEN || process.env.ANTHROPIC_API_KEY);
+  if (!hasAuth) {
+    console.log(
+      'grade-gate: SKIP — no grader auth (CLAUDE_CODE_OAUTH_TOKEN / ANTHROPIC_API_KEY) configured. ' +
+        'This check is green-but-not-gating until the operator wires the secret AND marks it a required check ' +
+        '(ADR 0042 cutover precondition #1). It is NOT a real gate yet.'
+    );
+    process.exit(0);
+  }
+
+  const base = process.env.GRADE_BASE_REF || 'origin/main';
+  let baseline;
+  try {
+    baseline = git(['merge-base', base, 'HEAD']);
+  } catch (_) {
+    baseline = base; // shallow checkout / no common ancestor — diff against the ref directly
+  }
+
+  const changedFiles = ship.computeChangedFiles(baseline);
+  if (!changedFiles.length) {
+    console.log('grade-gate: no changes vs base — pass (nothing to grade).');
+    process.exit(0);
+  }
+
+  const task = {
+    id: process.env.GRADE_TASK_ID || null,
+    title: process.env.GRADE_TASK_TITLE || '(pull request)',
+  };
+  const valueSummary = process.env.GRADE_VALUE_SUMMARY || '';
+
+  console.log(`grade-gate: grading ${changedFiles.length} changed file(s) vs ${baseline.slice(0, 12)} ...`);
+  const result = await ship.runSubagentGrader({ task, valueSummary, baseline, changedFiles });
+
+  console.log(`grade-gate: verdict = ${result.passed ? 'PASS' : 'FAIL'}`);
+  if (result.notes_md) console.log(String(result.notes_md).slice(0, 6000));
+  // Fail-closed: only an explicit pass exits 0.
+  process.exit(result.passed ? 0 : 1);
+})().catch((err) => {
+  // FAIL-CLOSED: a grader error must block the merge, never wave it through.
+  console.error('grade-gate: FAIL (grader error — failing closed):', err && err.message ? err.message : err);
+  process.exit(1);
+});

package/scripts/bongos/claim-recall.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+// Claim-time recall hits (#956 / V4.R18 — criterion sessions-start-knowing).
+//
+// When a builder claims a task, surface the top project-knowledge sources for it
+// (POST /api/bongos/search — the rank/owner-scoped lexical recall layer, ADR 0060) so
+// the work starts already pointed at the relevant ADRs / recipes / session-logs /
+// learnings instead of re-discovering them. This is the claim-time half of the
+// recall surface the V4.R04 context pack (#942) promised; #963 added the
+// resumed-session (SessionStart) half. The two share the same /api/bongos/search call
+// and the same title-cleaning, so a session sees the same knowledge whether it
+// claims fresh or resumes.
+//
+// Contract (mirrors printRelevantLearnings in claim.js): best-effort + SILENT on
+// any failure — it must NEVER block or delay a successful claim. The rows are
+// merged with the learnings surface and deduped, so a learning and its indexed
+// search chunk don't echo each other.
+
+const RECALL_LIMIT = 5;
+
+// ---- pure helpers (exported for tests) -------------------------------------
+
+// Build the search query from the claimed task: the title with the decorative
+// "V4.R18 — " rank prefix and any trailing "(...)" aside stripped (same cleaning
+// as the #963 SessionStart hint), plus a short single-line lead from the
+// description — so the query is the substantive phrase, not planning chrome. The
+// description lead is what distinguishes this from #963's title-only hint: a claim
+// happens with the full task in hand, so we use it.
+function claimRecallQuery(task) {
+  const rawTitle = String((task && task.title) || '').trim();
+  let title = rawTitle
+    .replace(/^[A-Za-z0-9.]+\s+[—-]\s+/, '') // leading "V4.R18 — " / "R18 - " (require spaces around the dash so an in-word hyphen like "co-located" isn't eaten)
+    .replace(/\s*\([^)]*\)\s*$/, '')          // trailing parenthetical aside
+    .trim();
+  if (!title) title = rawTitle; // stripping emptied it → fall back to the raw title
+  const descLead = String((task && task.description) || '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 160)
+    .trim();
+  return [title, descLead].filter(Boolean).join(' ').trim();
+}
+
+// The dedup identities for a row (a recall result OR a learning). A row is a
+// duplicate of another surface if ANY of its keys collide — we key on both the
+// source ref and the title because a learning's ref in the `learnings` table and
+// its indexed `search_chunks` ref don't always match, but the titles do.
+function rowKeys(row) {
+  const keys = [];
+  const ref = row
+    && (row.source_ref || row.source || (Array.isArray(row.related_files) && row.related_files[0]));
+  if (ref) keys.push(`ref:${String(ref).toLowerCase()}`);
+  const t = row && (row.title || row.heading_path);
+  if (t) keys.push(`title:${String(t).toLowerCase()}`);
+  return keys;
+}
+
+// Render the top-N recall sources as a printable block, dropping:
+//   - the claimed task's OWN indexed chunk (source_ref `task:<id>`) — the builder
+//     already holds the task; echoing it is noise (same filter as #963);
+//   - any row that collides with an already-shown learning (`excludeKeys`).
+// Returns null when nothing is left to show, so the caller stays silent.
+function formatRecallSources(results, { limit = RECALL_LIMIT, excludeKeys = [], currentTaskId = null } = {}) {
+  const selfKey = currentTaskId != null ? `ref:task:${String(currentTaskId).toLowerCase()}` : null;
+  const seen = new Set((excludeKeys || []).map((k) => String(k).toLowerCase()));
+  if (selfKey) seen.add(selfKey);
+  const rows = [];
+  for (const r of (Array.isArray(results) ? results : [])) {
+    const keys = rowKeys(r);
+    if (keys.length === 0) continue;
+    if (keys.some((k) => seen.has(k))) continue; // self-match or learning dup
+    keys.forEach((k) => seen.add(k));            // also dedup within the recall set
+    rows.push(r);
+    if (rows.length >= limit) break;
+  }
+  if (rows.length === 0) return null;
+  const lines = [`\n🔎 Relevant project knowledge (${rows.length}):`];
+  for (const r of rows) {
+    const where = r.heading_path || r.source_ref || '';
+    const title = r.title || r.source_ref || '(untitled)';
+    lines.push(`  - ${title}${where ? `  — ${where}` : ''}`);
+  }
+  lines.push('  (rank-scoped recall; run /recall <query> to dig further)');
+  return lines.join('\n');
+}
+
+// ---- network leg (fail-open) -----------------------------------------------
+
+// Query the recall layer for the claimed task and print the top sources, deduped
+// against the learnings already printed (`excludeKeys`). Best-effort + silent —
+// never block a claim. Uses the shared client (throwOnError:false → {status, ok,
+// data}; it does NOT exit the process on a non-2xx, so a swallow here is safe).
+async function printClaimRecall(task, { excludeKeys = [] } = {}) {
+  const q = claimRecallQuery(task);
+  if (!q) return;
+  try {
+    // Over-fetch so dropping the self-match + learning dups still leaves a full set.
+    const limit = RECALL_LIMIT + (excludeKeys ? excludeKeys.length : 0) + 3;
+    const { cliClient } = require('./cli-lib');
+    const api = await cliClient();
+    const r = await api.search.postSearch({ body: { q, limit } });
+    if (!r || r.status !== 200 || !r.data || !Array.isArray(r.data.results)) return;
+    const block = formatRecallSources(r.data.results, {
+      excludeKeys,
+      currentTaskId: task && task.id,
+    });
+    if (block) console.log(block);
+  } catch (_) {
+    // swallow — never block a successful claim on a recall lookup
+  }
+}
+
+module.exports = { claimRecallQuery, rowKeys, formatRecallSources, printClaimRecall, RECALL_LIMIT };