@bugb-technologies/bravos 0.0.0-stage → 1.0.1

package/hooks/pre-pr.mjs

@@ -0,0 +1,54 @@
+// @comment -- "bravos's pre-PR gate entry, two ways. As the opt-in PreToolUse hook it reads the hook payload from stdin, gates only Bash commands that run gh pr create or gh pr ready, and exits 2 with the reason on stderr to block; every other command, unparseable input and BRAVOS_PRE_PR=off exit 0. Run by hand (--check, or no stdin / a TTY) it gates the current branch before any PR exists: exit 2 on lint errors, a confirmed claim on a changed file without a @ticket, or an input that fails; new exposures are printed to disclose, not blocked on. The repo root is git's top level for the working directory, never the payload cwd as given."
+import { entitled, refusal, status as licenceStatus } from './lib/licence.mjs';
+import { prAction, resolveRoot, runGate } from './lib/pre-pr.mjs';
+
+async function readStdin() {
+  const chunks = [];
+  for await (const c of process.stdin) chunks.push(c);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+function finish({ decision, reason }, check) {
+  if (decision === 'block') {
+    process.stderr.write(reason + '\n');
+    process.exit(2);
+  }
+  if (check) process.stdout.write((reason ? reason + '\n' : '') + 'bravos pre-PR gate: pass\n');
+  else if (reason) process.stderr.write(reason + '\n');
+  process.exit(0);
+}
+
+async function main() {
+  const env = process.env;
+  if (env.BRAVOS_PRE_PR === 'off') process.exit(0);
+  // Without a Team licence the gate stands down: one line on stderr (never a block), so a teammate
+  // without a seat still opens their PR and knows why nothing was checked.
+  const lic = licenceStatus(env);
+  if (!entitled(lic, 'pre-pr')) {
+    process.stderr.write(`bravos pre-PR gate: skipped — ${refusal(lic, 'pre-pr', 'the pre-PR gate')}\n`);
+    process.exit(0);
+  }
+  let check = process.argv.includes('--check') || process.stdin.isTTY === true;
+  let raw = '';
+  if (!check) {
+    raw = await readStdin();
+    if (raw.trim() === '') check = true;
+  }
+  if (check) {
+    const cwd = process.cwd();
+    finish(runGate({ root: resolveRoot(cwd, env), cwd, action: 'check', command: '', env }), true);
+  }
+  let input;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    process.exit(0);
+  }
+  const command = input?.tool_input?.command;
+  const action = prAction(command);
+  if (!action) process.exit(0);
+  const cwd = input?.cwd || env.CLAUDE_PROJECT_DIR || process.cwd();
+  finish(runGate({ root: resolveRoot(cwd, env), cwd, action, command, env }), false);
+}
+
+main();

package/hooks/session-start.mjs

