coderifts 4.4.1 → 4.7.0

package/CHANGELOG.md

@@ -1,5 +1,80 @@
 # Changelog
 
+## 4.7.0
+
+### Added
+- **`coderifts enforce --check`** — provider-native CD enforcement evidence.
+  Queries GitHub (and local workflow files) and reports, per layer,
+  `VERIFIED` / `NOT_VERIFIED` / `UNVERIFIABLE(reason)`:
+  1. required check `CodeRifts / contract-gate` on default-branch protection
+  2. `enforce_admins` (admin bypass)
+  3. `required_status_checks.strict`
+  4. GitHub Environment protection rules (`--env`)
+  5. workflow references `coderifts/contract-gate@v0` (local)
+  6. workflow runs `coderifts deploy-gate` (local)
+
+  `inescapable_deploy` is **true only when every layer is VERIFIED**. Otherwise
+  the field stays false and the JSON carries the queried facts. `--json`
+  includes each layer's status, the API endpoint consulted, and `queried_at`.
+
+  Auth: `GITHUB_TOKEN` / `GH_TOKEN` (user). App installation token
+  (`GITHUB_APP_TOKEN`) is accepted but **cannot** query branch protection —
+  the GitHub App permission set is contents:read, pull_requests, checks
+  (AUDIT.md §2.4); `GET .../protection` needs `administration:read`. No
+  token → `UNVERIFIABLE` with the exact instruction. Token values are never
+  printed. GitLab/Bitbucket: no adapter (UNVERIFIABLE, never stubbed).
+
+### Changed
+- **`observeCDEnforcement`:** `CODERIFTS_DEPLOY_NO_BYPASS` is recorded as
+  `host_claim_no_bypass` and no longer sets `bypass_possible: false`.
+  `--enforce` still marks the step ENFORCING (exit is already fail-closed)
+  but is a **host claim**. `bypass_possible` is false only when
+  `providerEvidence.inescapable_deploy === true` from `enforce --check`.
+  Guard `deployGate` still consumes `{ enforcement, bypass_possible }` — the
+  CLI must not pass a flag-derived “no bypass”.
+
+## 4.6.0
+
+**Version pick:** the parallel Cursor-hook round claimed **4.5.0**
+(`8eab5f9`, `packages/cli/package.json` 4.5.0). This command takes the next
+free minor. (4.5.0's CHANGELOG entry was not written in that round; the
+commit message is the record of `coderifts cursor-hook` + `hook install
+--cursor`.)
+
+### Added
+- **`coderifts init --agents`** — one command that wires a repository for
+  governed agent work. Four pieces:
+  1. repo-level MCP config per host (never one file for all):
+     Claude Code `.mcp.json` uses `mcpServers.coderifts` with **`type":"http"`
+     + `url`** (a `url` without `type` is skipped — measured
+     code.claude.com/docs/en/mcp 2026-08-22); Cursor `.cursor/mcp.json` uses
+     **`url` and no `type`** (measured docs.cursor.com). Gemini `httpUrl` is
+     extension-level — this command does not write it.
+  2. generated agent rule files, via **`writeAgentHostFiles`** extracted from
+     `agent-setup` (not a second copy). Cursor `.mdc` is included because the
+     4.5.0 round landed it.
+  3. host hook where one exists: `installClaudeHook` and (4.5.0)
+     `installCursorHook` — JSON-merge, `.bak`, idempotent. `--no-hook` skips.
+  4. `.github/workflows/coderifts.yml` at `coderifts/contract-gate@v0`, with
+     `require-verified-monitoring` commented (honest default: false).
+     `--no-workflow` skips. Existing workflow files are never clobbered.
+- `--hosts=claude,cursor,all` (default `all`), `--dry-run` (plan, no write),
+  `--check` (which of the four pieces are present).
+- Idempotent re-run: unchanged files are skipped; JSON MCP configs are merged
+  (other servers preserved, `.bak` alongside any file it modifies).
+- Summary names created / merged / skipped and WHY, the next manual step
+  (add `CODERIFTS_API_KEY` to repo secrets — the CLI never writes a key),
+  and what this does **not** do: enable branch protection
+  (ENFORCEMENT.md), make raw host tools inescapable, or enforce the
+  workflow until the required check is turned on in repo settings.
+
+### Shared vs new
+- **Shared:** `writeAgentHostFiles` (extracted from `agent-setup`);
+  `installClaudeHook` / `installCursorHook` (`silent` + `dryRun` passed
+  through).
+- **New:** `src/mcp-repo-config.js`, `src/contract-gate-workflow.js`,
+  `src/commands/init-agents.js`.
+
 ## 4.4.1
 
 **Sequencing:** `@coderifts/agent-guard` **9.0.0** is the verifier of record

