clud-bug 0.7.0-rc.21 → 0.7.0-rc.23

package/src/cli/configure-github.ts

@@ -25,13 +25,23 @@ import { spawn, spawnSync } from 'node:child_process';
 import {
   applyCanonicalRuleset,
   loadCanonicalV1,
+  loadPreset,
+  isPresetName,
+  DEFAULT_PRESET,
+  PRESET_NAMES,
   type OctokitLike,
   type ApplyResult,
+  type PresetName,
 } from '../core/configure-github.js';
 
 export interface RunConfigureGithubOptions {
   /** "owner/repo" target — required. */
   target?: string | null;
+  /**
+   * Ruleset preset: baseline · clud-bug · skdd · public-guard.
+   * Defaults to `skdd`. Invalid values exit 2 (usage error).
+   */
+  preset?: string;
   /** Target branch (default `main`). */
   branch?: string;
   /** Render diff only; skip PATCH calls. */
@@ -50,13 +60,22 @@ export interface RunConfigureGithubOptions {
   stderr?: (msg: string) => void;
 }
 
-const HELP = `clud-bug configure-github — apply SPEC §7 canonical branch protection.
+const HELP = `clud-bug configure-github — one-stop repo setup (conveniences + SPEC §7 ruleset).
 
 Usage:
   clud-bug configure-github <owner>/<repo> [options]
 
+Applies, in order, for the selected preset:
+  1. Repo conveniences (ALL presets): squash-only merges, auto-merge +
+     delete-branch-on-merge on, PR title/body as the squash commit message.
+  2. The canonical branch ruleset for the chosen preset.
+
 Options:
-  --dry-run         Compute diff and print it, but do NOT call PATCH endpoints.
+  --preset <name>   Ruleset preset: baseline | clud-bug | skdd | public-guard.
+                    Default: skdd. (baseline = structural only; clud-bug adds
+                    the clud-bug-review gate; skdd adds SkDD derived-docs
+                    checks; public-guard = 1 approval + code-owner.)
+  --dry-run         Compute diff and print it, but do NOT create/update anything.
   --branch <name>   Target branch (default: main).
   --quiet,-q        Suppress progress chatter; emit only the final summary.
   --json            Emit the status payload as JSON (machine consumption).
@@ -68,7 +87,7 @@ Auth (resolved in order):
 
 Exit codes:
   0  success or already-canonical
-  1  auth missing, PATCH error, or unrecoverable transport failure
+  1  auth missing, ruleset write error, or unrecoverable transport failure
   2  CLI usage error (missing target, bad flag)
 `;
 
@@ -76,6 +95,8 @@ Exit codes:
 export interface ConfigureSummary {
   owner: string;
   repo: string;
+  /** The preset applied (baseline · clud-bug · skdd · public-guard). */
+  preset?: string;
   /** True when the repo already matches canonical-v1 (idempotent no-op). */
   alreadyCanonical: boolean;
   /** True when this was a --dry-run (no PATCH calls made). */
@@ -90,20 +111,22 @@ export interface ConfigureSummary {
  * consumption, key-colon-value for humans.
  */
 export function formatConfigureSummary(summary: ConfigureSummary, json: boolean): string {
-  const { owner, repo, alreadyCanonical, dryRun, changes } = summary;
+  const { owner, repo, preset, alreadyCanonical, dryRun, changes } = summary;
   if (json) {
     return (
-      JSON.stringify({ owner, repo, alreadyCanonical, rulesetVersion: 'v1', dryRun, changes }) + '\n'
+      JSON.stringify({ owner, repo, preset, alreadyCanonical, rulesetVersion: 'v2', dryRun, changes }) + '\n'
     );
   }
+  const presetTag = preset ? ` preset: ${preset}` : '';
+  const presetParen = preset ? ` (${preset})` : '';
   if (alreadyCanonical) {
-    return `ok configure-github: owner: ${owner} repo: ${repo} alreadyCanonical: true rulesetVersion: v1\n`;
+    return `ok configure-github: owner: ${owner} repo: ${repo}${presetTag} alreadyCanonical: true rulesetVersion: v2\n`;
   }
   const plural = changes === 1 ? '' : 's';
   if (dryRun) {
-    return `ok configure-github: dry-run on ${owner}/${repo} — ${changes} change${plural} pending\n`;
+    return `ok configure-github: dry-run on ${owner}/${repo}${presetParen} — ${changes} change${plural} pending\n`;
   }
-  return `ok configure-github: ${owner}/${repo} converged to canonical-v1 (${changes} change${plural})\n`;
+  return `ok configure-github: ${owner}/${repo} converged to canonical-v1${presetParen} (${changes} change${plural})\n`;
 }
 
 /**
@@ -117,6 +140,7 @@ export async function runConfigureGithub(
 ): Promise<number> {
   const {
     target,
+    preset: presetOpt,
     branch = 'main',
     dryRun = false,
     quiet = false,
@@ -140,6 +164,15 @@ export async function runConfigureGithub(
   }
   const [, owner, repo] = match as unknown as [unknown, string, string];
 
+  // Resolve + validate the preset (usage error before any network call).
+  const preset: string = presetOpt ?? DEFAULT_PRESET;
+  if (!isPresetName(preset)) {
+    stderr(
+      `clud-bug configure-github: unknown preset "${preset}" (valid: ${PRESET_NAMES.join(', ')}).\n`,
+    );
+    return 2;
+  }
+
   const token = await resolveToken();
   if (!token) {
     stderr(
@@ -151,7 +184,7 @@ export async function runConfigureGithub(
 
   if (!quiet) {
     stdout(
-      `\u{1F41B} configure-github: applying canonical-v1 ruleset to ${owner}/${repo} (branch=${branch})\n`,
+      `\u{1F41B} configure-github: applying "${preset}" preset (conveniences + ruleset) to ${owner}/${repo} (branch=${branch})\n`,
     );
   }
 
@@ -174,18 +207,19 @@ export async function runConfigureGithub(
       owner,
       repo,
       branch,
+      preset,
       dryRun,
     });
   } catch (err) {
     stderr(
-      `clud-bug configure-github: ${dryRun ? 'failed to read current state' : 'PATCH failed'}: ${stringifyError(err)}\n`,
+      `clud-bug configure-github: ${dryRun ? 'failed to read current state' : 'ruleset write failed'}: ${stringifyError(err)}\n`,
     );
     return 1;
   }
 
   if (result.alreadyCanonical) {
     if (!quiet) stdout('  No changes — repo already matches canonical-v1.\n');
-    stdout(formatConfigureSummary({ owner, repo, alreadyCanonical: true, dryRun, changes: 0 }, json));
+    stdout(formatConfigureSummary({ owner, repo, preset, alreadyCanonical: true, dryRun, changes: 0 }, json));
     return 0;
   }
 
@@ -196,11 +230,11 @@ export async function runConfigureGithub(
   }
 
   if (dryRun) {
-    stdout(formatConfigureSummary({ owner, repo, alreadyCanonical: false, dryRun: true, changes: result.changes.length }, json));
+    stdout(formatConfigureSummary({ owner, repo, preset, alreadyCanonical: false, dryRun: true, changes: result.changes.length }, json));
     return 0;
   }
 
-  stdout(formatConfigureSummary({ owner, repo, alreadyCanonical: false, dryRun: false, changes: result.changes.length }, json));
+  stdout(formatConfigureSummary({ owner, repo, preset, alreadyCanonical: false, dryRun: false, changes: result.changes.length }, json));
   return 0;
 }
 
@@ -242,9 +276,9 @@ export function ghCliOctokit(token: string): OctokitLike {
         args.push('--input', '-');
       }
       args.push(path);
-      // Add an Accept header so 404s return the structured error, not a
-      // friendlier shell hint. The wrapping err.message detection in
-      // `isBranchNotProtected` keys on the structured form.
+      // Pin the rulesets API media type; the wrapping error carries the
+      // parsed HTTP status (from `HTTP NNN` in gh's stderr) so transport
+      // failures surface with a real status code, not a shell hint.
       args.push('-H', 'Accept: application/vnd.github+json');
       const child = spawn('gh', args, {
         env,
@@ -289,26 +323,67 @@ export function ghCliOctokit(token: string): OctokitLike {
 
   return {
     repos: {
-      async getBranchProtection({ owner, repo, branch }) {
+      async getRepoRulesets({ owner, repo, includes_parents }) {
+        // `?per_page=100` (not `--paginate`) to grab all rulesets in one
+        // call — a repo realistically has a handful, and --paginate emits
+        // multiple concatenated JSON arrays that our single JSON.parse can't
+        // consume (see the v0.6.30 --paginate → ?per_page=100 decision).
+        const parents = includes_parents === undefined ? false : includes_parents;
         const data = await ghApi<unknown>(
           'GET',
-          `/repos/${owner}/${repo}/branches/${branch}/protection`,
+          `/repos/${owner}/${repo}/rulesets?per_page=100&includes_parents=${parents}`,
         );
-        return { data: data as Awaited<ReturnType<OctokitLike['repos']['getBranchProtection']>>['data'] };
+        return {
+          data: (Array.isArray(data) ? data : []) as Awaited<
+            ReturnType<OctokitLike['repos']['getRepoRulesets']>
+          >['data'],
+        };
       },
-      async updateBranchProtection({ owner, repo, branch, ...rest }) {
-        return ghApi(
-          'PUT',
-          `/repos/${owner}/${repo}/branches/${branch}/protection`,
-          rest,
+      async getRepoRuleset({ owner, repo, ruleset_id }) {
+        const data = await ghApi<unknown>(
+          'GET',
+          `/repos/${owner}/${repo}/rulesets/${ruleset_id}`,
         );
+        return {
+          data: data as Awaited<
+            ReturnType<OctokitLike['repos']['getRepoRuleset']>
+          >['data'],
+        };
       },
-      async get({ owner, repo }) {
+      async createRepoRuleset({ owner, repo, ...body }) {
         const data = await ghApi<unknown>(
-          'GET',
-          `/repos/${owner}/${repo}`,
+          'POST',
+          `/repos/${owner}/${repo}/rulesets`,
+          body,
+        );
+        return {
+          data: data as Awaited<
+            ReturnType<OctokitLike['repos']['createRepoRuleset']>
+          >['data'],
+        };
+      },
+      async updateRepoRuleset({ owner, repo, ruleset_id, ...body }) {
+        const data = await ghApi<unknown>(
+          'PUT',
+          `/repos/${owner}/${repo}/rulesets/${ruleset_id}`,
+          body,
         );
-        return { data: data as Awaited<ReturnType<OctokitLike['repos']['get']>>['data'] };
+        return {
+          data: data as Awaited<
+            ReturnType<OctokitLike['repos']['updateRepoRuleset']>
+          >['data'],
+        };
+      },
+      // Repo-level conveniences (universal hygiene): GET the repo settings,
+      // PATCH the drifted merge/branch-cleanup fields. Restored alongside the
+      // ruleset applier so `configure-github` is the one-stop setup command.
+      async get({ owner, repo }) {
+        const data = await ghApi<unknown>('GET', `/repos/${owner}/${repo}`);
+        return {
+          data: data as Awaited<
+            ReturnType<OctokitLike['repos']['get']>
+          >['data'],
+        };
       },
       async update({ owner, repo, ...rest }) {
         return ghApi('PATCH', `/repos/${owner}/${repo}`, rest);
@@ -323,7 +398,9 @@ function stringifyError(err: unknown): string {
 }
 
 /**
- * Re-exported so callers can preload the ruleset (e.g. for a `--show-ruleset`
- * flag in future). Currently exists for parity with the App's pattern.
+ * Re-exported so callers can preload a ruleset (e.g. for a `--show-ruleset`
+ * flag in future). `loadCanonicalV1` resolves the default (skdd) preset;
+ * `loadPreset(name)` picks a specific variant.
  */
-export { loadCanonicalV1 };
+export { loadCanonicalV1, loadPreset };
+export type { PresetName };

package/src/cli/hooks.ts

@@ -57,7 +57,11 @@ export function buildCommitReviewCommand(pin: string = 'next'): string {
     `if [ -n "$ev" ]; then case "$ev" in *'git commit'*|*'logmind log'*) ;; *) exit 0 ;; esac; fi`,
     `sha=$(git rev-parse HEAD 2>/dev/null) || exit 0`,
     `gitdir=$(git rev-parse --git-dir 2>/dev/null) || exit 0`,
-    `marker="$gitdir/clud-bug-last-commit-review"`,
+    // Pure LOOP-GUARD, not an attestation (§10.3.3): records only that the recipe
+    // was already SURFACED for this SHA (avoids a re-review on an amend / double
+    // fire). It never means "reviewed" and never yields a green check — the only
+    // authoritative "reviewed" state is the notary-issued `clud-bug-review` check.
+    `marker="$gitdir/clud-bug-hook-fired"`,
     `[ "$(cat "$marker" 2>/dev/null)" = "$sha" ] && exit 0`,
     // H4 — one retry on a transient npx/network blip (a stale lock, a slow
     // registry) before giving up, so a hiccup doesn't silently skip the review.

package/src/cli/main.ts

@@ -71,7 +71,7 @@ function parseArgs(argv) {
     withLocalReview: false,
     withHooks: false,
     // rc.16: `clud-bug init --with-design` installs the design-critic kit
-    // (3 `kind: design` skills) and flips the off-by-default `design` block to
+    // (4 `kind: design` skills) and flips the off-by-default `design` block to
     // enabled so the visual review lens runs (local recipe + hosted bot).
     withDesign: false,
     // rc.18: `clud-bug init --local-only` installs MAX MODE (skills + slash
@@ -82,8 +82,10 @@ function parseArgs(argv) {
     localOnly: false,
     // v0.7.0-rc.4: `clud-bug configure-github` flags.
     // --dry-run prints the diff but skips PATCH; --branch overrides "main".
+    // --preset selects the vendored ruleset variant (default: skdd).
     dryRun: false,
     branch: null,
+    preset: null,
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -112,6 +114,7 @@ function parseArgs(argv) {
     else if (a === '--local-only') args.localOnly = true;
     else if (a === '--dry-run') args.dryRun = true;
     else if (a === '--branch') args.branch = argv[++i];
+    else if (a === '--preset') args.preset = argv[++i];
     else if (a === '--trigger') args.trigger = argv[++i];
     else if (a === '--diff-size') args.diffSizeBytes = Number(argv[++i]);
     // H3: `clud-bug post-check-run` flags.
@@ -123,6 +126,8 @@ function parseArgs(argv) {
     else if (a === '--no-strict') args.strict = false;
     else if (a === '--owner') args.owner = argv[++i];
     else if (a === '--details-url') args.detailsUrl = argv[++i];
+    // Phase Z: notary attestation bundle (JSON path) for `post-check-run`.
+    else if (a === '--bundle') args.bundle = argv[++i];
     else args._.push(a);
   }
   return args;
@@ -145,11 +150,14 @@ Commands:
   update                Re-render workflows + refresh baseline specimens to the latest shipped
                         templates. Custom and skills.sh-installed specimens left alone.
   configure-github <owner>/<repo>
-                        Apply the SPEC §7 canonical branch protection ruleset to a repo.
-                        Auth: GITHUB_TOKEN env first, then \`gh auth token\`. Use
-                        --dry-run to print the diff without PATCH-ing; --branch to
-                        target a non-main branch. Idempotent — already-canonical
-                        repos exit 0 with no changes.
+                        One-stop repo setup: repo conveniences (squash-only merges,
+                        auto-merge, delete-branch-on-merge, PR title/body squash
+                        message — ALL presets) + the SPEC §7 canonical branch
+                        ruleset. \`--preset baseline|clud-bug|skdd|public-guard\`
+                        picks the variant (default: skdd). Auth: GITHUB_TOKEN env
+                        first, then \`gh auth token\`. Use --dry-run to print the
+                        diff without writing; --branch to target a non-main branch.
+                        Idempotent — already-canonical repos exit 0 with no changes.
   edit-workflow         Helper for editing .github/workflows/clud-bug-*.yml in an isolated
                         PR (the action refuses to review PRs that modify its own workflow).
   usage                 Read recent clud-bug-review run JSON + normalize cost per LOC.
@@ -223,6 +231,10 @@ Commands:
                         clean|critical|failed --sha <sha> [--critical-count N]
                         [--source local|ci] [--strict|--no-strict] [--dry-run].
                         clean→success, critical+strict→failure, else neutral.
+                        With CLUD_BUG_NOTARY_URL set + --bundle <file>, submits a
+                        notary attestation bundle instead (Phase Z); the notary
+                        issues the check. Falls back to the self-attested post if
+                        the endpoint is unreachable.
 
 Options:
   --offline             Skip skills.sh; pin only the bundled baseline specimens.
@@ -237,7 +249,7 @@ Options:
                         \`git commit\` / \`logmind log\`, it fetches a review recipe and
                         surfaces it to the agent (on this session's subscription)
                         via asyncRewake. Implies --with-local-review. Off by default.
-  --with-design         (init) Install the design-critic kit (3 \`kind: design\`
+  --with-design         (init) Install the design-critic kit (4 \`kind: design\`
                         skills) and enable the off-by-default visual review
                         lens — renders changed UI and critiques it. Off by default.
   --local-only          (init) MAX MODE: install the slash command + commit hook
@@ -253,9 +265,11 @@ Options:
                         required_conversation_resolution on the default
                         branch (init only). Use for repos that manage
                         branch protection via ruleset or org policy.
-  --dry-run             Print the canonical-v1 diff without PATCH-ing
+  --dry-run             Print the canonical-v1 diff without writing
                         (configure-github only).
   --branch <name>       Target branch for configure-github (default: main).
+  --preset <name>       configure-github ruleset preset: baseline | clud-bug |
+                        skdd | public-guard (default: skdd).
   --trigger <ctx>       review-prompt context: commit (default) | push | pr.
   --repo <owner/name>   Restrict \`usage\` to a single repo. Default: all repos
                         with clud-bug-review.yml in the gh user's auth scope.
@@ -1380,7 +1394,7 @@ async function runInit(args) {
     }
   }
 
-  // rc.16: --with-design installs the bundled design-critic kit (3 `kind:
+  // rc.16: --with-design installs the bundled design-critic kit (4 `kind:
   // design` skills) and enables the off-by-default design lens. writeSkills
   // writes the SKILL.md files + merges the manifest entries; the `design` block
   // is flipped on the manifest read below so the local recipe + hosted bot both
