session-orchestrator 3.20.0 → 3.21.0

package/scripts/lib/mirror-issues-banner.mjs

@@ -0,0 +1,266 @@
+/**
+ * mirror-issues-banner.mjs — the mirror blind spot (#1022 follow-up)
+ *
+ * `skills/gitlab-ops/SKILL.md` § VCS Auto-Detection picks EXACTLY ONE platform
+ * via if/else. In a repo whose `origin` is GitLab and whose `github` remote is
+ * a public mirror, no code path ever reads issues from the mirror — so issues
+ * filed by external reporters against the mirror are structurally invisible to
+ * every session. This probe is the counter-measure: it asks the OTHER side.
+ *
+ * The VCS family is therefore HARD-PINNED to `'github'`, never auto-detected.
+ * Auto-detection is the defect this module exists to compensate for; deriving
+ * the family here would reproduce it.
+ *
+ * No new Session Config key by design. `resolveRepoSpec({ vcs:'github' })`
+ * derives the `gh -R` spec straight from `git remote` (its `REMOTE_PREFERENCE`
+ * tries the remote literally named `github` first, and its `WRONG_FAMILY_HOST`
+ * guard discards a cross-family match). That makes the probe SELF-DISABLING: a
+ * repo without a GitHub mirror resolves to `undefined` → `null` → no spawn, no
+ * network call. A config key would be a second SSOT drifting against
+ * `git remote`.
+ *
+ * Plain-JS — no Zod dependency. Never throws.
+ *
+ * Mirrors the Phase 4 banner contract documented in
+ * `scripts/lib/loop-readiness-banner.mjs:23-26`: a single `checkXxx()` entry
+ * point returning `null` or `{ severity, message, ... }`.
+ *
+ * Cross-references:
+ *  - `scripts/lib/ci-status-banner.mjs` — the sibling project-facing probe
+ *    (whose `null`-collapsing this module deliberately does NOT copy, see below).
+ *  - `scripts/lib/reconcile-nudge-banner.mjs:183-186` — the same
+ *    absence-preserving discipline applied to a count.
+ *  - `skills/session-start/SKILL.md` Phase 4 — banner render site.
+ */
+
+import { execFile as _execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { resolveRepoSpec as _resolveRepoSpec } from './vcs-repo-spec.mjs';
+
+const execFileAsync = promisify(_execFile);
+
+/** Default timeout in ms for the `gh` invocation. Mirrors `ci-status-banner.mjs:20`. */
+export const DEFAULT_TIMEOUT_MS = 8000;
+
+/** Default `--limit` passed to `gh issue list`. */
+export const DEFAULT_LIMIT = 20;
+
+/**
+ * The VCS family this probe queries. Deliberately a module constant, not a
+ * parameter: querying the auto-detected platform would make this probe a no-op
+ * in exactly the repos it exists for.
+ */
+const MIRROR_VCS = 'github';
+
+/** How many issue numbers the banner message names before summarising. */
+const MESSAGE_ISSUE_CAP = 5;
+
+/**
+ * Closed set of `degraded` reasons. A degraded result means "the mirror was
+ * NOT successfully read" — never "the mirror is clean".
+ *
+ * `query-failed` is the residual bucket for a `gh` that ran and exited
+ * non-zero for a reason that is neither missing-CLI, timeout, nor auth
+ * (network down, repo renamed, rate limit). It is a deliberate fifth member
+ * beyond the four originally specified: folding those into `parse-error`
+ * would mislabel a network failure as malformed output, reintroducing the
+ * dishonest-state class this module was built to remove.
+ *
+ * @type {readonly ['cli-missing','timeout','parse-error','auth-error','query-failed']}
+ */
+export const DEGRADED_REASONS = Object.freeze([
+  'cli-missing',
+  'timeout',
+  'parse-error',
+  'auth-error',
+  'query-failed',
+]);
+
+/**
+ * Run `cmd` with a timeout race. Mirrors `ci-status-banner.mjs:30-38`.
+ *
+ * The timer is cleared and `unref`ed so a fast success does not hold the event
+ * loop open for the full budget (`.claude/rules/testing.md` § Async & Timeout
+ * Patterns). KNOWN LIMIT, inherited from the shared pattern and NOT fixed
+ * here: losing the race abandons the `gh` child process rather than killing
+ * it — a hung `gh` is left orphaned.
+ *
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {{ cwd?: string, timeoutMs?: number, execFile?: Function }} [opts]
+ * @returns {Promise<{ stdout?: string, stderr?: string }>}
+ */
+async function execWithTimeout(cmd, args, opts = {}) {
+  const { cwd, timeoutMs = DEFAULT_TIMEOUT_MS, execFile = execFileAsync } = opts;
+  /** @type {NodeJS.Timeout | undefined} */
+  let timer;
+  try {
+    return await Promise.race([
+      execFile(cmd, args, { cwd, env: process.env }),
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error('timeout')), timeoutMs);
+        if (typeof timer.unref === 'function') timer.unref();
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/**
+ * Map a failed `gh` invocation onto a {@link DEGRADED_REASONS} member.
+ *
+ * @param {unknown} err
+ * @returns {'cli-missing'|'timeout'|'auth-error'|'query-failed'}
+ */
+function classifyFailure(err) {
+  const code = err && typeof err === 'object' ? /** @type {any} */ (err).code : undefined;
+  if (code === 'ENOENT') return 'cli-missing';
+
+  const message = err instanceof Error ? err.message : String(err ?? '');
+  if (message === 'timeout') return 'timeout';
+
+  const stderr = err && typeof err === 'object' ? String(/** @type {any} */ (err).stderr ?? '') : '';
+  const haystack = `${message}\n${stderr}`.toLowerCase();
+  if (
+    haystack.includes('gh auth login') ||
+    haystack.includes('not logged in') ||
+    haystack.includes('authentication') ||
+    haystack.includes('http 401') ||
+    haystack.includes('http 403')
+  ) {
+    return 'auth-error';
+  }
+  return 'query-failed';
+}
+
+/**
+ * Build the degraded result. Distinct from `null` on purpose: `null` in the
+ * banner contract reads as "all clear", which a failed query has NOT
+ * established.
+ *
+ * @param {string} repoSpec
+ * @param {string} reason
+ * @returns {{ severity: 'warn', message: string, repoSpec: string, degraded: string }}
+ */
+function degradedResult(repoSpec, reason) {
+  return {
+    severity: 'warn',
+    message:
+      `⚠ mirror-issues: Mirror ${repoSpec} konnte nicht abgefragt werden (${reason}) ` +
+      `— Zustand unbekannt, nicht "sauber".`,
+    repoSpec,
+    degraded: reason,
+  };
+}
+
+/**
+ * Render the found-issues banner message, naming issue numbers up to
+ * {@link MESSAGE_ISSUE_CAP} and summarising any remainder.
+ *
+ * @param {string} repoSpec
+ * @param {Array<{ number: number, title: string }>} issues
+ * @returns {string}
+ */
+function formatMessage(repoSpec, issues) {
+  const named = issues.slice(0, MESSAGE_ISSUE_CAP).map((i) => `#${i.number}`).join(', ');
+  const rest = issues.length - Math.min(issues.length, MESSAGE_ISSUE_CAP);
+  const tail = rest > 0 ? ` (+${rest} weitere)` : '';
+  const plural = issues.length === 1 ? 'offenes Issue' : 'offene Issues';
+  return (
+    `⚠ mirror-issues: ${issues.length} ${plural} im Mirror ${repoSpec}: ${named}${tail} ` +
+    `— kein anderer Codepfad dieser Session liest sie.`
+  );
+}
+
+/**
+ * Check the GitHub mirror for open issues and produce a session-start banner.
+ *
+ * Return contract — three states, not two:
+ *  - `null` when the mirror remote does not resolve (repo genuinely has no
+ *    mirror; NO subprocess is spawned) or when the query SUCCEEDED and found
+ *    zero open issues (measured and clean).
+ *  - `{ severity:'warn', message, count, repoSpec, issues }` when N > 0.
+ *  - `{ severity:'warn', message, repoSpec, degraded }` when the query did not
+ *    succeed. `degraded` is present ONLY in this case, so its absence proves
+ *    the mirror was actually read — the distinction `ci-status-banner.mjs`
+ *    collapses (CLI-missing, bad JSON and no-remote all return `null` there,
+ *    which is why the mirror gap went unseen for months).
+ *
+ * Never throws.
+ *
+ * @param {{ repoRoot?: string, timeoutMs?: number, limit?: number }} [opts]
+ * @param {{ execFile?: Function, resolveRepoSpec?: Function }} [deps] DI for tests only.
+ * @returns {Promise<null | { severity: 'warn', message: string, repoSpec: string, count?: number, issues?: Array<{number:number,title:string}>, degraded?: string }>}
+ */
+export async function checkMirrorIssues(opts = {}, deps = {}) {
+  try {
+    const { repoRoot, timeoutMs = DEFAULT_TIMEOUT_MS, limit = DEFAULT_LIMIT } = opts ?? {};
+    if (!repoRoot || typeof repoRoot !== 'string') return null;
+
+    const { execFile = execFileAsync, resolveRepoSpec = _resolveRepoSpec } = deps ?? {};
+
+    // Step 1 — resolve the mirror spec from `git remote`. `undefined` here is
+    // the self-disabling path: no mirror, no spawn, no network cost.
+    let repoSpec;
+    try {
+      repoSpec = resolveRepoSpec({ repoRoot, vcs: MIRROR_VCS });
+    } catch {
+      return null;
+    }
+    if (!repoSpec || typeof repoSpec !== 'string') return null;
+
+    // Step 2 — query. Args array, never a shell string.
+    let stdout;
+    try {
+      const result = await execWithTimeout(
+        'gh',
+        [
+          'issue',
+          'list',
+          '-R',
+          repoSpec,
+          '--state',
+          'open',
+          '--limit',
+          String(limit),
+          '--json',
+          'number,title',
+        ],
+        { cwd: repoRoot, timeoutMs, execFile },
+      );
+      stdout = String(result?.stdout ?? '');
+    } catch (err) {
+      return degradedResult(repoSpec, classifyFailure(err));
+    }
+
+    // Step 3 — parse. A CLI that exited 0 with unusable output is degraded,
+    // NOT clean.
+    let issues;
+    try {
+      const parsed = JSON.parse(stdout);
+      if (!Array.isArray(parsed)) return degradedResult(repoSpec, 'parse-error');
+      issues = parsed
+        .filter((entry) => entry && typeof entry === 'object' && Number.isFinite(Number(entry.number)))
+        .map((entry) => ({ number: Number(entry.number), title: String(entry.title ?? '') }));
+    } catch {
+      return degradedResult(repoSpec, 'parse-error');
+    }
+
+    // Step 4 — measured and clean.
+    if (issues.length === 0) return null;
+
+    return {
+      severity: 'warn',
+      message: formatMessage(repoSpec, issues),
+      count: issues.length,
+      repoSpec,
+      issues,
+    };
+  } catch {
+    // Defensive catch-all: a banner must never break session-start.
+    return null;
+  }
+}
+
+export default checkMirrorIssues;

package/scripts/lib/named-vault-resolver.mjs

@@ -16,6 +16,29 @@
  * IO is fully injectable (existsSync, realpathSync, env, gitRemote) so every
  * branch is unit-testable without touching disk or git.
  *
+ * ── Remote resolution (#1039) ────────────────────────────────────────────────
+ *
+ * The default `gitRemote` reads the repo's remote through the shared core in
+ * `vcs-repo-spec.mjs` ({@link resolvePreferredRemote}), VCS-LESS. Two properties
+ * of that call are load-bearing here and must not be "tidied":
+ *
+ *   1. **`vcs` is deliberately omitted.** This module needs a URL, not a
+ *      platform family, and the vcs-less preference order is `origin` first.
+ *      That order is what keeps the derived slug STABLE: in a repo carrying both
+ *      `origin` (→ `<group>/<repo>`) and `gitlab`/`github` mirrors under other
+ *      namespaces, a `gitlab`-first order would re-namespace — i.e. silently
+ *      RENAME — every vault note already written under the origin namespace.
+ *   2. **Absence and query-failure are kept apart.** The former
+ *      `git remote get-url origin` implementation returned `''` for *both* "no
+ *      remote configured" and "git blew up / this is not a repo", and a falsy
+ *      URL skips the walk-up entirely. The vault then resolved to the
+ *      single-vault fallback with no trace of why — one `source:'fallback'`
+ *      label covering a benign repo state and a broken measurement. The
+ *      fallback result now carries an optional `remoteError` (a
+ *      `REMOTE_RESOLUTION_REASONS` value) so the two are separable BY VALUE, and
+ *      only a query failure ({@link isQueryFailure}) WARNs — an absence is
+ *      normal and stays silent.
+ *
  * ── Exports ──────────────────────────────────────────────────────────────────
  *
  *   parseNamedVaults(ownerConfig)
@@ -28,7 +51,7 @@
 
 import { join, dirname } from 'node:path';
 import { existsSync as nodeExistsSync, realpathSync as nodeRealpathSync } from 'node:fs';
-import { spawnSync } from 'node:child_process';
+import { resolvePreferredRemote, isQueryFailure } from './vcs-repo-spec.mjs';
 
 // ---------------------------------------------------------------------------
 // Internal helpers
@@ -289,12 +312,31 @@ export function findRepoRoot(cwd = process.cwd(), { existsSync = nodeExistsSync,
  * `gitRemote(repoRoot)` is called ONLY in the walk-up path — injecting a
  * stub that throws proves the explicit path never calls it.
  *
+ * `gitRemote` keeps its `(repoRoot) => string` contract verbatim; the optional
+ * second argument is an OUT-parameter the default implementation uses to report
+ * WHY it returned `''`. A one-arg stub ignores it and classifies as
+ * `'no-remotes'` on `''` / `'git-error'` on a throw — so every pre-existing
+ * injection still works unchanged.
+ *
+ * `gitRun` is injected into the DEFAULT `gitRemote` only, and is ignored when
+ * `gitRemote` is supplied (the caller has replaced the thing that would use it).
+ * It exists so the default remote-resolution path — preference order, reason
+ * propagation — is testable at all; a `gitRemote` stub answers that question
+ * before the code under test runs and can only ever confirm itself.
+ *
+ * `remoteError` is present ONLY on a `source:'fallback'` result that was reached
+ * because the remote query produced nothing; it is absent when the fallback was
+ * reached for any other reason (no vaults configured, no repo root, the repo IS
+ * a vault, no org-prefix match). Additive — pre-#1039 readers see the identical
+ * four fields.
+ *
  * @param {{
  *   vaultName?: string|null,
  *   cwd?: string,
  *   ownerConfig?: object,
  *   env?: Record<string, string|undefined>,
- *   gitRemote?: (repoRoot: string) => string,
+ *   gitRemote?: (repoRoot: string, out?: {reason?: string}) => string,
+ *   gitRun?: (args: string[]) => {ok: boolean, stdout: string, stderr: string, status?: number, code?: string},
  *   existsSync?: Function,
  *   realpathSync?: Function,
  * }} [opts]
@@ -302,7 +344,8 @@ export function findRepoRoot(cwd = process.cwd(), { existsSync = nodeExistsSync,
  *   root: string|null,
  *   suffix: string,
  *   name: string|null,
- *   source: 'explicit'|'walkup'|'fallback'
+ *   source: 'explicit'|'walkup'|'fallback',
+ *   remoteError?: string
  * }}
  */
 export function resolveNamedVault({
@@ -310,11 +353,14 @@ export function resolveNamedVault({
   cwd = process.cwd(),
   ownerConfig,
   env = process.env,
-  gitRemote = _defaultGitRemote,
+  gitRemote,
+  gitRun,
   existsSync = nodeExistsSync,
   realpathSync = nodeRealpathSync,
 } = {}) {
   const vaults = parseNamedVaults(ownerConfig);
+  const readRemote =
+    typeof gitRemote === 'function' ? gitRemote : (root, out) => _defaultGitRemote(root, out, gitRun);
 
   // ── Path 1: explicit vault-name ──────────────────────────────────────────
   const trimmedName = typeof vaultName === 'string' ? vaultName.trim() : '';
@@ -330,18 +376,39 @@ export function resolveNamedVault({
   }
 
   // ── Path 2: walk-up org-prefix match ────────────────────────────────────
+  /** @type {string|undefined} — set ONLY when the remote query is why we fall through */
+  let remoteError;
+
   if (vaults.length > 0) {
     const repoRoot = findRepoRoot(cwd, { existsSync, realpathSync });
     if (repoRoot !== null) {
-      // Get the git remote for origin
+      // Resolve the repo's preferred remote (vcs-less → origin-first; see the
+      // module docblock for why that order must not move).
+      /** @type {{reason?: string, stderr?: string}} */
+      const remoteOut = {};
       let remoteUrl;
       try {
-        remoteUrl = gitRemote(repoRoot);
-      } catch {
+        remoteUrl = readRemote(repoRoot, remoteOut);
+      } catch (err) {
+        // A throwing gitRemote could not answer the question — that is a query
+        // failure, never "this repo has no remote".
         remoteUrl = '';
+        remoteOut.reason = 'git-error';
+        remoteOut.stderr = err instanceof Error ? err.message : String(err);
       }
 
-      if (remoteUrl) {
+      if (!remoteUrl) {
+        // Falsy URL: keep the REASON instead of collapsing it into a bare
+        // `source:'fallback'`. A one-arg stub that reported nothing means the
+        // benign "no remote configured" case.
+        remoteError = remoteOut.reason ?? 'no-remotes';
+        if (isQueryFailure(remoteError)) {
+          const detail = remoteOut.stderr ? `: ${String(remoteOut.stderr).trim()}` : '';
+          process.stderr.write(
+            `WARN named-vault-resolver: could not read the git remote of "${repoRoot}" (${remoteError})${detail}; falling back to the single-vault default\n`,
+          );
+        }
+      } else {
         // Derive org/repo from the remote URL (strip suffix/.git/scheme)
         const repoSlug = _deriveSlugFromRemote(remoteUrl);
 
@@ -366,11 +433,14 @@ export function resolveNamedVault({
   }
 
   // ── Path 3: single-vault fallback ────────────────────────────────────────
+  // `remoteError` is spread in only when set, so a fallback reached for any
+  // other reason keeps the exact pre-#1039 four-field shape.
   return {
     root: null,
     suffix: _resolveEnvSuffix(env) ?? DEFAULT_SUFFIX,
     name: null,
     source: 'fallback',
+    ...(remoteError === undefined ? {} : { remoteError }),
   };
 }
 
@@ -420,14 +490,33 @@ function _deriveSlugFromRemote(url) {
 }
 
 /**
- * Default gitRemote implementation: runs `git -C <repoRoot> remote get-url origin`.
+ * Default gitRemote implementation (#1039).
+ *
+ * Delegates to the shared {@link resolvePreferredRemote} core VCS-LESS, which
+ * makes this resolver work in the repos the old hard-coded
+ * `git remote get-url origin` was blind in — a repo whose remotes are named
+ * `gitlab`/`github`, a fork whose sole remote is `upstream`. The vcs-less
+ * preference order still tries `origin` FIRST, so the slug derived for a repo
+ * that has an `origin` is byte-identical to the pre-#1039 value.
+ *
+ * Return type stays `string` (the `gitRemote` DI contract depends on it). The
+ * failure reason travels through the optional `out` OUT-parameter instead:
+ * folding it into the return value would have meant changing that contract for
+ * every injected stub.
+ *
  * @param {string} repoRoot
- * @returns {string}
+ * @param {{reason?: string, stderr?: string}} [out] — populated with the
+ *   {@link REMOTE_RESOLUTION_REASONS} reason when the resolution failed
+ * @param {Function} [gitRun] — injectable git runner; `undefined` uses the real one
+ * @returns {string} the remote URL, or `''` when none resolved
  */
-function _defaultGitRemote(repoRoot) {
-  const res = spawnSync('git', ['-C', repoRoot, 'remote', 'get-url', 'origin'], {
-    encoding: 'utf8',
-  });
-  if (res.status !== 0) return '';
-  return res.stdout.trim();
+function _defaultGitRemote(repoRoot, out, gitRun) {
+  // `vcs` deliberately omitted — see the module docblock (origin-first order).
+  const resolved = resolvePreferredRemote({ repoRoot, gitRun });
+  if (resolved.ok) return resolved.url;
+  if (isPlainObject(out)) {
+    out.reason = resolved.reason;
+    if (resolved.stderr) out.stderr = resolved.stderr;
+  }
+  return '';
 }

package/scripts/lib/peer-cards/schema.mjs

@@ -6,8 +6,12 @@
  * YAML frontmatter on read and before write.
  *
  * Design notes:
- *   - Follows the `mission-status-schema.mjs` convention (pure regex/checks)
- *     rather than `skills/vault-sync/validator.mjs` (zod). The repo root has
+ *   - Pure regex/checks rather than `skills/vault-sync/validator.mjs` (zod).
+ *     (This line used to cite `scripts/lib/mission-status-schema.mjs` as the
+ *     exemplar for that convention; that module was deleted on 2026-08-15 for
+ *     having zero production callers while three prose sites promised it ran.
+ *     The convention below stands on its own reason, stated next.)
+ *     The repo root has
  *     no `zod` dependency — only `skills/vault-sync/` does, scoped to that
  *     skill's own `node_modules`. Keeping this validator dependency-free lets
  *     callers from anywhere under `scripts/lib/` use it without extra setup.

package/scripts/lib/reconcile/writer.mjs

@@ -123,12 +123,37 @@ function writeTextAtomic(destPath, content) {
  *    `globs=null, meta={}, parseError=true` → always-on again, and with empty
  *    meta it passes every gate by design.
  *
- * Scope note: the checks below fire only for a document that DECLARES
- * `auto-generated: true` (plus the parse check, which applies to every
- * document). The module's contract stays general — a caller may still write a
- * document with no frontmatter — but every document the reconcile pipeline
- * actually produces carries `auto-generated: true` on its first frontmatter
- * line, so the machine-authored path is fully covered.
+ * Scope (#1018 L2) — three tiers, deliberately not one:
+ *
+ *  1. PARSE — every document. Unparseable means unsafe, not unknown.
+ *  2. `alwaysApply: true` — every document, regardless of any marker. A rule
+ *     file that DECLARES itself always-on is precisely the outcome this gate
+ *     exists to prevent, and declaring it must not be the way around the gate.
+ *     Before #1018 this check sat behind the `auto-generated: true` branch, so
+ *     a document with `alwaysApply: true` and no `auto-generated` key was
+ *     written to disk unexamined — measured, not inferred: a `writeApprovedRules`
+ *     probe returned `written: 1` for exactly that input.
+ *  3. The never-always-on invariant set (activation axis, non-empty globs,
+ *     `learning-key`, `expires-at`) — every document carrying ANY machine-
+ *     provenance marker (`auto-generated: true`, `learning-key`, or
+ *     `expires-at`). Keying on the marker SET rather than on `auto-generated`
+ *     alone means a document that loses its `auto-generated` line to truncation
+ *     but keeps its provenance keys is still held to the invariant.
+ *
+ * Why tier 3 is marker-scoped and not universal — measured against the live
+ * corpus, not assumed: applying the invariant set to EVERY document would
+ * refuse 16 of the 29 files currently in `.claude/rules/`. Those 16 are the
+ * hand-authored always-on rules (`development.md`, `security.md`,
+ * `parallel-sessions.md`, …), for which always-on is the intended, correct
+ * shape — they carry no frontmatter at all. A universal gate would therefore
+ * refuse the legitimate majority of the corpus to catch a machine-path defect.
+ * Marker-scoped refuses 0 of 29. The module's general contract survives: a
+ * caller may still write a document with no frontmatter.
+ *
+ * CEILING (BV-004): the marker set is a fixed three-key list, not a schema
+ * lookup. Revisit if the renderer gains a fourth provenance key, or if a second
+ * non-reconcile caller of `writeApprovedRules` appears — today there is exactly
+ * one production caller and it passes renderer output.
  *
  * Mirrors `scripts/lib/validate/check-rules.mjs`, which enforces the same
  * invariants as a CI gate. Two enforcement points, one invariant: CI catches
@@ -147,37 +172,51 @@ function frontmatterRefusalReason(content) {
   }
 
   const { globs, meta } = parsed;
-
-  // Not a machine-authored auto-generated rule → the never-always-on invariant
-  // does not bind (see the scope note above).
-  if (meta['auto-generated'] !== true) return null;
+  const hasKey = (key) => Object.prototype.hasOwnProperty.call(meta, key);
 
   const problems = [];
 
-  const hasEmptyGlobs = Array.isArray(globs) && globs.length === 0;
-  const hasGlobs = Array.isArray(globs) && globs.length > 0;
-  const hasHostClass = Object.prototype.hasOwnProperty.call(meta, 'host-class');
-
-  if (hasEmptyGlobs) {
-    // NOT the "no axis" case and NOT always-on — the opposite: rule-loader.mjs
-    // excludes on `globs.length === 0` unconditionally, AFTER gating, so the
-    // rule never loads in ANY context even alongside a host-class: key.
-    problems.push('empty globs array (globs: []) — the rule would match nothing and never load in ANY context');
-  } else if (!hasGlobs && !hasHostClass) {
-    problems.push('no activation axis (globs absent AND host-class absent) — the rule would load always-on');
-  }
-  if (!Object.prototype.hasOwnProperty.call(meta, 'learning-key')) {
-    problems.push('missing required frontmatter key: learning-key');
-  }
-  if (!Object.prototype.hasOwnProperty.call(meta, 'expires-at')) {
-    problems.push('missing required frontmatter key: expires-at');
-  }
+  // ── Tier 2: binds on EVERY document (see the scope note above) ────────────
+  // Not gated behind any marker: a document that declares itself always-on is
+  // the exact outcome this gate prevents, so the declaration cannot be the
+  // escape hatch. The renderer only ever emits `alwaysApply: false`.
   if (meta.alwaysApply === true) {
-    problems.push('alwaysApply: true on an auto-generated rule — the renderer only ever emits false');
+    problems.push(
+      'alwaysApply: true — a rule written through this writer must never declare itself always-on (the renderer only ever emits false)',
+    );
+  }
+
+  // ── Tier 3: binds on any machine-provenance-bearing document ──────────────
+  // Marker-scoped rather than universal so the hand-authored always-on corpus
+  // (16 of 29 live rule files) keeps writing; marker-scoped rather than
+  // `auto-generated`-only so a document that loses that line to truncation but
+  // keeps its provenance keys is still held to the invariant.
+  const isProvenanceBearing =
+    meta['auto-generated'] === true || hasKey('learning-key') || hasKey('expires-at');
+
+  if (isProvenanceBearing) {
+    const hasEmptyGlobs = Array.isArray(globs) && globs.length === 0;
+    const hasGlobs = Array.isArray(globs) && globs.length > 0;
+    const hasHostClass = hasKey('host-class');
+
+    if (hasEmptyGlobs) {
+      // NOT the "no axis" case and NOT always-on — the opposite: rule-loader.mjs
+      // excludes on `globs.length === 0` unconditionally, AFTER gating, so the
+      // rule never loads in ANY context even alongside a host-class: key.
+      problems.push('empty globs array (globs: []) — the rule would match nothing and never load in ANY context');
+    } else if (!hasGlobs && !hasHostClass) {
+      problems.push('no activation axis (globs absent AND host-class absent) — the rule would load always-on');
+    }
+    if (!hasKey('learning-key')) {
+      problems.push('missing required frontmatter key: learning-key');
+    }
+    if (!hasKey('expires-at')) {
+      problems.push('missing required frontmatter key: expires-at');
+    }
   }
 
   if (problems.length === 0) return null;
-  return `auto-generated rule fails the never-always-on invariant: ${problems.join('; ')}`;
+  return `rule fails the never-always-on invariant: ${problems.join('; ')}`;
 }
 
 // ---------------------------------------------------------------------------