package/README.md

@@ -61,6 +61,42 @@ Interactive configuration generator. Creates a `.coderifts.yml` file with indust
 - `microservices-internal`
 - `ai-agent-platform`
 
+### `coderifts init --agents`
+
+One command that wires **this repository** for governed agent work. Re-run is
+a no-op. Existing JSON is merged (never clobbered); a `.bak` sits next to any
+file it modifies.
+
+```bash
+coderifts init --agents                  # all hosts, all four pieces
+coderifts init --agents --dry-run        # plan only — writes nothing
+coderifts init --agents --hosts=claude   # Claude Code only
+coderifts init --agents --hosts=cursor   # Cursor only
+coderifts init --agents --no-hook        # skip host hook install
+coderifts init --agents --no-workflow    # skip .github/workflows/coderifts.yml
+coderifts init --agents --check          # which of the four pieces are present
+```
+
+| Piece | What it writes | Host-specific shape |
+|-------|----------------|---------------------|
+| **MCP config** | `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor) | Claude: `mcpServers.coderifts` with `type: "http"` + `url`. Cursor: `url` only (no `type`). Never `httpUrl` (that is Gemini, extension-level — this command does not write it). |
+| **Agent rules** | generated host files via `agent-setup`'s writer | `AGENTS.md` is always written. Claude also gets `CLAUDE.md`; Cursor also gets `.cursor/rules/coderifts.mdc`. `--hosts=all` adds Copilot, LangGraph, and OpenAI instructions. (`coderifts init agent` is a different command — it writes a `.coderifts.yml` template.) |
+| **Host hook** | `.claude/settings.json`, `.cursor/hooks.json` | Reuses `hook install --claude` / `--cursor` (JSON-merge, backup, idempotent) |
+| **CI workflow** | `.github/workflows/coderifts.yml` | `coderifts/contract-gate@v0`. `require-verified-monitoring` is commented (honest default: **false**) |
+
+**Next manual step:** add `CODERIFTS_API_KEY` to the repository secrets. The
+CLI never writes a key anywhere.
+
+**This command does not:** enable branch protection (see
+[ENFORCEMENT.md](https://github.com/coderifts/contract-gate/blob/main/ENFORCEMENT.md)),
+make raw host tools inescapable, or enforce the workflow until
+`CodeRifts / contract-gate` is a required check in repo settings.
+
+The three separate commands this replaces for a fresh repo: `coderifts
+agent-setup`, `coderifts hook install --claude` (and `--cursor`), plus a
+hand-copied workflow file. Repo-level MCP config was generated by nothing
+before 4.6.0.
+
 ### `coderifts login`
 
 Save your CodeRifts API key for cloud features. Get a free key at [app.coderifts.com/api/signup](https://app.coderifts.com/api/signup).
@@ -132,8 +168,11 @@ gate reason + `renderDecisionWhy` when a body exists) and
 unsigned file still prints the unsigned-receipt truth loudly.
 
 **`--enforce` / `CODERIFTS_DEPLOY_ENFORCE=true`:** accepted silently (no-op
-for exit — default is already fail-closed). Still attests ENFORCING for the
-`inescapable_deploy` claim.
+for exit — default is already fail-closed). This is a **host claim** that the
+step is ENFORCING. It does **not** set `inescapable_deploy`. That field is
+true only from queried pipeline protection (`coderifts enforce --check`).
+`CODERIFTS_DEPLOY_NO_BYPASS` is recorded as a host claim and does not clear
+`bypass_possible`.
 
 **Infra vs policy:** missing `--env` / `--artifact`, malformed receipt JSON, or
 an unreachable `--keys` registry prints distinct `INFRA` wording plus
@@ -346,13 +385,44 @@ failed, **1** on missing repo/key, API error, or any apply failure.
 |------|-------------|---------|
 | `[repo]` / `--repo <owner/repo>` | Repository | none (required) |
 | `--apply` | Run underlying setup commands | dry-run |
+| `--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 |
 | `--json` | Machine-readable JSON result | `false` |
 
 ```bash
 coderifts enforce owner/repo
 coderifts enforce --repo owner/repo --apply
+coderifts enforce --check --repo owner/repo --env production --json
 ```
 
