coderifts 3.1.0 → 3.3.0

package/README.md

@@ -94,6 +94,57 @@ is **never** treated as a silent NEW_ARTIFACT pass.
 
 On success the command prints a **receipt reference** when the preflight path issues one.
 
+### `coderifts deploy-gate`
+
+Gate a **deploy** on the current `{ environment, artifact }` using a preflight
+receipt (phase-1 advisory). The CD sibling of `publish-gate` / the merge-gate
+App check. Composes the validated `deployGate` from `@coderifts/agent-guard` —
+the CLI only binds env + artifact + receipt + observed CD enforcement. No
+scoring is reimplemented here.
+
+Phase 1 **reports** and exits **0** even on a gate deny, unless the step is
+marked enforcing (`--enforce` or `CODERIFTS_DEPLOY_ENFORCE=true`), in which
+case a failure exits **1**. Missing `--env` / `--artifact` is a usage error
+(exit **1**). No receipt → pending (never a fabricated allow).
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--env <environment>` | Target environment (e.g. `production`, `staging`) | required |
+| `--artifact <artifact_id>` | Immutable artifact identity (content digest or commit SHA) | required |
+| `--receipt <file>` | Path to the deploy-scoped receipt JSON from preflight | none |
+| `--json` | Binding result as JSON | `false` |
+| `--enforce` | Attest ENFORCING and exit non-zero on a gate failure | `false` |
+
+```bash
+coderifts deploy-gate --env production --artifact "$SHA" --receipt receipt.json
+coderifts deploy-gate --env production --artifact "$SHA" --receipt receipt.json --enforce
+```
+
+### `coderifts outcome <kind>`
+
+Report a **post-hoc** observed outcome for a past `decision_id` to
+`POST /api/v1/outcomes`. Records the **caller's assertion** (your deploy job
+knows success/failure) — the command does **not** itself verify the deploy.
+
+`kind` is a closed set: `deploy_succeeded`, `deploy_failed`, `rolled_back`,
+`consumer_break_reported`, `remediation_verified_working`,
+`false_positive_reported`, `other_reported`.
+
+Requires a cloud API key (`coderifts login` or `CODERIFTS_API_KEY`). Reporter
+is derived from the key. Exit **0** on success, **1** on usage / API error.
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--decision <decision_id>` | `decision_result.decision_id` (required) | none |
+| `--observed-at <iso>` | When the outcome was observed (ISO-8601) | now |
+| `--details <json>` | Optional JSON object/array bound to the row | none |
+| `--json` | Print the API response JSON | `false` |
+
+```bash
+coderifts outcome deploy_succeeded --decision "$DECISION_ID"
+coderifts outcome deploy_failed --decision "$DECISION_ID" --json
+```
+
 ### `coderifts registry-gate [dir]`
 
 Local **registry admission gate** for a directory of OpenAPI/Swagger specs
@@ -138,6 +189,111 @@ After upgrading the `coderifts` CLI, re-run `coderifts hook install` so the
 installed hook matches the package (already-installed hooks are not
 auto-updated).
 
