@vodmal/vdx-cli 0.31.2 → 0.32.0

package/README.md

@@ -48,7 +48,7 @@ vdx publish <patch|minor|major> [--dry-run] [--force] [--no-push]
 # Push the branch; one that requires checks on GitHub takes the commit once they pass
 vdx push [project-path] [--dry-run]   # default: cwd
 
-# Environment self-check (Node / git / mise / npm auth / docker / Claude Code plugin; git hooks of the project)
+# Environment self-check (Node / git / mise / npm auth / docker / Claude Code plugin; git hooks of the project; the GitHub token vdx asks with)
 vdx doctor [project-path] [--format=ansi|markdown|json]   # default: cwd
 vdx doctor --check [project-path]   # one line per hook declared but not running here — the plugin's SessionStart hook tells the agent
 vdx doctor --fix                    # write the profile's personal hooks (git.hooks) into ~/.gitconfig

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vodmal/vdx-cli",
-  "version": "0.31.2",
+  "version": "0.32.0",
   "description": "vdx — unified lifecycle interface (up/down/build/test/check/fix) + versioned maturity audit with drift detection. Pairs with the vdx Claude Code plugin.",
   "keywords": [
     "vdx",

package/src/ai.ts

@@ -762,7 +762,7 @@ export function sleepSync(ms: number): void {
 }
 
 /** Read one line from the terminal, synchronously: the prompt runs before tmux takes it. */
-function askLine(prompt: string): string | null {
+export function askLine(prompt: string): string | null {
   process.stderr.write(prompt);
   const buf = Buffer.alloc(256);
   let text = '';

package/src/audit.ts

@@ -137,7 +137,7 @@ export function audit(
       });
       continue;
     }
-    const { achieved, not_required, unknown } = evalAxisDetailed(axis, evalCtx);
+    const { achieved, not_required, unknown, not_met } = evalAxisDetailed(axis, evalCtx);
     const ov = overrideByAxis.get(axis.id);
     const target = (ov?.target as LevelName) ?? axis.default_target;
     const drift: 'aligned' | 'gap' | 'over' =
@@ -156,6 +156,7 @@ export function audit(
     if (ov?.target) entry.override_target = ov.target as LevelName;
     if (not_required) entry.not_required = not_required;
     if (unknown) entry.unknown = unknown;
+    if (not_met) entry.not_met = not_met;
     if (axis.clone_check) {
       const c = cloneCheck(axis.clone_check, ctx.projectRoot);
       if (c && c.status !== 'ok') entry.note = c.remedy ? `${c.message} → ${c.remedy}` : c.message;

package/src/doctor.ts

@@ -3,10 +3,11 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
-import { effectiveAuthor, isGitRepo, rankAuthors, scanPool } from './author.ts';
+import { effectiveAuthor, isGitRepo, rankAuthors, remoteParts, scanPool } from './author.ts';
 import { authorPoolDirs, loadEnvironment, resolveEnvironmentPath, shellQuote, type Environment } from './ai.ts';
 import { checkRepoHooks } from './clone-checks.ts';
-import { at, dict } from './narrow.ts';
+import { githubToken, machineIo, type HostingIo } from './hosting.ts';
+import { at, dict, errorMessage, str } from './narrow.ts';
 import {
   checkPersonalHooks,
   defaultPersonalHookDeps,
@@ -417,6 +418,61 @@ export function checkGitAuthor(ctx: DoctorCtx): CheckResult | null {
   };
 }
 
+/**
+ * The token vdx asks GitHub with, for a repository whose origin is there — the audit
+ * (`branch-protection`) and `vdx push` ask. Without one GitHub answers 60 requests an
+ * hour; a token that no longer works is worse than none: every answer is a 401.
+ * `/rate_limit` tells both apart and costs nothing of the limit.
+ */
+export function checkGithubToken(
+  ctx: DoctorCtx,
+  io: HostingIo | null = ctx.projectRoot ? machineIo(ctx.projectRoot) : null,
+  ghOnPath: boolean = findOnPath('gh') !== null,
+  platform: NodeJS.Platform = process.platform,
+): CheckResult | null {
+  if (ctx.projectRoot === null || io === null) return null;
+  const url = io.git(['remote', 'get-url', 'origin']);
+  if (!url || remoteParts(url).host !== 'github.com') return null;
+  const id = 'github-token';
+  const label = 'GitHub token';
+  if (io.env.VDX_OFFLINE) return { id, label, status: 'ok', message: 'VDX_OFFLINE is set — vdx does not ask GitHub' };
+  const t = githubToken(io);
+  let status: number;
+  let body: unknown;
+  try {
+    ({ status, body } = io.get('/rate_limit', t?.token ?? null));
+  } catch (e) {
+    return { id, label, status: 'warning', message: `GitHub did not answer: ${errorMessage(e)}` };
+  }
+  if (status === 401 && t) {
+    return {
+      id,
+      label,
+      status: 'warning',
+      message: `the token from ${t.source} does not work (GitHub: ${str(at(body, 'message')) ?? '401'}) — every answer is a 401`,
+      remedy: t.source === 'gh' ? 'gh auth login -h github.com' : `a working ${t.source}, or unset it`,
+    };
+  }
+  if (status !== 200) return { id, label, status: 'warning', message: `GitHub answered ${status} for /rate_limit` };
+  const limit = at(body, 'resources', 'core', 'limit');
+  const left = at(body, 'resources', 'core', 'remaining');
+  const hour = typeof limit === 'number' ? `${limit} requests an hour` : 'its limit';
+  const remaining = typeof left === 'number' ? `, ${left} left` : '';
+  if (t) return { id, label, status: 'ok', message: `from ${t.source}: ${hour}${remaining}` };
+  return {
+    id,
+    label,
+    status: 'warning',
+    message: `none — GitHub answers ${hour} without one${remaining}; an audit takes about 3, vdx push about 10`,
+    remedy: !ghOnPath
+      ? 'install gh (https://cli.github.com) and gh auth login, or set GH_TOKEN'
+      : io.env.SSH_CONNECTION && platform === 'darwin'
+        ? // m3, 2026-10-19: logged in, and `ssh m3 gh` saw no token, while tmux there did.
+          'over ssh gh cannot read the macOS keychain where it keeps the token — in a local terminal or tmux it can; else gh auth login -h github.com'
+        : 'gh auth login -h github.com',
+  };
+}
+
 const CHECKS: Array<(ctx: DoctorCtx) => CheckResult | null> = [
   checkVdxVersion,
   checkVdx,
@@ -430,6 +486,7 @@ const CHECKS: Array<(ctx: DoctorCtx) => CheckResult | null> = [
   (ctx) => checkRepoHooks(ctx.projectRoot),
   (ctx) => checkPersonalHooks(ctx.projectRoot),
   checkGitAuthor,
+  (ctx) => checkGithubToken(ctx),
 ];
 
 export function resolveDoctorCtx(cwd: string = process.cwd()): DoctorCtx {

package/src/evaluator.ts

@@ -1,6 +1,6 @@
 import type { Predicate } from './rubric.ts';
 import type { Ctx } from './facts.ts';
-import { REGISTRY, isUnknown, type Args, type Unknown, type Verdict } from './predicates.ts';
+import { REGISTRY, isFalse, isNo, isUnknown, type Args, type No, type Unknown, type Verdict } from './predicates.ts';
 import { at, isDict, list } from './narrow.ts';
 
 export { isUnknown, type Verdict };
@@ -25,6 +25,11 @@ function firstUnknown(vs: Verdict[]): Unknown | undefined {
   return vs.find(isUnknown);
 }
 
+/** Not met, with the first reason a branch gave, if one did. */
+function no(vs: Verdict[]): false | No {
+  return vs.find(isNo) ?? false;
+}
+
 /**
  * Three-valued: true, false, or unknown with the reason the fact could not be
  * read (a CI system or a hosting vdx does not inspect). Unknown never turns
@@ -40,13 +45,13 @@ export function evalVerdict(p: Predicate, ctx: Ctx): Verdict {
 
     if ('all_of' in obj) {
       const vs = list(obj['all_of']).map((q) => evalVerdict(q, ctx));
-      if (vs.some((v) => v === false)) return false;
+      if (vs.some(isFalse)) return no(vs);
       return firstUnknown(vs) ?? true;
     }
     if ('any_of' in obj) {
       const vs = list(obj['any_of']).map((q) => evalVerdict(q, ctx));
       if (vs.some((v) => v === true)) return true;
-      return firstUnknown(vs) ?? false;
+      return firstUnknown(vs) ?? no(vs);
     }
     if ('at_least_n_of' in obj) {
       const { n, predicates } = obj['at_least_n_of'] as { n: number; predicates: Predicate[] };
@@ -54,12 +59,12 @@ export function evalVerdict(p: Predicate, ctx: Ctx): Verdict {
       const matched = vs.filter((v) => v === true).length;
       if (matched >= n) return true;
       const open = vs.filter(isUnknown).length;
-      if (matched + open < n) return false;
+      if (matched + open < n) return no(vs);
       return firstUnknown(vs)!;
     }
     if ('not' in obj) {
       const v = evalVerdict(obj['not'], ctx);
-      return isUnknown(v) ? v : !v;
+      return isUnknown(v) ? v : v !== true;
     }
     if ('fn' in obj) {
       const name = String(obj['fn']);

package/src/hosting.ts

@@ -115,13 +115,25 @@ function judge(io: HostingIo, repo: string, token: string | null): Verdict {
   const refusedBranch = refusal(b, repo, token);
   if (refusedBranch) return refusedBranch;
   const classic = at(b.body, 'protection', 'required_status_checks');
-  if (at(classic, 'enforcement_level') === 'everyone' && checkCount(classic) > 0) return true;
+  const level = at(classic, 'enforcement_level');
+  const named = checkCount(classic) > 0;
+  if (level === 'everyone' && named) return true;
+  // Why not, for the report (DL #11): what classic protection lacks.
+  const classicWhy =
+    at(b.body, 'protected') !== true
+      ? `${branch} is not protected`
+      : level === 'non_admins' && named
+        ? `${branch} requires checks of everyone but admins — and an agent pushes as its owner, an admin (DL #3)`
+        : level === 'everyone'
+          ? `${branch} is protected, but names no check it requires`
+          : `${branch} is protected without required checks`;
 
   // Rulesets: a rule that requires checks, in a ruleset nobody bypasses.
   const rules = io.get(`/repos/${repo}/rules/branches/${ref}`, token);
   const refusedRules = refusal(rules, repo, token);
   if (refusedRules) return refusedRules;
   let hidden = false;
+  let bypassers = 0;
   for (const rule of list(rules.body)) {
     if (at(rule, 'type') !== 'required_status_checks') continue;
     if (list(at(rule, 'parameters', 'required_status_checks')).length === 0) continue;
@@ -130,13 +142,19 @@ function judge(io: HostingIo, repo: string, token: string | null): Verdict {
     const bypass = ruleset?.status === 200 ? at(ruleset.body, 'bypass_actors') : undefined;
     if (!Array.isArray(bypass)) hidden = true;
     else if (bypass.length === 0) return true;
+    else bypassers = Math.max(bypassers, bypass.length);
   }
   if (hidden) {
     return {
       unknown: `a ruleset requires checks on ${branch}, but GitHub shows who bypasses it only to ${token ? 'a repository admin' : 'a token; gh auth login, or GH_TOKEN'}`,
     };
   }
-  return false;
+  return {
+    no:
+      bypassers > 0
+        ? `${classicWhy}; a ruleset requires checks, but ${bypassers} actor(s) may bypass it`
+        : `${classicWhy}, and no ruleset requires checks`,
+  };
 }
 
 /**
@@ -170,7 +188,15 @@ export function githubRepo(io: HostingIo, remote: string): { repo: string; token
   // The host only: a URL can carry a token.
   if (host !== 'github.com')
     return { unknown: `${remote} is on ${host || 'a host vdx cannot tell'} — vdx reads GitHub only` };
-  return { repo, token: io.env.GH_TOKEN || io.env.GITHUB_TOKEN || io.ghToken() };
+  return { repo, token: githubToken(io)?.token ?? null };
+}
+
+/** The token vdx asks GitHub with and where it comes from — `GH_TOKEN`, `GITHUB_TOKEN`, then gh, as gh itself picks. */
+export function githubToken(io: HostingIo): { token: string; source: 'GH_TOKEN' | 'GITHUB_TOKEN' | 'gh' } | null {
+  if (io.env.GH_TOKEN) return { token: io.env.GH_TOKEN, source: 'GH_TOKEN' };
+  if (io.env.GITHUB_TOKEN) return { token: io.env.GITHUB_TOKEN, source: 'GITHUB_TOKEN' };
+  const gh = io.ghToken();
+  return gh ? { token: gh, source: 'gh' } : null;
 }
 
 function isUnknownRepo(v: { repo: string } | Unknown): v is Unknown {

package/src/index.ts

@@ -35,7 +35,7 @@ import {
 } from './publish.ts';
 import { resolveDefaultRubric } from './defaults.ts';
 import { defaultGateDeps, GATE_PREFIX, planGate, pushThroughGate } from './gate.ts';
-import { runAi, runAiCheck, runAiRemote, defaultDeps, hostLabel, REMOTE_HOST_RE } from './ai.ts';
+import { askLine, runAi, runAiCheck, runAiRemote, defaultDeps, hostLabel, REMOTE_HOST_RE } from './ai.ts';
 import { isConversationId } from './conversations.ts';
 
 const DEFAULT_RUBRIC = resolveDefaultRubric();
@@ -156,7 +156,10 @@ mise.toml is overwritten only with --force.
   git commit and tag, then \`git push --follow-tags\` to the branch's upstream —
   through its checks when it requires some, as \`vdx push\` does: the pre-flight
   then refuses local commits not pushed yet, npm would get them before CI;
-  a wait until the registry shows the new version (up to 3 min).
+  a wait until the registry shows the new version (up to 10 min from npm publish;
+  Ctrl-C there stops only the wait).
+Nothing in the package's directory changed since the tag of its version: the
+same package under a new number — at a terminal a question, Enter releases nothing.
 --dry-run runs the pre-flight and prints the plan; --force goes on past a failed
 pre-flight; --no-push leaves the commit and the tag local.
 `,
@@ -193,7 +196,9 @@ or GitHub stopped answering; a plain git push exits with git's own code.
     help: `Checks this machine for what vdx needs (Node, git, mise, npm auth, docker, the
 Claude Code plugin) and, inside a project (default: cwd), its commit author and
 its git hooks: are the hooks the repository declares on in this clone, and do
-the personal hooks of your profile (git.hooks) run on this machine. Reads only.
+the personal hooks of your profile (git.hooks) run on this machine; with origin on
+GitHub, the token vdx asks GitHub with ($GH_TOKEN, $GITHUB_TOKEN or gh) and
+whether it works — without one GitHub answers 60 requests an hour. Reads only.
 Exit 2 when something is missing.
 
   --check  for the agent's own session (the vdx plugin's SessionStart hook): one
@@ -438,7 +443,8 @@ function cmdPublish(opts: ParsedArgs): void {
   const deps = defaultPublishDeps();
   const interactive = process.stdin.isTTY === true && process.stdout.isTTY === true;
   if (!plan.preflightPassed && !planOpts.force && interactive && preflightFixable(plan)) {
-    for (const c of plan.preflight.filter((c) => !c.ok && c.fix)) {
+    const fixes = plan.preflight.filter((c) => !c.ok && c.fix);
+    for (const c of fixes) {
       process.stderr.write(`\n→ ${c.name}: ${c.fix!.cmd} ${c.fix!.args.join(' ')}\n`);
       try {
         deps.run(c.fix!.cmd, c.fix!.args, projectRoot);
@@ -447,11 +453,27 @@ function cmdPublish(opts: ParsedArgs): void {
         process.exit(2);
       }
     }
-    plan = replan();
-    process.stdout.write('\n' + renderPublishPlan(plan));
+    if (fixes.length > 0) {
+      plan = replan();
+      process.stdout.write('\n' + renderPublishPlan(plan));
+    }
+  }
+
+  // A failure the person may waive (nothing changed since the release): a question, Enter no.
+  let waived = false;
+  const left = plan.preflight.filter((c) => !c.ok);
+  if (!planOpts.force && interactive && left.length > 0 && left.every((c) => c.waive)) {
+    for (const c of left) {
+      process.stderr.write(`\n${c.name}: ${c.message}\n`);
+      if (!/^y(es)?$/i.test(askLine(c.waive!) ?? '')) {
+        process.stderr.write('nothing released\n');
+        process.exit(2);
+      }
+    }
+    waived = true;
   }
 
-  if (!plan.preflightPassed && !planOpts.force) {
+  if (!plan.preflightPassed && !planOpts.force && !waived) {
     process.stderr.write('\nerror: pre-flight failed (use --force to bypass)\n');
     process.exit(2);
   }

package/src/predicates.ts

@@ -24,11 +24,24 @@ export type Args = Record<string, unknown>;
 export interface Unknown {
   unknown: string;
 }
-export type Verdict = boolean | Unknown;
+/** Not met, and why — from a predicate that knows (DL #11 of docs/tasks/hosting-extension). */
+export interface No {
+  no: string;
+}
+export type Verdict = boolean | Unknown | No;
 type PredicateFn = (args: Args, ctx: Ctx) => Verdict;
 
 export function isUnknown(v: Verdict): v is Unknown {
-  return typeof v === 'object' && v !== null;
+  return typeof v === 'object' && v !== null && 'unknown' in v;
+}
+
+export function isNo(v: Verdict): v is No {
+  return typeof v === 'object' && v !== null && 'no' in v;
+}
+
+/** Not met: `false`, or `false` with its reason. */
+export function isFalse(v: Verdict): v is false | No {
+  return v === false || isNo(v);
 }
 
 /**

package/src/publish.ts

@@ -24,6 +24,8 @@ export interface PreflightCheck {
   message: string;
   /** A failed check a command at the terminal can fix — `npm login` for an expired session. */
   fix?: { cmd: string; args: string[] };
+  /** A failed check the person at the terminal may waive: the question, Enter answering no. */
+  waive?: string;
 }
 
 /** Where the release goes after the tag. */
@@ -311,6 +313,9 @@ export function planPublish(
   });
 
   preflight.push(checkNpmAuth(publishRegistry(pkg, npm), npm));
+  preflight.push(
+    checkChangesSinceRelease(opts.projectRoot, path.dirname(pkgJsonPath), currentVersion, newVersion, git),
+  );
 
   let published: string | null = null;
   let registryError: string | null = null;
@@ -397,10 +402,50 @@ export function planPublish(
   };
 }
 
-/** Every failed check has a command that fixes it — run at a terminal, then plan again. */
+/**
+ * Anything to release? 0.30.0 went out on 2026-10-18 with nothing since v0.29.0 but
+ * its release commit (hosting-extension Sidetrack #6). Nothing in the package's
+ * directory since the tag of the current version — the same package under a new
+ * number; a terminal asks, Enter answering no.
+ */
+export function checkChangesSinceRelease(
+  projectRoot: string,
+  packageDir: string,
+  current: string,
+  next: string,
+  git: GitRunner,
+): PreflightCheck {
+  const name = 'changes-since-release';
+  const tag = `v${current}`;
+  try {
+    git(['rev-parse', '--verify', '--quiet', `refs/tags/${tag}`], projectRoot);
+  } catch {
+    return { name, ok: true, message: `OK (no tag ${tag} to compare with)` };
+  }
+  const where = path.relative(projectRoot, packageDir) || '.';
+  const shown = where === '.' ? `${path.basename(packageDir)}/` : `${where}/`;
+  let count: number;
+  try {
+    count = parseInt(git(['rev-list', '--count', `${tag}..HEAD`, '--', where], projectRoot).trim(), 10) || 0;
+  } catch {
+    return { name, ok: true, message: `OK (git could not compare with ${tag})` };
+  }
+  if (count > 0) return { name, ok: true, message: `OK (${count} commit(s) in ${shown} since ${tag})` };
+  return {
+    name,
+    ok: false,
+    message: `nothing in ${shown} has changed since ${tag}: ${next} would be the package ${current} is`,
+    waive: `Release ${next} anyway, the same package under a new number? [y/N] `,
+  };
+}
+
+/**
+ * Every failed check is resolved at a terminal: a command that fixes it (run, then
+ * plan again) or a question the person may answer yes to.
+ */
 export function preflightFixable(plan: PublishPlan): boolean {
   const failed = plan.preflight.filter((c) => !c.ok);
-  return failed.length > 0 && failed.every((c) => c.fix);
+  return failed.length > 0 && failed.every((c) => c.fix || c.waive);
 }
 
 /** Runs a command on this terminal (stdio inherited); throws on a non-zero exit. */
@@ -431,7 +476,7 @@ export function defaultPublishDeps(): PublishDeps {
     npm: runNpm,
     log: (line) => process.stderr.write(line + '\n'),
     sleep: sleepSync,
-    registryWaitMs: 180_000,
+    registryWaitMs: 10 * 60_000,
     progress: process.stderr.isTTY ? (text) => process.stderr.write(`\r${text}\x1b[K`) : undefined,
     gatePush: (target, projectRoot) => pushThroughGate(target, defaultGateDeps(projectRoot)),
   };
@@ -447,19 +492,22 @@ export function bumpLockText(text: string, version: string): string {
 }
 
 /**
- * npm answers `202 Accepted` and the version shows up a minute or two later;
- * until then `npm view` and `npx` still see the previous one. Waiting here
- * turns "is it out?" into an answer. A version that does not show up in time
- * is not a failure: npm took it.
+ * npm answers `202 Accepted` and the version shows up minutes later — 0.30.0
+ * about 6 min after publish, 0.31.2 past 5 (hosting-extension Sidetrack #9); until
+ * then `npm view` and `npx` still see the previous one. Waiting here turns "is it
+ * out?" into an answer. The time counts from `npm publish` (`since`): the push
+ * through CI before the wait is part of it. A version that does not show up in
+ * time is not a failure: npm took it.
  */
-export function waitForRegistry(name: string, version: string, deps: PublishDeps): boolean {
-  const started = Date.now();
+export function waitForRegistry(name: string, version: string, deps: PublishDeps, since = Date.now()): boolean {
+  const started = since;
   const deadline = started + deps.registryWaitMs;
   const limit = Math.round(deps.registryWaitMs / 1000);
   const seconds = () => Math.round((Date.now() - started) / 1000);
   deps.log(
     `→ waiting for the registry to show ${name}@${version} — npm has taken it; ` +
-      `the registry usually shows it within ~2 min (giving it ${limit} s)`,
+      `the registry has taken up to 6 min to show a version (giving it ${limit} s from publish; ` +
+      `Ctrl-C stops only this wait)`,
   );
   const shown = () => {
     try {
@@ -556,6 +604,7 @@ export function executePublish(plan: PublishPlan, deps: PublishDeps = defaultPub
   } finally {
     for (const s of signals) process.off(s, holdOut);
   }
+  const publishedAt = Date.now();
   deps.log(`✓ published ${plan.packageName}@${plan.newVersion}`);
 
   // 3. git add + commit + tag (at project root)
@@ -597,7 +646,7 @@ export function executePublish(plan: PublishPlan, deps: PublishDeps = defaultPub
   }
 
   // 5. registry
-  waitForRegistry(plan.packageName, plan.newVersion, deps);
+  waitForRegistry(plan.packageName, plan.newVersion, deps, publishedAt);
 }
 
 export function renderPublishPlan(plan: PublishPlan): string {
@@ -643,7 +692,10 @@ export function renderPublishPlan(plan: PublishPlan): string {
       const fixes = plan.preflight
         .filter((c) => !c.ok && c.fix)
         .map((c) => `\`${c.fix!.cmd} ${c.fix!.args.join(' ')}\``);
-      lines.push(`0. ${fixes.join(', ')} — at a terminal, then the pre-flight again`);
+      if (fixes.length > 0) lines.push(`0. ${fixes.join(', ')} — at a terminal, then the pre-flight again`);
+      for (const c of plan.preflight.filter((c) => !c.ok && c.waive)) {
+        lines.push(`0. At a terminal: ${c.waive!.trim()} — Enter releases nothing`);
+      }
     }
     lines.push(`1. Set \`version\` in ${files} → \`${plan.newVersion}\``);
     lines.push(`2. \`npm publish\` (cwd = directory containing package.json)`);
@@ -658,7 +710,7 @@ export function renderPublishPlan(plan: PublishPlan): string {
             ? `5. \`git push --follow-tags\` → ${push.upstream}${push.ahead ? ` (with ${push.ahead} local commit(s) not pushed yet)` : ''}`
             : '5. Not pushed: the branch has no upstream',
     );
-    lines.push(`6. Wait until the registry shows ${plan.newVersion} (up to 3 min)`);
+    lines.push(`6. Wait until the registry shows ${plan.newVersion} (up to 10 min from publish)`);
   } else {
     lines.push('> Pre-flight failed. Use `--force` to bypass at your own risk.');
   }

package/src/report.ts

@@ -47,6 +47,14 @@ export function reportMarkdown(r: AuditResult): string {
     lines.push(`| \`${a.axis_id}\` | ${cls} | ${achievedCell(a)} | ${a.target} | ${drift} |`);
   }
 
+  const notMet = r.per_axis.filter((a) => a.not_met && !a.suppressed && a.drift_kind !== 'excluded');
+  if (notMet.length > 0) {
+    lines.push('');
+    lines.push(`## Not met`);
+    lines.push('');
+    for (const a of notMet) lines.push(`- \`${a.axis_id}\` ${a.not_met!.level}: ${a.not_met!.reason}`);
+  }
+
   const unknown = r.per_axis.filter((a) => a.unknown);
   if (unknown.length > 0) {
     lines.push('');

package/src/scoring.ts

@@ -1,6 +1,7 @@
 import type { Axis, LevelName, Rubric } from './rubric.ts';
 import type { Ctx } from './facts.ts';
 import { evalPredicate, evalVerdict, isUnknown } from './evaluator.ts';
+import { isNo } from './predicates.ts';
 
 const LEVELS: LevelName[] = ['L1', 'L2', 'L3', 'L4'];
 
@@ -18,6 +19,8 @@ export interface AxisResult {
   not_required?: LevelName[];
   /** The level whose requirement could not be checked, and why; the ascent stopped there. */
   unknown?: { level: LevelName; reason: string };
+  /** The level whose requirement is not met, and why — when the predicate knows. */
+  not_met?: { level: LevelName; reason: string };
   /** A clone check printed next to the axis; does not change the level. */
   note?: string;
 }
@@ -26,6 +29,7 @@ export interface AxisEvaluation {
   achieved: LevelName;
   not_required?: LevelName[];
   unknown?: { level: LevelName; reason: string };
+  not_met?: { level: LevelName; reason: string };
 }
 
 export function evalAxis(axis: Axis, ctx: Ctx): LevelName {
@@ -41,6 +45,7 @@ function evalAxisLevels(axis: Axis, ctx: Ctx): AxisEvaluation {
   let achieved: LevelName = 'L0';
   const notRequired: LevelName[] = [];
   let unknown: AxisEvaluation['unknown'];
+  let notMet: AxisEvaluation['not_met'];
   for (const L of LEVELS) {
     const lvl = axis.levels?.[L];
     if (!lvl) break;
@@ -55,6 +60,7 @@ function evalAxisLevels(axis: Axis, ctx: Ctx): AxisEvaluation {
     } else {
       // delta-style: discontinuity → stop ascent; unknown is "not met", named
       if (isUnknown(v)) unknown = { level: L, reason: v.unknown };
+      else if (isNo(v)) notMet = { level: L, reason: v.no };
       break;
     }
   }
@@ -62,6 +68,7 @@ function evalAxisLevels(axis: Axis, ctx: Ctx): AxisEvaluation {
     achieved,
     ...(notRequired.length > 0 ? { not_required: notRequired } : {}),
     ...(unknown ? { unknown } : {}),
+    ...(notMet ? { not_met: notMet } : {}),
   };
 }