+### `coderifts enforce --check`
+
+Provider-native pipeline-protection evidence. This is **not** a host claim:
+`--enforce` and `CODERIFTS_DEPLOY_NO_BYPASS` do **not** set
+`inescapable_deploy`. The field is true only when every layer below is
+`VERIFIED`.
+
+| Layer | VERIFIED when |
+|-------|----------------|
+| `required_check` | Default-branch protection requires `CodeRifts / contract-gate` |
+| `enforce_admins` | `enforce_admins.enabled` is **true** (admins cannot bypass). `false` = NOT_VERIFIED (admin bypass open) |
+| `strict_status_checks` | `required_status_checks.strict` is true |
+| `environment_protection` | `--env` names a GitHub Environment with protection rules or a deployment branch policy |
+| `workflow_contract_gate` | a local `.github/workflows` file references `coderifts/contract-gate@v0` |
+| `workflow_deploy_gate` | a local workflow runs `coderifts deploy-gate` |
+
+Statuses: `VERIFIED` / `NOT_VERIFIED` / `UNVERIFIABLE(reason)`. Auth:
+`GITHUB_TOKEN` (never printed). **No token** → API layers `UNVERIFIABLE` with
+the instruction to set `GITHUB_TOKEN` (repo + `administration:read`). The
+CodeRifts GitHub App **cannot** query branch protection (permissions are
+contents / pull requests / checks — not `administration:read`).
+
+`--json` is the quotable evidence document (`spec`:
+`provider-enforcement-evidence.v1`): each layer's status, the API endpoint
+consulted, `queried_at`. Exit **0** when a report was produced (evidence, not
+a gate). GitLab/Bitbucket: no adapter — `UNVERIFIABLE`, never stubbed.
+
 ### Agent host files (`coderifts agent-setup`)
 
 Writes the six CodeRifts agent-host rule files **plus** the Claude Code

package/bin/coderifts.js

@@ -86,10 +86,49 @@ program
   });
 
 // ── 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.
 program
   .command('init [template]')
