coderifts 4.6.0 → 4.7.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # 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**

package/README.md

@@ -168,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
@@ -382,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

@@ -184,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');
@@ -194,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;

package/dist/cli.js

@@ -3028,7 +3028,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "coderifts",
-      version: "4.6.0",
+      version: "4.7.0",
       description: "Detect breaking API changes from the command line. Works locally or with the CodeRifts cloud API.",
       author: "CodeRifts <hello@coderifts.com>",
       license: "MIT",
@@ -207461,18 +207461,31 @@ var require_deploy_gate2 = __commonJS({
       return isEnvFlag(e, "CODERIFTS_DEPLOY_ADVISORY") || isEnvFlag(e, "CODERIFTS_ADVISORY");
     }
     function observeCDEnforcement(options = {}) {
+      const evidence = options.providerEvidence;
+      const hostClaimNoBypass = String(process.env.CODERIFTS_DEPLOY_NO_BYPASS || "").toLowerCase() === "true";
+      if (evidence && evidence.inescapable_deploy === true) {
+        return {
+          enforcement: "ENFORCING",
+          bypass_possible: false,
+          step_is_required: true,
+          required_step_name: "CodeRifts / deploy-gate",
+          attestation_source: "provider_query",
+          host_claim_no_bypass: hostClaimNoBypass
+        };
+      }
       const envVal = String(process.env.CODERIFTS_DEPLOY_ENFORCE || "").toLowerCase();
       let enforcement;
       if (enforceSignal(options)) enforcement = "ENFORCING";
       else if (envVal === "unknown") enforcement = "UNKNOWN";
       else enforcement = "ADVISORY";
-      const bypass_possible = String(process.env.CODERIFTS_DEPLOY_NO_BYPASS || "").toLowerCase() !== "true";
       return {
         enforcement,
-        bypass_possible,
+        bypass_possible: true,
+        // host NO_BYPASS is a claim, not queried evidence
         step_is_required: enforcement === "ENFORCING",
         required_step_name: "CodeRifts / deploy-gate",
-        attestation_source: "cli_flag"
+        attestation_source: "cli_flag",
+        host_claim_no_bypass: hostClaimNoBypass
       };
     }
     function deployReportResiduals(state, enforcement_inescapable, enforcement, change_set_rebound) {
@@ -207795,7 +207808,7 @@ var require_deploy_gate2 = __commonJS({
       if (bind.report_residuals.length) lines.push(`  Residuals:          ${bind.report_residuals.join(", ")}`);
       if (bind.must_re_preflight) lines.push(chalk.yellow("  Action: re-preflight this { environment, artifact } \u2014 the receipt does not authorize it."));
       lines.push("");
-      lines.push(enforce ? chalk.dim("  Attested ENFORCING (inescapable_deploy claim). Exit is fail-closed by default.") : chalk.dim("  Fail-closed default \u2014 a failing gate exits non-zero. " + SOFTEN_HINT + "."));
+      lines.push(enforce ? chalk.dim("  Attested ENFORCING via --enforce (host claim). inescapable_deploy requires queried pipeline protection (`coderifts enforce --check`). Exit is fail-closed by default.") : chalk.dim("  Fail-closed default \u2014 a failing gate exits non-zero. " + SOFTEN_HINT + "."));
       lines.push("");
       return lines.join("\n");
     }
@@ -236999,6 +237012,538 @@ var require_status = __commonJS({
   }
 });
 
+// src/provider/github-enforcement.js
+var require_github_enforcement = __commonJS({
+  "src/provider/github-enforcement.js"(exports2, module2) {
+    "use strict";
+    var fs = require("fs");
+    var path = require("path");
+    var {
+      CHECK_NAME,
+      extractRequiredContexts
+    } = require_setup_required_check();
+    var { GATE_ACTION } = require_contract_gate_workflow();
+    var EVIDENCE_SPEC = "provider-enforcement-evidence.v1";
+    var APP_INSTALLATION = Object.freeze({
+      can_query_protection: false,
+      permissions: Object.freeze([
+        "contents:read",
+        "pull_requests:read+write",
+        "checks:read+write"
+      ]),
+      missing_scope: "administration:read",
+      reason: "GET /repos/{owner}/{repo}/branches/{branch}/protection requires administration:read (or repo admin). The CodeRifts GitHub App permission set is contents:read, pull_requests:read+write, checks:read+write \u2014 administration:read is not granted."
+    });
+    var NO_TOKEN_INSTRUCTION = "NO token \u2014 set GITHUB_TOKEN (repo + administration:read; Environments: Read if querying --env). The CodeRifts GitHub App installation cannot query branch protection (permissions: contents:read, pull_requests:read+write, checks:read+write \u2014 missing administration:read).";
+    var LAYER_IDS = Object.freeze([
+      "required_check",
+      "enforce_admins",
+      "strict_status_checks",
+      "environment_protection",
+      "workflow_contract_gate",
+      "workflow_deploy_gate"
+    ]);
+    var STATUS = Object.freeze({
+      VERIFIED: "VERIFIED",
+      NOT_VERIFIED: "NOT_VERIFIED",
+      UNVERIFIABLE: "UNVERIFIABLE"
+    });
+    function resolveGitHubAuth(env = process.env) {
+      const user = String(env && (env.GITHUB_TOKEN || env.GH_TOKEN) || "").trim();
+      if (user) {
+        return { ok: true, source: "github_token", token: user };
+      }
+      const app = String(env && (env.GITHUB_APP_TOKEN || env.CODERIFTS_GITHUB_APP_TOKEN) || "").trim();
+      if (app) {
+        return { ok: true, source: "github_app_installation", token: app };
+      }
+      return { ok: false, source: "none", token: null, reason: NO_TOKEN_INSTRUCTION };
+    }
+    function redactSecrets(text) {
+      return String(text || "").replace(/Bearer\s+\S+/gi, "Bearer [redacted]").replace(/ghp_[A-Za-z0-9_]+/g, "ghp_[redacted]").replace(/github_pat_[A-Za-z0-9_]+/g, "github_pat_[redacted]");
+    }
+    function createGitHubHttpClient(opts = {}) {
+      const token = opts.token;
+      const fetchFn = opts.fetchImpl || (typeof fetch === "function" ? fetch.bind(globalThis) : null);
+      const apiBase = (opts.apiBase || "https://api.github.com").replace(/\/$/, "");
+      return {
+        name: "github",
+        async get(apiPath) {
+          const endpoint = `${apiBase}/${String(apiPath).replace(/^\//, "")}`;
+          if (!fetchFn) {
+            return {
+              status: 0,
+              body: null,
+              endpoint,
+              error: "fetch is not available in this runtime"
+            };
+          }
+          const res = await fetchFn(endpoint, {
+            method: "GET",
+            headers: {
+              Authorization: `Bearer ${token}`,
+              Accept: "application/vnd.github+json",
+              "X-GitHub-Api-Version": "2022-11-28",
+              "User-Agent": "coderifts-cli"
+            }
+          });
+          const text = await res.text();
+          let body = null;
+          try {
+            body = text ? JSON.parse(text) : null;
+          } catch {
+            body = null;
+          }
+          return { status: res.status, body, endpoint };
+        }
+      };
+    }
+    function enforceAdminsEnabled(protection) {
+      if (!protection || typeof protection !== "object") return false;
+      const ea = protection.enforce_admins;
+      if (ea === true) return true;
+      if (ea && typeof ea === "object" && ea.enabled === true) return true;
+      return false;
+    }
+    function strictEnabled(protection) {
+      if (!protection || typeof protection !== "object") return false;
+      const rsc = protection.required_status_checks;
+      return !!(rsc && typeof rsc === "object" && rsc.strict === true);
+    }
+    function environmentProtected(body) {
+      if (!body || typeof body !== "object") return false;
+      const rules = Array.isArray(body.protection_rules) ? body.protection_rules : [];
+      if (rules.length > 0) return true;
+      const policy = body.deployment_branch_policy;
+      if (policy && typeof policy === "object") {
+        return policy.protected_branches === true || policy.custom_branch_policies === true;
+      }
+      return false;
+    }
+    function layer(id, status, extra = {}) {
+      return { id, status, ...extra };
+    }
+    function evaluateLayers({
+      protectionRead,
+      environmentRead,
+      environmentName,
+      local,
+      auth
+    } = {}) {
+      const layers = [];
+      const localFiles = local || { contractGateFiles: [], deployGateFiles: [] };
+      const noAuth = !auth || auth.source === "none" || !auth.ok;
+      const prot = protectionRead || null;
+      if (noAuth && !prot) {
+        const why = auth && auth.reason || NO_TOKEN_INSTRUCTION;
+        for (const id of ["required_check", "enforce_admins", "strict_status_checks"]) {
+          layers.push(layer(id, STATUS.UNVERIFIABLE, {
+            reason: why,
+            endpoint: null,
+            missing_scope: APP_INSTALLATION.missing_scope
+          }));
+        }
+      } else if (!prot) {
+        const why = "branch protection was not queried";
+        for (const id of ["required_check", "enforce_admins", "strict_status_checks"]) {
+          layers.push(layer(id, STATUS.UNVERIFIABLE, { reason: why, endpoint: null }));
+        }
+      } else if (prot.status === 403) {
+        const why = "GitHub HTTP 403 \u2014 missing scope administration:read (branch protection). Grant Administration: Read on the token, or use a repo-admin token.";
+        const endpoint = prot.endpoint ? `GET ${prot.endpoint}` : null;
+        for (const id of ["required_check", "enforce_admins", "strict_status_checks"]) {
+          layers.push(layer(id, STATUS.UNVERIFIABLE, {
+            reason: why,
+            endpoint,
+            missing_scope: "administration:read",
+            http_status: 403
+          }));
+        }
+      } else if (prot.status === 404) {
+        const endpoint = prot.endpoint ? `GET ${prot.endpoint}` : null;
+        layers.push(layer("required_check", STATUS.NOT_VERIFIED, {
+          reason: `classic branch protection is absent \u2014 required check "${CHECK_NAME}" is not required`,
+          endpoint,
+          http_status: 404
+        }));
+        layers.push(layer("enforce_admins", STATUS.NOT_VERIFIED, {
+          reason: "classic branch protection is absent \u2014 administrators are unrestricted",
+          endpoint,
+          http_status: 404
+        }));
+        layers.push(layer("strict_status_checks", STATUS.NOT_VERIFIED, {
+          reason: "classic branch protection is absent \u2014 required_status_checks.strict is not set",
+          endpoint,
+          http_status: 404
+        }));
+      } else if (prot.status >= 400 || prot.status === 0) {
+        const endpoint = prot.endpoint ? `GET ${prot.endpoint}` : null;
+        const why = `GitHub HTTP ${prot.status || 0} reading branch protection \u2014 cannot verify`;
+        for (const id of ["required_check", "enforce_admins", "strict_status_checks"]) {
+          layers.push(layer(id, STATUS.UNVERIFIABLE, {
+            reason: redactSecrets(why),
+            endpoint,
+            http_status: prot.status
+          }));
+        }
+      } else {
+        const protection = prot.body && typeof prot.body === "object" ? prot.body : {};
+        const endpoint = prot.endpoint ? `GET ${prot.endpoint}` : null;
+        const contexts = extractRequiredContexts(protection);
+        const hasCheck = contexts.includes(CHECK_NAME);
+        layers.push(layer("required_check", hasCheck ? STATUS.VERIFIED : STATUS.NOT_VERIFIED, {
+          reason: hasCheck ? `required_status_checks includes "${CHECK_NAME}"` : `required_status_checks does not include "${CHECK_NAME}" (have: ${contexts.join(", ") || "none"})`,
+          endpoint,
+          required_contexts: contexts
+        }));
+        const admins = enforceAdminsEnabled(protection);
+        layers.push(layer("enforce_admins", admins ? STATUS.VERIFIED : STATUS.NOT_VERIFIED, {
+          reason: admins ? "enforce_admins.enabled is true \u2014 administrators cannot bypass required checks" : "enforce_admins.enabled is false \u2014 repository administrators can bypass required checks",
+          endpoint,
+          enforce_admins: admins
+        }));
+        const strict = strictEnabled(protection);
+        layers.push(layer("strict_status_checks", strict ? STATUS.VERIFIED : STATUS.NOT_VERIFIED, {
+          reason: strict ? "required_status_checks.strict is true" : "required_status_checks.strict is not true \u2014 a branch need not be up to date before merge",
+          endpoint,
+          strict
+        }));
+      }
+      if (!environmentName) {
+        layers.push(layer("environment_protection", STATUS.UNVERIFIABLE, {
+          reason: "no --env supplied; pass --env <GitHub Environment name> to query environment protection rules",
+          endpoint: null
+        }));
+      } else if (noAuth && !environmentRead) {
+        layers.push(layer("environment_protection", STATUS.UNVERIFIABLE, {
+          reason: auth && auth.reason || NO_TOKEN_INSTRUCTION,
+          endpoint: null,
+          missing_scope: "actions:read / Environments: Read"
+        }));
+      } else if (!environmentRead) {
+        layers.push(layer("environment_protection", STATUS.UNVERIFIABLE, {
+          reason: "environment was not queried",
+          endpoint: null
+        }));
+      } else if (environmentRead.status === 403) {
+        layers.push(layer("environment_protection", STATUS.UNVERIFIABLE, {
+          reason: "GitHub HTTP 403 \u2014 missing scope to read environments (Actions/Environments: Read, or repo admin).",
+          endpoint: environmentRead.endpoint ? `GET ${environmentRead.endpoint}` : null,
+          missing_scope: "environments:read",
+          http_status: 403
+        }));
+      } else if (environmentRead.status === 404) {
+        layers.push(layer("environment_protection", STATUS.NOT_VERIFIED, {
+          reason: `GitHub Environment "${environmentName}" does not exist (or has no protection)`,
+          endpoint: environmentRead.endpoint ? `GET ${environmentRead.endpoint}` : null,
+          http_status: 404
+        }));
+      } else if (environmentRead.status >= 400 || environmentRead.status === 0) {
+        layers.push(layer("environment_protection", STATUS.UNVERIFIABLE, {
+          reason: `GitHub HTTP ${environmentRead.status || 0} reading environment "${environmentName}"`,
+          endpoint: environmentRead.endpoint ? `GET ${environmentRead.endpoint}` : null,
+          http_status: environmentRead.status
+        }));
+      } else {
+        const ok = environmentProtected(environmentRead.body);
+        layers.push(layer("environment_protection", ok ? STATUS.VERIFIED : STATUS.NOT_VERIFIED, {
+          reason: ok ? `GitHub Environment "${environmentName}" has protection rules or a deployment branch policy` : `GitHub Environment "${environmentName}" exists but has no protection_rules and no deployment_branch_policy`,
+          endpoint: environmentRead.endpoint ? `GET ${environmentRead.endpoint}` : null,
+          environment: environmentName
+        }));
+      }
+      const cg = localFiles.contractGateFiles || [];
+      layers.push(layer("workflow_contract_gate", cg.length ? STATUS.VERIFIED : STATUS.NOT_VERIFIED, {
+        reason: cg.length ? `workflow references ${GATE_ACTION} (${cg.join(", ")})` : `no .github/workflows file references ${GATE_ACTION}`,
+        endpoint: "local:.github/workflows",
+        files: cg
+      }));
+      const dg = localFiles.deployGateFiles || [];
+      layers.push(layer("workflow_deploy_gate", dg.length ? STATUS.VERIFIED : STATUS.NOT_VERIFIED, {
+        reason: dg.length ? `workflow runs coderifts deploy-gate (${dg.join(", ")})` : "no .github/workflows file runs coderifts deploy-gate",
+        endpoint: "local:.github/workflows",
+        files: dg
+      }));
+      const byId = Object.fromEntries(layers.map((l) => [l.id, l]));
+      const inescapable = LAYER_IDS.every((id) => byId[id] && byId[id].status === STATUS.VERIFIED);
+      return {
+        layers,
+        inescapable_deploy: inescapable,
+        claim: {
+          inescapable_deploy: inescapable,
+          basis: inescapable ? "all six layers VERIFIED from queried provider evidence + local workflow files" : "inescapable_deploy stays false until every layer is VERIFIED"
+        }
+      };
+    }
+    function scanLocalWorkflows(cwd, deps = {}) {
+      const exists = deps.exists || fs.existsSync.bind(fs);
+      const readdir = deps.readdir || ((p) => fs.readdirSync(p));
+      const readFile = deps.readFile || ((p) => fs.readFileSync(p, "utf8"));
+      const dir = path.join(cwd, ".github", "workflows");
+      const contractGateFiles = [];
+      const deployGateFiles = [];
+      if (!exists(dir)) return { contractGateFiles, deployGateFiles };
+      let names = [];
+      try {
+        names = readdir(dir);
+      } catch {
+        return { contractGateFiles, deployGateFiles };
+      }
+      for (const name of names) {
+        if (!/\.ya?ml$/i.test(name)) continue;
+        const rel = `.github/workflows/${name}`;
+        let body = "";
+        try {
+          body = String(readFile(path.join(dir, name)));
+        } catch {
+          continue;
+        }
+        if (body.includes(GATE_ACTION)) contractGateFiles.push(rel);
+        if (/\bcoderifts\s+deploy-gate\b/.test(body)) deployGateFiles.push(rel);
+      }
+      return { contractGateFiles, deployGateFiles };
+    }
+    async function queryGitHubEnforcement({
+      owner,
+      repo,
+      branch,
+      environmentName,
+      client
+    } = {}) {
+      const protectionPath = branch ? `repos/${owner}/${repo}/branches/${encodeURIComponent(branch)}/protection` : null;
+      const envPath = environmentName ? `repos/${owner}/${repo}/environments/${encodeURIComponent(environmentName)}` : null;
+      let resolvedBranch = branch || null;
+      let repoRead = null;
+      if (!resolvedBranch && client) {
+        repoRead = await client.get(`repos/${owner}/${repo}`);
+        if (repoRead && repoRead.status === 200 && repoRead.body && repoRead.body.default_branch) {
+          resolvedBranch = String(repoRead.body.default_branch);
+        }
+      }
+      const protPath = resolvedBranch ? `repos/${owner}/${repo}/branches/${encodeURIComponent(resolvedBranch)}/protection` : protectionPath;
+      const protectionRead = client && protPath ? await client.get(protPath) : null;
+      const environmentRead = client && envPath ? await client.get(envPath) : null;
+      return {
+        branch: resolvedBranch,
+        repoRead,
+        protectionRead,
+        environmentRead
+      };
+    }
+    module2.exports = {
+      EVIDENCE_SPEC,
+      APP_INSTALLATION,
+      NO_TOKEN_INSTRUCTION,
+      LAYER_IDS,
+      STATUS,
+      CHECK_NAME,
+      GATE_ACTION,
+      resolveGitHubAuth,
+      redactSecrets,
+      createGitHubHttpClient,
+      evaluateLayers,
+      scanLocalWorkflows,
+      queryGitHubEnforcement,
+      enforceAdminsEnabled,
+      strictEnabled,
+      environmentProtected
+    };
+  }
+});
+
+// src/commands/enforce-check.js
+var require_enforce_check = __commonJS({
+  "src/commands/enforce-check.js"(exports2, module2) {
+    "use strict";
+    var chalk = require_source();
+    var {
+      EVIDENCE_SPEC,
+      APP_INSTALLATION,
+      NO_TOKEN_INSTRUCTION,
+      resolveGitHubAuth,
+      createGitHubHttpClient,
+      evaluateLayers,
+      scanLocalWorkflows,
+      queryGitHubEnforcement
+    } = require_github_enforcement();
+    var { isValidRepo } = require_status();
+    var { resolveOwnerRepo } = require_setup_required_check();
+    if (process.env.NO_COLOR) chalk.level = 0;
+    var USAGE = [
+      "Usage: coderifts enforce --check --repo owner/repo [--env <github-environment>] [--branch <name>] [--json]",
+      "",
+      "Query the provider (GitHub) and local workflow files. Report, per layer:",
+      "  VERIFIED / NOT_VERIFIED / UNVERIFIABLE(reason).",
+      "inescapable_deploy is true only when every layer is VERIFIED.",
+      "",
+      "Auth: GITHUB_TOKEN (or GH_TOKEN). Never prints token values.",
+      "The CodeRifts GitHub App installation cannot query branch protection",
+      "(missing administration:read)."
+    ].join("\n");
+    function statusColor(status) {
+      if (status === "VERIFIED") return chalk.green(status);
+      if (status === "NOT_VERIFIED") return chalk.yellow(status);
+      return chalk.red(status);
+    }
+    function renderHuman(report) {
+      const lines = [];
+      lines.push(chalk.bold("CodeRifts enforce --check"));
+      lines.push(`  repo:    ${report.repo}`);
+      lines.push(`  branch:  ${report.branch || "(unknown)"}`);
+      if (report.environment) lines.push(`  env:     ${report.environment}`);
+      lines.push(`  queried: ${report.queried_at}`);
+      lines.push(`  auth:    ${report.auth.source} (value not printed)`);
+      lines.push(chalk.dim(`  App installation: cannot query protection (${report.auth.app_installation.missing_scope})`));
+      lines.push("");
+      lines.push(chalk.bold("  Layer                              Status"));
+      for (const l of report.layers) {
+        const id = String(l.id).padEnd(34, " ");
+        lines.push(`  ${id}${statusColor(l.status)}`);
+        if (l.status !== "VERIFIED" && l.reason) {
+          lines.push(chalk.dim(`    WHY    ${l.reason}`));
+        }
+        if (l.endpoint) lines.push(chalk.dim(`    via    ${l.endpoint}`));
+      }
+      lines.push("");
+      const claim = report.claim && report.claim.inescapable_deploy === true;
+      lines.push(`  inescapable_deploy: ${claim ? chalk.green("true") : chalk.yellow("false")}`);
+      lines.push(chalk.dim(`  ${report.claim.basis}`));
+      lines.push("");
+      lines.push(chalk.dim("  This is queried evidence, not a host claim."));
+      lines.push(chalk.dim("  --enforce / CODERIFTS_DEPLOY_NO_BYPASS are host claims and do not set this field."));
+      if (!claim) {
+        lines.push("");
+        lines.push(chalk.bold("  ACTION"));
+        const missing = report.layers.filter((l) => l.status !== "VERIFIED");
+        for (const l of missing) {
+          if (l.id === "required_check") {
+            lines.push(chalk.dim('    require "CodeRifts / contract-gate" on default-branch protection'));
+            lines.push(chalk.dim("    (coderifts setup-required-check --apply)"));
+          } else if (l.id === "enforce_admins") {
+            lines.push(chalk.dim("    set enforce_admins: true so administrators cannot bypass"));
+            lines.push(chalk.dim("    (coderifts setup-required-check --enforce-admins --apply)"));
+          } else if (l.id === "strict_status_checks") {
+            lines.push(chalk.dim("    set required_status_checks.strict: true"));
+          } else if (l.id === "environment_protection") {
+            lines.push(chalk.dim("    add a GitHub Environment with protection rules, pass --env <name>"));
+          } else if (l.id === "workflow_contract_gate") {
+            lines.push(chalk.dim("    add .github/workflows/coderifts.yml using coderifts/contract-gate@v0"));
+            lines.push(chalk.dim("    (coderifts init --agents)"));
+          } else if (l.id === "workflow_deploy_gate") {
+            lines.push(chalk.dim("    add a CD step: coderifts deploy-gate --env <env> --artifact <id> --receipt <file>"));
+          }
+        }
+      }
+      return lines.join("\n");
+    }
+    async function runEnforceCheck(options = {}, deps = {}) {
+      const log = deps.log || console.log.bind(console);
+      const errLog = deps.errLog || console.error.bind(console);
+      const cwd = deps.cwd || options.cwd || process.cwd();
+      const now = deps.now || (() => (/* @__PURE__ */ new Date()).toISOString());
+      const env = deps.env || process.env;
+      const repoArg = options.repo;
+      let ownerRepo = null;
+      if (repoArg && isValidRepo(String(repoArg).trim())) {
+        const [owner, repo] = String(repoArg).trim().split("/");
+        ownerRepo = { owner, repo };
+      } else if (!repoArg) {
+        try {
+          ownerRepo = resolveOwnerRepo(cwd, deps.gitImpl);
+        } catch {
+          ownerRepo = null;
+        }
+      }
+      if (!ownerRepo) {
+        errLog(chalk.red("Error: missing repo (pass --repo owner/repo)"));
+        errLog(USAGE);
+        return { exitCode: 1, error: "missing_repo" };
+      }
+      const providerName = String(options.provider || "github").toLowerCase();
+      const queriedAt = now();
+      const environmentName = options.env ? String(options.env).trim() : null;
+      const local = (deps.scanLocalWorkflows || scanLocalWorkflows)(cwd, deps.fs || {});
+      const authPublic = {
+        source: "none",
+        app_installation: { ...APP_INSTALLATION }
+      };
+      if (providerName !== "github") {
+        const reason = `no ${providerName} adapter \u2014 GitHub is the only implemented provider; refusing to stub results`;
+        const evaluated2 = evaluateLayers({
+          protectionRead: null,
+          environmentRead: null,
+          environmentName,
+          local,
+          auth: { ok: false, source: "none", reason }
+        });
+        const report2 = {
+          command: "enforce --check",
+          spec: EVIDENCE_SPEC,
+          queried_at: queriedAt,
+          repo: `${ownerRepo.owner}/${ownerRepo.repo}`,
+          branch: options.branch || null,
+          environment: environmentName,
+          provider: providerName,
+          auth: { ...authPublic, reason },
+          ...evaluated2
+        };
+        if (options.json) log(JSON.stringify(report2, null, 2));
+        else log(renderHuman(report2));
+        return { exitCode: 0, report: report2 };
+      }
+      const auth = (deps.resolveAuth || resolveGitHubAuth)(env);
+      authPublic.source = auth.source;
+      if (auth.reason) authPublic.reason = auth.reason;
+      let branch = options.branch ? String(options.branch).trim() : null;
+      let protectionRead = null;
+      let environmentRead = null;
+      if (auth.ok) {
+        const client = deps.githubClient || createGitHubHttpClient({
+          token: auth.token,
+          fetchImpl: deps.fetchImpl
+        });
+        const queried = await queryGitHubEnforcement({
+          owner: ownerRepo.owner,
+          repo: ownerRepo.repo,
+          branch,
+          environmentName,
+          client
+        });
+        branch = queried.branch || branch;
+        protectionRead = queried.protectionRead;
+        environmentRead = queried.environmentRead;
+      }
+      const evaluated = evaluateLayers({
+        protectionRead,
+        environmentRead,
+        environmentName,
+        local,
+        auth
+      });
+      const report = {
+        command: "enforce --check",
+        spec: EVIDENCE_SPEC,
+        queried_at: queriedAt,
+        repo: `${ownerRepo.owner}/${ownerRepo.repo}`,
+        branch,
+        environment: environmentName,
+        provider: "github",
+        auth: authPublic,
+        ...evaluated
+      };
+      if (options.json) log(JSON.stringify(report, null, 2));
+      else log(renderHuman(report));
+      return { exitCode: 0, report };
+    }
+    module2.exports = {
+      runEnforceCheck,
+      renderHuman,
+      USAGE,
+      NO_TOKEN_INSTRUCTION
+    };
+  }
+});
+
 // src/commands/enforce.js
 var require_enforce = __commonJS({
   "src/commands/enforce.js"(exports2, module2) {
@@ -237021,14 +237566,19 @@ var require_enforce = __commonJS({
     var USAGE = [
       "Usage: coderifts enforce --repo owner/repo [--apply]",
       "   or: coderifts enforce owner/repo [--apply]",
+      "   or: coderifts enforce --check --repo owner/repo [--env <name>] [--json]",
       "",
       "Cross-layer orchestrator: reads enforcement-status, then closes gaps by calling existing",
       "setup commands (setup-required-check, hook install, deploy-gate guidance).",
       "",
+      "--check: query GitHub + local workflows and report VERIFIED / NOT_VERIFIED /",
+      "UNVERIFIABLE per layer. inescapable_deploy is true only when every layer is VERIFIED.",
+      "Does not use the CodeRifts API key. Auth: GITHUB_TOKEN. Read-only.",
+      "",
       "DRY-RUN BY DEFAULT \u2014 without --apply, prints what WOULD run and mutates NOTHING.",
       "With --apply, threads apply into each underlying command (their own safety still applies).",
       "",
-      "Requires a cloud API key for the status read (coderifts login / CODERIFTS_API_KEY).",
+      "Requires a cloud API key for the (non --check) status read (coderifts login / CODERIFTS_API_KEY).",
       "Merge apply uses your local `gh` credentials, not the CodeRifts API key."
     ].join("\n");
     var AGENT_GUARD_GUIDANCE = [
@@ -237039,8 +237589,10 @@ var require_enforce = __commonJS({
     ].join("\n");
     var DEPLOY_GUIDANCE = [
       "Deploy is declared-only on the server (never server-observed ENFORCING).",
-      "Add a CD step that runs: coderifts deploy-gate --env <env> --artifact <id> --receipt <file> --enforce",
-      "  (fail-closed by default; --enforce attests ENFORCING for inescapable_deploy. CODERIFTS_DEPLOY_ADVISORY=1 to soften.)",
+      "Add a CD step that runs: coderifts deploy-gate --env <env> --artifact <id> --receipt <file>",
+      "  (fail-closed by default. --enforce is a host claim, not inescapable_deploy.",
+      "   Prove pipeline protection with: coderifts enforce --check --repo owner/repo --env <env>.",
+      "   CODERIFTS_DEPLOY_ADVISORY=1 to soften the exit.)",
       "Also set policy.require_source_binding: true in .coderifts.yml for the deploy declaration leg."
     ].join("\n");
     var CONTENT_GUIDANCE = [
@@ -237067,6 +237619,15 @@ var require_enforce = __commonJS({
       }
     }
     async function runEnforce(options = {}, deps = {}) {
+      if (options.check === true) {
+        if (options.apply === true) {
+          const errLog2 = deps.errLog || console.error.bind(console);
+          errLog2(chalk.red("Error: --check is read-only evidence and cannot be combined with --apply"));
+          return { exitCode: 1, error: "check_apply_conflict", outcomes: [] };
+        }
+        const { runEnforceCheck } = require_enforce_check();
+        return runEnforceCheck(options, deps);
+      }
       const apply = options.apply === true;
       const getKey = deps.getApiKey || getApiKey;
       const fetchStatus = deps.cloudGetEnforcementStatus || cloudGetEnforcementStatus;
@@ -240058,12 +240619,13 @@ program.command("status [repo]").description("Show cross-layer enforcement statu
     process.exitCode = result.exitCode;
   }
 });
-program.command("enforce [repo]").description("Close enforcement gaps by chaining setup-required-check / hook / deploy guidance (dry-run default; use --apply to mutate)").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("--json", "Machine-readable JSON result").action(async (repoPositional, options) => {
+program.command("enforce [repo]").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_enforce();
   const result = await runEnforce({
     ...options,
     repo: options.repo || repoPositional || null,
-    apply: !!options.apply
+    apply: !!options.apply,
+    check: !!options.check
   });
   if (result && typeof result.exitCode === "number") {
     process.exitCode = result.exitCode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coderifts",
-  "version": "4.6.0",
+  "version": "4.7.0",
   "description": "Detect breaking API changes from the command line. Works locally or with the CodeRifts cloud API.",
   "author": "CodeRifts <hello@coderifts.com>",
   "license": "MIT",