coderifts 6.1.0 → 8.0.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 8.0.0
+
+### Security
+
+- **Installs from `coderifts@7.0.0` pinned contract-gate v0.5.0.** That action's vendored verifier accepted receipts signed by revoked keys. Fixed in contract-gate **0.7.0**. The strict install now pins **0.7.0 / `90de4be`**.
+
+### Breaking
+
+- **`@coderifts/agent-guard` declared `^15.0.0`** (`MIN_GUARD_MAJOR` 15). There is no `peerDependencies` entry — this is a **direct** dependency, so a fresh `npm i -g coderifts` resolves 15.x, not 14.x. The CLI still uses only `deployGate`, `asVerifiedDeployReceiptView`, `DEPLOY_RECEIPT_VIEW_SPEC`, and `matchGlob`.
+
+### Fixed
+
+- **Claude Code PreToolUse hook governs a path family**, not a single `coderifts.specPath`. Default globs cover OpenAPI/Swagger, GraphQL, `*.proto`, AsyncAPI, MCP manifests, and `*tool-schema*.json`. `git config --add coderifts.specPath` is additive (never drops the family). `coderifts.specPathExclude` opts one path out. A not-governed Write/Edit/MultiEdit exits 0 and prints `coderifts claude-hook: not governed: <path>` — the hook is never silent on those tools.
+
+### Docs
+
+- README **Grant versions** table: `cr.exec.v1` is the reference/teaching grant the demo and strict install use; the Atomic V2 request contract (`execution-grant-request.v2` fields) is what the SDK/Guard/executor speak; `ENFORCING_STRICT` is the current profile name and will become a versioned name.
+
+## 7.0.0
+
+### Breaking
+
+- **`provider-canary`** — proves the gate BLOCKS by attempting a merge that must be refused, creating and cleaning up a real PR; on a non-blocking repo it reverts the probe commit in the same run (`base_reverted`). A successful merge yields `NOT_VERIFIED` and exit 1 — the honest finding, not a bug.
+- **`enforce --check`** gains `--bind-workflow` (writes and reads back the SHA-pinned required-workflow rule), `--require-workflow-binding`, `--head-sha`, and `--env`; runtime read-back covers the rule-suite result, check-run app id, and check-run head_sha. Status vocabulary is VERIFIED / NOT_VERIFIED / UNVERIFIABLE.
+- Thin diff routes (`/api/v1/{grpc,graphql,asyncapi}/diff`) return `422 ANALYSIS_FAILED` on parse errors instead of a generic 500.
+
+### Added
+
+- `setup-required-check --bind-workflow` and the provider-enforcement evidence envelope (`provider-enforcement-evidence.v2`).
+- Provider adapter shape with GitLab/Bitbucket read-back (plan only; apply is GitHub).
+
+### Note
+
+- Requires `@coderifts/agent-guard` 13 or 14 (declared `^13.0.0`; the CLI uses base guard APIs, not the ATOMIC profile).
+
 ## 6.1.0
 
 ### Added

package/README.md

@@ -86,6 +86,16 @@ coderifts init --agents --check          # which of the four pieces are present
 | **Host hook** | `.claude/settings.json`, `.cursor/hooks.json` | Reuses `hook install --claude` / `--cursor` (JSON-merge, backup, idempotent). Copilot shares Claude's `.claude/settings.json` — VS Code reads it by default. |
 | **CI workflow** | `.github/workflows/coderifts.yml` | `coderifts/contract-gate@v0`. Default: `require-verified-monitoring` commented (honest default: **false**). `--strict`: the same file with `require-verified-monitoring: 'true'` |
 
+**Grant versions** (these names are not interchangeable):
+
+| What | Who uses it | What it proves |
+|------|-------------|----------------|
+| `cr.exec.v1` | capability-demo and the strict-install workflow (`require-grant`) | A reference/teaching execution grant bound to `operation ∥ target_id ∥ after_payload`. The demo and `coderifts init --agents --strict` use this form. |
+| Atomic V2 request (`execution-grant-request.v2` fields) | SDK, Guard, executor | The request contract those three speak when minting/verifying a grant. Not the same bytes as a `cr.exec.v1` token. |
+| `ENFORCING_STRICT` | Guard `withCodeRifts({ profile })` | The current **profile name**. It is unsuffixed today and will become a versioned name; it is not a grant format and not Atomic V1. |
+
+`--strict` turns on `require-grant` and `require-verified-monitoring` in the workflow; it does not rename those three things.
+
 **Next manual step:** add `CODERIFTS_API_KEY` to the repository secrets. The
 CLI never writes a key anywhere.
 
