@humanbased/crosscheck 1.2.0 → 1.3.0-beta.100

package/docs/linear-identity-contract.md

@@ -0,0 +1,139 @@
+# Linear identity: the shared contract
+
+**Contract version: 1.1.** Additive changes bump the minor; removing or renaming a
+field is a major bump and a breaking change for every adopter. 1.1 added
+`identity.per_step_actor`, `identity.icon_url`, and the `{model}` / `{reviewer}` /
+`{icon}` signature placeholders — all optional, all defaulted, so a 1.0
+implementation stays conformant.
+
+crosscheck and symphony are separate open-source products that both write to Linear.
+This document is the contract they implement identically, so an operator configures
+identity once and it means the same thing in both — and so a third product can adopt
+it without inventing a fourth shape.
+
+Humanbased's HB Agent Gateway is not special here. It is one `client_credentials`
+configuration of this contract.
+
+For step-by-step setup, see [linear-identity.md](linear-identity.md). This document is
+the specification.
+
+---
+
+## Config shape
+
+```yaml
+linear:
+  enabled: false                        # opt-in; default off
+  auth:
+    mode: api_key                       # api_key | client_credentials
+    api_key_env: LINEAR_API_KEY
+    client_id_env: LINEAR_CLIENT_ID
+    client_secret_env: LINEAR_CLIENT_SECRET
+    scopes: "read write"
+  identity:
+    actor: crosscheck                   # product name; symphony uses `symphony`
+    signature: "🤖 {actor} · {product}"
+    per_step_actor: true                # suffix the actor with the unit of work
+```
+
+Every key under `auth` ending in `_env` names an **environment variable**, never a
+secret. A product implementing this contract must not accept an inline credential in
+config. Non-credential fields (`mode`, `scopes`, everything under `identity`) are
+ordinary config values and are written literally.
+
+---
+
+## Tiers
+
+| Tier | Mode | Setup | Attribution |
+|---|---|---|---|
+| **T0** | `api_key` | none | Operator's account; signature line only |
+| **T1** | `client_credentials` | one OAuth app | The app itself (botActor), via `createAsUser` |
+| **T2** | public app | none (future) | Centrally operated app — see IN-2272 |
+
+T0 is the default so an existing `api_key` config keeps working unchanged. T2 is not
+implemented; it is gated on T1 adoption feedback.
+
+---
+
+## Required behaviours
+
+A conforming implementation must:
+
+1. **Lead every write with the rendered signature.** `{actor}` and `{product}` are the
+   defined placeholders. This is T0's entire attribution mechanism and is retained in
+   T1 as fallback text.
+
+2. **Mint T1 tokens per run, not per write.** Linear app tokens carry roughly a 30-day
+   TTL; treat them as ephemeral anyway. Resolve identity at run start so a
+   misconfiguration fails before any expensive work.
+
+3. **Abort when a configured T1 mint fails.** Never fall back to `api_key`. A silent
+   downgrade re-attributes agent writes to a human, which is the failure the whole
+   contract exists to prevent. Surface the env var name that needs fixing.
+
+4. **Keep secrets off argv.** The mint sends credentials in a POST body; the token
+   travels in an `Authorization` header. Nothing reaches a process list. Failure
+   messages carry HTTP status codes, never credential material.
+
+5. **Preserve backward compatibility.** An existing `api_key` configuration must keep
+   working with T0 semantics and no new required keys.
+
+---
+
+## Per-worker actors
+
+`per_step_actor: true` suffixes the actor with the unit of work, so a fleet does not
+collapse into one indistinguishable bot:
+
+| Product | Unit of work | Example actor |
+|---|---|---|
+| crosscheck | workflow step | `crosscheck/review`, `crosscheck/fix`, `crosscheck/recheck` |
+| symphony | worker | `symphony/worker-3` |
+
+In T1 the suffixed name is what `createAsUser` sends, so it is what Linear renders. In
+T0 it reaches only the signature line — still worth doing, since that is all T0 has.
+
+The suffix composes: deriving twice yields `crosscheck/review/shard-2`. Deriving must
+not mutate the base identity, so one run can produce several scoped identities from a
+single minted token.
+
+---
+
+## The token mint
+
+```
+POST https://api.linear.app/oauth/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=client_credentials&client_id=<id>&client_secret=<secret>&scope=read+write
+```
+
+Response: `{ "access_token": "..." }`, used as `Authorization: Bearer <token>`.
+
+T0 keys are sent **bare** — `Authorization: <key>` with no `Bearer` prefix. Getting
+this backwards is the most common integration bug.
+
+---
+
+## Two Linear gotchas worth encoding
+
+Both cost real debugging time and neither is discoverable from the API:
+
+- The OAuth application form **requires a Redirect URI** even though
+  `client_credentials` never uses one. Any placeholder on a domain you control works.
+- `read write` does **not** cover initiatives. `initiative:read` and `initiative:write`
+  are separate scopes.
+
+---
+
+## Reference implementation
+
+crosscheck's lives in `src/linear/`:
+
+| Concern | File |
+|---|---|
+| Auth resolution, token mint, `withWorker` | `identity.ts` |
+| All Linear API traffic | `client.ts` |
+| Which issue a write targets | `ref.ts` |
+| Credential reads (the only place) | `../config/loader.ts` |

