@bugb-technologies/bravos 0.0.0-stage → 1.0.1

package/skills/bravos-campaign/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: bravos-campaign
+description: "Reach a security goal over many rounds and then stop: annotation coverage to a target, every open exposure tested on loopback, or every stale claim rechecked. Plans disjoint batches, runs one subagent per batch each round, gates every batch, rests between rounds with the harness's own loop or wakeup, and reports before-and-after numbers. Use when asked to reach 100% coverage, annotate or test everything, run until done, go on autopilot, or loop and schedule rounds with rests."
+---
+# Bravos campaign: rounds toward a goal, gated, then stop
+
+## When
+
+- The user names a goal larger than one session's slice: "coverage 100%", "test every open exposure", "recheck everything", "until done", "autopilot".
+- The user asks for rounds, batches, subagents per round, or a rest between rounds.
+- The briefing shows a large worklist or many untested exposures and the user wants it cleared.
+
+## Do
+
+**Plan check first.** Campaigns are on the Team plan. Run `bravos licence --json` once per session (the briefing's `Plan:` line says the same); if `licensed` is false, tell the person in two sentences what this skill would do here and that it needs a Team licence — `bravos account activate` starts a 30-day trial with no card, or https://account.bugb.io/pricing — then stop, and do nothing else from this skill. A licence in grace still counts.
+
+1. Read the goal, the effort, the rest interval and any spend cap from the request. Goals: `coverage <N>%` (annotate), `test` (templatize, then env, then prove, loopback only), `recheck`, or several in that order. Effort: the user's words, else a `bravos effort: <level>` line in `AGENTS.md` / `CLAUDE.md`, else high (a campaign is a big job). Rest: the user's interval, else 10 minutes. If `.guardlink/intent.md` is missing, run bravos-context first and ask its questions once, before any round.
+2. Read where things stand: `guardlink ci -f json` (`summary.coverage`, `exposures[]`, `stale[]`) and `guardlink hypothesis next --json`. If the goal is already met, say so and stop.
+3. Estimate and say it before the first round: files or exposures left, batch size and batches per round (default 5 × 3, a starting point, not a limit; at max, as many batches as the work splits into cleanly), rounds expected, and that every round spends model tokens. At max this is information; below max, wait for the user's go-ahead once.
+4. Plan the round's batches: `node {{SKILLS_ROOT}}/bravos-annotate/scripts/slice.mjs --base origin/<base> --n <size> --batches <k>` gives disjoint `batches`, entry points first, generated, test and CI files last. For `test` and `recheck`, split the exposures or claims the same way, one directory per batch. Reorder by your own reading of the code when it disagrees, and say why.
+5. Run the round: one subagent per batch, through the harness's own subagent tool (in Claude Code the Agent tool; in Codex its subagents if this session has them, otherwise the batches one after another here). Brief each with its batch only, the skill to follow (bravos-annotate, bravos-templatize, bravos-prove or bravos-recheck), the effort, and the `<start>` commit. Each subagent runs that skill's gate to 0 errors and commits its batch alone.
+6. Check the round here: `guardlink validate .`, then `guardlink ci -f json`. Report per batch and in total: files or exposures done, coverage before and after, gate errors, anything a subagent left. A batch whose gate failed is not committed; give it back to the next round once, then report it.
+7. Rest, then start the next round at step 2. In Claude Code, schedule the next round after the rest interval with the session's wakeup or self-paced loop tool, passing this campaign's goal; if none is available, tell the user to run `/loop` with the campaign prompt. In Codex there is no in-session timer: run the next round straight away, or hand the campaign to the nightly workflow (bravos-schedule). Say which you did.
+8. Stop when the goal is met, a round adds nothing, the same batch fails its gate twice, or the spend cap is reached. Final report: before and after numbers, commits per round, what is left and why, and the three states (open / mitigated, untested / confirmed / refuted, verified / stale) for what changed.
+
+## Never
+
+- Give two subagents overlapping files, or let one write outside its batch.
+- Commit a batch whose gate failed, or carry on past a goal that is already met.
+- Run a live test against anything but loopback, unless the host is in a committed, reviewed `scope.yaml` and the human typed their authorization in this session; never use `--destructive-ok` in a campaign.
+- Launch an external agent CLI (a guardlink or cxg agent flag) for a batch; subagents come from the harness this session runs in.
+- Open or update a pull request, or push, unless the user asked for it.
+- Write `@accepts`, `@entitles` or `@confirmed`.
+
+## Done when
+
+- The goal is met, or the stop rule fired and you said which one.
+- Every committed batch passed its gate; every skipped or failed batch is listed with its reason.
+- The user has before and after numbers, the commits per round, and what was not tested.
+
+## What it leaves for the next skill
+
+- The campaign's commits on the current branch and the list of what is left, for bravos-ship before a pull request.
+
+## Go deeper
+
+- `{{SKILLS_ROOT}}/bravos-annotate/SKILL.md` — what each annotation batch does and its gate.
+- `{{SKILLS_ROOT}}/bravos-prove/SKILL.md` — the authorized run a `test` batch makes.
+- `{{SKILLS_ROOT}}/bravos-schedule/SKILL.md` — the nightly option when no in-session timer exists.

package/skills/bravos-cicd/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: bravos-cicd
+description: "Audit and write the repo's security CI: the bravos PR gate (validate, lint since the merge base, undisclosed new exposure, confirmed exploits on changed paths, SARIF to code scanning), the nightly annotation workflow, and optional licensed SAST, fixing broken guardlink calls and script-injection risks in existing workflows. Use when asked to add or review security CI, a PR gate, code-scanning upload or a nightly job, or when a workflow calls guardlink with flags it does not have."
+---
+# Bravos CI/CD: the gate and the nightly job as workflows
+
+## When
+
+- The user asks to add, fix or review security CI, a PR check or code-scanning upload.
+- bravos-schedule chose the nightly workflow.
+- An existing workflow calls guardlink or cxg, or interpolates pull-request text into a shell step.
+
+## Do
+
+**Plan check first.** CI and nightly workflows are on the Team plan. Run `bravos licence --json` once per session (the briefing's `Plan:` line says the same); if `licensed` is false, tell the person in two sentences what this skill would do here and that it needs a Team licence — `bravos account activate` starts a 30-day trial with no card, or https://account.bugb.io/pricing — then stop, and do nothing else from this skill. A licence in grace still counts.
+
+1. Audit `.github/workflows/*.yml`. For each guardlink or cxg call, check every flag against that command's `--help`; a `guardlink diff` call with `--from`/`--to` flags is the known broken pattern, since diff takes one positional ref. Flag any `github.event.pull_request`, issue or comment field, or `github.head_ref`, expanded straight into a `run:` line: that text is attacker-controlled and runs as shell.
+2. Write bravos's workflows with `bravos init --ci` (or `bravos sync --ci`): `bravos-pr-gate.yml` plus the nightly variants. Delete the nightly variant for the harness the team does not use. A workflow someone edited by hand is kept and reported; never overwrite it.
+3. Check the PR gate does what bravos-ship does: `guardlink validate .`, `guardlink lint . --since <base>` against the merge base, `guardlink diff <base> --fail-on-new --markdown` (passing when the PR body discloses new exposure in a Security gate section), a block on confirmed claims in changed files, and `guardlink sarif . --profile github -o guardlink.sarif` uploaded to code scanning.
+4. Fix what the audit found in workflows bravos did not write: replace a broken guardlink call with the form above, and pass event text through `env:` and quote it in the shell. Show each change to the user before committing it.
+5. SAST in CI, only when the team has a bravos licence: add a step running `bravos-cli analyze . --ci --fail-on error -f sarif,json -o sast` with the licence from a repo secret, and upload `sast.sarif` under its own code-scanning category.
+6. Validate the workflows: run `actionlint` on them if it is installed; otherwise parse each as YAML. Fix every error.
+7. Name the secrets and settings the user must add (`ANTHROPIC_API_KEY` or `OPENAI_API_KEY` for the nightly job, the bravos licence for SAST, permission for Actions to create pull requests) without writing any value.
+8. Ship the workflow changes as a pull request through bravos-ship.
+
+## Never
+
+- Write a secret, token, licence or session into a workflow or any committed file.
+- Interpolate pull-request, issue or comment text, or a branch name, directly into a `run:` line.
+- Use `guardlink validate . --strict` as a PR gate on a repo with recorded legacy exposures; it fails on every one of them, not on what the PR adds.
+- Add a job that runs a live test or scan unattended; that needs the human's authorization typed in a session.
+- Delete or rewrite a workflow bravos did not write without the user's go-ahead.
+- Write `@accepts`, `@entitles` or `@confirmed`.
+
+## Done when
+
+- Every guardlink and cxg call in the repo's workflows uses only flags that command has, and no workflow writes event text into a shell line.
+- `actionlint` (or a YAML parse) reports no error on any workflow you wrote or changed.
+- The user has the list of secrets and settings to add, and the change is in a pull request.
+
+## What it leaves for the next skill
+
+- The workflow files, the audit findings in workflows bravos did not write, and the secrets still to add, for bravos-ship.
+
+## Go deeper
+
+- `{{SKILLS_ROOT}}/bravos-ship/SKILL.md` — the gate these workflows run.
+- `{{SKILLS_ROOT}}/bravos-schedule/SKILL.md` — choosing between a loop, a nightly job and a cloud task.

package/skills/bravos-codegraph/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: bravos-codegraph
+description: "Ask the repo's code graph (codegraph-mcp) one bounded question — routes, attack surface, sinks a symbol reaches, whether code is live, blast radius, annotation gaps in a change — instead of grepping. Use before editing security-relevant code, when judging a finding's reachability, when tracing a handler to its sinks, and when bravos-annotate or bravos-ship needs targets."
+---
+# Bravos codegraph: one question, one tool, one verdict
+
+## When
+
+- You are about to edit security-relevant code and need its callers or blast radius.
+- You are judging whether a finding's code is reachable from an entry point, or live at all.
+- You are tracing a handler to the sinks it reaches, or listing routes and attack surface.
+- bravos-annotate or bravos-ship needs file:symbol targets, such as unannotated entry points in a change.
+
+## Do
+
+**Plan check first.** The code graph is on the Team plan. Run `bravos licence --json` once per session (the briefing's `Plan:` line says the same); if `licensed` is false, tell the person in two sentences what this skill would do here and that it needs a Team licence — `bravos account activate` starts a 30-day trial with no card, or https://account.bugb.io/pricing — then stop, and do nothing else from this skill. A licence in grace still counts.
+
+1. Ask the graph one bounded question per call; a graph answer replaces reading or grepping the tree. There are two ways in, with the same answers: the MCP tools (`codegraph_attack_surface` …) when the `codegraph` server is connected, or `bravos graph <question> --json` in the shell, where the question is the tool name without `codegraph_` and with hyphens (`codegraph_attack_surface` → `bravos graph attack-surface --json`, `codegraph_callers` → `bravos graph callers '<file>::<symbol>' --json`; `bravos graph --json` lists every question and its arguments). The shell route needs no MCP reconnect and works in every harness. The briefing's `Code graph:` line says which route is there. If neither is (no codegraph-mcp), set it up yourself: `bravos setup --check` reports what is missing without changing anything; show the person `bravos setup --dry-run --codegraph` and with their go-ahead run `bravos setup --codegraph` (it fetches the signed bundle through the account portal and verifies it before anything lands). If an install fails, quote its error and give the exact command for their own terminal; until then say "code graph unavailable; the other skills read the code instead" and answer by reading. Read the effort: the user's words ("at high"), else a `bravos effort: <level>` line in `AGENTS.md` / `CLAUDE.md`, else medium. It sets a starting budget, not a limit; go beyond it when the work needs it and say why in one line. Starting budget — low: the one question asked; medium: whatever questions the task needs; high: start from `codegraph_attack_surface`; max: the full attack surface plus `codegraph_impact` on every changed symbol.
+2. Build or refresh the graph when an answer says there is none for this repository, or its `graph_currency` is `diverged`: `bravos graph build . --scip no-exec` indexes without running the repository's build scripts (`--scip auto` and `--isolate` run them; use those only on a repo the user trusts and only when they say so). A build that reports `semantic <language>: off` lacks that language's type checker; say that calls through interfaces may not connect and that `bravos setup --indexers` (with their go-ahead) adds it. For the MCP route, `bravos sync` registers the server from the bravos install; the person reconnects MCP (`/mcp` in Claude Code) to load it. In a bravos workspace, build one graph over the app folder (`bravos graph build <app folder> --scip no-exec`, the folder the briefing's `Workspace:` line names) and ask cross-service questions there: only a graph that holds both services links one service's HTTP, gRPC, GraphQL or OpenAPI client call to the other's handler (`callees` shows `via_framework`). A graph built inside one member stops at its own repository.
+3. Pick the one tool that answers the question:
+   find a symbol → `codegraph_search`
+   routes → `codegraph_routes`
+   ranked attack surface → `codegraph_attack_surface`
+   sinks reachable from a symbol → `codegraph_reachable_sinks`
+   is it live (reachable from an entry point) → `codegraph_entry_reach`
+   blast radius of a change → `codegraph_impact`
+   callers → `codegraph_callers`
+   unannotated entry points in a change → `codegraph_annotation_gaps`
+   who may reach a route → `codegraph_auth_boundary`
+   the call path from an entry point to a symbol → `codegraph_call_chain`
+   untested exposures ranked by reach → `codegraph_untested_exposures`
+   code no entry point reaches → `codegraph_dead_code`
+4. Read `verdict` and `confidence` before anything else in the answer. `unknown` and `insufficient_resolution` mean the graph could not tell: report them as not determined, never as clean or unreachable.
+5. Quote the tool's verdict with its confidence, and hand the file:symbol targets to bravos-annotate (gaps to annotate) or bravos-ship (gaps blocking a PR).
+
+## Never
+
+- Treat `unknown` or `insufficient_resolution` as clean, unreachable or dead.
+- Grep or read the tree for a question the graph answers while `graph_currency` is `current`.
+- Build with `--scip auto`, `--scip trusted` or `--isolate` (they run the repository's own build scripts) without the user's say-so.
+
+## Done when
+
+- You asked one question, named the tool, and quoted its `verdict` and `confidence`.
+- If the graph was `diverged`, you rebuilt with `no-exec` and the answer you report came after the rebuild.
+- Reachability is not exploitability: say the graph judged reach, and that no run tested the finding. An exposure the graph shows as reachable is still untested until a run confirms or refutes it.
+
+## What it leaves for the next skill
+
+- A short list of file:symbol targets with the verdict and confidence that produced each, for bravos-annotate or bravos-ship.
+- The same tools serve other skills directly: bravos-templatize (the route and auth that reach a sink), bravos-recheck (callers and blast radius of a fix), bravos-context (the real public surface) and bravos-prove (test order by reach). Each falls back to reading the code when the graph is unavailable.
+
+## Go deeper
+
+- The tool list the `codegraph` MCP server exposes (ask your MCP client for it) — 31 tools; the nine above cover Phase 1.
+- `docs/GUARDLINK_REFERENCE.md` — how graph targets map to annotations.
+- `{{SKILLS_ROOT}}/guardlink-annotate-exploitable/SKILL.md` — the evidence bar for a claim built from a graph answer (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-context/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: bravos-context
+description: "Learn what the software intends before judging its code: for a project being researched (the default) draft its intent from upstream's own docs and ask only the scope decisions — configuration baseline, deployment, attackers in scope, unclear intended behaviours; for the user's own product run the owner interview — and get answers in bravos's review page, pre-filled with suggestions the team edits and confirms. Record them as .guardlink/intent.md plus actors, assets, invariant threats and boundaries in the threat model. Use when .guardlink/intent.md is missing, when asked to learn the app or its business logic, to say what matters or what is intended, before a first annotation pass or campaign, and after a large change to the product."
+---
+# Bravos context: what the product intends, so threats mean something
+
+## When
+
+- `.guardlink/intent.md` is missing, and bravos-annotate, bravos-campaign or the front door is about to judge code.
+- The user asks you to learn the app, its business logic, what matters, or whether something is intended.
+- The product changed a lot (new roles, payments, tenants, a new surface); refresh the intent.
+
+## Do
+
+1. Decide the perspective. **Researcher** (the default): the repo is software being studied, such as an open-source project or a vendor's code; its intent is upstream's to state. **Owner**: the repo is the user's own product; it is theirs. Use what the user said, the origin remote and the README; ask in one line only if it is unclear.
+2. Read before you suggest. Researcher: upstream's security docs, deployment and hardening guides, SECURITY.md and docs/, each with its URL or path, then the auth and role code. Owner: the README, route table, auth and role code, data models, anything touching money or other users' data. Both: `.guardlink/definitions.*`, and `.guardlink/intent.md` if it exists (you are refreshing, not starting over). Build the code graph first when there is none or it is diverged: `bravos graph build . --scip no-exec` (no tokens, a few minutes; bravos-codegraph step 2). With the code graph (its MCP tools, or `bravos graph <question> --json` — same answers; see bravos-codegraph) (briefing `Code graph:` says `current`): `codegraph_routes`, `codegraph_attack_surface` and `codegraph_auth_boundary` give the real public surface — which routes answer unauthenticated callers, which need a tenant, which are admin-only; cite "code graph" as the source of each fact, suggestion and candidate INT item they produce ("these N APIs answer unauthenticated callers; upstream documents M of them"). Without it, say "code graph unavailable; surface read from the route table" and read the routes and auth code.
+3. Suggest every answer yourself. Researcher, the open decisions (5 to 8, each `mustTouch: true`): which configuration to rate against (shipped defaults, upstream's recommended hardened setup, or both); single organisation or multi-tenant; which attackers are in scope (`multi`: unauthenticated network, authenticated low-privilege tenant, malicious client or worker, compromised peer or replica, internal network, operator, suggesting the last two out unless upstream says otherwise); each intended-looking behaviour upstream does not clearly document ("upstream is silent"); which invariants to test first. Everything else is a fact with `folded: true` and its source: actors, crown jewels, boundaries, behaviours upstream documents as intended (cite where), and invariants worded as the properties upstream claims. Owner: purpose, users and roles, crown jewels, two to five must-never rules, intended-by-design powers and boundaries; open by default, the rule and intended items `mustTouch`. Give every question a `suggested` answer, a one-line `reason`, its `sources` and a `confidence`; mark `low` and `mustTouch` anything you are unsure of.
+4. Write it to `.guardlink/intent-draft.json` (schema `bravos.review/v1`, `perspective` set; question types `choice`, `multi`, `item`, `text`) and run `bravos review intent`. Tell the user: "the page that just opened has my suggestions filled in; change what is wrong, make the calls marked 'needs your call', then Confirm. Teammates run `bravos review intent` after pulling; say done when everyone has." If they prefer chat, or no browser can open, ask the same open decisions in one message. If they ask to share it on claude.ai and this is Claude Code, run `bravos review intent --share`, say first that their security intent will sit on claude.ai, publish the page it writes with the Artifact tool and `capabilities: {db: {}}`, and give them the link.
+5. Wait for "done". Run `bravos review intent --summary` (for a shared page, first copy each document in its `answers` collection to `.guardlink/intent-answers/<name>.json` with ArtifactData). Settle each DISAGREE with the people involved; take EDITED answers as given. If the user is away on an unattended campaign, record your suggestions marked `— draft` and carry on; never record a decision nobody made.
+6. Write `.guardlink/intent.md` from `{{SKILL_DIR}}/intent.example.md`. Researcher: an `## Assumptions` section first, with the configuration baseline, deployment and attackers in scope, each ending `— set by <names>, <date>`. Then purpose, actors, crown jewels, invariants `INV-1`…, intended-by-design `INT-1`… (researcher items carry `(upstream: <url or path>)`, or `(upstream is silent)`), and boundaries. End each item with how it was decided: `— suggested by bravos, accepted by <names>`, `— edited by <names>`, `— chosen by <names>`, or `— draft`. Commit the draft and answers files with it.
+7. Put the structured facts in the threat model. In `.guardlink/definitions.*`, reusing ids and never redefining one: `@actor` per role, `@asset` per crown jewel, and one `@threat` per invariant, e.g. `@threat Cross-tenant read (#inv-tenant-isolation) [high] -- "INV-2: a user reads only their own tenant's orders"`. Beside the code they describe: `@handles <class> on <Asset>` for each crown jewel's data and `@boundary` for each boundary.
+8. Run `guardlink validate .` and fix what it reports in the lines you wrote.
+9. Commit `.guardlink/intent.md` and the definitions together, message `context: intent and invariants`.
+10. Hand the invariant threat ids, the Assumptions and the intended-by-design list to bravos-annotate.
+
+## Never
+
+- Mark a draft invariant or intended-by-design item as confirmed, or put words in the user's mouth.
+- Record a must-touch decision (an assumption, an unclear intended behaviour) as made unless a named person chose it in the page or in chat; accepting a suggestion untouched never counts for those.
+- Present an upstream behaviour as intended without citing where upstream says so; write "upstream is silent" instead.
+- Mark an item confirmed that no named person agreed to, in the review page or in chat.
+- Publish the review page to claude.ai unless the user asked to share it and heard that it puts their security intent there.
+- Rewrite a confirmed line in `.guardlink/intent.md`; append a dated change beneath it instead.
+- Treat an intended-by-design item as an accepted risk: write `@accepts`, `@entitles` or `@confirmed`, or remove an existing claim because of it.
+- Redefine an id that already exists in `.guardlink/definitions.*`.
+
+## Done when
+
+- `.guardlink/intent.md` exists, and every item is marked confirmed or draft.
+- To read it again later, nothing needs re-running: `.guardlink/intent.md` itself, `bravos review intent --summary` (answers against suggestions), or `i` in `bravos watch`. Re-run this skill only to refresh the intent after the product or scope changes.
+- Each invariant has a threat id in the definitions, and `guardlink validate .` exits 0.
+- You told the user which items are still drafts and what confirming them changes.
+
+## What it leaves for the next skill
+
+- The invariant threat ids, the intended-by-design list and the boundaries, for bravos-annotate and bravos-templatize.
+
+## Go deeper
+
+- `{{SKILL_DIR}}/intent.example.md` — the shape of the intent file, with examples.
+- `{{SKILLS_ROOT}}/bravos-annotate/SKILL.md` — how intent changes what gets annotated and how it is rated.

package/skills/bravos-context/intent.example.md

@@ -0,0 +1,48 @@
+# Intent — <product name>
+
+What the software is for and what it intends. For a researched project this comes from upstream's
+own docs, with each source cited; for your own product, from you. bravos-annotate judges every
+claim against this file. Each item ends with how it was decided — `— suggested by bravos,
+accepted by <names>`, `— edited by <names>`, `— chosen by <names>` or `— draft`; change a decided
+line by appending a dated note beneath it, never by rewriting it.
+
+## Assumptions (researched projects: what severities are rated against)
+
+- Configuration: <shipped defaults | upstream's recommended hardened setup | both, rated separately> — set by <names>, <date>
+- Deployment: <single organisation | multi-tenant | both> — set by <names>, <date>
+- Attackers in scope: <e.g. unauthenticated network, authenticated tenant, malicious worker, compromised peer>; out of scope: <e.g. internal network, operator> — set by <names>, <date>
+
+## Purpose
+
+- <One or two sentences: what it does, for whom, who pays.> — draft
+
+## Actors
+
+- <Role, e.g. Customer: signs up, places orders, sees only their own account.> — draft
+- <Role, e.g. Tenant admin: manages users inside one organisation.> — draft
+- <Role, e.g. Operator: internal staff with support tooling.> — draft
+
+## Crown jewels
+
+- <Asset and data class, e.g. Payment records (financial).> — draft
+- <e.g. Customer profiles (pii).> — draft
+
+## Invariants (must never happen)
+
+- INV-1: <e.g. A user never reads or changes another tenant's data.> — draft
+- INV-2: <e.g. A refund is never issued without an approved order.> — draft
+- INV-3: <e.g. No role can grant a role above its own.> — draft
+
+## Intended by design (looks dangerous, is the product)
+
+- INT-1: <e.g. Operators can impersonate a customer for support; it is logged.> (upstream: <url or path>, or: upstream is silent) — draft
+- INT-2: <e.g. The CLI runs user-supplied shell commands on the user's own machine.> — draft
+
+## Trust boundaries
+
+- <e.g. Public internet → API gateway (unauthenticated).> — draft
+- <e.g. API → billing provider (third party).> — draft
+
+## Changes
+
+- <YYYY-MM-DD: what changed and who confirmed it.>

package/skills/bravos-env/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: bravos-env
+description: "Bring up a test target the user owns and prepare it for an authorized cxg run, under bravos's governance: loopback by default, a committed and reviewed scope.yaml, the human's own typed authorization, and a real session captured or imported, never invented. Use before bravos-prove or a template replay, when asked to stand up a test environment, seed test users or roles, or capture an auth session."
+---
+# Bravos env: a target the user owns, ready for an authorized run
+
+## When
+
+- bravos-prove or bravos-recheck needs a running target and none is up.
+- The user asks to start the app for testing, seed test users, roles or orgs, or capture a login session.
+- A run was refused at pre-flight (cxg exit 4) or stopped on a dead session (exit 5).
+
+## Do
+
+1. Decide the target with the user. The default is the app running on this machine at a loopback address (`127.0.0.1`, `localhost`, `[::1]`). Start it with the repo's own tooling (its compose file, dev server script or desktop build) and wait until it answers. In a bravos workspace each service has its own target: take the URLs from `bravos workspace show` (set a missing one with `bravos workspace target <name> <service>=http://127.0.0.1:<port>`), bring up every service the test crosses, and list every service host in the reviewed scope's `host_allowlist`.
+2. On loopback, a recorded proving preference (`.guardlink/proving.md`, `choice: auto`) is the person's go-ahead for its target: start it with the recorded command and do not ask again. If the user names a non-loopback target, stop and get two things before going on: the host listed in a committed `scope.yaml` that has been through a reviewed PR, and the human's authorization typed by them in this session in their own words. Without both, the target is out of scope; say so and stay on loopback.
+3. Write the scope. Copy `{{SKILL_DIR}}/scope.example.yaml` to `.guardlink/scope.yaml`, or run `cxg pentest scope-init -o .guardlink/scope.yaml` for the full field reference, then narrow `url_allowlist` to the routes under test. `method_allowlist` is a strict bound: cxg refuses every method it does not list, even with `--destructive-ok`, so a test that needs PUT, PATCH or DELETE needs the target's owner to add them in the reviewed PR; never add them yourself. scope-init pre-fills `authorization_attestation` with an example sentence: blank it. Leave that field for the human to fill. Commit it and ship it as a PR for review before any non-loopback run.
+4. Seed test data with the repo's own fixtures, seed scripts or admin endpoints: the roles and users the threats need, such as two users of different tenants for an ownership check. Name any test that needs production-like data as such, and run it only where that data is synthetic.
+5. Get a session. On loopback, do it yourself: create the test accounts through the app's own signup, seed script or admin endpoint, write their email and password to a gitignored file under `.bravos/`, and log in with `cxg pentest auth --target <url> --profile <name> --creds-file <file> --login-path <login route>`, one profile per identity a check needs. If the app's login is not a JSON POST, drive the signup and login in your own browser tool and capture the session interactively with `cxg pentest auth --target <url> --profile <name>`. For an authorized non-loopback target, ask the human to capture the session in their own browser with the same command, or to paste a storage state you import with `cxg pentest auth import --storage-state <file> --profile <name> --target <url>`; CI uses the import with a session the human exported once.
+6. Confirm each session is live with `cxg pentest auth verify --profile <name>` before handing the target on, so a run never spends its budget unauthenticated.
+7. Record the target URL, the profile names, the scope path and whether the target is loopback, and hand them to bravos-prove.
+
+## Never
+
+- Invent, guess or brute-force a credential, token or session. Use accounts you created through the app on loopback, or a session the human captured or pasted for any other target.
+- Create accounts or log in yourself on a non-loopback target, or commit the test-account credentials file.
+- Point any run at a host that is not loopback unless it is in a committed, reviewed `scope.yaml` and the human typed their authorization in this session.
+- Write the `authorization_attestation` text yourself or paraphrase the human's words into it.
+- Record a proving preference the person did not state; `.guardlink/proving.md` quotes their words and never covers a non-loopback target.
+- Enable destructive probe classes against anything but a disposable loopback target, or add a `disposable_host_grants` entry.
+- Seed or test against real user data.
+- Write `@accepts`, `@entitles` or `@confirmed`; this skill prepares a target and judges nothing.
+
+## Done when
+
+- A target answers, and it is loopback or it is covered by a reviewed scope plus the human's typed authorization.
+- `.guardlink/scope.yaml` exists, is committed and leaves `authorization_attestation` to the human.
+- Each profile bravos-prove needs passes `cxg pentest auth verify --profile <name>`.
+- You told the user what you seeded and which tests need data that is not synthetic.
+
+## What it leaves for the next skill
+
+- The target URL, profile names, scope path and the loopback verdict, for bravos-prove and bravos-recheck.
+
+## Go deeper
+
+- `{{SKILL_DIR}}/scope.example.yaml` — the loopback starter and what each field limits.
+- `{{SKILLS_ROOT}}/bravos-prove/SKILL.md` — what happens with the target next.

package/skills/bravos-env/scope.example.yaml

@@ -0,0 +1,50 @@
+# bravos starter scope for cxg pentest — loopback only.
+#
+# Copy to .guardlink/scope.yaml, commit it, and get it reviewed in a PR before any run.
+# Full field reference: `cxg pentest scope-init -o /tmp/reference-scope.yaml`.
+#
+# This starter allows only the read-mostly methods, a small budget, and no disposable-host
+# grants, so destructive probe classes stay limited to a loopback target. Widening any of
+# it is a decision for the person who owns the target, made in the reviewed PR.
+
+# The human's written authorization, in their own words, typed in the session that runs
+# the test. bravos never writes this line for them. Leave it empty until they do.
+authorization_attestation: ""
+
+# A strict bound: cxg refuses every method not listed, even with --destructive-ok. A test that
+# needs PUT, PATCH or DELETE needs them added here, in the reviewed PR, by the target's owner.
+method_allowlist: [GET, POST, HEAD, OPTIONS]
+
+# Empty means every path under --target. Narrow it to the routes under test.
+url_allowlist: []
+
+# Paths no run may touch, whatever the allowlist says.
+url_blocklist: []
+
+# Paths no run may touch without --destructive-ok. cxg replaces its built-in list with this one,
+# so it carries all nine of cxg's defaults; add to it, do not trim it. Single quotes keep each
+# backslash literal: in double quotes YAML reads \b as a backspace and the pattern matches nothing.
+destructive_patterns:
+  - '/delete[-_]?all\b'
+  - '/wipe\b'
+  - '/purge\b'
+  - '/drop[-_]?(?:db|database|table|all)\b'
+  - '/reset[-_]?(?:all|db|database)\b'
+  - '/destroy[-_]?all\b'
+  - '/admin/(?:teardown|format|nuke)\b'
+  - '/__truncate__\b'
+  - '/factory[-_]?reset\b'
+
+# Target host only.
+host_allowlist: []
+
+max_requests_per_endpoint: 20
+max_requests_total: 500
+request_interval_seconds: 0.2
+max_socket_connections: 5
+five_xx_streak_threshold: 5
+
+# Empty: destructive classes run against a loopback target only.
+disposable_host_grants: []
+
+brute_force_min_attempts: 20

package/skills/bravos-prove/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: bravos-prove
+description: "Run the authorized test against a target the user owns and record what it showed: export the claims for cxg, replay the kits written in this session, let cxg generate probes for the rest through a model API, read the report's buckets and exit code, and write outcomes back only through guardlink's hypothesis ledger. Use when asked to prove, test or verify a finding, to check whether an exposure is exploitable, or after bravos-templatize and bravos-env have prepared a run."
+---
+# Bravos prove: an authorized run, and only a run decides
+
+## When
+
+- The user asks whether an exposure is exploitable, or to prove, test or verify a finding.
+- bravos-templatize wrote templates and bravos-env has a target ready.
+- `guardlink hypothesis next` puts an untested exposure at the top.
+
+## Do
+
+1. Check the preconditions from bravos-env: a target that answers, `.guardlink/scope.yaml` committed, each profile passing `cxg pentest auth verify --profile <name>`, and for any non-loopback target both a reviewed scope and the human's authorization typed in this session. If one is missing, stop and hand back to bravos-env. Read the effort: the user's words ("at high"), else a `bravos effort: <level>` line in `AGENTS.md` / `CLAUDE.md`, else medium. It sets a starting budget, not a limit; go beyond it when the work needs it and say why in one line. Starting budget — low: replay existing kits only; medium: also cxg generation for exposures without a kit, `--max-templates 8`, after asking about the spend; high: `--max-templates 32` with `--enable-chaining`; max: every testable class, spend pre-approved (no question).
+2. Order what to test, then read how the person wants proving handled. With the code graph (its MCP tools, or `bravos graph <question> --json` — same answers; see bravos-codegraph) (briefing `Code graph:` says `current`): `codegraph_untested_exposures` and `codegraph_untested_reach` rank untested exposures by reach; test the ones intent.md's Assumptions put in scope first, least privileged entry point first, and report exposures only an out-of-scope attacker reaches instead of running them. Without the graph, say "code graph unavailable; using guardlink hypothesis next order" and use that queue. Within that order, an exposure with a reachable SAST finding joined to it (`bravos sast candidates`) goes before one without, and its route goes into the run notes; with no SAST report or SAST unavailable, skip this. Then, for how the person wants proving handled: the briefing's `Proving:` line, from `.guardlink/proving.md`. If it is not set, ask them once, with a suggestion drawn from the repo (for example, "you have a docker-compose; I'd prove automatically on 127.0.0.1:8080"): prove automatically on their loopback target whenever new or changed exposures appear, ask each time, on a schedule (bravos-schedule's nightly), or not now; and whether cxg may generate probes through a model API, which spends money. Record their answer in `.guardlink/proving.md`: lines `choice: auto|ask|schedule|none`, `target: <loopback url>`, `start: <start command>`, `generation: yes|no`, their words quoted verbatim, and `— confirmed by <their name>, <date>`. Then follow it: `auto` proceeds on that target with their quoted words as the attestation and, with `generation: yes`, the spend approved; `ask` asks now; `schedule` hands to bravos-schedule; `none` stops here and says so. When they change their mind, rewrite the file with their new words.
+3. Export the claims cxg reads: `guardlink sarif . --profile pentest -o whitebox/findings.sarif`.
+4. Web or Electron target: replay the kits written in this session with `cxg pentest run --codebase . --target <url> --auth <profiles> --no-author --template-dir .guardlink/cxg-replay/ --scope-file .guardlink/scope.yaml --attestation "<the human's words>" --session-dir .guardlink/pentest-findings/<run> --ci`, adding `--target-type electron` for an Electron app. `<profiles>` is every login the kits' `@requires_identities` lines name, comma-separated (`victim,attacker` for an IDOR kit), each verified in bravos-env; a kit whose login is missing is skipped. `--no-author` keeps a replay to zero model calls: without it cxg can rewrite an ambiguous probe through the claude CLI. Copy the attestation verbatim from what the human typed; leave the flag off on loopback if they gave none. In a bravos workspace, run each kit against the URL of the service that owns its file (`bravos workspace show` lists the services, their URLs and the calls between them); a chain that crosses services is run one hop at a time, each hop against its own service's URL under that service's scope and authorization, with the previous hop's result carried as the next hop's input — never one run pointed at several hosts.
+5. Exposures with no kit yet: let cxg generate probes from the exported claims, steered by the operator guidance. First tell the user the run calls a model API (up to the template budget) and get their go-ahead, unless they already approved the spend (effort max, or a standing line saying so); then run `cxg pentest run --codebase . --target <url> --auth <profile> --ai --ai-provider anthropic --max-templates 8 --skills-file .guardlink/operator-guidance.md --scope-file .guardlink/scope.yaml --attestation "<the human's words>" --session-dir .guardlink/pentest-findings/<run> --ci` (use `openai` if that is the key the user has). Copy every generated template that confirmed or refuted into `.guardlink/cxg-replay/` so the next run replays it.
+6. Network or CLI templates from the translate method: run `cxg scan --scope <url> --template-dir .guardlink/cxg-templates/ --output .guardlink/pentest-findings/<run> --output-format json,sarif`, with a loopback URL or `cli:///absolute/path/to/binary` as the scope. That folder holds scanner templates only (bravos-templatize keeps probes in `.guardlink/cxg-replay/`); if a JavaScript probe is in it, cxg runs it under its default scope, so move the probe out, or add `--scope-file .guardlink/scope.yaml --auth <profiles> --session-dir .guardlink/pentest-findings/<run>` before running.
+7. Read the exit code before the report. For `cxg pentest run`: 0 none confirmed, 1 no templates ran, 2 confirmed findings, 3 hard-killed (5xx streak, scope violation, target died), 4 refused (at pre-flight, or a supplied probe was skipped for a missing login or refused), 5 session dead in CI. On 3 or 5 stop: nothing was proven, so report the cause and hand back to bravos-env. On 4 read the report before concluding: its `status`, `auth_skipped` and `probe_refusals` say what was skipped and why, and any probe that did run keeps its confirmed or refuted result. Write back those results, report the skipped ones as untested with their cause, and hand a missing login to bravos-env. For `cxg scan` with probes: 2 means confirmed, 4 a probe refused.
+8. Read the report's buckets: confirmed, refuted (a mitigation held), ambiguous, and not run with its cause. Ambiguous and not-run results prove nothing either way; report them as untested.
+9. Write back the confirmations: `guardlink hypothesis confirm --from-scan .guardlink/pentest-findings/<run>/report.json --write`. It records only findings whose claim key resolves, and writes the source line only for uncontested ones.
+10. Record each refuted result against its claim: `guardlink hypothesis refute <file:line> --evidence "<request sent and response received>"`, quoting the report entry.
+11. Run `guardlink hypothesis list --state confirmed --json` and report each new confirmation with its threat, asset and file:line, plus the refutations and every result left untested.
+12. Hand confirmed threats to the user as fix-first, and to bravos-recheck once a fix lands.
+
+## Never
+
+- Pass `--ai-provider claude`, `codex`, `gemini`, `crush` or `auto` to `cxg pentest run`; those launch another agent CLI. Only the API providers `anthropic` and `openai` generate probes, and only with the spend approved.
+- Run against a host outside the committed scope, or without the human's typed authorization when the target is not loopback.
+- Write `--attestation` text the human did not type, here or in `.guardlink/proving.md`.
+- Record a proving preference the person did not state, or read one as covering more than it says: it never covers a non-loopback target or a destructive class.
+- Use `--destructive-ok` unless the target is a disposable loopback instance and the human asked for it.
+- Write `@confirmed` yourself, or treat reading code as a confirmation; only `guardlink hypothesis confirm --from-scan` from a real report writes it.
+- Call an exposure refuted because a run found nothing, or because the run was killed, refused or never ran its template.
+- Write `@accepts` or `@entitles`.
+
+## Done when
+
+- The run exited 0 or 2 and its report was read bucket by bucket, or you reported why it stopped.
+- Every confirmed finding went through `guardlink hypothesis confirm --from-scan`, and every refutation cites its request and response.
+- For each claim you reported its three states: open or mitigated, confirmed, refuted or untested, and verified or stale, plus what was not tested.
+
+## What it leaves for the next skill
+
+- The run directory, the confirmed and refuted claim keys, and the untested ones, for bravos-recheck and bravos-ship, and for bravos-report to write up what was proven.
+
+## Go deeper
+
+- `{{SKILLS_ROOT}}/bravos-env/SKILL.md` — the target, scope and session this run depends on.
+- `{{SKILLS_ROOT}}/bravos-recheck/SKILL.md` — replaying these kits after a fix.

package/skills/bravos-recheck/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: bravos-recheck
+description: "Keep findings from going stale after code changes: list the claims a change made stale, re-read and re-verify them, replay the retest kits of confirmed threats against an authorized target, check the fix added no new exposure, and re-read what to test next. Use after a security fix lands, when the briefing lists stale claims, when asked whether a fix held, and before closing a security ticket."
+---
+# Bravos recheck: a fix is not done until the claim is current
+
+## When
+
+- A fix for a confirmed or open exposure has been written.
+- The briefing's `Went stale in files you changed since <base>` line is not empty.
+- The user asks whether a fix held, or wants to close a security ticket.
+
+## Do
+
+1. Find the base: `git symbolic-ref -q --short refs/remotes/origin/HEAD` prints `origin/<base>` (if empty, use `main`), then `git merge-base HEAD origin/<base>`. Read the effort: the user's words ("at high"), else a `bravos effort: <level>` line in `AGENTS.md` / `CLAUDE.md`, else medium. It sets a starting budget, not a limit; go beyond it when the work needs it and say why in one line. Starting budget — low: stale claims in the change only; medium: also confirmed threats on changed files; high: every confirmed threat; max: everything, then send annotation gaps to bravos-annotate.
+2. List what went stale: run `guardlink ci -f json` and take each `stale[]` entry whose file is in `git diff --name-only <base>...HEAD`. Then widen it past the changed files. With the code graph (its MCP tools, or `bravos graph <question> --json` — same answers; see bravos-codegraph) (briefing `Code graph:` says `current`; rebuild with `no-exec` when `diverged`): `codegraph_impact` on each changed symbol, and `codegraph_callers` where a control moved, give the code whose path runs through the change; add the claims in those files to the list. A fix that removes the only route to a sink (`codegraph_entry_reach` now says unreachable) is a reason to replay its kit and refute it with a run, never a refutation by itself. Read `verdict` and `confidence` first. Without the graph, say "code graph unavailable; rechecking the changed files only". When SAST is available and a run exists, rerun it on the changed files (bravos-sast, `--scope <file>` for each) and compare with `bravos-cli diff <new>.json <old>.json`: a finding that is gone is a reason to replay its kit and refute it with a run, never a refutation by itself. With SAST unavailable, say so and skip it.
+3. For each stale claim, re-read the code beneath it and decide whether the claim still says what the code does. If it does not, fix the annotation in this session with bravos-annotate's rules (write an `@audit` beside a claim you did not write rather than editing it).
+4. Re-lock only the claims you re-read and still hold: preview with `guardlink verify <file:line> --dry-run`, then run `guardlink verify <file:line>`. Never re-lock a claim you did not read.
+5. List confirmed threats on the changed files: `guardlink hypothesis list --state confirmed --json`, keeping those in the diff.
+6. Replay each one's retest kit against the authorized target from bravos-env: `cxg pentest run --codebase . --target <url> --auth <profile> --template-dir .guardlink/cxg-replay/ --scope-file .guardlink/scope.yaml --attestation "<the human's words>" --session-dir .guardlink/pentest-findings/<run> --ci`. Copy the attestation verbatim from what the human typed; leave the flag off on loopback if they gave none. No kit yet: hand the threat to bravos-templatize first.
+7. Read the result as bravos-prove does. Still confirmed: the fix did not hold; say so. Refuted with the same request: record it with `guardlink hypothesis refute <file:line> --evidence "<request sent and response received>"`, and tell the user the confirmation line in the source is theirs to remove. Killed, refused or not run: nothing was rechecked.
+8. Check the fix added nothing: `guardlink diff <base> --fail-on-new --markdown`, then `guardlink lint . --since <base> --json`, applying each `fix` only to lines this session wrote.
+9. Re-read the queue with `guardlink hypothesis next --json` and name the next item.
+
+## Never
+
+- Re-lock a stale claim with `guardlink verify --stale` or `--all` in bulk; each re-lock asserts a control still holds, so it needs the code read first.
+- Remove or edit a `@confirmed` line; after a replay shows the exploit no longer works, the human removes it.
+- Call a fix verified because the code changed, because a scan found nothing, or because a run was killed or refused.
+- Replay against a target outside the committed scope, or without the human's typed authorization when it is not loopback.
+- Write `@accepts` or `@entitles`.
+
+## Done when
+
+- Every stale claim in the change was re-read and either re-locked, corrected, or reported.
+- Every confirmed threat on a changed path was replayed, or you said why it was not.
+- `guardlink diff <base> --fail-on-new --markdown` exits 0, or each new exposure it lists is reported as open.
+- You named the three states for each claim you touched and what was not tested.
+
+## What it leaves for the next skill
+
+- The re-locked, corrected and still-confirmed claims, and the replay run directory, for bravos-ship, and for a bravos-report retest report that records the outcome beside the original finding.
+
+## Go deeper
+
+- `{{SKILLS_ROOT}}/bravos-prove/SKILL.md` — how a run's report is read.
+- `{{SKILLS_ROOT}}/bravos-annotate/SKILL.md` — the rules for correcting a claim.

package/skills/bravos-report/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: bravos-report
+description: "Write a crisp, evidence-bound white-box VAPT write-up in this session: a full assessment, a single finding, a retest report or an executive brief, built only from the facts bravos report data gathers (threat model, hypothesis ledger, cxg runs, SAST, code graph, intent, scope), with every claim of proof citing its evidence and its evidence level computed rather than asserted; check it with bravos report check, then export it to md, txt, html or pdf. Use when asked to write up, report, summarise for leadership, document a finding, or record a retest."
+---
+# Bravos report: decisions first, evidence underneath, nothing claimed that was not shown
+
+## When
+
+- The user asks for an assessment report, a write-up, a summary for leadership, or the findings documented.
+- bravos-prove confirmed or refuted something, and the result should reach someone who was not in the session.
+- bravos-recheck replayed a fix, and the retest should be recorded next to the original finding.
+- An engineer needs one finding written so they can reproduce it, fix its cause and show closure.
+
+## Do
+
+1. Pick the kind from the request: `assessment` (the default: the full eight-section report), `finding` (one self-contained write-up; needs `--finding <claim key prefix | file:line | EXP id>`), `retest` (original result, replay, residual exposure) or `brief` (the decision summary alone). Read the effort as the other skills do; it sets how deep the system context and narratives go, never which facts are included.
+2. Gather the facts: `bravos report data --kind <kind>` (add `--finding …` for one finding, `--no-graph` when the graph is slow or absent). It writes `.bravos/reports/<id>/evidence.json` and prints the report id and folder. Read the bundle: `candidates` are the exposures with their computed `level`, `items` are every citable fact by id, `runs` are the cxg results, `gaps` are what could not be gathered. If `runs` is empty, say in the report that nothing was exercised at runtime; no finding may then read as reproduced.
+3. Read `.guardlink/intent.md` (in the bundle as `intent.text`): its Assumptions name the attacker starting positions, the configuration baseline and the scope decisions. Keep the tester's access (source code, admin credentials, the loopback target) apart from what an attacker needs: every finding states the attacker's prerequisites, never the tester's. Then collect what a reader needs to rebuild the test, from the run folders the bundle lists, `.guardlink/proving.md` (target and start command), `.guardlink/scope.yaml` and the session's own history: how the product was built; every config and feature-flag change; how keys and accounts were made and which permission each held; what was seeded; and every helper written to test it (a stub handler, a gRPC client or worker), with how to install and run it. Copy the config files and scripts, never keys or tokens, into the run folder so the report can point at them.
+4. Consolidate before you write: group exposures that share one root cause into one finding (cite every EXP id it covers); order findings by remediation priority (exposure, asset sensitivity, prerequisites, compensating controls), kept apart from technical severity; build an attack narrative only from steps the evidence links (a run's chained steps, flows in the model, a code-graph call chain), and cite each step.
+5. Write `.bravos/reports/<id>/report.md` from the template for the kind: `{{SKILL_DIR}}/assessment.md`, `{{SKILL_DIR}}/finding.md`, `{{SKILL_DIR}}/retest.md` or `{{SKILL_DIR}}/brief.md`, in the voice `{{SKILL_DIR}}/style.md` sets. Write for the team that has to act on it: plain words first; what the attacker wants and what they need; why it is a vulnerability; the weaknesses one by one and how they chain step by step; the environment and the roles table; a cxg reproduction (`cargo install cert-x-gen`, the template, the exact `cxg scan` command and its expected output); granular manual steps; what held; and the fix with how to check it. Evidence ids go in the closing Evidence section, not in the prose. When the proof is a script rather than a cxg template, hand it to bravos-templatize to become one, and have bravos-prove replay it under the person's authorization before you quote its output; otherwise say the cxg command was not run.
+6. Give each finding a `**Status:**` line with the bundle's computed level for what it cites, word for word: `reproduced at runtime`, `control held at runtime`, `established by code or configuration review`, or `suspected, awaiting validation`. Repeat it in the Evidence section with the evidence ids in parentheses (the top line may say "see Evidence"). A weaker label than the evidence supports is allowed; a stronger one is not. "Not reproduced" names the conditions tested, from the run's not-run causes.
+7. Write coverage with its denominator ("cross-tenant reads exercised on 3 of 11 routes"; "83% of files, 1,417 of 1,712"), list the controls that held next to the weaknesses, and keep raw tool output in the appendices. Quote requests and responses from the run evidence with tokens and credentials redacted; the bundle already redacts what it recognises.
+8. Severity: give the rating and its rationale in this application's context. Use CVSS only when you can state the version and the full vector from facts in the bundle; never a bare score.
+9. Check: `bravos report check <id>`. Fix every error and rerun until it passes; read the warnings (long paragraphs, vague titles) and fix the ones that would slow a reader down.
+10. Export: `bravos report export <id> --format md,html` by default, or the formats the user asked for (`txt`, `pdf`; `--open` to open the html or pdf). PDF needs an installed Chrome, Edge, Brave or Chromium; without one, the html stands and the command says so.
+11. Tell the user where the files are, how many findings are reproduced at runtime, established by review, and suspected, and what remained untested (the bundle's gaps and not-run causes). The report stays in `.bravos/reports/`, which git ignores; sharing it is the person's decision.
+
+## Never
+
+- Call a finding reproduced, or a control held, without a ledger record or a run result the bundle lists; the check refuses it, and so should you.
+- Write `@confirmed`, `@accepts` or `@entitles`, or change a claim's tested state from a report; reports describe the ledger, they never write it.
+- Print a live secret, token, password or session cookie; cite the rule and file:line instead, as the SAST secrets list does.
+- Send traffic, start a target, or run a probe; this skill only reads the evidence and writes.
+- Turn a dependency advisory into an exploit claim when the vulnerable function is not shown reached.
+- Commit the report folder, or copy evidence into a tracked file, unless the person asks and has redacted it.
+
+## Done when
+
+- `bravos report check <id>` passes for the report.
+- The exports the user asked for exist beside `report.md`, and you named them.
+- The user knows what is reproduced, what is code-review only, what is suspected, and what was not tested.
+
+## What it leaves for the next skill
+
+- Each finding's F-id, its EXP ids and claim keys: bravos-recheck replays the reproduced ones after a fix, and a retest report records the outcome next to the original.
+- The remediation roadmap, with acceptance criteria per item, for tickets (`@ticket` is the developer's to add).
+
+## Go deeper
+
+- `{{SKILL_DIR}}/assessment.md` — the eight sections in reading order, and what each gives the reader.
+- `{{SKILL_DIR}}/finding.md` — the fields every finding carries.
+- `{{SKILL_DIR}}/retest.md` and `{{SKILL_DIR}}/brief.md` — the other two kinds.
+- `{{SKILL_DIR}}/style.md` — how to write it so an engineer can act without asking the author.

package/skills/bravos-report/assessment.md

@@ -0,0 +1,54 @@
+# Assessment template
+
+The full white-box assessment, in reading order: decisions first, then progressively deeper evidence. Keep the eight `##` headings as written (the numbers are optional); `bravos report check` reads them in this order.
+
+```markdown
+# <Application> security assessment — <month year>
+
+## 1. Executive assessment
+
+<One to two pages. The main risks in plain words, what was demonstrated (and what was only reviewed), the strengths that held, and the decisions needed from the reader. Lead with the single most important sentence.>
+
+## 2. Scope and limitations
+
+<Applications, repositories, environments, roles and workflows assessed; exclusions; the access provided to the tester; dates; the reviewed commit and the tested build; the configuration baseline from intent.md; and what was unavailable (the bundle's gaps).>
+
+## 3. System and threat context
+
+<A compact diagram of the real boundary or flow (a fenced mermaid block or a short list), the sensitive assets, the trust boundaries, and the attacker starting positions in scope (intent.md's Assumptions). Separate the tester's access from the attacker's.>
+
+<For an app made of several services (a workspace bundle, `bravos report data --workspace`): a short "Services and the calls between them" part — each service, where it answers, and each cross-service call (EDGE-n) that an attack can cross. Cite a service's evidence with its prefix, e.g. `orders:EXP-3`.>
+
+## 4. Coverage and approach
+
+<What was examined and how deeply, with denominators: annotated files out of source files, exposures tested out of declared, routes exercised out of routes known, roles used. Name the controls that held. Name what was not tested and why (not-run causes, missing logins, out-of-scope attackers).>
+
+## 5. Principal attack narratives
+
+<How the most consequential weaknesses work together, step by step, each step citing its evidence id. Only chains the evidence links; a plausible chain nobody exercised is labelled as such.>
+
+## 6. Findings
+
+<One block per finding, ordered by remediation priority: a "### F-01 — <who can do what to what>" heading, then the finding template's lines and sections (finding.md) one heading level down — **Status:** and **Severity:** lines, then #### headings for what the attacker needs, what we found, how it chains, impact, how to reproduce (cxg and by hand), what held, and the fix with how to check it.>
+
+## 7. Remediation roadmap
+
+<A table: action, finding ids, owner, depends on, target date (agreed, or "to agree"), acceptance criterion. Separate immediate containment from the durable fix.>
+
+## 8. Retest results and appendices
+
+<Retest outcomes so far (or "no retest yet"), then appendices: the test environment once for every finding (build, config changes, accounts and permissions, seeded data, helpers written), the evidence index (id → what it is), raw tool output summaries, tool versions, and the full list of exposures with their tested states.>
+```
+
+## What each section gives the reader
+
+| Section | The reader can then |
+|---|---|
+| Executive assessment | decide what to fund and what to stop |
+| Scope and limitations | know exactly what the conclusions cover |
+| System and threat context | see where the boundary is and who is outside it |
+| Coverage and approach | judge how much weight an absence of findings carries |
+| Principal attack narratives | understand the worst realistic outcome |
+| Findings | reproduce, fix and verify each issue |
+| Remediation roadmap | plan the work and know when it is done |
+| Retest and appendices | check closure and trace every claim to its evidence |