buhtig 0.1.0-alpha.1

package/packages/cli/dist/docs/buhtig-review/API.md

@@ -0,0 +1,486 @@
+# The review API
+
+Every call the review surface offers, in the order a run uses them.
+
+{{preamble}}
+
+---
+
+## 1 · The taxonomy
+
+What facets exist, the scales, the summary sections, and which fields you may write:
+
+```call review.config
+{ "owner": "$OWNER", "repo": "$REPO" }
+```
+
+`state` is `configured` | `absent` (no `review:` block, or the dir has no facet markdown) |
+`unknown` (configured but buhtig cannot reach it — `detail` says why). On anything but `configured`,
+stop and tell the human; do not invent a taxonomy.
+
+The **reviewable units** are the facets with `isFamily: false` — one assignment each. Families are
+containers, not units.
+
+`writable` names the fields an agent may set, **per resource and per verb**:
+`writable.finding.create` is what a write takes, `writable.finding.update` what an edit takes. It is
+derived from the request schemas, so it cannot drift from what the API actually accepts — anything
+outside it is stripped, and there is no reason to probe. `writable.disposition` is nearly empty **by
+design**.
+
+Facets may also carry three frontmatter declarations, all inherited by descendants — `dormant: true`
+(retired: planned as a `skipped` assignment, never dispatched), `when: { paths: [...] }` (review only
+when the change touches a matching file), and `effort: low|medium|high` (how deep to go). They arrive
+on the assignment as `status`/`reason`, `applies`, and `effort`.
+
+## 2 · One facet's brief
+
+```call review.facet
+{ "owner": "$OWNER", "repo": "$REPO", "facetId": "correctness/R1_type-safety.md" }
+```
+
+Returns the shared contract, the shared briefs, and **that facet's files only**. Hand this to the
+subagent; hand it nothing else from this skill except `FACET_REVIEWER`.
+
+## 3 · Start a run
+
+```call review.startRun
+{ "owner": "$OWNER", "repo": "$REPO", "number": "$PR", "runKey": "$PR-$HEAD7-1", "headSha": "$HEAD" }
+```
+
+- `runKey` is your idempotency key. **201** = created, **200** = resumed. Convention:
+  `<pr>-<head7>-<n>`. A retry with the same key continues the same run.
+- `headSha` is optional but **supply it**: it pins every anchor to the commit you actually read. Omit
+  it and the server uses the PR's current head, which may already have moved.
+- `previousRunId` links a re-review to the run it supersedes.
+- `hasBriefing` says whether §4's shared briefing exists yet. Assignments arrive pre-`skipped`
+  where the taxonomy already answered the question (`dormant`, or a `when:` predicate the change
+  misses); each carries a `reason`, and you may dispatch one anyway.
+
+## 4 · The briefing — write it once, before dispatching
+
+```call review.putBriefing
+{ "id": "$RUN_ID", "bodyMd": "# What this PR does\n\n…" }
+```
+
+```call review.getBriefing
+{ "id": "$RUN_ID" }
+```
+
+A **factual map** of the changed surface, not a findings list — see `ORCHESTRATOR` §4 for what goes in
+it. Every facet agent reads it.
+
+## 5 · Assignment bookkeeping
+
+Claim it, then close it out. `status` (did the work happen) and `outcome` (what it found) are
+independent — a facet can be partly out of scope AND produce findings.
+
+```call review.updateAssignment
+{ "id": "$ASSIGNMENT_ID", "status": "running" }
+```
+
+```call review.updateAssignment
+{
+  "id": "$ASSIGNMENT_ID",
+  "status": "complete",
+  "outcome": "findings",
+  "scopeMd": "Examined the new casts at the repo→service boundary. The frontend was out of scope."
+}
+```
+
+Reading one back — the update already returns it, this is for a resume:
+
+```call review.getAssignment
+{ "id": "$ASSIGNMENT_ID" }
+```
+
+`status`: `pending` `running` `complete` `failed` `skipped` · `outcome`: `findings` `clean`
+`not-applicable` · `reason`: required when `skipped` or `failed`.
+
+Every write here answers with the stored row, so there is nothing to confirm with a second call.
+`usageTokens` is the orchestrator's to record — the subagent cannot see its own total, and without it
+there is no way to tell whether a change made the fleet cheaper.
+
+## 6 · The report
+
+```call review.putReport
+{ "id": "$ASSIGNMENT_ID", "bodyMd": "# Type safety\n\nExamined every `as` cast the PR adds.\n\n## Verified clean\n…" }
+```
+
+One per assignment. It is full-text searchable, and a hit surfaces that facet's findings.
+
+## 7 · Findings — batched, one call per assignment
+
+```call review.writeFindings
+{
+  "id": "$ASSIGNMENT_ID",
+  "findings": [
+    {
+      "slugIndex": 1,
+      "title": "customer external ids are read with no tenant-scope check on the customer",
+      "severity": "P1",
+      "reviewPriority": "R0",
+      "confidence": "high",
+      "blocking": true,
+      "audience": "reviewer+author",
+      "section": "blockers",
+      "path": "src/modules/customer-external-ids.service.ts",
+      "line": 50,
+      "side": "RIGHT",
+      "bodyFinding": "All four routes take `customerId` straight from the path and never resolve it in the caller's tenant scope.",
+      "bodyWhy": "Cross-tenant read of a customer's identity records, and cross-tenant write of them.",
+      "bodyFix": "Resolve the customer first and 404 when it is not visible."
+    }
+  ]
+}
+```
+
+Response: `{ "ids": [...], "warnings": [...] }`.
+
+- **`slugIndex`** is yours, sequential from 1, unique **within your assignment**. Several facet files
+  may declare the same slug; numbering is per assignment, not per slug. Renders as `TYPESAFETY-1`.
+- **`section`** is the promotion signal — a finding carrying one gets an `F<N>` at synthesis and
+  appears in the summary. Keys come from `config.sections`. Omit it for the long tail; those stay
+  fully stored, searchable, and filterable, and can be promoted later.
+- **`displayIndex` is rejected.** You cannot know your global number.
+- **`bodyAuthor` is rejected too.** The author-facing body is composed from `title` + `bodyFinding` +
+  `bodyFix`, with a `Confidence: …` line — read it back on the finding detail, never write it.
+- **Warnings, not errors.** `path-not-found` (that path isn't at the head — usually a typo),
+  `not-in-diff` (real code, but GitHub would reject an inline comment there), `path-too-large` (the
+  file is there and past the read cap, so the anchor is unproven). All three keep the finding. Fix a
+  `path-not-found`; the other two need nothing from you.
+- **A batch without `replace` upserts on `slugIndex`** — re-send one finding to correct it, and its
+  siblings are untouched. `replace: true` makes the batch the **complete set** for the assignment,
+  deleting anything absent; use it only for a deliberate full rewrite.
+- Multi-line: add `endLine` (+ `endSide`). One-click fix: `suggestionMd`.
+- Merging across facets: set `mergedIntoSlugId` (e.g. `"TENANCY-2"`) on the contributor, at write
+  time or by edit at synthesis. It keeps its row and its scores. A slug id matching nothing in the
+  run is **rejected**, not dropped.
+- `fixGroupId`: an arbitrary string shared by findings one fix closes. Group them — it is what turns
+  sixty findings into twenty decisions.
+
+Editing one, including moving it — a changed `path`/`line` is re-anchored server-side:
+
+```call review.updateFinding
+{ "id": "$FINDING_ID", "bodyFix": "Resolve the customer through `ScopeFilter` first." }
+```
+
+Dropping one:
+
+```call review.deleteFinding
+{ "id": "$FINDING_ID" }
+```
+
+## 8 · Synthesize, then complete
+
+```call review.updateRun
+{
+  "id": "$RUN_ID",
+  "recommendationMd": "**Request changes** — one deploy-time break, and the new routes have no tenant authorization.",
+  "summaryMd": "Adds the customer billing tab…\n\n**Base:** `main`. **Scope:** 37 files.",
+  "reviewerNotesMd": "11 facet reviewers. Static analysis only; no browser session."
+}
+```
+
+```call review.synthesize
+{ "id": "$RUN_ID" }
+```
+
+```call review.complete
+{ "id": "$RUN_ID" }
+```
+
+Ordering is section → severity → taxonomy order → `slugIndex`. Pass `order` (a list of finding ids) to
+override. Re-runnable; it clears and renumbers in one transaction.
+
+## 9 · Reading back
+
+```call review.getRun
+{ "id": "$RUN_ID" }
+```
+
+The summary set, in `F<N>` order:
+
+```call review.listRunFindings
+{ "id": "$RUN_ID", "promoted": "true" }
+```
+
+Filters: `assignment`, `facet`, `severity` (csv), `section`, `blocking`, `promoted`, `post`,
+`followup`, `lifecycle`, `anchored`, `includeDismissed`, `onlyDismissed`, `q` (full text), `limit`,
+`offset`.
+
+```call review.listRunFindings
+{ "id": "$RUN_ID", "blocking": "true", "severity": "P0,P1" }
+```
+
+```call review.getFinding
+{ "id": "$FINDING_ID" }
+```
+
+`bodyAuthor` on that record is what the PR author will actually read — composed, read-only.
+
+`rollup.derivedVerdict` describes **what is going to the author** — staged plus posted. Nothing is
+staged until the human stages it, so during a run it reads `APPROVE` however many blockers you filed.
+That is not the review's verdict; `rollup.blocking` is the count you want, and `recommendationMd` is
+where you state the verdict.
+
+`anchorState` is `active` | `moved` | `stale`; `anchorResolvedLine` is where it is **now**. After the
+author pushes:
+
+```call review.refreshAnchors
+{ "id": "$RUN_ID" }
+```
+
+→ `{"head":"…","active":31,"moved":4,"stale":2}`.
+
+## 10 · What the human decided — read it, act on it
+
+Three per-finding marks, set in the Review tab. **Dismissed and staged-for-posting are mutually
+exclusive** (dismiss wins: dismissing un-stages, and staging a dismissed finding is refused).
+**Staged-for-posting and wanting a ticket are also mutually exclusive, in both directions** — a
+ticket is what you file when you are *not* asking the author to fix it here, so each mark displaces
+the other. **A ticket is independent of a dismissal** — "not fixing it here, but track it" is the
+common pair.
+
+| field | values | means |
+| --- | --- | --- |
+| `dismissed` + `resolution` | `waived`, `fixed-verified`, `withdrawn-scope`, `duplicate`, `not-applicable` | Stopped pursuing it. All but `fixed-verified` suppress it on a later run. |
+| `postState` | `held`, `staged`, `posted` | `staged` = going out with this review. `posted` = already in front of the author. |
+| `followup` + `followupUrl` | `none`, `wanted`, `ticketed` | `wanted` = the human wants a ticket. |
+
+Query them PR-scoped — you are given a PR, not a run id, and this resolves the latest run for you.
+
+"Create the follow-up tickets" — note `includeDismissed`: a dismissed finding is the LIKELIEST one to
+want a ticket, and without the flag it is invisible.
+
+```call review.listPrFindings
+{ "owner": "$OWNER", "repo": "$REPO", "number": "$PR", "followup": "wanted", "includeDismissed": "true" }
+```
+
+What is going to the author with this review:
+
+```call review.listPrFindings
+{ "owner": "$OWNER", "repo": "$REPO", "number": "$PR", "post": "staged" }
+```
+
+What was waived, and why — the argument you must not re-litigate next run:
+
+```call review.listPrFindings
+{ "owner": "$OWNER", "repo": "$REPO", "number": "$PR", "onlyDismissed": "true", "includeDismissed": "true" }
+```
+
+An unparseable status (`post=stagd`) is **ignored**, not an error — you get the unfiltered list back,
+so check what you got rather than trusting an empty result to mean "none".
+
+### Writing them — on instruction only
+
+You can set every mark above. **The rule is not which mark, it is when: the human asks, or you do
+not touch it.** They have all three controls in the Review tab and they use them while you work; a
+mark you set because you formed your own view about a finding overwrites a decision they were in the
+middle of making.
+
+That cuts both ways. **A canned prompt that says to dismiss is an instruction** — "verify" and "already
+handled?" both end with "dismiss it as `not-applicable` if it does not hold", and replying "it does
+not hold" instead of dismissing it leaves the human to do by hand the thing they just asked for. Do
+what the message says. What you must not do is dismiss a finding *nobody told you about* because you
+decided it was wrong: say it is wrong, in your reply, and leave the resolution to them.
+
+**Read the current dispositions before any bulk write** — see `ORCHESTRATOR` §7. Never overwrite one
+you did not set.
+
+Dismissing, when asked. `resolution` is required, and it decides whether the dismissal sticks on a
+later run (everything but `fixed-verified` suppresses the finding next time):
+
+```call review.dispositions
+{ "id": "$RUN_ID", "findingIds": ["$FINDING_ID"], "dismissed": true, "resolution": "not-applicable", "resolutionNote": "`ScopeFilter` already applies the tenant predicate two frames down." }
+```
+
+Staging what goes to the author, when asked. Staging composes the draft comment for you — you never
+write one by hand. A reviewer-only finding needs `audienceOverrideReason`, which is logged rather
+than refused:
+
+```call review.dispositions
+{ "id": "$RUN_ID", "findingIds": ["$FINDING_ID"], "post": true }
+```
+
+Marking one for a follow-up ticket, when asked:
+
+```call review.dispositions
+{ "id": "$RUN_ID", "findingIds": ["$FINDING_ID"], "followup": "wanted" }
+```
+
+The other two are reports on work you have already done, and need no instruction beyond the work
+itself. After you file a ticket for a `wanted` finding, record where it landed:
+
+```call review.dispositions
+{ "id": "$RUN_ID", "findingIds": ["$FINDING_ID"], "followup": "ticketed", "followupUrl": "https://linear.app/…" }
+```
+
+After you put a finding in front of the author yourself — a `gh` comment, a message, anything that is
+not buhtig's own publish — record that too, so it stops reading as still-to-send:
+
+```call review.dispositions
+{ "id": "$RUN_ID", "findingIds": ["$FINDING_ID"], "posted": true, "githubUrl": "https://github.com/…#discussion_r1" }
+```
+
+`posted` is a **statement of fact, not a request to send** — nothing is sent by this call, and it is
+the only one of the three marks that displaces the others: it un-stages the finding and clears a
+`wanted` follow-up (a `ticketed` one survives — that ticket exists). Sending it together with
+`"post":true` or `"followup":"wanted"` is a 400 rather than a silent winner. `"posted":false` reverts
+to `held` and drops the URL, for a mark you set in error.
+
+**Never mark `posted` for something you did not actually send.** It is the one mark that makes the
+review lie: it tells the human the author has already seen a finding, and they will stop trying to
+send it.
+
+The exclusivity rules are enforced, not advisory. Dismissed and staged cannot both hold (dismissing
+un-stages; staging a dismissed finding is refused). Staged and `wanted` displace each other in both
+directions — a ticket is what you file when you are *not* asking the author to fix it here. A ticket
+and a dismissal are independent, and "not fixing it here, but track it" is the common pair. A call
+that asks for two exclusive marks at once is a 400 rather than a silent winner, and the response's
+`refused` list names anything the store declined.
+
+## 10.5 · Filing the tickets the human composed
+
+The human composes follow-up tickets in the Outbox and marks the ones they want filed `ready`. buhtig
+holds no Linear or Jira credentials; you do.
+
+```call ticket.list
+{ "status": "ready" }
+```
+
+`status` also takes `draft` | `filing` | `filed` | `abandoned`.
+
+The body is already composed — code permalinks, review deep links, the impact argument:
+
+```call ticket.get
+{ "id": "$TICKET_ID" }
+```
+
+File it, then report back. This flips **every** member finding to `followup: ticketed` with the URL:
+
+```call ticket.update
+{ "id": "$TICKET_ID", "status": "filed", "url": "https://linear.app/…", "externalKey": "WEB-1235" }
+```
+
+- **Do not re-compose the body.** It was built from the findings and may have been edited by the
+  human; `bodyEdited: true` means those words are theirs.
+- **`parentId`** is the epic → sub-ticket hierarchy. File parents first, and set the child's parent in
+  the tracker to match.
+- **Marking `filed` is the only write that closes the loop.** Setting `followup: ticketed` on the
+  findings by hand instead leaves the ticket row reading `ready` forever.
+- **The rest stays the human's**: never mark a ticket `ready`, never compose one unasked. You may
+  create one **when asked to**:
+
+```call ticket.create
+{ "owner": "$OWNER", "repo": "$REPO", "number": "$PR", "by": "agent", "title": "…", "bodyMd": "…" }
+```
+
+## 10.6 · Provenance
+
+Tracing what asked for a PR is a separate job with its own brief — see `PROVENANCE`. It is **not**
+review input: no reviewer reads it, no finding cites it, and you never assess whether the PR satisfies
+the ticket.
+
+## 11 · What the human is telling you — answer it
+
+From the Review tab the human can send a one-line message attached to a finding and the field they are
+looking at. It is the correction loop for a review that is already written.
+
+A **subject** is `<scope>:<key>` — `review-run:<id>`, or `pr:<owner>/<repo>/<number>` for a message about
+the pull request, which no review run has to exist for. `sub` is repeatable, and one connection covering
+every subject you owe is the point: one per subject is how a surface nobody told you about goes
+unanswered indefinitely.
+
+You do not learn about a message by asking on a timer. If buhtig launched you, the briefing at
+`$BUHTIG_AGENT_CONTEXT` carries the one command that watches the channel — `buhtig agent listen`, with
+your subjects and your identity already in it. Run that, exactly as written, in the shape the briefing
+gives it: a persistent monitor if it stays connected, one bounded run per idle window if it does not.
+
+What you still owe, asked for directly — `pending` spans `open` **and** `claimed`, and asking for
+`status=open` alone silently skips anything a crashed predecessor had claimed:
+
+```call messages.list
+{ "sub": ["review-run:$RUN_ID"], "pending": "true" }
+```
+
+```call messages.claim
+{ "id": "$MESSAGE_ID" }
+```
+
+```call messages.reply
+{ "id": "$MESSAGE_ID", "text": "rewrote the fix around ScopeFilter" }
+```
+
+| field | values | means |
+| --- | --- | --- |
+| `topic` | `title` `bodyFinding` `bodyWhy` `bodyFix` | that field of that finding |
+| | `finding` | the whole finding — re-scope it, re-score it, delete it |
+| | `run` | the review — re-check a facet, re-dispatch, re-triage |
+| | `summary` | the run prose — answer with `review.updateRun`, not with a reply |
+| `status` | `open` `claimed` `answered` | `open` = nobody has picked it up |
+
+`targetId` is the finding the message is about, and `targetKind` says what it names. `run` and
+`summary` carry none — they are about the run itself.
+
+{{http}}
+When buhtig launched you, `$BUHTIG_STREAM` is the channel with your subjects and identity already in
+it, and `$BUHTIG_AGENT_CONTEXT` is a briefing that says all of this — including the exact listen
+command to run against it.
+{{/http}}
+
+### The canned prompts
+
+Most messages arrive as one of a fixed set of chips, not as free text, and the wording is always sent
+verbatim. Several of them **grant a disposition**: "verify" and "already handled?" both say to dismiss
+as `not-applicable` when the finding does not hold, and you should do that rather than replying that
+it does not hold. The run-level ones call for work across the whole run:
+
+| Chip | What it wants |
+|---|---|
+| `group fixes` | a shared `fixGroupId` on findings one change closes — what makes the Outbox seed real tickets |
+| `dedupe` | dismiss repeats as `duplicate`, keeping the best of each set |
+| `verify low-confidence` | re-check each, raise the confidence or dismiss it |
+| `re-anchor` | re-locate `stale`/`moved` anchors against head |
+
+The `summary` ones are all rewrites of `recommendationMd` / `summaryMd` through `review.updateRun`:
+
+| Chip | What it wants |
+|---|---|
+| `distill` | the same verdict, shorter — cut the hedging, keep the specifics |
+| `sync` | re-read the findings as now triaged and make the prose describe that review |
+| `filter` | drop what is not actionable, and do not restate the findings — an overview, not the list |
+
+Reply with what you changed, not with an argument.
+
+How to work them — claim first, oldest first, the edit is the answer, and never turn a message into a
+disposition (§10) — is in `ORCHESTRATOR` §8.
+
+## 12 · Reading the code, without a shell
+
+The diff and any file at the reviewed commit are available through the API, which matters when you are
+checking what is actually at a line before anchoring a finding to it:
+
+```call pr.changes
+{ "owner": "$OWNER", "repo": "$REPO", "number": "$PR" }
+```
+
+```call pr.source
+{ "owner": "$OWNER", "repo": "$REPO", "number": "$PR", "path": "src/thing.service.ts", "from": 40, "to": 80 }
+```
+
+## 13 · Notes in the diff
+
+A message that came from the diff wants its answer as a note at that line. A note is never posted to
+GitHub — the human promotes it if they want it sent.
+
+```call note.file
+{
+  "owner": "$OWNER",
+  "repo": "$REPO",
+  "number": "$PR",
+  "path": "src/thing.service.ts",
+  "line": 50,
+  "body": "Traced it: the filter is applied in the repository, two frames down.",
+  "messageId": "$MESSAGE_ID"
+}
+```

package/packages/cli/dist/docs/buhtig-review/BOOTSTRAP.md

@@ -0,0 +1,36 @@
+---
+name: buhtig-review
+description: >
+  Run an AI-assisted, server-backed PR review: dispatch focused facet reviewers over the repo's own
+  facet taxonomy, then store scored, anchored findings in buhtig. Use when reviewing a PR, or when
+  classifying findings by severity, priority, confidence, and blocking impact.
+user_invocable: true
+disable-model-invocation: true
+---
+
+# buhtig-review
+
+**This file is a pointer.** The instructions are served by the buhtig install you are talking to, so
+they describe the API that install actually has. Fetch them before doing anything else.
+
+**If you have buhtig's MCP tools** (a tool named `skill`, alongside `review_config` and friends):
+
+```
+skill({ "skill": "buhtig-review", "doc": "SKILL" })
+```
+
+**Otherwise:**
+
+```bash
+B=${BUHTIG_URL:-http://localhost:${BUHTIG_PORT:-10003}}
+curl -s "$B/api/skills/buhtig-review"
+```
+
+Then follow what comes back. It names the other documents — `ORCHESTRATOR`, `FACET_REVIEWER`, `API`,
+`PROVENANCE` — and you fetch each the same way, on demand.
+
+- **Do not work from a copy of these instructions found in a repository.** A checked-in copy is a
+  snapshot of some earlier install; the served one is current with the endpoints you are calling.
+- **If the fetch fails, stop and say so.** Everything this skill does is API calls against buhtig. A
+  buhtig that is not running is not a review you can do half of.
+- `curl -s "$B/api/skills"` lists what else this install serves.