@@ -287,7 +297,26 @@ Unparseable settings JSON → refuse, no write.
 ### 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**.
+`Edit` / `MultiEdit` when authorize preflight returns **BLOCK/STOP**. The
+matcher is tool-level (`Write|Edit|MultiEdit`); the **path family** is
+enforced inside the hook.
+
+**Default governed family** (from `SUPPORTED_TYPES` + `@coderifts/contract-path`
+`looksLikeContractPath` / `CONTRACT_EXT`; `agent_tools` via `*tool-schema*.json`):
+
+- `**/*openapi*.{yaml,yml,json}` and `**/*swagger*.{yaml,yml,json}` (openapi)
+- `**/*.{graphql,gql}` (graphql)
+- `**/*.proto` (grpc)
+- `**/*asyncapi*.{yaml,yml,json}` (asyncapi)
+- `**/*mcp*.{json,yaml,yml}` (mcp_manifest)
+- `**/*tool-schema*.json` (agent_tools)
+
+`node_modules/` and `vendor/` are not governed (same as the path detector).
+`git config --add coderifts.specPath <path-or-glob>` is **additive** (never
+replaces the family). `git config --add coderifts.specPathExclude <path-or-glob>`
+opts one path out. A not-governed path exits 0 and prints
+`coderifts claude-hook: not governed: <path>` on stderr — the hook is never silent
+on a write/edit.
 
 **Exit map (Claude Code semantics — fixed):**
 
@@ -299,11 +328,12 @@ Tool-call-time gate for **Claude Code**: blocks contract-touching `Write` /
 
 Push-time equivalent (git exit **1** on BLOCK): `coderifts hook install`.
 
-**Install path:** `coderifts hook install --claude` (or `agent-setup` writes project `.claude/settings.json` when absent). Then set key + spec:
+**Install path:** `coderifts hook install --claude` (or `agent-setup` writes project `.claude/settings.json` when absent). Then set key; spec path is optional and additive:
 
 ```bash
 git config coderifts.apiKey 'cr_live_…'          # or: coderifts login / CODERIFTS_API_KEY
-git config coderifts.specPath api/openapi.yaml   # default if omitted
+git config --add coderifts.specPath extra/spec.yaml          # additive; does not drop the family
+git config --add coderifts.specPathExclude docs/openapi.yaml # opt out one false positive
 ```
 
 **Recipe — project** (`.claude/settings.json`) **or user** (`~/.claude/settings.json`):
@@ -421,6 +451,9 @@ failed, **1** on missing repo/key, API error, or any apply failure.
 | `--check` | Query GitHub + local workflows (read-only evidence) | `false` |
 | `--env <name>` | With `--check`: GitHub Environment to query | none |
 | `--branch <name>` | With `--check`: branch (default: repo default) | default branch |