package/docs/linear-identity.md

@@ -0,0 +1,293 @@
+# Linear identity setup for your workspace
+
+crosscheck can mirror a review verdict onto the Linear issue a PR belongs to. This
+guide gets those writes attributed to *crosscheck* rather than to whoever's API key
+the daemon happens to hold.
+
+It assumes no prior Linear API experience. Budget about five minutes.
+
+---
+
+## Why this exists
+
+By default an agent writing to Linear uses whatever API key the operator supplied —
+usually a person's personal key. Every comment then looks like that person wrote it,
+and there is no way to tell agent activity from human activity.
+
+There is a ladder here. Each rung buys stronger attribution for a bit more setup —
+**start at the bottom.** Most people never need to climb it.
+
+| Rung | Mode | Setup | How writes appear |
+|---|---|---|---|
+| **T0** | `api_key` | one env var | Your account, led by a `🤖 crosscheck · <model>` signature line |
+| **T1** | `client_credentials` | one OAuth app, ~5 min, once per workspace | crosscheck itself, with its own icon |
+
+**T0 is not a broken version of T1.** Linear write-back is fully functional with just
+an API key: crosscheck finds the issue and posts the comment. What T0 lacks is
+*attribution*, not capability.
+
+So the question isn't "which is better", it's **how many things write to your
+workspace**. If you're the only one, T0 is the right answer and the app is ceremony.
+If several agents and several humans all write, T0 makes them indistinguishable —
+that's the problem T1 solves.
+
+`crosscheck onboard` asks which rung you want and writes the config for you:
+
+<img src="../assets/linear-onboard.svg" alt="crosscheck onboard, step 9.5 — choosing a Linear attribution rung" width="700" />
+
+---
+
+## T0 — api_key (zero setup)
+
+Create a personal API key under **Linear → Settings → API → Personal API keys**, then:
+
+```bash
+export LINEAR_API_KEY=lin_api_...
+```
+
+```yaml
+linear:
+  enabled: true
+  auth:
+    mode: api_key
+  team_keys:
+    - IN          # your team's key prefix
+```
+
+Every write leads with `🤖 crosscheck · <model>`. Linear still records your account
+as the author — the signature is a convention, not an identity.
+
+---
+
+## T1 — client_credentials (recommended)
+
+### 1. Create an OAuth application
+
+Go to **Linear → Settings → API → OAuth applications → Create new**.
+
+Fill in a name (`crosscheck`, or whatever you want to see on comments) and an icon —
+upload [`assets/icon-256.png`](../assets/icon-256.png) from this repo. That avatar is
+what Linear renders beside every comment crosscheck posts, and it is the *only* way to
+get the logo onto a comment: the icon comes from Linear's app settings, not from
+anything crosscheck sends. On T0 your own avatar appears, because Linear genuinely
+believes you wrote it.
+
+> **Gotcha:** the form **requires a Redirect URI** even though client credentials never
+> uses one. Any placeholder URL on a domain you control is fine —
+> `https://example.com/callback`. It is never called.
+
+### 2. Enable the client credentials toggle
+
+On the application page, enable **Client credentials**. Without this the token mint in
+step 5 returns `invalid_client`.
+
+Also authorize the app for your workspace with **app-actor** ("application acts as
+itself") so writes render as the app.
+
+### 3. Choose scopes
+
+`read,write` covers issues and comments — that is all crosscheck needs.
+
+> **Gotcha:** `read,write` does **not** cover initiatives. `initiative:read` and
+> `initiative:write` are separate scopes. Add them only if something else in your
+> workspace needs them. Skip the admin scope.
+
+### 4. Store the credentials
+
+Copy the client ID and secret into your environment — never into the config file:
+
+```bash
+export LINEAR_CLIENT_ID=...
+export LINEAR_CLIENT_SECRET=...
+```
+
+### 5. Verify the mint by hand
+
+Confirm the credentials work before wiring crosscheck up. The form body goes through
+**stdin**, so the secret never lands in your shell history or in `ps` output:
+
+```bash
+printf 'grant_type=client_credentials&client_id=%s&client_secret=%s&scope=read,write' "$LINEAR_CLIENT_ID" "$LINEAR_CLIENT_SECRET" | curl -s -X POST https://api.linear.app/oauth/token -H 'Content-Type: application/x-www-form-urlencoded' --data @- 
+```
+
+A successful response contains `access_token`. If you get `invalid_client`, revisit
+step 2 — the toggle is the usual cause.
+
+### 6. Configure crosscheck
+
+```yaml
+linear:
+  enabled: true
+  auth:
+    mode: client_credentials
+    client_id_env: LINEAR_CLIENT_ID
+    client_secret_env: LINEAR_CLIENT_SECRET
+    scopes: "read,write"
+  identity:
+    actor: crosscheck
+  comment_on:            # default; add APPROVE to comment on clean reviews too
+    - NEEDS_WORK
+    - BLOCK
+  team_keys:
+    - IN
+```
+
+Run a review against a PR whose branch or body references a Linear issue. The comment
+should appear authored by the app, not by you.
+
+---
+
+## What the comment looks like
+
+On the app rung, with the icon uploaded — the avatar and **APP** badge come from
+Linear, which knows the writer is an application rather than a person:
+
+<img src="../assets/linear-comment.svg" alt="A crosscheck review comment on a Linear issue, authored by the app actor" width="740" />
+
+The raw markdown behind that:
+
+```
+🤖 crosscheck/review · gpt-5.6-terra
+
+**NEEDS_WORK** — codex (gpt-5.6-terra) review of [feat: add rate limiting to the public API](https://github.com/acme/app/pull/312)
+```
+
+The signature is a template — `linear.identity.signature`, with placeholders
+`{actor}`, `{product}`, `{model}`, `{reviewer}`, and `{icon}`. Placeholders with no
+value resolve to empty and the leftover separators are tidied, so one template works
+whether or not the model is known.
+
+The model appears in two places: the signature (if your template asks for it) and the
+verdict line. When the vendor CLI picks the model without reporting which, the model
+is omitted rather than guessed.
+
+`{icon}` renders `linear.identity.icon_url` as an inline image. Before reaching for
+it, note the caveat above: the app avatar is the supported way to brand a comment, and
+inline images may render block-level rather than inline. Test it on a scratch issue
+before adopting it.
+
+---
+
+## Testing without waiting for a PR
+
+`crosscheck linear-test` exercises the whole path and posts nothing:
+
+```bash
+crosscheck linear-test ENG-42
+```
+
+<img src="../assets/linear-test.svg" alt="crosscheck linear-test verifying the Linear setup end to end without posting" width="700" />
+
+It resolves your identity, looks the issue up for real, checks whether the verdict
+would pass `comment_on`, and prints the exact comment body a review would post. Each
+step reports separately, so a failure names itself rather than leaving you guessing.
+
+Pass `--branch` or `--title` to test ref resolution the way a real PR would hit it,
+and `--verdict` to preview a different outcome.
+
+---
+
+## Verifying which identity you're on
+
+`crosscheck status` shows a **Linear** section whenever `linear.enabled` is true. It
+resolves the configured identity for real — minting a T1 token if that's the mode —
+and reports what a write would render as:
+
+<img src="../assets/linear-status.svg" alt="crosscheck status showing the Linear identity section" width="620" />
+
+On the app rung the same rows read:
+
+```
+  Linear
+  ✓ auth mode             client_credentials
+    organization          Inductive Network
+  ✓ writes as             crosscheck/<step> (crosscheck itself)
+```
+
+On T0 it names the human account instead, because that's the state worth seeing:
+
+```
+  Linear
+  ✓ auth mode             api_key
+    organization          Inductive Network
+  ✗ writes as             yi@example.com (human — switch to client_credentials)
+```
+
+Run this before and after a cutover. The `✗` is the condition to eliminate.
+
+---
+
+## Deploying with an existing OAuth app
+
+If your organization already operates a gateway app, point the daemon at its
+credentials rather than creating a second app. Only the env var *names* go in config:
+
+```yaml
+linear:
+  enabled: true
+  auth:
+    mode: client_credentials
+    client_id_env: LINEAR_HB_AGENT_GATEWAY_CLIENT_ID
+    client_secret_env: LINEAR_HB_AGENT_GATEWAY_CLIENT_SECRET
+  identity:
+    actor: crosscheck
+    per_step_actor: true
+```
+
+Cutover sequence:
+
+1. Make the gateway credentials available to the **daemon's** environment — not just
+   your interactive shell. A systemd unit or launchd plist needs them explicitly.
+2. Run `crosscheck status` and confirm `writes as ... (app actor)`.
+3. Run one review end to end and confirm the Linear comment is authored by the app.
+4. Only then retire the old personal API key from the daemon's environment.
+
+Step 4 last, deliberately: until steps 2 and 3 pass, the old key is your rollback.
+
+---
+
+## How crosscheck finds the issue
+
+Checked in order — branch name, then PR title, then PR body. Within each, an explicit
+URL wins over a bare identifier.
+
+1. **A `linear.app` issue URL** — `https://linear.app/acme/issue/IN-2269/slug`. Works
+   with no configuration, because it is unambiguous.
+2. **A bare identifier** — `IN-2269`, matched case-insensitively so a branch like
+   `feat/in-2269-thing` resolves. **Only for keys listed in `team_keys`.**
+
+That second restriction is deliberate. `UTF-8`, `SHA-256`, `ISO-8601`, `GPT-5` and
+`RFC-2119` all have the same shape as a Linear identifier. Reading the wrong issue is
+harmless; *commenting* on the wrong issue is not. So bare matching stays off until you
+name your team keys.
+
+If no issue is found, crosscheck skips the Linear write and the review proceeds
+normally.
+
+---
+
+## Security properties
+
+- **Secrets never reach argv.** The mint sends them in a POST body; the GraphQL token
+  rides in a header. Nothing shows up in `ps`.
+- **Secrets never reach logs or error traces.** Failure messages carry HTTP status
+  codes, not credentials.
+- **Tokens are minted per run** and held in memory only. Linear app tokens have a ~30
+  day TTL, but crosscheck treats them as ephemeral.
+- **A failed T1 mint aborts the run.** crosscheck will not fall back to `api_key` when
+  you configured `client_credentials` — a silent downgrade would put agent writes back
+  under a human's name, which is the exact failure this feature exists to prevent. You
+  get a non-zero exit and a message naming the env var to fix.
+- **Config holds env var *names*, never values.**
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause |
+|---|---|
+| `LINEAR_CLIENT_ID and LINEAR_CLIENT_SECRET is not set` | Env vars missing from the daemon's environment (not just your shell) |
+| `token mint rejected (HTTP 401)` | Client credentials toggle off, or wrong secret |
+| `Linear API error: Access denied` | Scope too narrow — needs `write` |
+| Comment never appears, no error | No issue ref found. Set `team_keys`, or put a `linear.app` URL in the PR body |
+| Comment appears as you, not the app | Still on `mode: api_key` |

package/docs/metrics.md

@@ -0,0 +1,115 @@
+# Metrics: what Crosscheck records, and where it stays
+
+Crosscheck records what it did so you can tell whether it is working. Every number comes from local log files, and **nothing is transmitted**: there is no endpoint, no account, no upload, and no network call in any of the code that produces or reads these metrics. Telemetry is opt-in in the strongest available sense — it does not exist yet.
+
+This document is the field-by-field inventory. If you find a field written to disk that is not listed here, that is a bug worth reporting.
+
+---
+
+## Where it lives
+
+| | |
+|---|---|
+| Location | `~/.crosscheck/logs/<YYYY-MM-DD>.ndjson` — one JSON object per line |
+| On by default | Yes (`logs.enabled: true`) |
+| Retention | `logs.retention_days`, default 30 — older files are deleted at startup |
+| Turn it off | `logs.enabled: false` in `crosscheck.config.yml` |
+
+Turning logging off is supported and costs you the reader commands: `crosscheck adoption`, `impact`, `diagnose`, and `optimize` all read these files and have nothing else to read.
+
+---
+
+## Reading it
+
+```bash
+crosscheck adoption                      # activation, usage, weekly active repos, latency, first-run failures
+crosscheck adoption --json               # the same report as JSON
+crosscheck adoption --since 2026-07-01   # narrow the window
+```
+
+`crosscheck adoption` answers "is this being used, and does a PR get a verdict fast enough to matter". Its sibling `crosscheck impact` prices reviews that already happened. Both read the same files and neither makes a network call.
+
+What the report shows:
+
+| Metric | Derived from |
+|---|---|
+| onboard started / completed / abandoned | `onboard_started`, `onboard_completed` |
+| reviews started / completed | `review_started`, `review_complete` |
+| rechecks completed | `review_complete` with `step_type: recheck` |
+| blocking findings posted | `blocking_finding_posted` |
+| fixes applied | `fix_complete` with `applied_count > 0` |
+| active repos, weekly active repos | distinct `repo` on `review_complete`, bucketed by ISO week |
+| PR open → verdict (median, p90, slowest) | `open_to_verdict_ms` on `review_complete` |
+| first-run failures | first `error` in a session that never logged a `review_complete` |
+
+Two honest limits worth knowing before you quote a number:
+
+- **Latency is only measured when the PR event carried an open time.** Hand-built events and some third-party webhook redeliveries do not. Those verdicts are excluded and counted separately as `unmeasured` rather than being given an invented start time.
+- **Everything is bounded by the retention window.** A 30-day default means a "total" is a 30-day total. Raise `logs.retention_days` if you need a longer baseline.
+
+---
+
+## What is recorded
+
+Identifying fields, on every event that has them:
+
+| Field | Example | Why |
+|---|---|---|
+| `ts` | `2026-07-08T10:00:00.000Z` | ordering, weekly bucketing |
+| `event` | `review_complete` | what happened |
+| `repo` | `acme/web` | which repo — this is a name, and it is the most identifying field written |
+| `pr` | `245` | which PR number |
+
+Everything else is a count, an enum, a duration, or a commit sha:
+
+| Field | Shape |
+|---|---|
+| `verdict` | `APPROVE` / `NEEDS WORK` / `BLOCK` |
+| `reviewer`, `model`, `effort` | vendor and model identifiers |
+| `step_type`, `step_name`, `round`, `trigger` | which step ran, and why |
+| `duration_ms` | how long the reviewer ran |
+| `open_to_verdict_ms` | PR open → verdict, in ms |
+| `tokens_used`, `input_tokens`, `output_tokens` | integer counts |
+| `applied_count`, `commentCount` | integer counts |
+| `sha`, `head_sha` | commit shas |
+| `category` | error class: `auth`, `permission`, `rate_limit`, `overloaded`, `budget`, `timeout`, `network`, `git`, `subprocess`, `unknown` |
+| `message`, `stack`, `stderr` | on error events only — the failure text, truncated |
+| `outcome`, `stage` | on `onboard_completed`: `completed` / `abandoned`, and where it stopped |
+| `deployment`, `repos`, `orgs`, `quality_tier`, `quality_mode`, `pipeline`, `tunnel`, `linear` | on `onboard_completed`: the **shape** of the setup — counts and enums, never repo or org names |
+
+## What is not recorded
+
+Standard logs never contain:
+
+- **source code or diffs**
+- **reviewer prompts**
+- **review text** — the verdict is recorded; the prose is not
+- **PR titles or bodies**
+- **PR author logins**
+- **tokens, keys, or secrets** — the one place a token could appear is the clone URL, which is redacted to `x-access-token:[REDACTED]` on every path that could log it
+
+Error events are the one place free text lands, because a failure you cannot read is a failure you cannot fix. `message`, `stack`, and `stderr` come from the failing subprocess or API call and are truncated. They can quote a file path or a git ref. They are local files, like everything else here.
+
+### The extended tier
+
+Richer fields — PR title, body, file paths, review text, author — exist behind `logs.extended.enabled`, which is:
+
+- **off by default**,
+- **not settable from any CLI flag** and not offered by `crosscheck onboard`, so it can only be turned on by hand-editing config, and
+- **tagged** — every line it writes carries `"_extended": true`, so it can be filtered or scrubbed independently of standard logs.
+
+If you have not deliberately edited your config, this tier is off and nothing in the product will nudge you toward it.
+
+---
+
+## Transmission
+
+There is none. To be specific about what that means:
+
+- No Crosscheck-operated server exists, so there is nowhere for a payload to go.
+- No code in `src/lib/adoption.ts` or `src/commands/adoption.ts` opens a socket.
+- Reporting is a local CLI command that prints to your terminal.
+
+If opt-in transmission is ever built, it will be per-category, individually documented, off unless you turn it on, and it will print the payload that leaves your machine. Until then, "opt-in telemetry" describes a design in `prd.md`, not shipped behaviour — and the metrics above are yours alone.
+
+Related: [docs/trust.md](./trust.md) covers what leaves your machine during normal operation, which is a different question from what gets logged.