+### Claude Code PreToolUse (`coderifts claude-hook`) — ID824
+
+Tool-call-time gate for **Claude Code**: blocks contract-touching `Write` /
+`Edit` / `MultiEdit` when authorize preflight returns **BLOCK/STOP**.
+
+**Exit map (Claude Code semantics — fixed):**
+
+| Exit | Meaning |
+|------|---------|
+| **2** | **BLOCK** — tool call cancelled; stderr is shown to the model |
+| **0** | Allow, or soft-skip (no key / wrong file / parse gap / API down) |
+| **1** | **Never used for deny** — Claude treats exit 1 as non-blocking (action proceeds) |
+
+Push-time equivalent (git exit **1** on BLOCK): `coderifts hook install`.
+
+**Install path:** `npm i -g coderifts` then set key + spec (same as the git hook):
+
+```bash
+git config coderifts.apiKey 'cr_live_…'          # or: coderifts login / CODERIFTS_API_KEY
+git config coderifts.specPath api/openapi.yaml   # default if omitted
+```
+
+**Recipe — project** (`.claude/settings.json`) **or user** (`~/.claude/settings.json`):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "coderifts claude-hook",
+            "timeout": 60
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+- **Project** `.claude/settings.json` — shared with the repo (commit if the team wants the gate).
+- **User** `~/.claude/settings.json` — personal; applies to all projects on this machine.
+- Matcher is case-sensitive tool names/regex. Exit-2 blocking is **Claude Code** semantics; the same decision discipline at push-time is the git pre-push hook above.
+
+**`CODERIFTS_STRICT` (opt-in, not a package guarantee):** env `1` or `true`
+(case-insensitive) hardens **enforcement-relevant** soft sites into **exit 2
+(BLOCK)** — “governance did not run” must not read as ALLOW. Hardened: missing
+API key; API unreachable (network/timeout/error); disk unreadable on the
+contract path; Edit/MultiEdit apply failure on the contract path. Still soft
+even in strict: non-spec path, identical content, unparseable stdin, missing
+`file_path`, WARN/REQUIRE_APPROVAL (governance ran), real ALLOW. Unset/empty →
+identical to the default soft UX. Hosts choose strict for CI/prod.
+
+```bash
+CODERIFTS_STRICT=1 coderifts claude-hook
+```
+
+### `coderifts status [repo]`
+
+**Read-only** cross-layer enforcement report (Runtime / Merge / Deploy, plus
+Content). Calls `GET /api/v1/enforcement-status` and prints the statuses the
+endpoint measured — no GitHub writes, no branch-protection changes. Pair with
+`coderifts enforce` (that command **acts**; this one only **shows**).
+
+Requires a cloud API key. Distinct from `coderifts hook status` (local
+pre-push hook install state). Exit **0** on a successful read, **1** on
+missing/invalid repo, missing key, or API error.
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `[repo]` / `--repo <owner/repo>` | Repository | none (required) |
+| `--json` | Machine-readable JSON (raw API body) | `false` |
+
+```bash
+coderifts status owner/repo
+coderifts status --repo owner/repo --json
+```
+
+### `coderifts enforce [repo]`
+
+Close enforcement gaps by chaining existing setup commands: Merge →
+`setup-required-check`; Runtime → `hook install` (apply only) + agent-guard
+guidance; Deploy → `deploy-gate` CD-step guidance; Content → guidance only.
+**Dry-run by default** (`--apply` to mutate). Does not bypass underlying
+command safety. Does not label Runtime/Content as server ENFORCING. Does not
+upgrade UNKNOWN.
+
+Requires a cloud API key for the status read. Merge `--apply` uses your local
+`gh` credentials, not the CodeRifts API key. Exit **0** when no chained step
+failed, **1** on missing repo/key, API error, or any apply failure.
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `[repo]` / `--repo <owner/repo>` | Repository | none (required) |
+| `--apply` | Run underlying setup commands | dry-run |
+| `--json` | Machine-readable JSON result | `false` |
+
+```bash
+coderifts enforce owner/repo
+coderifts enforce --repo owner/repo --apply
+```
+
 ### Agent host files (`coderifts agent-setup`)
 
 Writes the six CodeRifts agent-host rule files into the current repo (or `--out <dir>`):
@@ -163,6 +319,28 @@ re-sync with `node scripts/sync-cli-agent-host-embed.js` when the rule source ch
 
 Policy template for agent/MCP APIs: `coderifts init ai-agent` (aliases: `agent`, `mcp`).
 
+### Copilot MCP configs (`coderifts copilot-setup`)
+
+Writes GitHub Copilot MCP configs from the canonical tool names. Root keys
+differ: VS Code uses `servers`; Copilot cloud Settings paste uses `mcpServers`.
+
+```bash
+coderifts copilot-setup              # write (skip existing files)
+coderifts copilot-setup --force      # overwrite
+coderifts copilot-setup --check      # drift vs embedded content (exit 1 on drift)
+coderifts copilot-setup --out ./docs # custom root
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--out <dir>` | Target directory | cwd |
+| `--check` | Exit 0 if on-disk files match embedded content; exit 1 on drift | `false` |
+| `--force` | Overwrite existing files | skip collisions |
+
+Writes: `.vscode/mcp.json`, `copilot-cloud-agent-mcp.json`,
+`copilot-custom-agent-mcp.frontmatter.md`, `docs/copilot-mcp.md`. Unknown flags
+exit 1 (never silently ignored).
+
 ### Required check wizard (`coderifts setup-required-check`)
 
 Guided setup so **CodeRifts / contract-gate** is a **required status check** on