-  .description('Generate a .coderifts.yml from a policy template (startup, growth, fintech, public-api, microservices)')
-  .action(async (template) => {
+  .description('Generate a .coderifts.yml from a policy template, or wire governed agent work (--agents)')
+  .option('--agents', 'Wire this repo for governed agent work (MCP config, rule files, host hook, CI gate)')
+  .option('--hosts <list>', 'With --agents: claude, cursor, or all (default: all)', 'all')
+  .option('--no-hook', 'With --agents: skip host hook install')
+  .option('--no-workflow', 'With --agents: skip writing .github/workflows/coderifts.yml')
+  .option('--dry-run', 'With --agents: print the plan without writing')
+  .option('--check', 'With --agents: report which of the four pieces are present (no write)')
+  .option('--out <dir>', 'With --agents: target directory (default: cwd)')
+  .action(async (template, options) => {
+    const {
+      runInitAgents,
+      agentFlagsRequireAgents,
+      AGENT_FLAGS_REQUIRE_AGENTS,
+      AGENTS_NO_TEMPLATE,
+    } = require('../src/commands/init-agents');
+    if (options.agents) {
+      if (template) {
+        console.error(AGENTS_NO_TEMPLATE);
+        process.exitCode = 1;
+        return;
+      }
+      const result = runInitAgents({
+        hosts: options.hosts,
+        hook: options.hook,
+        workflow: options.workflow,
+        dryRun: !!options.dryRun,
+        check: !!options.check,
+        out: options.out,
+      });
+      if (result && typeof result.exitCode === 'number') {
+        process.exitCode = result.exitCode;
+      }
+      return;
+    }
+    if (agentFlagsRequireAgents(options)) {
+      console.error(AGENT_FLAGS_REQUIRE_AGENTS);
+      process.exitCode = 1;
+      return;
+    }
     const { init } = require('../src/commands/init');
     await init(template);
   });
@@ -145,9 +184,13 @@ program
 // No new GitHub writes with the CodeRifts API key (user's gh for merge; local fs for hook).
 program
   .command('enforce [repo]')
-  .description('Close enforcement gaps by chaining setup-required-check / hook / deploy guidance (dry-run default; use --apply to mutate)')
+  .description('Close enforcement gaps (dry-run default), or --check to query provider-native pipeline protection evidence')
   .option('--repo <owner/repo>', 'Repository (owner/repo); also accepted as a positional argument')
   .option('--apply', 'Actually run underlying setup commands (default: dry-run only)')
+  .option('--check', 'Query GitHub + local workflows; report VERIFIED / NOT_VERIFIED / UNVERIFIABLE (read-only)')
+  .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')
   .option('--json', 'Machine-readable JSON result')
   .action(async (repoPositional, options) => {
     const { runEnforce } = require('../src/commands/enforce');
@@ -155,6 +198,7 @@ program
       ...options,
       repo: options.repo || repoPositional || null,
       apply: !!options.apply,
+      check: !!options.check,
     });
     if (result && typeof result.exitCode === 'number') {
       process.exitCode = result.exitCode;
@@ -278,6 +322,27 @@ program
     }
   });
 
+// ── cursor-hook — Cursor preToolUse ({"permission":"deny"} on stdout; also exit 2) ──
+program
+  .command('cursor-hook')
+  .description(
+    'Cursor preToolUse gate: deny contract-touching Write|Delete on BLOCK/STOP/REQUEST_APPROVAL. '
+    + 'Emits {permission,user_message,agent_message} on stdout. Cursor does not enforce "ask" for '
+    + 'preToolUse, so REQUEST_APPROVAL maps to deny. Fail-closed on unparseable stdin.',
+  )
+  .addHelpText('after', () => {
+    const { USAGE } = require('../src/commands/cursor-hook');
+    return `\n${USAGE}\n`;
+  })
+  .action(async () => {
+    const { runCursorHook } = require('../src/commands/cursor-hook');
+    const fsMod = require('fs');
+    let stdin = '';
+    try { stdin = fsMod.readFileSync(0, 'utf8'); } catch { stdin = ''; }
+    const code = await runCursorHook({ argv: process.argv.slice(3), stdin });
+    if (typeof code === 'number') process.exitCode = code;
+  });
+
 // ── hook command group ──
 const hookCmd = program
   .command('hook')
@@ -287,12 +352,14 @@ hookCmd
   .command('install')
   .description('Install the CodeRifts pre-push hook in the current Git repo')
   .option('--claude', 'Write Claude Code PreToolUse hook to .claude/settings.json (JSON-merge)')
-  .option('--global', 'With --claude: write ~/.claude/settings.json instead of the project file')
-  .option('--log <path>', 'With --claude: embed CODERIFTS_GUARD_EVENT_LOG and CODERIFTS_SESSION_ID in the command')
+  .option('--cursor', 'Write Cursor preToolUse hook to .cursor/hooks.json (JSON-merge, failClosed:true)')
+  .option('--global', 'With --claude/--cursor: write the ~/ config instead of the project file')
+  .option('--log <path>', 'With --claude/--cursor: embed CODERIFTS_GUARD_EVENT_LOG and CODERIFTS_SESSION_ID in the command')
   .action((options) => {
     const { install } = require('../src/commands/hook');
     install({
       claude: !!options.claude,
+      cursor: !!options.cursor,
       global: !!options.global,
       log: options.log,
     });