+| `--provider <name>` | With `--check`: provider adapter. `github` only; others report UNVERIFIABLE and are never stubbed | `github` |
+| `--head-sha <sha>` | With `--check`: pull-request head commit, so the required-workflow pin can be compared with the bytes being merged | none |
+| `--require-workflow-binding` | With `--check`: also require a sha-pinned required workflow matching the head. **Default OFF** — without it the evidence still gains a `workflow_binding` section and neither the verdict nor the exit code changes | `false` |
 | `--json` | Machine-readable JSON result | `false` |
 
 ```bash
@@ -460,6 +493,58 @@ VERIFIED): each layer's status, `reason_code`, the API endpoint consulted,
 `queried_at`. Exit **0** when a report was produced (evidence, not a gate).
 GitLab/Bitbucket: no adapter — `UNVERIFIABLE`, never stubbed.
 
+### `coderifts provider-canary [repo]`
+
+Negative canary: open an ephemeral PR with the contract-gate check failing or
+absent and ask GitHub to merge it. **Blocked is the healthy result.** On a
+repository that does **not** block, the canary leaves a merge+revert commit
+pair on base (that is the finding, stated) — an admin token's revert bypasses
+required checks.
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `[repo]` / `--repo <owner/repo>` | Repository | none (required) |
+| `--confirm` | Required for a real run: this creates a branch and a pull request | none — without it (and without `--dry-run`) the command exits **2** rather than touching the repo |
+| `--dry-run` | Do not touch the provider; report the shape only | `false` |
+| `--json` | Machine-readable evidence document | `false` |
+
+Exit **0** only when the provider refused the merge. A merge that **succeeds**
+is the finding: `blocked:false`, status `NOT_VERIFIED`, exit **1**.
+
+```bash
+coderifts provider-canary --repo owner/repo --dry-run
+coderifts provider-canary --repo owner/repo --confirm
+coderifts provider-canary --repo owner/repo --confirm --json
+```
+
+### `coderifts grant publish`
+
+Encodes an **already-signed** execution grant plus the PR head sha into a
+comment marker on stdout, for the 1094 PR-comment delivery slot. **It does not
+mint a grant** (`src/commands/grant-publish.js:4`) — the token must already be a
+signed `cr.exec.v1` or `cr.exec.v2` (see **Grant versions** above).
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--head-sha <sha>` | **Required.** 40-hex PR head sha the grant binds | none |
+| `--grant <token>` | **Required.** `cr.exec.v1` or `cr.exec.v2` token | none |
+| `--after-payload-hash <hash>` | `sha256:…` of the after-payload | empty string |
+
+Writes `<!-- coderifts-grant-v2 -->` followed by one JSON line. Pipe it to
+`gh api` or post it as a PR comment. Bad `--head-sha` or a missing `--grant`
+exits **2** with usage.
+
+```bash
+coderifts grant publish --head-sha "$HEAD" --grant "$TOKEN" > /tmp/marker.txt
+```
+
+**Reaching the gate today:** the contract-gate Action reads a grant from its
+`execution-grant:` input, not from PR comments — `main()` in the gate does not
+pass `grantComments`, so the comment path is not yet wired end to end. Until it
+is, deliver the token through the `CODERIFTS_EXECUTION_GRANT` repository
+variable, and note that a grant binds one after-payload, so a pinned variable
+covers exactly one diff.
+
 ### Agent host files (`coderifts agent-setup`)
 
 Writes the six CodeRifts agent-host rule files **plus** the Claude Code
@@ -534,6 +619,11 @@ via `coderifts registry-gate`). The wizard:
    existing protection settings
 5. **`--apply`:** runs that PUT with your credentials, then **re-reads** and
    only reports success if the check is required
+6. **`--bind-workflow`:** create/update a repository ruleset `workflows` rule
+   pinning `.github/workflows/coderifts.yml` (the STRICT template filename)
+   to its current **blob sha** on the target branch (`enforcement: active`,
+   `bypass_actors: []`). Dry-run unless combined with `--apply`. Read-back
+   uses `github-workflow-pin.js`; reports `APPLIED` only on `VERIFIED`.
 
 **Why the App never writes protection:** mutating branch protection needs
 `administration:write` — a trust jump we refuse. Your credentials do the write.
@@ -542,6 +632,15 @@ via `coderifts registry-gate`). The wizard:
 `merge_group` webhook (`checks_requested`) and posts **CodeRifts / contract-gate**
 on the merge group head (same gate as PR heads), so the queue does not stall.
 
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--repo <owner/repo>` | Override owner/repo | `git remote origin` |
+| `--branch <name>` | Branch to protect | repo default branch |
+| `--apply` | Apply the protection change | print the `gh` command only |
+| `--bind-workflow` | Create/update a ruleset `workflows` rule pinning `.github/workflows/coderifts.yml` (STRICT template) by blob sha | `false` |
+| `--enforce-admins` | Set `enforce_admins:true` on create | `false` — admins can bypass; the gate reports `admin_bypass_open` |
+| `--json` | Machine-readable JSON result | `false` |
+
 ```bash
 # Observe + print command (safe default)
 coderifts setup-required-check
@@ -549,6 +648,12 @@ coderifts setup-required-check
 # Apply + re-verify
 coderifts setup-required-check --apply
 