@@ -198,6 +376,57 @@ coderifts setup-required-check --apply
 coderifts setup-required-check --branch main
 ```
 
+### `coderifts lock [repo]`
+
+Fetch the observed agent-contract lockfile (`coderifts.lock` v1) from
+`GET /api/v1/lock`, **or** `--check` MCP drift of a locked manifest against a
+live one (`scoreMcpRisk`). `--check` is **monitor only** — it does not block.
+Unreachable live → status `unreachable` (not drift). Lock v1 records
+agents/ops, not MCP tool bodies; pass `--locked-manifest` (or additive
+`mcp_manifests` on the lockfile) for `--check`.
+
+Requires a cloud API key for write mode.
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `[repo]` / `--repo <owner/repo>` | Repository | none (write mode) |
+| `--out <path>` | Output path | `coderifts.lock` |
+| `--json` | stdout-only JSON (write: lock doc; check: drift report) | `false` |
+| `--check` | Compare locked vs live MCP manifest | `false` |
+| `--locked-manifest <path>` | Baseline MCP manifest JSON (`tools[]`) for `--check` | none |
+| `--live-manifest <path>` | Live MCP manifest JSON for `--check` | none |
+| `--live-url <url>` | Fetch live MCP manifest JSON from URL for `--check` | none |
+| `--lockfile <path>` | Read `coderifts.lock` for additive `mcp_manifests` | none |
+
+```bash
+coderifts lock owner/repo
+coderifts lock --check --locked-manifest mcp.json --live-manifest live.json
+```
+
+**`--check` exit codes** (from `lock.js`): `0` unchanged; `3` drift; `2`
+unreachable / missing locked or live (not clean); `1` usage/error.
+
+### `coderifts adopt`
+
+Counterfactual report: what CodeRifts **would have done** on contract-artifact
+changes in **local git** history. Extracts spec-only paths (not source files
+whose names happen to contain “openapi”), then runs
+`buildCounterfactualReport`. Step B (GitHub API + outcome correlation) is not
+this command. Not a git repository → fail-closed (`GIT_ERROR`, exit **1**).
+Success → exit **0**.
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--days <n>` | Look back N days (`git log --since`) | last 50 commits if neither flag set |
+| `--commits <n>` | Last N commits | last 50 commits if neither flag set |
+| `--json` | Machine-readable JSON report (analyzer logs silenced) | `false` |
+
+```bash
+coderifts adopt
+coderifts adopt --days 30
+coderifts adopt --commits 20 --json
+```
+
 ## CI/CD Integration
 
 ### GitHub Actions
@@ -256,14 +485,18 @@ Two honest modes:
 |----------|-------------|
 | `CODERIFTS_API_KEY` | API key (alternative to `coderifts login`) |
 | `CODERIFTS_OASDIFF_BIN` | Explicit path to the `oasdiff` binary (overrides auto-detect) |
+| `CODERIFTS_STRICT` | `claude-hook` only: `1` or `true` (case-insensitive) turns enforcement-relevant soft sites into exit **2** (BLOCK). Unset/empty → default soft allow. Not a package-level guarantee. |
+| `CODERIFTS_DEPLOY_ENFORCE` | `deploy-gate`: `true` marks the step enforcing (same as `--enforce`); `unknown` is explicitly unobservable (never assume ENFORCING) |
 | `NO_COLOR` | Disable colored output |
 
 ## Exit Codes
 
 | Code | Meaning |
 |------|---------|
-| `0` | No breaking changes (or below threshold) |
-| `1` | Breaking changes found (in CI mode) or analysis failed |
+| `0` | Success: no breaking changes (or below threshold); advisory `deploy-gate`; `lock --check` unchanged; `adopt` / `status` / `outcome` success |
+| `1` | Breaking changes (CI mode), analysis/usage/API failure, or `deploy-gate` deny **when enforcing** |
+| `2` | `claude-hook` BLOCK (Claude Code cancel); `lock --check` unreachable / missing locked or live |
+| `3` | `lock --check` drift detected (monitor only — does not block the package) |
 
 ## Links
 

package/bin/coderifts.js

@@ -109,6 +109,7 @@ program
   .option('--branch <name>', 'Branch to protect (default: repo default branch)')
   .option('--repo <owner/repo>', 'Override owner/repo (default: git remote origin)')
   .option('--apply', 'Apply the protection change (default: print the exact gh command only)')
+  .option('--enforce-admins', 'Set enforce_admins:true on create (default: false — admins can bypass; gate reports admin_bypass_open)')
   .option('--json', 'Machine-readable JSON result')
   .action(async (options) => {
     const { runSetupRequiredCheck } = require('../src/commands/setup-required-check');
@@ -182,14 +183,21 @@ program
     runCopilotSetup(options, { exit: true });
   });
 
