@bugb-technologies/bravos 0.0.0-stage → 1.0.0

package/hooks/lib/pre-pr.mjs

@@ -0,0 +1,209 @@
+// @comment -- "The pre-PR gate behind bravos's opt-in PreToolUse hook, matching bravos-ship's rulings: recognises gh pr create / gh pr ready in a Bash command, runs guardlink validate, lint --since <base> --json, diff <base> --json (each new unmitigated exposure must be disclosed in the PR body by threat and asset id) and ci -f json (a confirmed claim on a changed file blocks unless that file carries a @ticket for it), and returns allow or block with a reason. A gate input that fails or does not parse blocks as unknown. Read-only: every command is spawned with an argv array, no shell, a per-spawn timeout and one shared deadline."
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+
+const PR_COMMAND = /(?:^|[\s;&|(])gh\s+pr\s+(create|ready)(?![\w-])/;
+const READY_ARG = /(?:^|[\s;&|(])gh\s+pr\s+ready\s+([^\s;&|)-][^\s;&|)]*)/;
+const BODY_FILE = /(?:--body-file|-F)[=\s]+("([^"]+)"|'([^']+)'|(\S+))/;
+// @comment -- "The hook is registered with a 180 s timeout; the whole gate shares 150 s so it always answers before the harness kills it."
+export const GATE_DEADLINE_MS = 150000;
+// @comment -- "The person's recorded proving preference (see autopilot.mjs readProving); a branch that changes it must disclose that in the PR body."
+export const PROVING_FILE = '.guardlink/proving.md';
+const SPAWN_CAP_MS = 60000;
+
+/** Which gh pr action a shell command runs, or null when it runs neither. */
+export function prAction(command) {
+  if (typeof command !== 'string') return null;
+  const m = PR_COMMAND.exec(command);
+  return m ? m[1] : null;
+}
+
+/** The PR number, URL or branch `gh pr ready <arg>` names, or null for the current branch's PR. */
+export function readyTarget(command) {
+  const m = READY_ARG.exec(command ?? '');
+  return m ? m[1].replace(/^["']|["']$/g, '') : null;
+}
+
+/**
+ * The PR body text a `gh pr create` command carries: the command string itself (an inline --body or a
+ * heredoc is part of it) plus the file a --body-file / -F names, resolved under the project root.
+ */
+// @comment -- "Reads the PR body from the command string (inline --body or heredoc) and from the --body-file / -F path it names, resolved under the project root; an unreadable file adds nothing."
+export function commandBody(command, root) {
+  let body = typeof command === 'string' ? command : '';
+  const m = BODY_FILE.exec(body);
+  if (!m) return body;
+  const rel = m[2] ?? m[3] ?? m[4];
+  if (rel === '-') return body;
+  const path = isAbsolute(rel) ? rel : join(root, rel);
+  try {
+    if (existsSync(path)) body += '\n' + readFileSync(path, 'utf8');
+  } catch {
+    // unreadable: the command text alone is the body
+  }
+  return body;
+}
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** Whether `text` names the threat-model id `id` as a whole token (`#api` is not found in `#api-key`). */
+export function mentionsId(text, id) {
+  if (typeof id !== 'string' || id === '') return false;
+  return new RegExp(`(?<![\\w#.-])${escapeRe(id)}(?![\\w-])`).test(text);
+}
+
+/** Default runner: argv array, no shell, stdin closed, timeout capped at 60 s. */
+export function spawnRunner(cmd, args, { cwd, env, timeoutMs = SPAWN_CAP_MS }) {
+  const r = spawnSync(cmd, args, { cwd, env, timeout: Math.min(SPAWN_CAP_MS, timeoutMs), encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] });
+  if (r.error) return { missing: r.error.code === 'ENOENT', error: r.error.code ?? r.error.message, status: null, stdout: '', stderr: '' };
+  return { status: r.status, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
+}
+
+/** Wraps a runner so every spawn gets min(60 s, what is left of the shared deadline); past the deadline nothing is spawned. */
+// @comment -- "Shared-deadline runner, as briefing.mjs collect() does: each spawn is capped individually and by the time left, and a spawn after the deadline returns a timed-out result instead of running."
+export function withDeadline(run, deadlineMs = GATE_DEADLINE_MS, now = Date.now) {
+  const deadline = now() + deadlineMs;
+  return (cmd, args, opts) => {
+    const left = deadline - now();
+    if (left <= 0) return { status: null, error: 'ETIMEDOUT', stdout: '', stderr: '' };
+    return run(cmd, args, { ...opts, timeoutMs: Math.min(SPAWN_CAP_MS, left) });
+  };
+}
+
+const tail = (s, n = 40) => s.trim().split('\n').slice(-n).join('\n');
+const why = (r) => (r.error === 'ETIMEDOUT' ? 'timed out' : r.error ? r.error : `exited ${r.status}`);
+
+/** Runs a command and parses its stdout as JSON: `{ ok: true, json }` or `{ ok: false, error }` naming what failed. */
+function runJson(run, label, cmd, args, opts, okStatus = [0]) {
+  const r = run(cmd, args, opts);
+  if (r.error || !okStatus.includes(r.status)) return { ok: false, error: `${label} ${why(r)}`, detail: tail((r.stdout ?? '') + (r.stderr ?? ''), 10) };
+  try {
+    return { ok: true, json: JSON.parse(r.stdout) };
+  } catch {
+    return { ok: false, error: `${label} output was not JSON`, detail: tail(r.stdout ?? '', 10) };
+  }
+}
+
+/** The repository root for a working directory: git's top level, else CLAUDE_PROJECT_DIR, else the directory itself. */
+// @comment -- "guardlink reports paths relative to the directory it runs in and git diff --name-only reports them relative to the top level, so the gate must run everything from the top level: a payload cwd in a subdirectory otherwise empties the confirmed-on-changed-file intersection and the gate passes."
+export function resolveRoot(cwd, env = process.env, run = spawnRunner) {
+  const top = run('git', ['rev-parse', '--show-toplevel'], { cwd, env });
+  if (top.status === 0 && top.stdout.trim()) return top.stdout.trim();
+  return env.CLAUDE_PROJECT_DIR || cwd;
+}
+
+/** The merge base the gate judges against, or null when it cannot be found. */
+export function findBase(root, env, run = spawnRunner) {
+  const head = run('git', ['symbolic-ref', '-q', '--short', 'refs/remotes/origin/HEAD'], { cwd: root, env });
+  const def = head.status === 0 && head.stdout.trim() ? head.stdout.trim().replace(/^origin\//, '') : 'main';
+  for (const ref of [`origin/${def}`, def]) {
+    const mb = run('git', ['merge-base', 'HEAD', ref], { cwd: root, env });
+    if (mb.status === 0 && mb.stdout.trim()) return mb.stdout.trim();
+  }
+  return null;
+}
+
+/** Whether `file` (repo-relative, under root) has a `@ticket` line naming both `threat` and `asset`. */
+// @comment -- "The ship gate's carve-out for a confirmed claim: a @ticket line in the same file naming that threat and that asset. Who wrote it is bravos-ship's check (blame), not this hook's."
+export function hasTicket(root, file, threat, asset) {
+  let text;
+  try {
+    text = readFileSync(isAbsolute(file) ? file : join(root, file), 'utf8');
+  } catch {
+    return false;
+  }
+  return text.split('\n').some((l) => l.includes('@ticket') && mentionsId(l, threat) && mentionsId(l, asset));
+}
+
+/**
+ * Decide whether a gh pr action may proceed. Returns { decision: 'allow' | 'block', reason }.
+ * Fails open (allow, with the reason) only when it cannot judge at all: guardlink absent or no merge base.
+ * Every other input that fails or does not parse blocks as "unknown".
+ */
+// @comment -- "validate, lint, the disclosure check and the confirmed check gate create and ready; an @exposes plus @audit stays listed by design and is reported, so disclosure by id in the PR body is the only way past a new exposure. Every command runs with cwd root; a --body-file is resolved against cwd, where the gh command would run. On ready the body comes from gh pr view, and a failed read blocks as unknown. action 'check' (a manual run before any PR exists) has no body: it lists the new exposures to disclose and blocks only on lint, confirmed claims and unknown inputs."
+export function runGate({ root, action, command, cwd = root, env = process.env, run: baseRun = spawnRunner, deadlineMs = GATE_DEADLINE_MS }) {
+  const run = withDeadline(baseRun, deadlineMs);
+  const o = { cwd: root, env };
+  const validate = run('guardlink', ['validate', '.'], o);
+  if (validate.missing) return { decision: 'allow', reason: 'bravos pre-PR gate: guardlink not on PATH, nothing checked' };
+  if (validate.error) return { decision: 'block', reason: `bravos pre-PR gate: unknown: guardlink validate ${why(validate)}` };
+  if (validate.status !== 0) {
+    return { decision: 'block', reason: `bravos pre-PR gate: guardlink validate failed. Fix what it reports, or run bravos-ship.\n${tail(validate.stdout + validate.stderr)}` };
+  }
+
+  const base = findBase(root, env, run);
+  if (!base) return { decision: 'allow', reason: 'bravos pre-PR gate: no merge base with the default branch found, lint, diff and ci not run' };
+
+  const blocks = [];
+  const notes = [];
+  const unknown = (r) => blocks.push(`unknown: ${r.error}${r.detail ? `\n${r.detail}` : ''}`);
+
+  // (a) lint errors on the branch's claims. lint exits non-zero when it reports errors, so its JSON decides.
+  const lint = runJson(run, `guardlink lint --since ${base}`, 'guardlink', ['lint', '.', '--since', base, '--json'], o, [0, 1]);
+  const errors = lint.ok ? lint.json?.summary?.errors : undefined;
+  if (!lint.ok) unknown(lint);
+  else if (typeof errors !== 'number') unknown({ error: `guardlink lint --since ${base} JSON has no summary.errors` });
+  else if (errors > 0) blocks.push(`guardlink lint --since ${base} reports ${errors} error(s). Apply each violation's fix to lines this branch wrote (bravos-ship), then retry.`);
+
+  // (b) each new unmitigated exposure is disclosed in the PR body by its threat and asset ids.
+  const diff = runJson(run, `guardlink diff ${base}`, 'guardlink', ['diff', base, '--json'], o);
+  const fresh = diff.ok ? diff.json?.newUnmitigatedExposures : undefined;
+  if (!diff.ok) unknown(diff);
+  else if (!Array.isArray(fresh)) unknown({ error: `guardlink diff ${base} JSON has no newUnmitigatedExposures` });
+  else if (fresh.length > 0) {
+    const list = (xs) => xs.map((e) => `  - ${e?.threat ?? '?'} on ${e?.asset ?? '?'} — ${e?.location?.file ?? '?'}:${e?.location?.line ?? '?'}`).join('\n');
+    let body = null;
+    if (action === 'create') body = commandBody(command, cwd);
+    else if (action === 'ready') {
+      const target = readyTarget(command);
+      const view = runJson(run, 'gh pr view', 'gh', ['pr', 'view', ...(target ? [target] : []), '--json', 'body'], o);
+      if (view.ok && typeof view.json?.body === 'string') body = view.json.body;
+      else unknown(view.ok ? { error: 'gh pr view JSON has no body' } : { error: 'gh pr view failed', detail: view.error });
+    } else {
+      notes.push(`bravos pre-PR gate: ${fresh.length} new unmitigated exposure(s) against ${base}, to disclose in the PR body by threat and asset id:\n${list(fresh)}`);
+    }
+    if (body !== null) {
+      const undisclosed = fresh.filter((e) => !(mentionsId(body, e?.threat) && mentionsId(body, e?.asset)));
+      if (undisclosed.length > 0) {
+        blocks.push(`this branch adds unmitigated exposure against ${base} that the PR body does not disclose. Name each threat and asset id in the PR body's Security gate section (bravos-ship writes it), then retry:\n${list(undisclosed)}`);
+      }
+    }
+  }
+
+  // (c) a confirmed-exploitable claim on a changed file blocks unless that file carries a @ticket for it.
+  const ci = runJson(run, 'guardlink ci -f json', 'guardlink', ['ci', '-f', 'json'], o);
+  const confirmed = ci.ok ? ci.json?.confirmed : undefined;
+  if (!ci.ok) unknown(ci);
+  else if (!Array.isArray(confirmed)) unknown({ error: 'guardlink ci -f json has no confirmed[]' });
+  else if (confirmed.length > 0) {
+    const names = run('git', ['diff', '--name-only', `${base}...HEAD`], o);
+    if (names.error || names.status !== 0) unknown({ error: `git diff --name-only ${base}...HEAD ${why(names)}` });
+    else {
+      const changed = new Set(names.stdout.split('\n').map((s) => s.trim()).filter(Boolean));
+      const hits = confirmed.filter((c) => changed.has(c?.location?.file) && !hasTicket(root, c.location.file, c?.threat, c?.asset));
+      if (hits.length > 0) {
+        const list = hits.map((c) => `  - ${c?.severity ?? 'unrated'} ${c?.threat ?? '?'} on ${c?.asset ?? '?'} — ${c.location.file}:${c?.location?.line ?? '?'}`);
+        blocks.push(`confirmed-exploitable claims sit on files this branch changes, with no @ticket for them in that file. A code change does not clear a confirmation; do not ship (bravos-ship step 7):\n${list.join('\n')}`);
+      }
+    }
+  }
+
+  // (d) a change to the recorded proving preference is a team decision: the PR body must say so.
+  const touched = run('git', ['diff', '--name-only', `${base}...HEAD`], o);
+  if (touched.status === 0 && touched.stdout.split('\n').some((l) => l.trim() === PROVING_FILE)) {
+    let body = null;
+    if (action === 'create') body = commandBody(command, cwd);
+    else if (action === 'ready') {
+      const view = runJson(run, 'gh pr view', 'gh', ['pr', 'view', ...(readyTarget(command) ? [readyTarget(command)] : []), '--json', 'body'], o);
+      body = view.ok && typeof view.json?.body === 'string' ? view.json.body : null;
+      if (body === null) unknown(view.ok ? { error: 'gh pr view JSON has no body' } : { error: 'gh pr view failed', detail: view.error });
+    }
+    const say = `this branch changes ${PROVING_FILE}, how the team wants findings proven; say "proving preference" in the PR body with what changed, so reviewers see it`;
+    if (action === 'check') notes.push(`bravos pre-PR gate: ${say}.`);
+    else if (body !== null && !/proving preference/i.test(body)) blocks.push(`${say}, then retry.`);
+  }
+
+  if (blocks.length > 0) return { decision: 'block', reason: ['bravos pre-PR gate: blocked.', ...blocks.map((b) => `- ${b}`), ...notes].join('\n') };
+  return { decision: 'allow', reason: notes.join('\n') };
+}

package/hooks/lib/sast.mjs

@@ -0,0 +1,207 @@
+// @comment -- "Reads bravos-sast's runs under .bravos/sast/<run>/ (bravos-cli analyze's bravos.analyze-report/v1 JSON plus bravos's meta.json): the newest run's counts, reach and staleness for the briefing, and its reachable findings grouped as candidates (joined to a GuardLink claim, not yet in the threat model, dependencies, secrets) for annotate, templatize, prove and recheck. Read-only; a missing or malformed report reads as null, never as zero findings. Dependency-free so it can be copied into target repos."
+import { spawnSync } from 'node:child_process';
+import { accessSync, constants, existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { delimiter, dirname, join } from 'node:path';
+import { status as licenceStatus } from './licence.mjs';
+
+export const REPORT_SCHEMA = 'bravos.analyze-report/v1';
+export const CANDIDATES_SCHEMA = 'bravos.sast-candidates/v1';
+const SAST_DIR = join('.bravos', 'sast');
+
+const arr = (v) => (Array.isArray(v) ? v : []);
+
+/** The report file inside a run folder: bravos-cli writes JSON next to the SARIF; the name varies by version. */
+function reportFile(dir) {
+  for (const name of ['report.json', 'analysis.json', 'bravos-analyze.json']) if (existsSync(join(dir, name))) return join(dir, name);
+  const json = readdirSync(dir).filter((n) => n.endsWith('.json') && n !== 'meta.json' && !n.startsWith('candidates'));
+  return json.length ? join(dir, json.sort()[0]) : null;
+}
+
+// @comment -- "Finds the newest run folder under .bravos/sast/ (by meta.json time, else folder mtime) and returns its parsed report and meta, or null when there is none or it is not a bravos.analyze-report/v1."
+export function latestRun(root) {
+  const base = join(root, SAST_DIR);
+  if (!existsSync(base)) return null;
+  const runs = [];
+  for (const name of readdirSync(base)) {
+    const dir = join(base, name);
+    try {
+      if (!statSync(dir).isDirectory()) continue;
+    } catch {
+      continue;
+    }
+    let meta = null;
+    try {
+      meta = JSON.parse(readFileSync(join(dir, 'meta.json'), 'utf8'));
+    } catch {
+      meta = null;
+    }
+    const at = Date.parse(meta?.at ?? '') || statSync(dir).mtimeMs;
+    runs.push({ name, dir, meta, at });
+  }
+  runs.sort((a, b) => b.at - a.at);
+  for (const run of runs) {
+    const file = reportFile(run.dir);
+    if (!file) continue;
+    try {
+      const report = JSON.parse(readFileSync(file, 'utf8'));
+      if (report?.schema !== REPORT_SCHEMA || !Array.isArray(report.findings)) continue;
+      return { ...run, file, report };
+    } catch {
+      /* unreadable: try the next run */
+    }
+  }
+  return null;
+}
+
+const isSecret = (f) => f?.finding_class === 'secret';
+const isDep = (f) => f?.finding_class === 'dependency';
+const joined = (f) => f?.guardlink_join && f.guardlink_join !== 'unjoined' && f.guardlink_join !== 'none';
+
+// @comment -- "Summarizes the newest run for the briefing: findings by class and severity, reachable, reachable but not in the threat model, suppressed, and how many commits the report is behind HEAD (from meta.json's sha). Null when there is no usable report."
+export function readSast(root, env = process.env) {
+  const run = latestRun(root);
+  if (!run) return null;
+  const findings = arr(run.report.findings);
+  const live = findings.filter((f) => !f?.suppressed);
+  const reachable = live.filter((f) => f?.reachable === true);
+  const byClass = {};
+  for (const f of live) byClass[f?.finding_class ?? 'static_analysis'] = (byClass[f?.finding_class ?? 'static_analysis'] ?? 0) + 1;
+  let staleCommits = null;
+  if (typeof run.meta?.sha === 'string' && /^[0-9a-f]{7,40}$/.test(run.meta.sha)) {
+    const r = spawnSync('git', ['rev-list', '--count', `${run.meta.sha}..HEAD`], { cwd: root, env, encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] });
+    if (r.status === 0) staleCommits = Number(r.stdout.trim());
+  }
+  return {
+    run: run.name,
+    sha: run.meta?.sha ?? null,
+    exit: run.meta?.exit ?? null,
+    total: live.length,
+    reachable: reachable.length,
+    unjoinedReachable: reachable.filter((f) => !joined(f) && !isSecret(f)).length,
+    suppressed: findings.length - live.length,
+    byClass,
+    staleCommits,
+  };
+}
+
+const where = (f) => ({
+  rule: f?.rule_id ?? null,
+  title: f?.title ?? null,
+  severity: f?.severity ?? null,
+  file: f?.file ?? null,
+  line: f?.line ?? null,
+  route: f?.http_method || f?.http_path ? `${f.http_method ?? ''} ${f.http_path ?? ''}`.trim() : null,
+  entryPoint: f?.entry_point ?? null,
+  pathLength: f?.path_length ?? null,
+  function: f?.enclosing_function ?? null,
+});
+
+// @comment -- "Groups the newest run's non-suppressed findings for the other skills: joined to a claim (taint evidence for that threat), reachable but unjoined (leads for bravos-annotate), dependencies (with vulnerable-function reach) and secrets (never pentest candidates; the value is never included). Only reachable findings unless all is set."
+export function sastCandidates(root, { all = false } = {}) {
+  const run = latestRun(root);
+  if (!run) return null;
+  const live = arr(run.report.findings).filter((f) => !f?.suppressed && (all || f?.reachable === true || isSecret(f)));
+  const out = { schema: CANDIDATES_SCHEMA, run: run.name, sha: run.meta?.sha ?? null, joined: [], unjoined: [], dependencies: [], secrets: [] };
+  for (const f of live) {
+    if (isSecret(f)) out.secrets.push({ rule: f?.rule_id ?? null, file: f?.file ?? null, line: f?.line ?? null, inHistory: !!f?.secret_in_history });
+    else if (isDep(f)) out.dependencies.push({ ...where(f), manifests: arr(f?.dep_manifests), devOnly: !!f?.dep_dev_only, vulnerableFunctionReached: f?.vulnerable_function_reachability ?? null });
+    else if (joined(f)) out.joined.push({ ...where(f), claimState: f.guardlink_join, confirmed: !!f?.guardlink_confirmed, accepted: !!f?.guardlink_accepted });
+    else out.unjoined.push(where(f));
+  }
+  return out;
+}
+
+// @comment -- "The Python bravos CLI (siete) on PATH, as `bravos` or renamed to `bravos-py`, and never this package's own `bravos` bin: an npm shim is a script that execs node on dist/cli.js, and skipping it keeps the hooks pointed at the Python install's analyzer and graph until phase 3 makes this CLI carry them."
+export function pythonBravos(env = process.env) {
+  // Its own name first, then bravos-py: the name it keeps once it is renamed so `bravos` means this CLI.
+  for (const name of ['bravos', 'bravos-py']) {
+    for (const dir of (env.PATH ?? '').split(delimiter)) {
+      if (!dir) continue;
+      const file = join(dir, name);
+      try {
+        if (!statSync(file).isFile()) continue;
+        accessSync(file, constants.X_OK);
+        const real = realpathSync(file);
+        if (real.endsWith('dist/cli.js') || readFileSync(real, 'utf8').includes('dist/cli.js')) continue;
+        return file;
+      } catch {
+        /* not here */
+      }
+    }
+  }
+  return null;
+}
+
+function onPath(name, env) {
+  for (const dir of (env?.PATH ?? '').split(delimiter)) {
+    if (!dir) continue;
+    try {
+      accessSync(join(dir, name), constants.X_OK);
+      return join(dir, name);
+    } catch {
+      /* keep looking */
+    }
+  }
+  return null;
+}
+
+// @comment -- "Finds bravos-cli the way the bravos launcher puts it on its own PATH: on PATH first, else <install>/analyzer/bravos-cli beside the real path of the bravos launcher (<install>/bin/bravos). Read-only; null when neither has it."
+export function findAnalyzer(env = process.env) {
+  // The bundle bravos setup staged wins; then PATH; then the Python install's own copy.
+  const home = env.BRAVOS_HOME || (env.HOME ? join(env.HOME, '.bravos') : null);
+  if (home) {
+    const stagedBin = join(home, 'analyzer', 'current', 'bravos-cli');
+    try {
+      accessSync(stagedBin, constants.X_OK);
+      return realpathSync(stagedBin);
+    } catch {
+      /* not staged */
+    }
+  }
+  const direct = onPath('bravos-cli', env);
+  if (direct) return direct;
+  const launcher = pythonBravos(env);
+  if (!launcher) return null;
+  try {
+    const file = join(dirname(dirname(realpathSync(launcher))), 'analyzer', 'bravos-cli');
+    accessSync(file, constants.X_OK);
+    return file;
+  } catch {
+    return null;
+  }
+}
+
+// @comment -- "Where a Bravos licence is, read-only: BRAVOS_LICENCE / BRAVOS_LICENSE, else licence.jwt or license.jwt in $BRAVOS_HOME, ~/.bravos, or ~/.bugb (where bravos still keeps its state until ~/.bravos holds some). Returns a short label for the source, or null."
+export function findLicence(env = process.env) {
+  if (env.BRAVOS_LICENCE) return 'BRAVOS_LICENCE';
+  if (env.BRAVOS_LICENSE) return 'BRAVOS_LICENSE';
+  const homes = [env.BRAVOS_HOME, env.HOME && join(env.HOME, '.bravos'), env.HOME && join(env.HOME, '.bugb')].filter(Boolean);
+  for (const home of homes) {
+    for (const name of ['licence.jwt', 'license.jwt']) {
+      if (existsSync(join(home, name))) return home === env.BRAVOS_HOME ? `$BRAVOS_HOME/${name}` : `${home.replace(env.HOME, '~')}/${name}`;
+    }
+  }
+  return null;
+}
+
+// @comment -- "Whether SAST can run here at all, read-only: bravos-cli found (findAnalyzer) and a licence that verifies to a paid tier (licence.mjs). On success it names the analyzer's path, which a skill uses when bravos-cli is only inside the bravos install."
+export function sastAvailable(env = process.env) {
+  const analyzer = findAnalyzer(env);
+  if (!analyzer) return { ok: false, missing: 'bravos-cli' };
+  // Presence is not enough: the licence must verify and be a paid tier that is not expired.
+  const v = licenceStatus(env);
+  if (!v.licensed) return { ok: false, missing: 'licence', analyzer, state: v.state };
+  return { ok: true, analyzer, licence: v.source };
+}
+
+// @comment -- "The one SAST line the briefing and bravos sast status print: the newest run's counts and age, or why there is none (not run here, or unavailable and what is missing)."
+export function sastLine(summary, available, licence = null) {
+  // An unlicensed machine is told once, by the plan line; here only that SAST is among the locked features.
+  if (licence && !licence.licensed && !summary) return 'SAST: on the Team plan (see Plan above); skills carry on without it';
+  if (summary) {
+    const age = summary.staleCommits === null ? '' : summary.staleCommits === 0 ? ', current' : `, ${summary.staleCommits} commit${summary.staleCommits === 1 ? '' : 's'} old`;
+    return `SAST: ${summary.total} findings (${summary.reachable} reachable, ${summary.unjoinedReachable} not in the threat model) at ${summary.sha ? summary.sha.slice(0, 9) : summary.run}${age} — bravos sast candidates`;
+  }
+  if (available?.ok) return `SAST: not run here — bravos-sast runs it (bravos-cli${available.analyzer && !available.analyzer.endsWith('/bin/bravos-cli') ? ` at ${available.analyzer}` : ''} and a licence are present)`;
+  return `SAST: unavailable here — ${available?.missing === 'licence' ? 'the person activates their Bravos licence (bravos account activate)' : 'bravos-sast installs bravos-cli with the person\'s go-ahead (bravos setup)'}; skills carry on without it`;
+}

package/hooks/lib/setup.mjs

@@ -0,0 +1,107 @@
+// @comment -- "bravos's setup score: which of the nine capabilities are switched on in this repo (intent, coverage, autopilot, pre-PR gate, code graph, proving preference, test target, CI, SAST), what each unlocks, how to switch it on in the harness's own words, and the next one to unlock. Pure over inputs collect() already gathered plus two file checks; read-only, no model."
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const SETUP_SCHEMA = 'bravos.setup/v1';
+const SIGIL = { claude: '/', codex: '$', omp: '/skill:', opencode: '/' };
+
+/** A skill the person can invoke: /bravos-x, $bravos-x, /skill:bravos-x, or "the bravos-x skill" elsewhere. */
+const skill = (name, harness) => (SIGIL[harness] ? `${SIGIL[harness]}${name}` : `the ${name} skill`);
+
+// @comment -- "Builds the nine setup items in dependency order: the code graph first (a machine step every later skill reads), then intent (people), coverage (annotate reads intent and the graph), SAST (reads the annotations), how findings are proven and a test target (needed to test), then the gates (autopilot, pre-PR, CI). Each has its done-state, what it unlocks and how, with skills in the harness syntax. bravos assumes a licensed bravos-cli, so a missing one is a to-do, not 'not available'."
+export function readSetup(root, i = {}, harness = 'other') {
+  const coverage = Number(i.guardlink?.ci?.summary?.coverage?.percent);
+  const items = [
+    {
+      id: 'graph',
+      on: i.codegraph === 'current' || i.codegraph === 'unknown' || i.codegraph === 'cli',
+      label: i.codegraph === 'not-built' ? 'rebuild the code graph for this commit' : 'build the code graph',
+      cta: `say "build the code graph"`,
+      unlocks: 'every later step reads it: real routes for intent, reach for annotate, call paths for templates, callers for rechecks',
+      how: `${i.codegraph === 'not-built' ? 'bravos has no graph for this commit (it keys a graph to the commit it was built at); ' : ''}ask "build the code graph" (${skill('bravos-codegraph', harness)}): the agent builds it with bravos graph build . --scip no-exec (no tokens, a few minutes; bravos setup first if bravos is missing, with your go-ahead) and asks it through bravos graph, no reconnect needed`,
+    },
+    {
+      id: 'intent',
+      on: i.intent?.status && i.intent.status !== 'none',
+      label: 'record what the app intends',
+      cta: skill('bravos-context', harness),
+      unlocks: 'severities judged against what the software is meant to do and which attackers are in scope',
+      how: `ask "learn what this app intends" (${skill('bravos-context', harness)})`,
+    },
+    {
+      id: 'coverage',
+      on: Number.isFinite(coverage) && coverage >= 80,
+      label: `cover the code${Number.isFinite(coverage) ? ` (now ${coverage}%)` : ''}`,
+      cta: skill('bravos-annotate', harness),
+      unlocks: 'the agent sees the security facts of the files it touches; SAST reads them',
+      how: `ask "annotate the uncovered files" (${skill('bravos-annotate', harness)}, or ${skill('bravos-campaign', harness)} for all of it)`,
+    },
+    {
+      id: 'sast',
+      on: !!i.sast?.summary,
+      label: 'run SAST',
+      cta: skill('bravos-sast', harness),
+      unlocks: 'dependency CVEs, secrets and request-to-sink taint feed annotate, templatize and prove',
+      how: i.sast?.available?.ok ? `ask "run SAST" (${skill('bravos-sast', harness)}), after annotating so it reads the threat model` : `ask "set up SAST" (${skill('bravos-sast', harness)}): the agent installs bravos-cli with your go-ahead (bravos setup); activate your licence with bravos account activate`,
+    },
+    {
+      id: 'proving',
+      on: i.proving?.status === 'set',
+      label: 'choose how findings are proven',
+      cta: 'say "prove the top 3"',
+      unlocks: '"prove the top 3" runs the way the team chose, without asking each time',
+      how: `ask "prove the top 3 threats" — the agent asks once how you want proving handled (${skill('bravos-prove', harness)})`,
+    },
+    {
+      id: 'target',
+      on: existsSync(join(root, '.guardlink', 'scope.yaml')) || !!i.proving?.target,
+      label: 'set up a test target',
+      cta: skill('bravos-env', harness),
+      unlocks: 'exposures can be tested for real instead of argued about',
+      how: `ask "bring up a test target" (${skill('bravos-env', harness)}); bravos sync --scope writes the loopback-only starter`,
+    },
+    {
+      id: 'autopilot',
+      on: !!i.autopilot,
+      label: 'turn on autopilot',
+      cta: 'bravos sync --autopilot',
+      unlocks: 'annotations and rechecks happen at the end of each turn without being asked',
+      how: 'bravos sync --autopilot (cheap; fine to switch on early)',
+    },
+    {
+      id: 'prepr',
+      on: !!i.prePr,
+      label: 'turn on the pre-PR gate',
+      cta: 'bravos sync --pre-pr-hook',
+      unlocks: 'no pull request goes out with undisclosed exposure or a confirmed exploit',
+      how: 'bravos sync --pre-pr-hook (autopilot turns it on too)',
+    },
+    {
+      id: 'ci',
+      on: existsSync(join(root, '.github', 'workflows', 'bravos-pr-gate.yml')),
+      label: 'add the CI gate and nightly',
+      cta: 'bravos sync --ci',
+      unlocks: 'the whole team is gated, and upkeep runs while laptops are closed',
+      how: 'bravos sync --ci, then commit .github/workflows/',
+    },
+  ].map((x) => ({ ...x, on: !!x.on }));
+  // Paid steps on an unlicensed machine say so in their `how` and are never the next step: the score
+  // counts what the person can do today, and the plan line (briefing, doctor, watch) says how to change it.
+  const licensed = !!i.licence?.licensed;
+  const paid = { sast: 'SAST', autopilot: 'autopilot', prepr: 'the pre-PR gate', ci: 'the CI gate and nightly' };
+  for (const x of items) {
+    if (!licensed && x.id in paid && !x.on) {
+      x.paid = true;
+      x.how = `${paid[x.id]} is on the Team plan: bravos account activate starts a 30-day trial (no card), then ${x.cta}`;
+    }
+  }
+  const done = items.filter((x) => x.on).length;
+  const next = items.find((x) => !x.on && !x.paid) ?? items.find((x) => !x.on) ?? null;
+  return { schema: SETUP_SCHEMA, done, total: items.length, items, next, plan: i.licence ? { licensed, state: i.licence.state, tier: i.licence.tier } : null };
+}
+
+/** The one Setup line the briefing gives the agent and the banner shows the person. */
+export function setupLine(s) {
+  if (!s) return null;
+  return s.next ? `Setup ${s.done}/${s.total} — next: ${s.next.label} (${s.next.unlocks}): ${s.next.how}` : `Setup ${s.done}/${s.total} — everything bravos can use here is on`;
+}

package/hooks/lib/workspace.mjs

@@ -0,0 +1,78 @@
+// @comment -- "Reads the bravos workspace snapshot (.bravos/workspace/workspace.json, written by bravos workspace) and its cached bravos export, for the briefing and watch: which application this repo belongs to, its sibling services, the cross-service edges into and out of it, and at the app folder a per-service summary. Read-only and dependency-free; a missing or foreign file reads as no workspace."
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+export const WORKSPACE_SCHEMA = 'bravos.workspace/v1';
+export const EXPORT_SCHEMA = 'bravos.workspace-export/v1';
+export const MAX_MEMBERS = 8;
+
+const read = (file, schema) => {
+  try {
+    const j = JSON.parse(readFileSync(file, 'utf8'));
+    return j?.schema === schema ? j : null;
+  } catch {
+    return null;
+  }
+};
+
+// @comment -- "The workspace this root belongs to: the snapshot, the cached export, whether root is the app folder, and which member it is (null at the app folder)."
+export function readWorkspace(root) {
+  const dir = join(root, '.bravos', 'workspace');
+  const snap = read(join(dir, 'workspace.json'), WORKSPACE_SCHEMA);
+  if (!snap || !Array.isArray(snap.members)) return null;
+  const exp = read(join(dir, 'export.json'), EXPORT_SCHEMA);
+  const here = resolve(root);
+  const member = snap.members.find((m) => resolve(m.path) === here) ?? null;
+  return { name: snap.name, appFolder: snap.appFolder ?? null, isAppFolder: !!snap.appFolder && resolve(snap.appFolder) === here, member: member?.name ?? null, members: snap.members, export: exp, at: snap.at };
+}
+
+// @comment -- "Runs guardlink ci -f json in each member (at most MAX_MEMBERS, concurrently, through the caller's runner) and returns {name: {open, bySeverity, confirmed, stale, coverage} | null}; a member that fails or times out reads as null, never as zero."
+export async function memberCounts(ws, runJson, env, timeoutMs) {
+  const out = {};
+  const members = ws.members.slice(0, MAX_MEMBERS);
+  const results = await Promise.all(members.map((m) => runJson('guardlink', ['ci', '-f', 'json'], { cwd: m.path, env, timeoutMs })));
+  members.forEach((m, k) => {
+    const r = results[k];
+    const s = r?.ok ? r.json?.summary : null;
+    out[m.name] = s
+      ? {
+          open: Number(s.exposures) || 0,
+          bySeverity: s.by_severity ?? {},
+          confirmed: Array.isArray(r.json.confirmed) ? r.json.confirmed.length : 0,
+          stale: Number(s.stale) || 0,
+          coverage: s.coverage ? Number(s.coverage.percent) || 0 : null,
+        }
+      : null;
+  });
+  return out;
+}
+
+const plural = (n, w) => `${n} ${w}${n === 1 ? '' : 's'}`;
+
+// @comment -- "The briefing's workspace lines: in a member, the app, the other services and the cross-service calls into and out of it; at the app folder, one row per service and the edges, unresolved references and clashes; and where to work for each kind of question."
+export function workspaceLines(ws, counts) {
+  if (!ws) return [];
+  const edges = ws.export?.edges ?? null;
+  const lines = [];
+  if (ws.isAppFolder) {
+    lines.push(`Workspace: ${ws.name} — this is the app folder for ${plural(ws.members.length, 'service')}; make changes inside a service's repo, ask questions that cross services here`);
+    for (const m of ws.members.slice(0, MAX_MEMBERS)) {
+      const c = counts?.[m.name];
+      const sev = c ? ['critical', 'high'].filter((k) => c.bySeverity?.[k]).map((k) => `${c.bySeverity[k]} ${k}`).join(', ') : '';
+      lines.push(`  ${m.name}${m.url ? ` (${m.url})` : ''}: ${c ? `${c.open} open${sev ? ` (${sev})` : ''} · ${c.confirmed} confirmed · coverage ${c.coverage ?? '?'}%` : 'counts unknown (guardlink ci failed or timed out)'}`);
+    }
+    if (ws.members.length > MAX_MEMBERS) lines.push(`  … and ${ws.members.length - MAX_MEMBERS} more (bravos workspace show)`);
+  } else {
+    const others = ws.members.filter((m) => m.name !== ws.member).map((m) => m.name);
+    const into = edges ? edges.filter((e) => e.dstMember === ws.member) : null;
+    const outof = edges ? edges.filter((e) => e.srcMember === ws.member) : null;
+    lines.push(`Workspace: ${ws.name} — this repo is the ${ws.member ?? '?'} service; the others are ${others.join(', ') || 'none'}`);
+    if (into && outof) {
+      const fmt = (e, dir) => (dir === 'in' ? `${e.srcMember}:${e.src} → ${e.dst}` : `${e.src} → ${e.dstMember}:${e.dst}`);
+      lines.push(`  calls into this service: ${into.length ? into.map((e) => fmt(e, 'in')).join(', ') : 'none declared'}; calls out: ${outof.length ? outof.map((e) => fmt(e, 'out')).join(', ') : 'none declared'}`);
+    } else lines.push('  cross-service calls: unknown (run bravos workspace show)');
+  }
+  if (edges) lines.push(`  ${plural(edges.length, 'cross-service edge')} declared${ws.export.unresolved?.length ? ` · ${ws.export.unresolved.length} unresolved reference${ws.export.unresolved.length === 1 ? '' : 's'}` : ''}${ws.export.clashes?.length ? ` · ${plural(ws.export.clashes.length, 'id clash')}` : ''}`);
+  lines.push(`  Declare a call to another service as @flows #<this>-<x> -> #<other>-<y> via http|grpc|queue (plain ids; not the dotted #repo.tag form). The code graph links services only when built over the app folder${ws.appFolder ? ` (bravos graph build ${ws.appFolder} --scip no-exec)` : ''}.`);
+  return lines;
+}