@humanbased/crosscheck 1.1.1-beta.0 → 1.2.0-beta.33

package/docs/linear-identity-contract.md

@@ -0,0 +1,133 @@
+# Linear identity: the shared contract
+
+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,224 @@
+# 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 are two tiers you can adopt, in increasing order of strength.
+
+| Tier | Mode | Setup | How writes appear |
+|---|---|---|---|
+| **T0** | `api_key` | none beyond a key | Your account, with a `🤖 crosscheck · crosscheck` signature line |
+| **T1** | `client_credentials` | one OAuth app, ~5 min | The app itself (botActor), via `createAsUser` |
+
+T0 works everywhere and is the default. T1 is recommended — it is the only tier where
+Linear itself, not just a text convention, distinguishes the writer.
+
+---
+
+## 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 · crosscheck`. 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.
+
+> **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:
+    - APPROVE
+    - 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.
+
+---
+
+## 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:
+
+```
+  Linear
+  ✓ auth mode             client_credentials
+    organization          Inductive Network
+  ✓ writes as             crosscheck/<step> (app actor)
+```
+
+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/get-started.md

@@ -156,6 +156,27 @@ export LINEAR_API_KEY=lin_api_...
 If it's unset while enrichment is on, crosscheck just skips enrichment and
 reviews the diff as usual — it never errors.
 
+### Linear identity — for writing back to Linear (optional)
+
+Separate from enrichment above, which only *reads*. When `linear.enabled: true`,
+crosscheck mirrors each review verdict onto the PR's Linear issue.
+
+Two tiers. `api_key` (T0) reuses `LINEAR_API_KEY` and tags writes with a
+`🤖 crosscheck · crosscheck` signature line, but Linear still attributes them to
+your account. `client_credentials` (T1) uses an OAuth app in your workspace so
+writes render as the app itself:
+
+```bash
+export LINEAR_CLIENT_ID=...
+export LINEAR_CLIENT_SECRET=...
+```
+
+A failed T1 token mint aborts the run rather than falling back to `api_key` —
+a silent downgrade would put agent writes back under a human's name.
+
+Full walkthrough, including the two Linear UI gotchas that trip people up:
+[docs/linear-identity.md](docs/linear-identity.md).
+
 ---
 
 ## Step 1 — Check your setup
@@ -1144,6 +1165,24 @@ post_review:
 server:
   port: 7891
   webhook_path: /webhook
+
+linear:                       # write review verdicts back to a Linear issue (opt-in)
+  enabled: false
+  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"      # comma-separated; initiative:* are separate scopes
+  identity:
+    actor: crosscheck
+    signature: "🤖 {actor} · {product}"
+    per_step_actor: true      # crosscheck/review vs crosscheck/fix in Linear
+  comment_on:                 # verdicts mirrored to the issue
+    - APPROVE
+    - NEEDS_WORK
+    - BLOCK
+  team_keys: []               # e.g. [IN] — required to match bare refs like IN-42
 ```
 
 ### Quality tiers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanbased/crosscheck",
-  "version": "1.1.1-beta.0",
+  "version": "1.2.0-beta.33",
   "description": "AI code review pipeline that turns agent-written PRs into merge-ready patches",
   "bin": {
     "crosscheck": "dist/cli.js",