@@ -0,0 +1,82 @@
+// @comment -- "SessionStart hook entry (--global: the user-level copy, silent where the repo has its own bravos hook or no .guardlink/; --briefing prints only the briefing text, for a skill that runs it by hand): reads the hook payload from stdin (bounded wait, bad input ignored; source, and Antigravity's workspacePaths), awaits collect() (read-only guardlink, git and gh facts under a shared 20 s deadline), and prints one JSON envelope: the briefing as additionalContext for the model, plus on a fresh start a banner as systemMessage for the human (brand-coloured; a three-line summary for Codex). With --harness agy it prints Antigravity's injectSteps instead. Always exits 0 so a session never fails to start."
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildBanner, buildBriefing, buildSummary, collect, readVersion } from './lib/briefing.mjs';
+
+const STDIN_WAIT_MS = 1000;
+
+/** The hook payload as an object ({} for no, empty or bad input). */
+async function readPayload() {
+  if (process.stdin.isTTY) return {};
+  const read = (async () => {
+    const chunks = [];
+    for await (const c of process.stdin) chunks.push(c);
+    return Buffer.concat(chunks).toString('utf8');
+  })().catch(() => '');
+  const raw = await Promise.race([read, new Promise((r) => setTimeout(() => r(''), STDIN_WAIT_MS).unref())]);
+  try {
+    const p = JSON.parse(raw);
+    return p && typeof p === 'object' ? p : {};
+  } catch {
+    return {};
+  }
+}
+
+function harnessArg(argv, env) {
+  const i = argv.indexOf('--harness');
+  const v = i === -1 ? null : argv[i + 1];
+  if (v === 'claude' || v === 'codex' || v === 'omp' || v === 'agy') return v;
+  return env.CLAUDE_PROJECT_DIR ? 'claude' : 'other';
+}
+
+async function main() {
+  const env = process.env;
+  const harness = harnessArg(process.argv, env);
+  if (process.argv.includes('--briefing')) {
+    // Plain text for an agent whose harness ran no hook: no JSON to parse, no banner to read past.
+    let t;
+    try {
+      t = buildBriefing(await collect(env.CLAUDE_PROJECT_DIR || process.cwd(), env));
+    } catch (e) {
+      t = `bravos briefing failed: ${e instanceof Error ? e.message : String(e)}`;
+    }
+    process.stdout.write(t + '\n');
+    process.exit(0);
+  }
+  const out = {};
+  let text;
+  try {
+    const payload = await readPayload();
+    const source = typeof payload.source === 'string' ? payload.source : null;
+    // Antigravity sends the workspace in the payload; Claude Code sets CLAUDE_PROJECT_DIR; others run in the repo.
+    const ws = Array.isArray(payload.workspacePaths) && typeof payload.workspacePaths[0] === 'string' ? payload.workspacePaths[0] : null;
+    const root = env.CLAUDE_PROJECT_DIR || ws || (typeof payload.cwd === 'string' ? payload.cwd : null) || process.cwd();
+    // User-level hook (bravos init --global): a repo's own bravos hook wins, and a repo with no
+    // threat model gets nothing, so the user hook never doubles the briefing or adds noise.
+    if (process.argv.includes('--global') && (existsSync(join(root, '.bravos', 'hooks', 'session-start.mjs')) || !existsSync(join(root, '.guardlink')))) {
+      process.exit(0);
+    }
+    const inputs = await collect(root, env);
+    text = buildBriefing(inputs);
+    if (env.BRAVOS_BANNER !== 'off' && (source === null || source === 'startup') && harness !== 'agy') {
+      const version = readVersion(dirname(fileURLToPath(import.meta.url)));
+      const color = !env.NO_COLOR && env.BRAVOS_BANNER_COLOR !== 'off';
+      // Codex lists a hook's message as a warning, so it gets a three-line summary, not the art.
+      // The leading newline puts the logo on its own lines: Claude Code prefixes the first line with "SessionStart:startup says:".
+      out.systemMessage = harness === 'codex' ? buildSummary(inputs, { harness, version }) : '\n' + buildBanner(inputs, { harness, version, color });
+    }
+  } catch (e) {
+    text = `bravos briefing failed: ${e instanceof Error ? e.message : String(e)}`;
+  }
+  if (harness === 'agy') {
+    // Antigravity's SessionStart output: steps injected before the first model call.
+    process.stdout.write(JSON.stringify({ injectSteps: [{ systemMessage: text, metadata: { source: 'bravos' } }] }) + '\n');
+    process.exit(0);
+  }
+  out.hookSpecificOutput = { hookEventName: 'SessionStart', additionalContext: text };
+  process.stdout.write(JSON.stringify(out) + '\n');
+  process.exit(0);
+}
+
+main();

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@bugb-technologies/bravos",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Skills pack and installer that make Claude Code and Codex power users of guardlink (threat-model-as-code) and cert-x-gen (pentest-as-code).",
+  "keywords": [
+    "security",
+    "threat-modeling",
+    "guardlink",
+    "cert-x-gen",
+    "pentest",
+    "claude-code",
+    "codex",
+    "skills"
+  ],
+  "author": "BugB Technologies (https://www.bugb.io)",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "bin": {
+    "bravos": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "hooks",
+    "templates",
+    "docs/GUIDE.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "pretest": "npm run build",
+    "test": "vitest run",
+    "capture-help": "bash scripts/capture-help.sh",
+    "prepublishOnly": "npm run build && npm test",
+    "build:plugin": "npm run build && node scripts/build-plugin.mjs"
+  },
+  "dependencies": {
+    "commander": "^15.0.0",
+    "smol-toml": "^1.9.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.5"
+  }
+}

