[GRV-32]: Add Linear auth doctor and GraphQL workspace adapter (#49)

## Summary

Wires the GRV-31 scaffold's `LinearWorkspace` port to a real Linear
GraphQL HTTP adapter and turns `human-handoff-linear doctor` into a
read-only auth check that fetches the current viewer/workspace. The
adapter exposes the full surface later mutating commands (label install,
template sync, project bootstrap) need, so no future issue has to
re-implement GraphQL transport or auth handling.

- `createLinearGraphqlWorkspace({ apiKey, fetch })` implements
`getViewer`, `listTeams`, `listLabels`, `createLabel`, `getTemplate`,
`createTemplate`, `updateTemplate`, `createIssue`, `createRelation`.
Maps HTTP 401/403/429 and GraphQL `extensions.code`
(`AUTHENTICATION_ERROR`, `FORBIDDEN`, `RATELIMITED`) to typed
`LinearAuthError` / `LinearPermissionError` / `LinearRateLimitError` /
`LinearNetworkError` / `LinearApiError`.
- `createInteractiveSecretReader` extends the env reader with an opt-in
hidden TTY prompt for the API key. `--no-prompt` disables the fallback
for CI.
- `doctor` use case resolves the token through the SecretReader port
and, when present, calls only `getViewer` through the LinearWorkspace
port. It never invokes mutating methods (proven by
`tests/use-cases.test.mjs` "doctor: never invokes mutating workspace
methods").
- CLI exit codes: 2 missing_token, 3 auth, 4 permission, 5 rate_limit, 6
network, 7 api, 1 unknown.

## Acceptance Criteria Review

- [x] CLI reads `LINEAR_API_KEY` from env, supports hidden interactive
prompt fallback (documented in README + `--help`), `--no-prompt`
disables prompt for CI.
- [x] `doctor` validates the token by calling `getViewer` through the
LinearWorkspace port; reports success without creating or updating
templates, labels, issues, or relations.
- [x] `LinearWorkspace` adapter implements all nine port methods
(viewer, teams, labels list/create, template get/create/update, issue
create, relation create).
- [x] GraphQL errors, missing permissions, missing token, and rate-limit
failures produce actionable CLI output and distinct non-zero exit codes.
- [x] Unit tests cover the adapter through an injected `fetch` double
and the use case through a stub workspace — no test requires a real
Linear API token.

## Out of Scope (per issue)

- Creating/updating the Human Handoff template. (Adapter exposes
`createTemplate`/`updateTemplate` but the scaffold's `sync-template`
command remains a no-op; `syncHumanHandoffTemplate` raises an actionable
not-yet-implemented error.)
- Creating labels. (Adapter exposes `createLabel`; no command invokes it
yet.)
- Creating project HH issues. (Adapter exposes
`createIssue`/`createRelation`; `bootstrap-project` command remains a
no-op; `bootstrapHumanHandoffProject` raises an actionable
not-yet-implemented error.)

## Clean Architecture Shape

- **Use case:** `ValidateLinearSetupAuth` (new) — implemented as
`src/use-cases/doctor.mjs`. Cataloged in
`docs/architecture/use-case-catalog.md`.
- **Ports:** `LinearWorkspace`, `SecretReader`, `ConsoleReporter`
(extended `ports.mjs` with full `LinearWorkspace` surface).
- **Adapters:** `createLinearGraphqlWorkspace` (GraphQL HTTP),
`createInteractiveSecretReader` (env + hidden TTY prompt),
`createStreamConsoleReporter` (existing).
- **Boundary rule:** `tests/boundary.test.mjs` continues to enforce — no
`process.env`, `node:child_process`, direct `fetch(`, or `node:process`
imports in `src/use-cases/`.

## Verification

- `npm test` — all 343 tests pass across `human-handoff-linear` (64),
`linear-agent-hooks` (35), `llm-cost-attribution` (203),
`llm-cost-estimation` (37), and root (2). `llm-cost-attribution`'s
`test:boundary` runs and passes.
- Smoke tests via the binary:
- `LINEAR_API_KEY=fake_test node
packages/human-handoff-linear/bin/human-handoff-linear.mjs doctor
--no-prompt` → exits 3 (auth) with `[auth] Linear API rejected the API
key (HTTP 401)`.
- `env -u LINEAR_API_KEY node
packages/human-handoff-linear/bin/human-handoff-linear.mjs doctor
--no-prompt` → exits 2 (missing_token) with `LINEAR_API_KEY is not set`.
- `human-handoff-linear --help` documents the `--no-prompt` flag and the
new auth section.

Skipped checks: none.

## Test Plan

- [x] `node --test packages/human-handoff-linear/tests/*.test.mjs` (64
tests)
- [x] `npm test` from repo root (all workspaces)
- [x] CLI smoke tests for help / missing-token / bad-token / unknown
command

Co-authored-by: riddim-developer-bot <developer-bot@riddimsoftware.com>

Author: riddim-developer-bot[bot]

README.md

@@ -22,6 +22,16 @@ Claude Code and Codex hooks that automatically post a provenance comment back to
 npx linear-agent-hooks setup
 ```
 
+### [`human-handoff-linear`](packages/human-handoff-linear)
+
+Linear-backed workflow primitives for the human-handoff pattern — one project-level Human Handoff issue that aggregates every step a human still has to do in an otherwise autonomous flow.
+
+Validate your Linear API key without touching any of your data:
+
+```bash
+LINEAR_API_KEY=lin_api_… npx human-handoff-linear doctor
+```
+
 ### [`llm-cost-attribution`](packages/llm-cost-attribution)
 
 Per-issue token, turn, and quota analytics for Claude Code and Codex CLI sessions. Reads the CLIs' own session JSONLs — no custom telemetry pipeline required.

docs/architecture/use-case-catalog.md

@@ -149,6 +149,17 @@ Inputs: setup command selection, optional Linear team selector, Human Handoff te
 Outputs: command contract metadata, no-op setup/sync/doctor/bootstrap results, mutation count, token-readiness signal, validated template body.
 Entities / values: SetupCommand, LinearTeamSelector, HumanHandoffTemplateBody.
 Ports: LinearWorkspace, ConsoleReporter, SecretReader.
-Primary adapters: CLI command parser, environment-backed SecretReader, stream ConsoleReporter, no-op LinearWorkspace adapter.
-Notes: foundation scaffold only. Core use-case modules import no process environment, child_process, direct fetch, or Linear API details; real GraphQL mutations belong in a future LinearWorkspace adapter.
+Primary adapters: CLI command parser, environment-backed SecretReader, stream ConsoleReporter, no-op LinearWorkspace adapter, real GraphQL LinearWorkspace adapter (`createLinearGraphqlWorkspace`).
+Notes: foundation scaffold for setup/sync-template/bootstrap-project; `doctor` is no longer no-op (see ValidateLinearSetupAuth). Core use-case modules import no process environment, child_process, direct fetch, or Linear API details — enforced by `tests/boundary.test.mjs`.
 Current implementation: `packages/human-handoff-linear/src/use-cases/define-human-handoff-linear-package-contract.mjs`, `packages/human-handoff-linear/src/use-cases/*.mjs`
+
+### ValidateLinearSetupAuth
+Actor: Workflow operator
+Goal: Validate the Linear API token by fetching the current viewer and workspace through the LinearWorkspace port, so `doctor` can confirm the token works before any mutating command attempts to use it. Read-only: never creates or updates templates, labels, issues, or relations.
+Inputs: SecretReader (resolves `LINEAR_API_KEY`), LinearWorkspace (`getViewer`), `tokenRequired` flag (default true).
+Outputs: DoctorResult `{ command, tokenPresent, ok, viewer, checks }` where each check carries `{ name, ok, required, error?, details? }`. The CLI maps a failing check's `error.kind` to a stable exit code (missing_token=2, auth=3, permission=4, rate_limit=5, network=6, api=7).
+Entities / values: LinearViewer, LinearOrganization, DoctorCheck.
+Ports: SecretReader, LinearWorkspace (only `getViewer` is called).
+Primary adapters: `createInteractiveSecretReader` (env + hidden TTY prompt), `createLinearGraphqlWorkspace` (HTTPS GraphQL with injected `fetch` for tests), `createStreamConsoleReporter`.
+Notes: core use case imports no fetch/env/child_process (enforced by `tests/boundary.test.mjs`). Tests cover GraphQL HTTP errors (401/403/429), GraphQL `errors[]` shapes, network failure, and the missing-token path through injected fetch and stub workspaces — no real Linear API token is required.
+Current implementation: `packages/human-handoff-linear/src/use-cases/doctor.mjs`

packages/human-handoff-linear/README.md

@@ -1,17 +1,32 @@
 # human-handoff-linear
 
-Linear workflow primitives for installing and maintaining the Human Handoff issue
-template used by autonomous project workflows.
+Linear workflow primitives for installing and maintaining the Human Handoff
+issue template used by autonomous project workflows.
 
-This package is intentionally a contract shell. It exposes the CLI and importable
-use-case boundaries that future work will wire to real Linear GraphQL mutations.
-Current commands are dry-run/no-op unless stated otherwise.
+This package is still a contract shell — most commands (`setup`,
+`sync-template`, `bootstrap-project`) are dry-run/no-op scaffolds awaiting
+later issues. The `doctor` command, however, performs a real Linear auth check
+through the GraphQL adapter, and the underlying `LinearWorkspace` adapter
+implements the full surface those later commands will use.
 
 ## Requirements
 
 - Node.js 20+
-- A Linear API token for future mutation-backed commands. The current scaffold
-  does not require a token for help, routing, or no-op checks.
+- A Linear personal API key. Create one at
+  <https://linear.app/settings/api>.
+
+## Auth
+
+The CLI reads the API key from the `LINEAR_API_KEY` environment variable.
+
+```bash
+export LINEAR_API_KEY=lin_api_…
+```
+
+If the variable is unset and you run from an interactive terminal, the CLI
+prompts for the key without echoing it. Pass `--no-prompt` to disable that
+fallback (use in CI, where there is no TTY anyway). The key is never logged,
+written to disk, or echoed back.
 
 ## CLI
 
@@ -21,16 +36,33 @@ npx human-handoff-linear --help
 
 Subcommands:
 
-- `setup` - validate the package contract and report the future Linear template
-  setup plan. No Linear mutations are performed in this scaffold.
-- `sync-template` - report the checked-in Human Handoff issue body template that
-  future work will sync into Linear.
-- `doctor` - check local CLI readiness without contacting Linear.
-- `bootstrap-project` - reserve the project bootstrap command surface for later
-  implementation.
+- `doctor` — validate the Linear API token by fetching the current viewer and
+  workspace. Read-only: never creates or updates templates, labels, issues, or
+  relations.
+- `setup`, `sync-template`, `bootstrap-project` — scaffold-only today; reserved
+  command surfaces that later issues will wire to real Linear mutations.
 
-All commands are safe for non-interactive use. Unknown commands fail with a
-terse message and do not require a Linear token.
+### `doctor`
+
+```text
+$ human-handoff-linear doctor
+human-handoff-linear doctor - validating Linear auth (read-only).
+Linear token: present.
+Authenticated as Ada Lovelace in workspace Riddim (riddim).
+human-handoff-linear doctor complete - no mutations performed
+```
+
+Failure cases map to stable exit codes for scripting:
+
+| Condition | Stderr prefix | Exit |
+|---|---|---|
+| `LINEAR_API_KEY` unset and `--no-prompt` (or non-TTY) | `LINEAR_API_KEY is not set` | 2 |
+| HTTP 401 / GraphQL `AUTHENTICATION_ERROR` | `[auth]` | 3 |
+| HTTP 403 / GraphQL `FORBIDDEN` | `[permission]` | 4 |
+| HTTP 429 / GraphQL `RATELIMITED` | `[rate_limit]` | 5 |
+| Network/transport failure | `[network]` | 6 |
+| Other GraphQL or HTTP error | `[api]` | 7 |
+| Other / unknown | (no prefix) | 1 |
 
 ## Application API
 
@@ -41,20 +73,36 @@ modules with injected ports:
 import {
   createBootstrapProjectUseCase,
   createDoctorUseCase,
+  createLinearGraphqlWorkspace,
   createSetupUseCase,
   createSyncTemplateUseCase,
 } from 'human-handoff-linear';
+
+const workspace = createLinearGraphqlWorkspace({ apiKey: process.env.LINEAR_API_KEY });
+const doctor = createDoctorUseCase({
+  reporter: { info: console.log, error: console.error },
+  secretReader: { read: (name) => process.env[name] },
+  workspace,
+});
+const result = await doctor();
+if (!result.ok) process.exit(1);
 ```
 
 Ports are plain objects:
 
-- `ConsoleReporter` - receives `info`, `error`, and optional `verbose` messages.
-- `SecretReader` - resolves secrets such as `LINEAR_API_KEY`.
-- `LinearWorkspace` - future adapter boundary for Linear workspace/template
-  operations.
+- `ConsoleReporter` — receives `info`, `error`, and optional `verbose` messages.
+- `SecretReader` — resolves secrets such as `LINEAR_API_KEY`.
+- `LinearWorkspace` — adapter boundary for Linear workspace operations.
+
+The full LinearWorkspace surface (`getViewer`, `listTeams`, `listLabels`,
+`createLabel`, `getTemplate`, `createTemplate`, `updateTemplate`,
+`createIssue`, `createRelation`) is implemented by
+`createLinearGraphqlWorkspace`. Later mutating commands build on these
+methods; they do not implement their own GraphQL.
 
-Core use-case modules do not read environment variables, call `fetch`, or exit
-the process. Those responsibilities stay in CLI/adapter code.
+Core use-case modules do not read environment variables, call `fetch`, or
+exit the process. Those responsibilities stay in CLI/adapter code (enforced
+by `tests/boundary.test.mjs`).
 
 ## Template
 

packages/human-handoff-linear/src/adapters/interactive-secret-reader.mjs

@@ -0,0 +1,100 @@
+/**
+ * InteractiveSecretReader — SecretReader adapter that resolves a secret from
+ * the environment first, then falls back to a hidden interactive TTY prompt.
+ *
+ * Conforms to the SecretReader port: `read(name)` returns the secret value or
+ * `null`. The hidden prompt is opt-in per call via the `interactive` option
+ * passed to `readLinearApiKey` so non-interactive use (CI / scripts) never
+ * blocks on stdin.
+ *
+ * The API key is never logged, written to disk, or echoed to the terminal.
+ */
+
+import { createEnvironmentSecretReader } from './environment-secret-reader.mjs';
+
+/**
+ * @typedef {object} InteractiveSecretReaderOptions
+ * @property {Record<string, string|undefined>} [env]
+ * @property {NodeJS.ReadStream} [stdin]
+ * @property {NodeJS.WriteStream} [stdout]
+ * @property {(opts: { stdin: NodeJS.ReadStream, stdout: NodeJS.WriteStream, prompt: string }) => Promise<string>} [hiddenPrompt]
+ */
+
+/**
+ * @param {InteractiveSecretReaderOptions} [opts]
+ * @returns {import('../ports.mjs').SecretReader & {
+ *   readLinearApiKey: (opts?: { interactive?: boolean, prompt?: string }) => Promise<string | null>,
+ * }}
+ */
+export function createInteractiveSecretReader({
+  env = {},
+  stdin,
+  stdout,
+  hiddenPrompt = defaultHiddenPrompt,
+} = {}) {
+  const baseReader = createEnvironmentSecretReader(env);
+
+  return Object.freeze({
+    read(name) {
+      return baseReader.read(name);
+    },
+
+    async readLinearApiKey({ interactive = false, prompt = 'Linear API key: ' } = {}) {
+      const fromEnv = baseReader.read('LINEAR_API_KEY');
+      if (typeof fromEnv === 'string' && fromEnv.trim() !== '') return fromEnv.trim();
+      if (!interactive) return null;
+      if (!stdin?.isTTY) return null;
+      const entered = (await hiddenPrompt({ stdin, stdout, prompt }))?.trim() ?? '';
+      return entered === '' ? null : entered;
+    },
+  });
+}
+
+/**
+ * Read one line from `stdin` without echoing to `stdout`. Restores raw mode
+ * and listeners on exit so the process is left in a clean state.
+ */
+function defaultHiddenPrompt({ stdin, stdout, prompt }) {
+  return new Promise((resolve, reject) => {
+    if (typeof stdin.setRawMode !== 'function') {
+      reject(new Error('hidden prompt requires a TTY stdin with setRawMode'));
+      return;
+    }
+
+    stdout.write(prompt);
+    const previousRaw = stdin.isRaw === true;
+    try { stdin.setRawMode(true); } catch (e) { reject(e); return; }
+    stdin.resume();
+    stdin.setEncoding('utf8');
+
+    let buffer = '';
+    const cleanup = () => {
+      stdin.removeListener('data', onData);
+      try { stdin.setRawMode(previousRaw); } catch { /* best-effort */ }
+      stdin.pause();
+      stdout.write('\n');
+    };
+
+    const onData = (chunk) => {
+      for (const ch of chunk) {
+        if (ch === '') { // Ctrl-C
+          cleanup();
+          reject(new Error('Interactive prompt cancelled.'));
+          return;
+        }
+        if (ch === '\r' || ch === '\n') {
+          cleanup();
+          resolve(buffer);
+          return;
+        }
+        if (ch === '' || ch === '\b') { // DEL or BS
+          buffer = buffer.slice(0, -1);
+          continue;
+        }
+        buffer += ch;
+      }
+    };
+
+    stdin.on('data', onData);
+  });
+}