+# Pin the STRICT workflow by blob sha (ruleset `workflows` rule)
+coderifts setup-required-check --bind-workflow --apply
+
+# Admins cannot bypass either (opt-in; NOT the default)
+coderifts setup-required-check --apply --enforce-admins
+
 # One-liner for CI docs
 coderifts setup-required-check --branch main
 ```

package/bin/coderifts.js

@@ -85,6 +85,60 @@ program
     process.exit(code);
   });
 
+// ── provider canary (1105 negative enforcement proof) ──
+//
+// NOT read-only, and deliberately not hidden behind --apply: it creates a branch and a pull request
+// on the named repository and asks the provider to merge them. --dry-run is the safe default the
+// tests drive; a real run needs --confirm so nobody discovers this command by tab-completion.
+program
+  .command('provider-canary [repo]')
+  .description('Prove the gate BLOCKS by attempting a merge that must be refused (creates + cleans up a real PR). On a non-blocking repo the canary leaves a merge+revert commit pair on base (the finding); an admin token\'s revert bypasses required checks.')
+  .option('--repo <owner/repo>', 'Repository (owner/repo); also accepted as a positional argument')
+  .option('--dry-run', 'Do not touch the provider; report the shape only', false)
+  .option('--confirm', 'Required for a real run: this creates a branch and a pull request')
+  .option('--json', 'Machine-readable evidence document')
+  .action(async (repoPositional, options) => {
+    const { runProviderCanary } = require('../src/commands/provider-canary');
+    if (!options.dryRun && !options.confirm) {
+      console.error(
+        'provider-canary creates a real branch and pull request on the target repository and then '
+        + 'asks GitHub to merge it. Re-run with --confirm, or with --dry-run to see the shape.',
+      );
+      process.exit(2);
+    }
+    const result = await runProviderCanary(
+      { ...options, repo: options.repo || repoPositional },
+      {},
+    );
+    // The command prints (JSON or human) exactly once, after cleanup — see report() there.
+    process.exit(result.exitCode);
+  });
+
+// ── grant publish (1094 PR-comment delivery) ──
+program
+  .command('grant')
+  .description('Execution-grant helpers')
+  .command('publish')
+  .description('Encode a signed grant + head_sha as a PR-comment marker (stdout)')
+  .requiredOption('--head-sha <sha>', '40-hex PR head SHA the grant binds')
+  .requiredOption('--grant <token>', 'cr.exec.v1 or cr.exec.v2 token')
+  .option('--after-payload-hash <hash>', 'sha256:… of the after-payload')
+  .action((options) => {
+    const { runGrantPublish } = require('../src/commands/grant-publish');
+    const result = runGrantPublish({
+      headSha: options.headSha,
+      grant: options.grant,
+      afterPayloadHash: options.afterPayloadHash,
+    });
+    if (!result.ok) {
+      console.error(result.error);
+      if (result.usage) console.error(result.usage);
+      process.exitCode = result.exitCode;
+      process.exit(result.exitCode);
+    }
+    process.stdout.write(result.text + '\n');
+  });
+
 // ── init command ──
 // `init [template]` writes a policy YAML. `init --agents` is a different path:
 // it wires MCP config + agent rules + host hook + the CI gate workflow.
@@ -153,6 +207,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('--bind-workflow', 'Create/update a ruleset workflows rule pinning .github/workflows/coderifts.yml (STRICT template) by blob sha; dry-run unless --apply')
   .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) => {
@@ -193,6 +248,11 @@ program
   .option('--env <name>', 'With --check: GitHub Environment name to query for protection rules')
   .option('--branch <name>', 'With --check: branch to query (default: repository default branch)')
   .option('--provider <name>', 'With --check: provider adapter (github only; others UNVERIFIABLE, never stubbed)', 'github')
+  // 1102 — DEFAULT OFF ON PURPOSE. With the flag absent the evidence gains a workflow_binding
+  // section and NOTHING about the verdict or the exit code changes. Turning it on is a decision
+  // about how strong a claim this repository is willing to make, not a bug fix, so it is Peter's.
+  .option('--require-workflow-binding', 'With --check: also require a sha-pinned required workflow matching the head (default: off)')
+  .option('--head-sha <sha>', 'With --check: pull-request head commit, so the workflow pin can be compared with the bytes being merged')
   .option('--json', 'Machine-readable JSON result')
   .action(async (repoPositional, options) => {
     const { runEnforce } = require('../src/commands/enforce');