package/skills/bravos/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: bravos
+description: "Start here in any repo bravos is installed in: reads the security picture, explains the evidence loop in five lines, and routes to bravos-annotate, bravos-codegraph or bravos-ship. Use when asked where to start on security, what is open or confirmed, what to fix next, or whenever a task touches security-relevant code."
+---
+# Bravos: where this repo stands and what to do next
+
+## When
+
+- The user asks where to start on security, what is open, what is confirmed exploitable, or what to fix next.
+- A task touches security-relevant code: endpoints, authn/authz, validation, queries, file I/O, external calls, crypto, process spawning, config parsing.
+- You are about to pick one of the other bravos skills and are not sure which.
+- The user is new or asks how to get started: "help me get started", "what can bravos do here?", "I'm new", or runs this skill with no task.
+
+## Do
+
+1. If the user is new or asks how to start, give the guided start and stop there: read the briefing's `Setup n/9` line (or run `bravos next --json`); say in three sentences what bravos does here; show what is on and the next step with its exact command and what it unlocks; offer three things to try now that fit the repo, in setup order — the code graph comes first because every later step reads it (graph off → build it with `bravos graph build . --scip no-exec`; intent none → learn what the app intends; low coverage → annotate the top files; then SAST, which reads the annotations; untested exposures → prove the top 3; a branch with changes → the ship check), in plain words with the skill named second; point to `bravos guide roles`, and mention once that `bravos watch` in a second terminal pane shows all of this live while they work. Run a setup command that changes config or hooks only after the person agrees. Otherwise read the session-start briefing. It opens with `GuardLink security picture (bravos) — <repo> @ <sha>, base <base>`. If none is in context (a harness that ran no hook), run `node .bravos/hooks/session-start.mjs --briefing` once: it prints the briefing as plain text. Pull out: the `Open exposures:` line (severity counts, coverage, worklist), `FIX NOW — confirmed exploitable`, `Next to test or fix (guardlink hypothesis next)`, `Went stale in files you changed since <base>`, `Open tickets`, `In flight by teammates`, the `Code graph:` state, and the `Intent:` line (none or draft means severities are not yet calibrated to the product; offer bravos-context). `Open exposures: unknown (guardlink ci unavailable)` means the picture is unknown, not empty. bravos keeps no state of its own (`.bravos/` holds only the hook and the skills lock); when the briefing says a tool is unavailable, `bravos doctor` reports which tools are present. When the briefing has a `Workspace:` line, this repo is one service of a larger app: changes belong in the service's own repo, questions across services go to the app folder it names, and `bravos workspace show` lists the services, their URLs and the calls between them.
+2. Explain the evidence loop in five lines when the user is new to it or asks what a finding means:
+   claim (an annotation says code is exposed or mitigated) → testable template → authorized run against a target the user owns → verified outcome → recheck when the code changes.
+   Three states are independent of each other: open / mitigated / accepted · untested / confirmed / refuted · verified / stale. A mitigated claim can still be untested; a confirmed one can go stale.
+3. Route the request:
+   no `.guardlink/intent.md` yet, business logic, "what matters here", "is this intended?", learning the app → bravos-context (run it before a first annotation pass).
+   coverage, annotating, "threat-model this", a worklist in the briefing → bravos-annotate.
+   reachability, blast radius, "is this live", tracing a handler to sinks → bravos-codegraph.
+   before a PR, push for review, or marking a draft ready → bravos-ship.
+   pentest templates, a retest kit, making a claim testable → bravos-templatize.
+   standing up a test target, seeding test users, capturing a session → bravos-env.
+   proving a finding, testing whether an exposure is exploitable → bravos-prove (after bravos-env).
+   a fix landed, stale claims, closing a security ticket → bravos-recheck.
+   write up the assessment, a finding, a retest or a brief for leadership → bravos-report.
+   static analysis, dependency, secret or IaC findings → bravos-sast; "what did SAST find" → `bravos sast candidates` (the briefing's `SAST:` line says whether a run exists, or that SAST is unavailable).
+   keep annotating while I work, nightly or periodic runs → bravos-schedule.
+   security CI, a PR check, code-scanning upload → bravos-cicd.
+   reach a goal over many rounds ("100% coverage", "test every exposure", "until done", autopilot, a campaign) → bravos-campaign.
+   The briefing's `Plan:` line says which tier this machine is on. On Free, the research loop (context, annotate, templatize, env, prove, recheck, report, watch) is all there; the pre-PR gate, CI and nightly, schedule, workspaces, campaign, SAST and the code graph are on Team. When the request needs one of those, still name the right skill, say in one sentence that it is on the Team plan (`bravos account activate` starts a 30-day trial, no card), and offer the nearest free step instead; never pretend the feature ran.
+4. bravos adds method and memory to what you can already do; it never caps it. Budgets in the skills are defaults: exceed them when the work calls for it and say why. Effort (low, medium, high, max) comes from the user's words, else a `bravos effort: <level>` line in `AGENTS.md` / `CLAUDE.md`, else medium. Only the safety rules under each skill's Never are hard.
+5. Name the next step in one line, taken from the briefing: a `FIX NOW` item first, then a stale claim in a file the user changed, then the top `guardlink hypothesis next` item, then coverage.
+6. When the user takes an item to work on and it already has a ticket in their tracker, record the pick-up beside its claim so the hive can see it: write `@ticket #<threat> on #<asset> <ticket-ref> sla "<label>" by <assignee> until <YYYY-MM-DD>` directly beside the claim's `@exposes`, clauses in that order, dropping `sla "<label>"` and `until <YYYY-MM-DD>` unless the user gives them, then run `guardlink validate .`. The briefing's `Open tickets` line and `guardlink lookup tickets` show it to teammates; removing the line is how the ticket leaves the model.
+
+## Never
+
+- Run a setup command for the person (bravos sync --autopilot, --ci, --pre-pr-hook, bravos setup, bravos graph build with --scip auto) without their go-ahead.
+- Run `guardlink annotate` or guardlink translate with an agent flag. Those launch a second agent outside this session; you are the agent, so do the work here.
+- Write `@accepts`, `@entitles` or `@confirmed`. Acceptance and entitlement are a human's decision; confirmation needs a reproduced run, and reading code is not one.
+- Call anything clean, safe or fixed unless a gate said so with exit 0.
+- Invent a ticket id, SLA, assignee or due date; take each from the user or their tracker.
+
+## Done when
+
+- The user knows the three states for what you reported: open vs mitigated or accepted, untested vs confirmed vs refuted, verified vs stale.
+- Every finding you mention names the tool that judged it (guardlink ci, the code graph, a cxg run) and what was not tested.
+- You named one next step and the skill that owns it.
+
+## What it leaves for the next skill
+
+- The briefing lines you quoted and the one next step, so the routed skill starts from the same picture.
+
+## Go deeper
+
+- Autopilot (`bravos init --autopilot`): an end-of-turn check sends you back once when changed code lacks annotations, sits under a confirmed or stale claim, or adds exposures; the briefing's `Autopilot:` and `Proving:` lines say whether it is on and how the person wants proving handled.
+- `bravos guide` (in a shell; no model) explains bravos by role, by task and skill by skill, with the safety rules; `docs/GUIDE.md` in the bravos package is the same text. Point a person there when they ask how to use bravos.
+- `docs/GUARDLINK_REFERENCE.md` — annotation syntax and verbs.
+- `.guardlink/README.md` — where annotations go in this repo.
+- `{{SKILLS_ROOT}}/guardlink-annotate-exploitable/SKILL.md` — the evidence bar a claim must meet (written by `guardlink init --agent claude` under `.claude/skills/` when present; otherwise `guardlink annotate --stdout --playbook exploitable "<scope>"` prints the same method).

package/skills/bravos-annotate/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: bravos-annotate
+description: "Keep the GuardLink threat model correct and growing, in this session: pick a budgeted slice of files (or go deep on request), follow guardlink's own playbook skill, write annotations that meet the evidence bar, run the lint gate until clean, and report the coverage delta. Use when asked to annotate, threat-model or cover code, after writing security-relevant code, when the briefing shows coverage or a worklist, and when asked to annotate deeply or run multiple rounds."
+---
+# Bravos annotate: a budgeted slice of the threat model, gated
+
+## When
+
+- The user asks to annotate, threat-model or cover code, or to go deep / run several rounds.
+- You just wrote or changed security-relevant code and its claims are missing or stale.
+- The briefing's `Open exposures:` line shows low coverage or a non-empty worklist.
+- bravos-ship or bravos-codegraph handed you gaps to annotate.
+
+## Do
+
+1. Set up. You annotate in this session: guardlink supplies the method (its playbook skills), you supply the edits. `<base>` below is the base branch name, e.g. `main`; the briefing prints it as `base origin/<base>`, and without a briefing `git symbolic-ref -q --short refs/remotes/origin/HEAD` prints `origin/<base>` (if it prints nothing, use `main`). Run `git fetch origin <base>` before you use `origin/<base>`, so it is current; if the fetch fails (offline, no `origin`), say so and continue with the local ref. Record `git rev-parse HEAD` now as `<start>`: the lint gate judges only what this session writes. Definitions (`@asset`, `@threat`, `@control` with `#id`) live in `.guardlink/definitions.*`; reuse those ids and never redefine one. Read `.guardlink/intent.md`: its invariants (`INV-n`), intended-by-design items (`INT-n`), actors and crown jewels shape every claim below. If it is missing, run bravos-context first; if the user declines, carry on and tell them severities are not calibrated to the product.
+2. Run `guardlink ci -f json`. Note `summary.coverage.percent` as p0 and the worklist size from the briefing or `guardlink unannotated --json` (`summary.worklist`).
+3. Read the effort: the user's words ("at high"), else a `bravos effort: <level>` line in `AGENTS.md` / `CLAUDE.md`, else medium. Starting budgets — low: the changed files only; medium: changed plus 5 from the worklist; high: 25 per round, then the `chains` playbook; max: rounds until the worklist is empty (bravos-campaign runs those with subagents). These are defaults, not limits: take more or fewer when the code calls for it, and say why in one line ("12 files, not 5: the auth path spans them"). For a large pick, tell the user the files and rounds before you start.
+4. Run `node {{SKILL_DIR}}/scripts/slice.mjs --base origin/<base> --n <budget>` (`--deep` for no limit, `--batches <k>` to split the pick for parallel work, `--prefer <file>` for entry points `codegraph_entry_points` found). It prints one JSON object: `diff` (changed files), `coverage` (unannotated files to cover, entry points and trust code first, generated, test and CI files last), `coverage_detail` (`{path, tier, why}`), `batches`, `skipped` (`{path, reason}`), `coverage_before`, `notes`. The order is advice: if your reading of the code says a different file matters more, take it and say why. Tell the user which `skipped` files teammates have in flight. Report every `notes` entry to the user; if one says gh was unavailable, say in-flight PRs were not checked before you take the `coverage` files. Exit 1 means `guardlink unannotated --json` failed: report it and stop. When the briefing's `SAST:` line shows a run, `bravos sast candidates` lists reachable findings not in the threat model yet: add their files to the pick as leads, open each, and annotate only what meets the evidence bar, as `@exposes` + `@audit` citing the rule and route, or an `@audit` naming a false positive. A static finding is never `@confirmed`. With SAST unavailable or no report, pick as usual.
+5. Pick the playbook: `diff` files → `diff`; `coverage` files → `coverage`. Deep rounds run `exploitable`, then `chains`, then `coverage`, then `verify`. Add a logic pass when intent.md lists invariants (always at high and max, or when guardlink offers a `logic` playbook use it): walk each user journey that touches an invariant — signup, invite, role change, checkout, refund, export — and at each step ask what it assumes about the caller and the step before: ownership, tenant, state, amount, rate. The sink of a logic claim is the state change (the write, the transfer, the grant); the absent control is the missing ownership or state check. Claim it against the invariant's threat: `@mitigates <Asset> against #inv-… using #<control>` for a check that holds, `@exposes <Asset> to #inv-…` for one that is missing and meets the evidence bar, `@audit` for a doubt.
+6. Open `{{SKILLS_ROOT}}/guardlink-annotate-<id>/SKILL.md` (guardlink writes it under `.claude/skills/`, and `bravos init` mirrors it into `.agents/skills/` for Codex) and follow it. Otherwise call the MCP tool `guardlink_annotate` (server `guardlink`) with `prompt: "<scope>"` and `playbook: "<id>"`, or run `guardlink annotate --stdout --playbook <id> "<scope>"` (for the `diff` playbook, `guardlink annotate --stdout --playbook diff --since origin/<base> "<scope>"`, since `--since` defaults to HEAD and would list no changed files), and follow the prompt it returns.
+7. Write the annotations in each file's own comment syntax, directly above the code they describe, coupled: every `@exposes` with its `@mitigates` or `@audit`, the `@flows` the data takes, and a `@comment` on what the code does. Each claim meets the evidence bar: it names the code, the threat and the control by id, and you could point at the line that makes it true.
+   Rate each `@exposes` by impact × reach × ease, within its threat's band, under intent.md's `## Assumptions` when it has them (the configuration baseline, deployment and attackers in scope; an exposure only an out-of-scope attacker reaches gets an `@audit`, not a severity): impact from the asset's `@handles` class and intent.md's crown jewels; reach from the boundary in front of it (public, then signed-in, then admin-only, then internal; with the code graph (its MCP tools, or `bravos graph <question> --json` — same answers; see bravos-codegraph), `codegraph_auth_boundary` for the route and `codegraph_reachable_sinks` for what the handler reaches; code `codegraph_entry_reach` or `codegraph_dead_code` shows no entry point reaches gets an `@audit` "not reachable per code graph", not a severity; without the graph, judge reach by reading the code and say the graph was unavailable); ease from its preconditions. Write the severity inline and the reason in the description ("high: reachable unauthenticated, touches payment records").
+   Intended? When the code does what an intent.md `INT-n` item says the product does on purpose, write no `@exposes`: write an `@audit` citing it ("by design per intent.md INT-2; check only admins reach it") and annotate the guard that should hold. When it looks intended but intent.md is silent, write an `@audit` asking "intended?" with your reason, and list it for the user. They answer with a fix, an intent.md line or their own `@accepts`; you never accept it. In a bravos workspace (the briefing's `Workspace:` line, or `.bravos/workspace/workspace.json`), define only this service's own assets, with ids prefixed by the service (`#orders-create`), never another service's; declare each call to another service as `@flows #<this>-<x> -> #<other>-<y> via http|grpc|queue -- "..."` with the other service's own id. Do not write the dotted `#repo.tag` form that guardlink's Workspace Context block suggests: cxg cannot chain it, so the cross-service attack is never tested.
+8. Gate: run `guardlink lint . --since <start> --json`. For each entry in `violations[]`, apply its `fix`. Repeat until `summary.errors` is 0. A violation on a line you did not write this session is not yours: leave the line as it is and report it to the user.
+9. Run `guardlink validate .` and fix what it reports in the lines you wrote.
+10. Run `guardlink ci -f json` again and report `+<files>, <p0>% → <p1>%, <errors> lint errors`. Deep only: repeat steps 4–10 once per round, and stop when `coverage` comes back empty or a round adds no claims.
+11. Commit the slice on its own: `git add` only the annotated files, message `annotate: <n> files, <playbook>`. Ship it as a small PR or on the feature branch, whichever the team does.
+12. Hand the new claims to bravos-ship, and the new `@exposes` ids to bravos-templatize so they become testable.
+
+## Never
+
+- Run `guardlink annotate` with an agent flag. Use `--stdout` and do the work here.
+- Write `@accepts`, `@entitles` or `@confirmed`.
+- Apply a lint `fix` to a line this session did not write. For `accepts-written`, `entitles-written` or `confirmed-without-evidence` on someone else's line, never remove or downgrade it: stop and report it to the user.
+- Edit or delete an existing claim. If one looks wrong, write an `@audit` beside it saying why.
+- Treat an intended-by-design match as an accepted risk, or drop an existing claim because intent.md covers it.
+- Annotate a file `guardlink unannotated` lists under `excluded`.
+- Pad coverage with claims that fail the evidence bar. An honest `@exposes` plus `@audit` beats a guessed `@mitigates`.
+
+## Done when
+
+- `guardlink lint . --since <start> --json` reports `summary.errors` 0 and `guardlink validate .` exits 0.
+- You reported the delta line from step 10, the files left in `skipped`, and any lint violation on a line you did not write.
+- Each new `@exposes` carries a severity with its reason, and every "intended?" `@audit` is listed for the user.
+- Each new claim's state is clear: open or mitigated (none accepted by you), untested (an annotation alone confirms or refutes nothing), and verified or stale per `guardlink ci`. Say what was not tested. Do not call the code clean; the lint gate judges annotations, not code.
+
+## What it leaves for the next skill
+
+- One commit of annotated files and the list of new `@exposes` ids and files, for bravos-ship.
+
+## Go deeper
+
+- `{{SKILLS_ROOT}}/guardlink-annotate-exploitable/SKILL.md` — the evidence bar (guardlink writes it under `.claude/skills/`, and `bravos init` mirrors it into `.agents/skills/` for Codex; otherwise `guardlink annotate --stdout --playbook exploitable "<scope>"` prints the same method).
+- `docs/GUARDLINK_REFERENCE.md` — verbs and syntax.
+- `.guardlink/README.md` — placement rules for this repo.

package/skills/bravos-annotate/scripts/lib/pick.mjs

@@ -0,0 +1,127 @@
+// @comment -- "Pure slice picker for bravos-annotate: ranks the worklist (entry points first, tests/generated/CI last), decides which files this session or its subagents annotate, skips files teammates have in open PRs, and splits the pick into disjoint directory-coherent batches; dependency-free, copied verbatim into target repos."
+
+const arr = (v) => (Array.isArray(v) ? v : []);
+const dirOf = (p) => (p.includes('/') ? p.slice(0, p.lastIndexOf('/')) : '');
+
+// Words in a path that mark code where attacker input arrives or trust is decided.
+const ENTRY_WORDS = new Set([
+  'handler', 'handlers', 'server', 'route', 'routes', 'router', 'controller', 'controllers', 'api', 'auth',
+  'authn', 'authz', 'jwt', 'token', 'tokens', 'session', 'sessions', 'middleware', 'interceptor', 'interceptors',
+  'gateway', 'ingress', 'rpc', 'grpc', 'webhook', 'webhooks', 'upload', 'admin', 'login', 'oauth', 'crypto',
+  'secret', 'secrets', 'key', 'keys', 'jwks', 'cert', 'certs', 'tls', 'permission', 'permissions', 'rbac', 'acl',
+  'endpoint', 'endpoints', 'frontend', 'proxy', 'graphql', 'resolver', 'resolvers', 'views',
+]);
+const ENTRY_PREFIXES = ['authoriz', 'authentic', 'authn', 'claim', 'identit', 'credential', 'password', 'saml', 'oidc'];
+
+const tokens = (p) =>
+  p
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean);
+
+/**
+ * classify(path, generated) -> { tier, why }
+ *   tier 1: entry points and trust code; tier 2: other source; tier 3: tests, generated, CI/tooling,
+ *   vendored, docs/config. Tier 3 stays pickable; it only comes last.
+ */
+export function classify(path, generated = new Set()) {
+  const p = `/${path}`;
+  const base = path.slice(path.lastIndexOf('/') + 1);
+  if (generated.has(path) || /\.pb\.go$|_pb2(_grpc)?\.py$|\.pb\.(ts|js)$|[._]gen\.|\/generated\/|\.g\.dart$/.test(p))
+    return { tier: 3, why: 'generated code' };
+  if (/\/(vendor|third_party|node_modules)\//.test(p)) return { tier: 3, why: 'vendored code' };
+  if (/(_test\.|\.test\.|\.spec\.|^test_|_spec\.)/.test(base) || /\/(tests?|__tests__|testdata|fixtures?)\//.test(p))
+    return { tier: 3, why: 'test code' };
+  if (/\/(\.github|\.circleci|ci|scripts|tools|build|hack)\//.test(p)) return { tier: 3, why: 'CI or tooling' };
+  if (/\.(md|txt|rst|json|ya?ml|toml|ini|lock|csv|svg|png)$/i.test(base)) return { tier: 3, why: 'docs or config' };
+  if (/\.config\.(c|m)?[jt]s$|^\.[a-z]+rc(\.[a-z]+)?$/i.test(base)) return { tier: 3, why: 'docs or config' };
+  const t = tokens(path);
+  const hit = t.find((w) => ENTRY_WORDS.has(w) || ENTRY_PREFIXES.some((x) => w.startsWith(x)));
+  if (hit) return { tier: 1, why: `entry point or trust code (${hit})` };
+  return { tier: 2, why: 'source' };
+}
+
+// The directory a batch groups by: the first two path segments of the file's directory.
+const groupOf = (p) => dirOf(p).split('/').slice(0, 2).join('/');
+
+/**
+ * pickSlice({ worklist, annotated, excluded, changed, inFlight, ownedDirs, generated, prefer, n, batches })
+ *   -> { diff, coverage, coverage_detail, batches, skipped, tiers }
+ * diff: changed files minus excluded, in input order.
+ * coverage: up to n × batches worklist files not changed and not in flight. Walk order: tier-3 files last;
+ *   otherwise files in the directory of a changed file or under an owned dir first, then by tier
+ *   (`prefer` files — e.g. code-graph entry points — before tier 1), each group in worklist rank order.
+ * batches: coverage split into `batches` disjoint lists of up to n, consecutive in directory order so each
+ *   batch is mostly one directory.
+ * skipped: files passed over (in-flight or changed) by the same walk, only those met before coverage filled.
+ * tiers: how many worklist files fell in each tier.
+ */
+export function pickSlice(input) {
+  const n = input?.n;
+  const k = Number.isInteger(input?.batches) && input.batches > 0 ? input.batches : 1;
+  const budget = n === Infinity ? Infinity : n * k;
+  const worklist = arr(input?.worklist);
+  const excluded = new Set(arr(input?.excluded));
+  const changed = arr(input?.changed);
+  const inFlight = arr(input?.inFlight);
+  const ownedDirs = arr(input?.ownedDirs);
+  const generated = new Set(arr(input?.generated));
+  const prefer = new Set(arr(input?.prefer));
+
+  const diff = changed.filter((f) => !excluded.has(f));
+
+  const changedSet = new Set(changed);
+  const changedDirs = new Set(changed.map(dirOf));
+  const flightPr = new Map();
+  for (const pr of inFlight) {
+    for (const f of arr(pr?.files)) if (!flightPr.has(f)) flightPr.set(f, pr.pr);
+  }
+
+  const info = new Map();
+  const tiers = { 1: 0, 2: 0, 3: 0 };
+  worklist.forEach((path, rank) => {
+    const c = prefer.has(path) ? { tier: 1, why: 'entry point (code graph)' } : classify(path, generated);
+    tiers[c.tier] += 1;
+    const preferred = changedDirs.has(dirOf(path)) || ownedDirs.some((d) => path.startsWith(`${d}/`));
+    info.set(path, { ...c, rank, preferred, graph: prefer.has(path) });
+  });
+  const key = (p) => {
+    const i = info.get(p);
+    return [i.tier === 3 ? 1 : 0, i.preferred ? 0 : 1, i.graph ? 0 : 1, i.tier, i.rank];
+  };
+  const cmp = (a, b) => {
+    const ka = key(a);
+    const kb = key(b);
+    for (let j = 0; j < ka.length; j++) if (ka[j] !== kb[j]) return ka[j] - kb[j];
+    return 0;
+  };
+  const ordered = [...worklist].sort(cmp);
+
+  const coverage = [];
+  const skipped = [];
+  for (const path of ordered) {
+    if (coverage.length >= budget) break;
+    if (flightPr.has(path)) skipped.push({ path, reason: `in-flight PR #${flightPr.get(path)}` });
+    else if (changedSet.has(path)) skipped.push({ path, reason: 'in current change' });
+    else coverage.push(path);
+  }
+
+  // Batches: keep the walk's priority across groups (a group's place is set by its best file), keep files of
+  // one directory together, then cut consecutive runs.
+  const groupRank = new Map();
+  coverage.forEach((p, i) => {
+    const g = groupOf(p);
+    if (!groupRank.has(g)) groupRank.set(g, i);
+  });
+  const grouped = [...coverage].sort((a, b) => groupRank.get(groupOf(a)) - groupRank.get(groupOf(b)) || coverage.indexOf(a) - coverage.indexOf(b));
+  const size = n === Infinity ? Math.ceil(grouped.length / k) || 1 : n;
+  const batches = [];
+  for (let i = 0; i < grouped.length && batches.length < k; i += size) batches.push(grouped.slice(i, i + size));
+
+  const coverage_detail = coverage.map((path) => {
+    const i = info.get(path);
+    return { path, tier: i.tier, why: i.why };
+  });
+  return { diff, coverage, coverage_detail, batches, skipped, tiers };
+}

package/skills/bravos-annotate/scripts/slice.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+// @comment -- "Entry for bravos-annotate: gathers git diff, guardlink worklist/coverage and open PRs via read-only spawnSync calls, runs pickSlice and prints bravos.slice/v2 JSON (coverage, coverage_detail, batches, tiers); dependency-free, copied verbatim into target repos."
+import { spawnSync } from 'node:child_process';
+import { closeSync, openSync, readSync } from 'node:fs';
+import { join } from 'node:path';
+import { pickSlice } from './lib/pick.mjs';
+
+/** Read-only spawnSync wrapper (no shell, timeout, bounded buffer); mirrors hooks/lib/briefing.mjs runJson. */
+function runJson(cmd, args, { cwd, timeoutMs = 10000, env = process.env } = {}) {
+  const r = spawnSync(cmd, args, { cwd, env, timeout: timeoutMs, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] });
+  if (r.error) {
+    if (r.error.code === 'ETIMEDOUT') return { ok: false, error: `${cmd}: timed out after ${timeoutMs / 1000}s` };
+    return { ok: false, error: `${cmd}: ${r.error.code ?? r.error.message}` };
+  }
+  if (r.status !== 0) return { ok: false, error: `${cmd} exited ${r.status}` };
+  try {
+    return { ok: true, json: JSON.parse(r.stdout) };
+  } catch {
+    return { ok: false, error: `${cmd}: output was not JSON` };
+  }
+}
+
+function usage(msg) {
+  process.stderr.write(`slice.mjs: ${msg} (usage: slice.mjs [--base <ref>] [--n <int>=5] [--batches <int>=1] [--prefer <file>]... [--deep] [--json])\n`);
+  process.exit(2);
+}
+
+function parseArgs(argv) {
+  const o = { base: null, n: 5, batches: 1, prefer: [], deep: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--deep') o.deep = true;
+    else if (a === '--json') continue;
+    else if (a === '--base') {
+      o.base = argv[++i];
+      if (!o.base) usage('--base needs a ref');
+    } else if (a === '--n') {
+      const v = argv[++i];
+      if (v === undefined || !/^\d+$/.test(v) || Number(v) < 1) usage('--n needs an integer >= 1');
+      o.n = Number(v);
+    } else if (a === '--batches') {
+      const v = argv[++i];
+      if (v === undefined || !/^\d+$/.test(v) || Number(v) < 1) usage('--batches needs an integer >= 1');
+      o.batches = Number(v);
+    } else if (a === '--prefer') {
+      const v = argv[++i];
+      if (!v || v.startsWith('--')) usage('--prefer needs a file path');
+      o.prefer.push(v);
+    } else usage(`unknown argument ${a}`);
+  }
+  return o;
+}
+
+const paths = (v) => (Array.isArray(v) ? v : []).map((e) => (typeof e === 'string' ? e : (e?.path ?? e?.file))).filter((p) => typeof p === 'string');
+
+const opts = parseArgs(process.argv.slice(2));
+const cwd = process.cwd();
+const notes = [];
+
+let base = opts.base;
+if (!base) {
+  const r = spawnSync('git', ['symbolic-ref', '-q', '--short', 'refs/remotes/origin/HEAD'], { cwd, encoding: 'utf8', timeout: 10000, stdio: ['ignore', 'pipe', 'ignore'] });
+  base = r.status === 0 && r.stdout.trim() ? r.stdout.trim() : 'origin/main';
+}
+
+let changed = [];
+const d = spawnSync('git', ['diff', '--name-only', '--diff-filter=ACMR', `${base}...HEAD`], { cwd, encoding: 'utf8', timeout: 10000, maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] });
+if (d.error || d.status !== 0) {
+  const why = d.error ? (d.error.code ?? d.error.message) : (d.stderr || '').trim().split('\n')[0] || `exited ${d.status}`;
+  notes.push(`git diff failed: ${why}`);
+} else {
+  changed = d.stdout.split('\n').filter(Boolean);
+}
+
+const un = runJson('guardlink', ['unannotated', '--json'], { cwd });
+if (!un.ok) {
+  process.stderr.write(`slice.mjs: guardlink unannotated failed: ${un.error}\n`);
+  process.exit(1);
+}
+
+let inFlight = [];
+const gh = runJson('gh', ['pr', 'list', '--state', 'open', '--json', 'number,files', '--limit', '50'], { cwd });
+if (gh.ok && Array.isArray(gh.json)) {
+  inFlight = gh.json.map((p) => ({ pr: p.number, files: paths(p.files) }));
+} else {
+  notes.push('gh unavailable: in-flight PRs not checked');
+}
+
+let coverageBefore = null;
+const ci = runJson('guardlink', ['ci', '-f', 'json'], { cwd });
+const cov = ci.ok ? ci.json?.summary?.coverage : null;
+if (cov) coverageBefore = { percent: cov.percent, annotated_files: cov.annotated_files, source_files: cov.source_files };
+else notes.push('guardlink ci unavailable: coverage_before omitted');
+
+// A file whose first 2 KB says it is generated ("Code generated ... DO NOT EDIT", "@generated") ranks last.
+function isGenerated(rel) {
+  let fd;
+  try {
+    fd = openSync(join(cwd, rel), 'r');
+    const buf = Buffer.alloc(2048);
+    const len = readSync(fd, buf, 0, 2048, 0);
+    return /Code generated .*DO NOT EDIT|@generated\b|autogenerated|auto-generated/i.test(buf.toString('utf8', 0, len));
+  } catch {
+    return false;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+const worklistPaths = paths(un.json?.worklist);
+const generated = worklistPaths.slice(0, 5000).filter(isGenerated);
+
+const n = opts.deep ? Infinity : opts.n;
+const picked = pickSlice({
+  worklist: worklistPaths,
+  annotated: paths(un.json?.annotated),
+  excluded: paths(un.json?.excluded),
+  changed,
+  inFlight,
+  ownedDirs: [],
+  generated,
+  prefer: opts.prefer,
+  n,
+  batches: opts.batches,
+});
+
+process.stdout.write(
+  JSON.stringify({
+    schema: 'bravos.slice/v2',
+    base,
+    n: opts.deep ? 'unbounded' : n,
+    mode: opts.deep ? 'deep' : 'slice',
+    diff: picked.diff,
+    coverage: picked.coverage,
+    coverage_detail: picked.coverage_detail,
+    batches: picked.batches,
+    tiers: picked.tiers,
+    skipped: picked.skipped,
+    coverage_before: coverageBefore,
+    notes,
+  }) + '\n',
+);