-// ── lock — agent contract lockfile v1 (observed usage; ID847) ──
-// GET /api/v1/lock?repo= → write coderifts.lock. Observed-only; empty agents when none recorded.
+// ── lock — agent contract lockfile v1 (observed usage; ID847) + MCP drift --check (896) ──
+// Write: GET /api/v1/lock?repo= → coderifts.lock. Check: locked MCP vs live via scoreMcpRisk.
 program
   .command('lock [repo]')
-  .description('Fetch the observed agent-contract lockfile (coderifts.lock v1) for a repo')
+  .description(
+    'Fetch observed agent-contract lockfile (coderifts.lock v1), or --check MCP drift vs live manifest',
+  )
   .option('--repo <owner/repo>', 'Repository (owner/repo); also accepted as a positional argument')
   .option('--out <path>', 'Output path (default: coderifts.lock in cwd)')
-  .option('--json', 'Print the lock document JSON to stdout (still writes --out)')
+  .option('--json', 'Print JSON to stdout only (write: lock doc; check: drift report)')
+  .option('--check', 'MCP supply-chain monitor: compare locked vs live manifest (scoreMcpRisk)')
+  .option('--locked-manifest <path>', 'Baseline MCP manifest JSON (tools[]) for --check')
+  .option('--live-manifest <path>', 'Live MCP manifest JSON for --check')
+  .option('--live-url <url>', 'Fetch live MCP manifest JSON from URL for --check')
+  .option('--lockfile <path>', 'Read coderifts.lock for additive mcp_manifests (optional)')
   .action(async (repoPositional, options) => {
     const { runLock } = require('../src/commands/lock');
     const result = await runLock({
@@ -201,6 +209,71 @@ program
     }
   });
 
+// ── adopt — counterfactual "what would CodeRifts have done" from local git (roadmap 893 Step A) ──
+// Stateless core in app src/core/counterfactual-adopt.js; CLI extracts change sets via git
+// (mirrors publish-gate gitImpl). Not named "shadow" (shadowApis is taken).
+program
+  .command('adopt')
+  .description(
+    'Counterfactual report: what CodeRifts would have done on contract-artifact changes in local git history',
+  )
+  .option('--days <n>', 'Look back N days of git history', (v) => parseInt(v, 10))
+  .option('--commits <n>', 'Look at the last N commits', (v) => parseInt(v, 10))
+  .option('--json', 'Machine-readable JSON report')
+  .action(async (options) => {
+    const { runAdopt } = require('../src/commands/adopt');
+    const result = await runAdopt({
+      days: options.days,
+      commits: options.commits,
+      json: !!options.json,
+    });
+    if (result && typeof result.exitCode === 'number') {
+      process.exitCode = result.exitCode;
+    }
+  });
+
+// ── outcome — POST /api/v1/outcomes (caller assertion; does not verify the deploy) ──
+program
+  .command('outcome <kind>')
+  .description(
+    'Report a post-hoc outcome for a decision_id (deploy_succeeded/deploy_failed/…). '
+    + 'Records the caller\'s assertion — does not verify the deploy itself.',
+  )
+  .option('--decision <decision_id>', 'Decision id from decision_result.decision_id (required)')
+  .option('--observed-at <iso>', 'When the outcome was observed (ISO-8601; default: now)')
+  .option('--details <json>', 'Optional JSON object/array bound to the outcome row')
+  .option('--json', 'Print the API response JSON to stdout')
+  .addHelpText('after', () => {
+    const { USAGE } = require('../src/commands/outcome');
+    return `\n${USAGE}\n`;
+  })
+  .action(async (kind, options) => {
+    const { runOutcome } = require('../src/commands/outcome');
+    const result = await runOutcome(kind, options);
+    if (result && typeof result.exitCode === 'number') {
+      process.exitCode = result.exitCode;
+    }
+  });
+
+// ── claude-hook — Claude Code PreToolUse (exit 2 = BLOCK; never exit 1 for deny) ──
+program
+  .command('claude-hook')
+  .description(
+    'Claude Code PreToolUse gate: block contract-touching Write|Edit|MultiEdit on BLOCK/STOP '
+    + '(exit 2). Soft-allow when unconfigured/unparseable/API down.',
+  )
+  .addHelpText('after', () => {
+    const { USAGE } = require('../src/commands/claude-hook');
+    return `\n${USAGE}\n`;
+  })
+  .action(async () => {
+    const { runClaudeHook } = require('../src/commands/claude-hook');
+    const result = await runClaudeHook();
+    if (result && typeof result.exitCode === 'number') {
+      process.exitCode = result.exitCode;
+    }
+  });
+
 // ── hook command group ──
 const hookCmd = program
   .command('hook')