@@ -1498,6 +1512,13 @@ async function runInit(args) {
   }
   log('  • Opt out by setting "strictMode": false in .claude/skills/.clud-bug.json.');
 
+  // Phase M — a quiet, on-voice support nudge for the free tiers (max mode +
+  // self-hosted Action run on the user's own resources; no metered charge fits).
+  // The GitHub "Sponsor" button + the Stripe "coffee" link both live in FUNDING.yml.
+  log('');
+  log('clud-bug forages on your own subscription — free, and meant to stay that way.');
+  log('If the specimens earn their keep, you can feed the bug: github.com/sponsors/thrillmade');
+
   // v0.6.33 — opt-in unified install (mirror of logmind v0.6.8). When
   // --with-skdd is passed, subprocess to `pip install logmind` + `logmind init`
   // so Node-first users get the same one-command bootstrap as Python-first
@@ -1967,13 +1988,14 @@ async function runUpdateCmd(_args) {
 // SPEC §7 canonical ruleset applier from src/cli/configure-github.ts;
 // thin wrapper here just maps CLI args into the typed entry point. The
 // command is idempotent — re-runs on a converged repo exit 0 with no
-// PATCH calls. See `src/core/configure-github.ts` for the diff + rule
+// create/update calls. See `src/core/configure-github.ts` for the diff + rule
 // table.
 async function runConfigureGithubCmd(args) {
   const { runConfigureGithub } = await import('./configure-github.js');
   const target = args._[1] ?? null;
   const code = await runConfigureGithub({
     target,
+    preset: args.preset || undefined,
     branch: args.branch || 'main',
     dryRun: Boolean(args.dryRun),
     quiet: QUIET,

package/src/cli/post-check-run.ts

@@ -3,7 +3,7 @@
 // merge on those surfaces too (the hosted bot already posts it).
 //
 // Usage:
-//   clud-bug post-check-run --sha <sha> --verdict clean|critical|failed \
+//   clud-bug post-check-run --sha <sha> --verdict clean|critical|failed|unverified \
 //     [--critical-count N] [--source local|ci] [--strict|--no-strict] \
 //     [--owner O --repo R] [--details-url URL] [--dry-run]
 //
@@ -14,8 +14,20 @@
 
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
 
-import { deriveCheck, normalizeVerdict, CLUD_BUG_CHECK_NAME } from '../core/index.js';
+import {
+  deriveCheck,
+  normalizeVerdict,
+  CLUD_BUG_CHECK_NAME,
+  parseBundle,
+  validateBundle,
+  validateConsistency,
+  splitUnifiedDiff,
+  notaryResponseIsRejection,
+  type NotaryBundle,
+  type DiffFile,
+} from '../core/index.js';
 import { readManifest } from './skills.js';
 
 interface PostCheckRunArgs {
@@ -27,6 +39,8 @@ interface PostCheckRunArgs {
   owner?: string;
   repo?: string;
   detailsUrl?: string;
+  /** Path to a notary attestation bundle (JSON). Activates the notary submit path. */
+  bundle?: string;
   dryRun?: boolean;
   cwd?: string;
   _?: string[];
@@ -37,6 +51,115 @@ function sh(cmd: string, cmdArgs: string[], input?: string): { ok: boolean; out:
   return { ok: r.status === 0, out: (r.stdout ?? '').trim(), err: (r.stderr ?? '').trim() };
 }
 
+/**
+ * Best-effort load of the diff a bundle attests to, as `DiffFile[]`, for the
+ * LOCAL pre-check. Prefers the PR diff (matches GitHub's view); falls back to
+ * the commit diff. Returns `[]` when neither is obtainable — the caller then
+ * skips the diff-dependent checks (③④) and lets the SERVER do the authoritative
+ * validation against GitHub's ground truth (Z4).
+ */
+function loadDiffFiles(bundle: NotaryBundle): DiffFile[] {
+  let raw = '';
+  if (bundle.pr !== undefined) {
+    const r = sh('gh', ['pr', 'diff', String(bundle.pr), '--color', 'never']);
+    if (r.ok) raw = r.out;
+  }
+  if (!raw && bundle.head_sha) {
+    // -c core.quotepath=false → git emits non-ASCII paths as literal UTF-8
+    // (no octal quoting), so the splitter sees real filenames.
+    const r = sh('git', ['-c', 'core.quotepath=false', 'show', '--no-color', '--format=', bundle.head_sha]);
+    if (r.ok) raw = r.out;
+  }
+  return raw ? splitUnifiedDiff(raw) : [];
+}
+
+type NotaryOutcome = 'posted' | 'rejected' | 'fallback';
+
+interface NotaryResult {
+  outcome: NotaryOutcome;
+  /** The parsed + locally-validated bundle, when we got that far (for a bundle-derived fallback). */
+  bundle: NotaryBundle | null;
+}
+
+/**
+ * The notary submit path (Phase Z). Reads + parses the bundle, LOCALLY
+ * re-validates it (the handshake — a deterministic program refusing to certify
+ * an inconsistent/ungrounded review), then POSTs to the notary. The server (Z4)
+ * re-validates ①–⑤ against GitHub and — as SOLE issuer — posts the pinned check.
+ *
+ * Outcomes:
+ *   'posted'   — the notary accepted; the SERVER owns the check, do not self-post.
+ *   'rejected' — the certification is definitively refused (malformed / inconsistent /
+ *                ungrounded bundle, OR a server 4xx AUTHORITATIVELY declining). Post
+ *                NO check — never a false green off a bad artifact or over a server "no".
+ *   'fallback' — the endpoint is DOWN (network error or 5xx), not a verdict; the caller
+ *                may self-post the self-attested check (derived from THIS bundle) so local
+ *                max mode keeps gating while Z4 is pending.
+ */
+async function submitToNotary(
+  notaryUrl: string,
+  bundlePath: string,
+  warn: (m: string) => void,
+): Promise<NotaryResult> {
+  let bundle: NotaryBundle | null;
+  try {
+    bundle = parseBundle(JSON.parse(await readFile(bundlePath, 'utf8')));
+  } catch (e) {
+    warn(`could not read the bundle at ${bundlePath} (${e instanceof Error ? e.message : String(e)}); not certifying.`);
+    return { outcome: 'rejected', bundle: null };
+  }
+  if (!bundle) {
+    warn(`the bundle at ${bundlePath} is malformed; not certifying (fix the review artifact).`);
+    return { outcome: 'rejected', bundle: null };
+  }
+
+  // Local pre-check: consistency is diff-free (always run); coverage + grounding
+  // need the diff (run only when one is obtainable — else defer to the server).
+  const diffFiles = loadDiffFiles(bundle);
+  const consistency = validateConsistency(bundle.verdict, bundle.findings);
+  if (!consistency.ok) {
+    warn(`bundle is internally inconsistent — ${consistency.reason}; not certifying.`);
+    return { outcome: 'rejected', bundle };
+  }
+  if (diffFiles.length > 0) {
+    const v = validateBundle(bundle, diffFiles);
+    if (!v.coverage.ok) {
+      warn(`bundle coverage is incomplete — unreviewed changed file(s): ${v.coverage.missingFiles.join(', ')}; not certifying.`);
+      return { outcome: 'rejected', bundle };
+    }
+    if (!v.grounding.ok) {
+      warn(`bundle has ungrounded critical finding(s): ${v.grounding.violations.map((x) => x.reason).join('; ')}; not certifying.`);
+      return { outcome: 'rejected', bundle };
+    }
+  }
+
+  // Submit. TODO(Z4): the server mints/consumes the nonce, re-fetches GitHub's
+  // ground-truth diff, re-runs ①–⑤, signs, and posts the pinned check.
+  const url = notaryUrl.replace(/\/+$/, '') + '/notarize';
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(bundle),
+    });
+    if (res.ok) {
+      process.stdout.write(`clud-bug: notarized ${bundle.repo}@${bundle.head_sha.slice(0, 12)} (verdict=${bundle.verdict}); the notary posts the check.\n`);
+      return { outcome: 'posted', bundle };
+    }
+    // A 4xx is the SOLE issuer authoritatively declining — terminal, no check.
+    // Only a 5xx (server down) is a fallback-able outage.
+    if (notaryResponseIsRejection(res.status)) {
+      warn(`notary declined the bundle (HTTP ${res.status}); not certifying.`);
+      return { outcome: 'rejected', bundle };
+    }
+    warn(`notary unavailable (HTTP ${res.status}); falling back to the self-attested check.`);
+    return { outcome: 'fallback', bundle };
+  } catch (e) {
+    warn(`notary endpoint unreachable (${e instanceof Error ? e.message : String(e)}); falling back to the self-attested check.`);
+    return { outcome: 'fallback', bundle };
+  }
+}
+
 export async function runPostCheckRun(args: PostCheckRunArgs): Promise<void> {
   const cwd = args.cwd ?? process.cwd();
   const warn = (m: string) => process.stderr.write(`clud-bug post-check-run: ${m}\n`);
@@ -49,6 +172,21 @@ export async function runPostCheckRun(args: PostCheckRunArgs): Promise<void> {
     sha = r.out;
   }
 
+  // --- Notary submit path (Phase Z) — the un-forgeable route -------------
+  // When CLUD_BUG_NOTARY_URL is set and a --bundle is supplied, submit an
+  // attestation bundle: the CLI locally re-checks it (the handshake) and the
+  // notary (Z4) issues the pinned check. Only 'fallback' (endpoint unreachable)
+  // continues to the self-attested self-post below; 'posted'/'rejected' are terminal.
+  let fallbackBundle: NotaryBundle | null = null;
+  const notaryUrl = process.env.CLUD_BUG_NOTARY_URL?.trim();
+  if (notaryUrl && typeof args.bundle === 'string' && args.bundle && !args.dryRun) {
+    const { outcome, bundle } = await submitToNotary(notaryUrl, args.bundle, warn);
+    if (outcome !== 'fallback') return;
+    // Endpoint down → self-post below, derived from the ALREADY-VALIDATED bundle
+    // (not the raw --verdict flags, which a bundle-only invocation never passes).
+    fallbackBundle = bundle;
+  }
+
   // --- strictMode: explicit flag wins, else the repo manifest -----------
   let strictMode = false;
   if (typeof args.strict === 'boolean') {
@@ -62,9 +200,15 @@ export async function runPostCheckRun(args: PostCheckRunArgs): Promise<void> {
     }
   }
 
-  const verdict = normalizeVerdict(typeof args.verdict === 'string' ? args.verdict : undefined);
-  const criticalCount = Number(args.criticalCount ?? 0) || 0;
-  const source = args.source === 'local' ? 'local' : 'ci';
+  // A bundle-fallback self-post reflects what was actually VALIDATED (bundle
+  // verdict + its critical count, local source); otherwise the raw flags.
+  const verdict = fallbackBundle
+    ? fallbackBundle.verdict
+    : normalizeVerdict(typeof args.verdict === 'string' ? args.verdict : undefined);
+  const criticalCount = fallbackBundle
+    ? fallbackBundle.findings.filter((f) => f.severity === 'critical').length
+    : Number(args.criticalCount ?? 0) || 0;
+  const source: 'local' | 'ci' = fallbackBundle ? 'local' : args.source === 'local' ? 'local' : 'ci';
   const { conclusion, title, summary } = deriveCheck({ verdict, strictMode, criticalCount, source });
 
   // --- resolve owner/repo (flags, else gh) ------------------------------