session-orchestrator 4.2.0 → 5.0.0

package/skills/bootstrap/references/bootstrap-retroactive-flow.md

@@ -0,0 +1,108 @@
+# Bootstrap — Retroactive Flow (`--retroactive`)
+
+> Reference of the `bootstrap` skill, split out of `SKILL.md` (#1246). Body moved **byte-identical**; only this header is new.
+> **Sibling-file paths inside this body are relative to the parent directory, not to `references/`**: `SKILL.md` → `../SKILL.md`. They were deliberately NOT rewritten, so the moved bytes stay verifiable against the pre-split file.
+
+## Retroactive Flow (`--retroactive`)
+
+Entered when `$ARGUMENTS` contains `--retroactive`. Writes the lock file and, per #182, optionally patches missing mandatory Session Config fields with defaults.
+
+**Purpose:** Adopt an existing repo that already has `CLAUDE.md` + `## Session Config` but was bootstrapped manually (no `bootstrap.lock`). Writes the lock so the gate passes on all future invocations, and ensures the Session Config block satisfies the validated schema defined in `scripts/lib/config-schema.mjs`.
+
+**Steps:**
+
+1. **Verify preconditions.** Confirm `CLAUDE.md` (or `AGENTS.md`) exists and contains `## Session Config`. If not, abort: `Error: CLAUDE.md with Session Config required for retroactive bootstrap.`
+
+2. **Check lock not already present.** If `.orchestrator/bootstrap.lock` already exists and has valid `version` + `tier` fields, report: `bootstrap.lock already present (tier: <tier>). Nothing to do.` and exit 0 (idempotent).
+
+3. **Infer tier from file inventory.** Examine the repo root:
+
+   | Condition (evaluated in order) | Inferred Tier |
+   |---|---|
+   | CI file present (`.gitlab-ci.yml` OR `.github/workflows/`) AND `CHANGELOG.md` present | `deep` |
+   | Package manifest present (`package.json` OR `pyproject.toml`) | `standard` |
+   | Neither of the above | `fast` |
+
+   Store as `INFERRED_TIER`.
+
+4. **Infer archetype.** Run Phase 0.5's read-only source detection. For a private
+   contract, use its detected `selected.id`; retain `null` with an explicit
+   `insufficient-evidence` report if no markers match. An invalid configured
+   contract aborts. Do not scaffold or apply rules in this retroactive flow.
+   For the public path, use best-effort detection from existing files:
+   - `pyproject.toml` present → `python-uv`
+   - `package.json` with `next` in dependencies → `nextjs-minimal`
+   - `package.json` without `next` → `node-minimal`
+   - No manifest → `null`
+
+   Store as `INFERRED_ARCHETYPE`.
+
+5. **Write bootstrap.lock.** Create `.orchestrator/` if needed, then write:
+   ```yaml
+   # .orchestrator/bootstrap.lock
+   version: 1
+   tier: <INFERRED_TIER>
+   archetype: <INFERRED_ARCHETYPE or null>
+   timestamp: <current ISO 8601 UTC>
+   source: retroactive
+   plugin-version: <current plugin version from $PLUGIN_ROOT/package.json>
+   ```
+
+6. **Patch Session Config (#182).** Run the validator against the current `## Session Config` block; append any missing mandatory fields with defaults. The 7 mandatory fields (per `scripts/lib/config-schema.mjs`) are: `test-command`, `typecheck-command`, `lint-command`, `agents-per-wave`, `waves`, `persistence`, `enforcement`.
+
+   ```bash
+   CONFIG_OUT="$(node "$PLUGIN_ROOT/scripts/parse-config.mjs" 2>&1 >/dev/null)"
+   # parse-config.mjs emits validation warnings to stderr when enforcement=warn.
+   # Grep for 'must be' lines (issued by validate-config.mjs) to detect missing fields.
+   MISSING_FIELDS="$(echo "$CONFIG_OUT" | grep -oE '(test-command|typecheck-command|lint-command|agents-per-wave|waves|persistence|enforcement)' | sort -u || true)"
+   if [[ -n "$MISSING_FIELDS" ]]; then
+     # Detect package manager to pick sensible defaults for commands.
+     PM_DEFAULTS="$(node --input-type=module -e "
+       import {detectPackageManager, defaultQualityGateCommands} from '$PLUGIN_ROOT/scripts/lib/package-manager.mjs';
+       const pm = detectPackageManager(process.cwd());
+       const cmds = defaultQualityGateCommands(pm);
+       console.log('test-command: ' + cmds.test.command);
+       console.log('typecheck-command: ' + cmds.typecheck.command);
+       console.log('lint-command: ' + cmds.lint.command);
+     " 2>/dev/null)"
+
+     CONFIG_FILE="CLAUDE.md"
+     [[ -f "AGENTS.md" ]] && CONFIG_FILE="AGENTS.md"
+
+     # Append each missing field under the ## Session Config block.
+     for field in $MISSING_FIELDS; do
+       case "$field" in
+         test-command|typecheck-command|lint-command)
+           default_line="$(echo "$PM_DEFAULTS" | grep "^$field:")" ;;
+         agents-per-wave) default_line="agents-per-wave: 6" ;;
+         waves)           default_line="waves: 5" ;;
+         persistence)     default_line="persistence: true" ;;
+         enforcement)     default_line="enforcement: warn" ;;
+       esac
+       # Insert after `## Session Config` line if not already present.
+       grep -q "^$field:" "$CONFIG_FILE" \
+         || awk -v insert="$default_line" '/^## Session Config/ && !done { print; print ""; print insert; done=1; next } { print }' "$CONFIG_FILE" > "$CONFIG_FILE.tmp" \
+         && mv "$CONFIG_FILE.tmp" "$CONFIG_FILE"
+     done
+     echo "Patched $CONFIG_FILE with defaults for: $MISSING_FIELDS"
+   fi
+   ```
+
+   This patch is best-effort: existing fields are never overwritten. If no fields are missing, this step is a no-op.
+
+7. **Commit.** Stage the lock file (and the patched config file, if it changed) and commit:
+   ```bash
+   mkdir -p .orchestrator
+   git add .orchestrator/bootstrap.lock
+   # Also stage CLAUDE.md/AGENTS.md if step 6 patched it.
+   git diff --name-only --cached CLAUDE.md AGENTS.md 2>/dev/null | head -1 >/dev/null || {
+     [[ -f CLAUDE.md ]] && git diff --quiet CLAUDE.md || git add CLAUDE.md
+     [[ -f AGENTS.md ]] && git diff --quiet AGENTS.md || git add AGENTS.md
+   }
+   git commit -m "chore: bootstrap lock (retroactive)"
+   ```
+
+8. **Report.** Print: `Retroactive bootstrap complete. Lock written (tier: <INFERRED_TIER>, source: retroactive).` Include a second line `Patched Session Config: <fields>` when step 6 applied any patches, otherwise `No config changes.`.
+
+---
+

package/skills/bootstrap/references/bootstrap-rules-fetch-bridge.md

@@ -0,0 +1,64 @@
+# Bootstrap — Phase 3.6: (Optional) Rules-Fetch Bridge
+
+> Reference of the `bootstrap` skill, split out of `SKILL.md` (#1246). Body moved **byte-identical**; only this header is new.
+> **Sibling-file paths inside this body are relative to the parent directory, not to `references/`**: `SKILL.md` → `../SKILL.md`, `private-contract.md` → `../private-contract.md`, `standard-template.md` → `../standard-template.md`, `deep-template.md` → `../deep-template.md`. They were deliberately NOT rewritten, so the moved bytes stay verifiable against the pre-split file.
+
+## Phase 3.6: (Optional) Rules-Fetch Bridge
+
+> Closes session-orchestrator issue #110.
+
+After scaffolding, the Standard and Deep templates execute S99. On the private
+path, it applies the selected contract's local rule union, rechecks conditional
+dependencies and preserves existing files. It excludes every plugin-owned
+basename and aborts on an invalid configured contract; see `private-contract.md`.
+
+On the public path, S99 retains the optional remote rules-fetch step. It pulls
+canonical `.claude/rules/*.md` directly from the configured baseline GitLab
+project, excluding all plugin-owned basenames. The remote step only fires when:
+
+- `baseline-ref` is present in Session Config
+- `GITLAB_TOKEN` env var is set
+- `scripts/lib/fetch-baseline.mjs` is present in the plugin
+- A GitLab host is resolvable from the `gitlab-host` Session Config key (or the `GITLAB_HOST` env var) — never a hardcoded default
+
+When triggered, the step:
+
+1. Loops over a default rule manifest, invoking `node scripts/lib/fetch-baseline.mjs <project_id> <file_path> <baseline-ref>` once per rule. The CLI prints one file body to stdout (exit 0 success; 1 auth, 2 not-found, 3 network) — bootstrap redirects stdout to the target path and skips failures so a single 404 cannot abort the batch.
+2. Fetches each rule listed in the default manifest from the configured `baseline-project-id` (default `52`) at the configured `baseline-ref`
+3. Writes `.claude/.baseline-fetch.lock` (via an inline `node --input-type=module -e`) recording what was fetched
+4. Populates `.claude/.baseline-cache/` for offline fallback on subsequent invocations
+
+When the fetch fails (network error, auth, missing file), bootstrap **does not abort**. Rules will arrive in the repo via Clank's weekly baseline sync MRs (the legacy path). A warning is printed.
+
+**Why opt-in:** Repos without `baseline-ref` continue to receive rules via the existing Clank sync flow. The fetch bridge is a faster on-demand alternative for newly-bootstrapped repos that want current rules immediately.
+
+**Local edits:** Re-running bootstrap with `baseline-ref` set will overwrite `.claude/rules/*.md` (rules are canonical). Repo-specific extensions belong in `.claude/rules/local/*.md` (not fetched, not overwritten).
+
+See `standard-template.md` (Step S99) and `deep-template.md` (Step D99) for the implementation, and `docs/session-config-reference.md` for the `baseline-ref` and `baseline-project-id` field definitions.
+
+### `.claude/.baseline-fetch.lock` Schema
+
+The lock file is committed to git and records what was fetched.
+
+```yaml
+# .claude/.baseline-fetch.lock
+version: 1
+project_id: 52
+baseline_ref: main
+fetched_at: 2026-04-17T13:42:00Z   # ISO 8601 UTC
+files:
+  - .claude/rules/development.md
+  - .claude/rules/security.md
+  - .claude/rules/...
+```
+
+| Field | Description |
+|---|---|
+| `version` | Lock file schema version. Currently `1`. |
+| `project_id` | GitLab project ID the files were fetched from. |
+| `baseline_ref` | The git ref (branch/tag/SHA) at fetch time. |
+| `fetched_at` | ISO 8601 UTC timestamp. |
+| `files` | List of fetched file paths (relative to repo root). |
+
+---
+

package/skills/claude-md-drift-check/SKILL.md

@@ -41,7 +41,7 @@ PHASE 1 IMPLEMENTED (2026-04-19). Session-end opt-in quality gate. Upstream of `
 | 6 | `session-config-parity` | Top-level keys under `## Session Config` in `CLAUDE.md` / `AGENTS.md` | diff against `docs/session-config-template.md`; a missing MANDATORY (minimal-baseline) key is an error, a missing OPT-IN-baseline-only key is a warning |
 | 7 | `vault-dir-parity` | `vault-integration.vault-dir` in BOTH `CLAUDE.md` AND `AGENTS.md` | reuse `_parseVaultIntegration`; flag when the two files disagree. Short-circuits to PASS when the two are the SAME file by construction (symlink / same inode / byte-identical generated copy) |
 | 8 | `generated-rule-staleness` *(WARN only)* | `.claude/rules/*.md` with `auto-generated: true` frontmatter | extract `learning-key`; WARN when the key is absent from `.orchestrator/metrics/learnings.jsonl` or its learning's `expires_at` is in the past; skipped silently when no auto-generated rules exist |
-| 9 | `rule-scoping` | `.claude/rules/*.md` frontmatter + `## See Also` footers + `.claude/rules/<name>.md` citations in `CLAUDE.md`/`AGENTS.md` | five probes: `paths:` frontmatter (error), cited-but-missing rule citations (error), zero-match `globs:` patterns (warn), foreign PascalCase glob tokens (warn), unreadable rule files (warn — surfaced instead of silently skipped); skipped silently when `.claude/rules/` is absent |
+| 9 | `rule-scoping` | `.claude/rules/*.md` frontmatter + `## See Also` footers + `.claude/rules/<name>.md` citations in `CLAUDE.md`/`AGENTS.md` | six probes: `paths:` frontmatter (error), cited-but-missing rule citations (error), zero-match `globs:` patterns (warn), foreign PascalCase glob tokens (warn), unreadable rule files (warn — surfaced instead of silently skipped), declared fleet-intent globs (**note**, never warn); skipped silently when `.claude/rules/` is absent |
 | 10 | `docs-parity` | `docs/components.md` count-claims, Session Config key parity (`docs/session-config-template.md` vs `docs/session-config-reference.md`), `.claude/metrics/` stale-path references in `docs/*.md` / `docs/examples/*.md` | three sub-checks (a/b/c) — see below; skipped silently when `docs/components.md` is absent |
 
 Check 3 deliberately scopes to forward-looking sections. Mentions inside "Recently Closed", "Decisions", "Archive", etc. describe history and must not be flagged.
@@ -65,7 +65,9 @@ Check 7 (issue #600) is the **only** check that intentionally reads BOTH instruc
 
 The same predicate guards Check 9's probe 2a, which iterates `['CLAUDE.md', 'AGENTS.md']`: with an aliased `AGENTS.md` it scans `CLAUDE.md` only, because otherwise every dangling `.claude/rules/*.md` citation would be reported TWICE — one defect, two errors, and in `--mode strict` a doubled blocking surface against a file the operator is not allowed to edit.
 
-Check 9 (`rule-scoping`) validates `.claude/rules/*.md` frontmatter against the `scripts/lib/rule-loader.mjs` contract, catching the class of defect where a rule silently drifts out of the activation pipeline the loader actually implements. Four probes: **(1) paths-presence** — a top-level `paths:` frontmatter key is not a key `rule-loader.mjs` recognises (it only reads `globs:`), so a rule with `paths:` silently loads ALWAYS-ON regardless of intended file scope; flagged as an error. **(2) cited-but-missing** — `(a)` `.claude/rules/<name>.md` citations inside `CLAUDE.md`/`AGENTS.md` that don't resolve to a file on disk, and `(b)` bare `<name>.md` tokens in a rule's own `## See Also` footer that don't exist as sibling rule files (tokens carrying a path separator, e.g. `../../skills/_shared/state-ownership.md`, are cross-directory references and explicitly out of scope); both flagged as errors. **(3) zero-match-globs** — a `globs:` pattern matching zero files in `git ls-files` (falls back to a manual directory walk when git is unavailable); flagged as a WARNING, not an error, because library/exemplar repos legitimately carry dead stack rules (this repo alone carries ~37 by design — Swift/Next.js/Supabase rules with no matching files in a pure-Node-ESM codebase). **(4) foreign-glob** — a glob pattern containing a PascalCase product-like token (regex `[A-Z][a-z]+[A-Z]`, e.g. `WalkAITalkieTests`) — a likely copy-paste leftover from another project's rule scope; flagged as a WARNING. Glob matching reuses the same picomatch-with-inline-fallback resolution `scripts/lib/rule-loader.mjs` uses (`parseGlobsFrontmatter` is imported directly; the picomatch resolution itself is duplicated locally since `rule-loader.mjs` does not export a public matcher function). The check is skipped silently (no `checks_run` entry, no `checks_skipped` entry) when `.claude/rules/` is absent, or explicitly via `--skip-rule-scoping`.
+Check 9 (`rule-scoping`) validates `.claude/rules/*.md` frontmatter against the `scripts/lib/rule-loader.mjs` contract, catching the class of defect where a rule silently drifts out of the activation pipeline the loader actually implements. Six probes: **(1) paths-presence** — a top-level `paths:` frontmatter key is not a key `rule-loader.mjs` recognises (it only reads `globs:`), so a rule with `paths:` silently loads ALWAYS-ON regardless of intended file scope; flagged as an error. **(2) cited-but-missing** — `(a)` `.claude/rules/<name>.md` citations inside `CLAUDE.md`/`AGENTS.md` that don't resolve to a file on disk, and `(b)` bare `<name>.md` tokens in a rule's own `## See Also` footer that don't exist as sibling rule files (tokens carrying a path separator, e.g. `../../skills/_shared/state-ownership.md`, are cross-directory references and explicitly out of scope); both flagged as errors. **(3) zero-match-globs** — a `globs:` pattern matching zero files in `git ls-files` (falls back to a manual directory walk when git is unavailable); flagged as a WARNING, not an error, because library/exemplar repos legitimately carry dead stack rules. **(4) foreign-glob** — a glob pattern containing a PascalCase product-like token (regex `[A-Z][a-z]+[A-Z]`, e.g. `WalkAITalkieTests`) — a likely copy-paste leftover from another project's rule scope; flagged as a WARNING. **(5) unreadable-file** — a rule file that could not be read (permissions, a race with a concurrent delete); flagged as a WARNING rather than silently skipped, so a completeness audit does not drop files, and so an unreadable file cannot brick the gate under `mode: hard`. **(6) fleet-intent-glob** — a `globs:` pattern DECLARED as fleet intent goes to `notes[]` (see below), never to `warnings[]`, and the declaration also settles probe 4 for that same pattern: a pattern the rule author declared is by construction not a copy-paste leftover. Glob matching reuses the same picomatch-with-inline-fallback resolution `scripts/lib/rule-loader.mjs` uses (`parseGlobsFrontmatter` is imported directly; the picomatch resolution itself is duplicated locally since `rule-loader.mjs` does not export a public matcher function). The check is skipped silently (no `checks_run` entry, no `checks_skipped` entry) when `.claude/rules/` is absent, or explicitly via `--skip-rule-scoping`.
+
+**Fleet-intent declaration (Check 9, probe 6).** A rule may declare that a `globs:` pattern is aimed at CONSUMER repos rather than this one, via its own frontmatter key `fleet-intent-globs:`. Accepted forms are block style (`fleet-intent-globs:` plus indented `  - "<pattern>"` lines), flow style (`fleet-intent-globs: ["a", "b"]`) and a single inline value; surrounding quotes are stripped, blank and `#` comment lines are ignored. The key is inert for rule loading — `rule-loader.mjs`'s `parseGlobsFrontmatter` skips unknown top-level keys and their continuation lines. A declared pattern is reported in `notes[]` with its file, the pattern, whether it matches `≥1` or `0` tracked files here, and the declaration `source` (`frontmatter`). The grain is per pattern AND per rule file: declaring one glob amnesties neither a sibling glob in the same rule nor the same pattern in another rule. There is deliberately NO checker-side exemption list: a rule that does not declare the pattern itself is not exempt, so the declaration always sits with the rule it describes.
 
 Check 10 (`docs-parity`, issue #780) validates the public docs surface against live repository state via three sub-checks, all reported under the single `docs-parity` check id: **(a) count-claims** — `docs/components.md`'s own heading counts ("## Skills (N user-facing)", "## Commands (N)", "## Agents (N typed sub-agents)", "## Hook event types (N)") are compared against the SAME actual on-disk derivation the surface-count family (Check 5) uses (`countSkills`/the commands-dir listing/`countAgents`/`readHookCounts`) — NOT Check 5's `claimRe` regexes, which are tuned for CLAUDE.md/README prose phrasing and verifiably do not match `components.md`'s own heading convention; a dedicated set of regexes tailored to the doc's actual authored structure is used instead. **(b) config-block-parity** — top-level Session Config keys documented in `docs/session-config-template.md` (opt-in baseline, via the Check 6 'last'-occurrence extractor) are compared against `docs/session-config-reference.md`; a key is considered documented in the reference when it appears in a `yaml` fence (any indent), a `##`/`###`/`####` heading, or the first cell of a markdown table row (`` | `key-name` | ... ``) — the reference's dominant documentation shape is one table row per field, so a naive fence-only extraction under-counts what it actually documents. Missing keys surface as `docs-parity` errors attributed to `docs/session-config-reference.md`. **(c) metrics-path-liveness** — any `.claude/metrics/` path reference (stale; canonical is `.orchestrator/metrics/`) found in root `docs/*.md` or `docs/examples/*.md` surfaces as an error at its exact file/line. The whole check is skipped silently (no `checks_run` entry, no `checks_skipped` entry) when `docs/components.md` is absent, or explicitly via `--skip-docs-parity`.
 
@@ -124,10 +126,15 @@ Environment:
   "warnings": [
     { "check": "<name>", "file": "<relative path>", "line": N, "message": "<human>", "extracted": "<raw text>" }
   ],
+  "notes": [
+    { "check": "rule-scoping", "probe": "fleet-intent-glob", "file": "<relative path>", "line": N, "message": "<human>", "extracted": "<pattern>", "source": "frontmatter" }
+  ],
   "command_count": { "actual": N }
 }
 ```
 
+`notes[]` is the THIRD output category, alongside `errors[]` and `warnings[]`: a finding that is reported but asks for no action. It never affects `status` or the exit code, and it is always present (empty array when nothing was noted, including on the short-circuit "no scope files matched" path). Its only producer today is Check 9's fleet-intent-glob probe.
+
 The `resolved_path` / `resolved_kind` pair surfaces the alias resolution outcome (issue #33 AC2) so users on either platform can audit which instruction file the checker scanned. `kind: 'claude'` for `CLAUDE.md`, `kind: 'agents'` for `AGENTS.md`, `null` when neither was found.
 
 When `command-count` fires a drift error, the error object also carries `"command_count": { "actual": N, "claimed": M }` for easy programmatic diffing.

package/skills/claude-md-drift-check/checker.mjs

@@ -551,6 +551,21 @@ function lookupIssueState(iid, repo, cache, vaultDir) {
 //      of being silently skipped, since a completeness audit that silently
 //      drops files defeats its purpose. WARN, not error — an unreadable file
 //      must not brick the gate under `mode: hard`.
+//   6. fleet-intent-glob → notes[]:    a glob DECLARED as fleet intent in the
+//      rule's own `fleet-intent-globs:` frontmatter key — reported with its
+//      local match count, never warned, and it settles probes 3+4 for that
+//      pattern. See FLEET_INTENT_FM_KEY below.
+//
+// This list is numeric, not a call sequence — the code below does NOT run
+// 1→2→3→4→5→6 in order. Per rule file: probe 5's read-failure guard runs
+// FIRST (it gates every other probe via `continue` on an unreadable file,
+// before probe 1 ever sees the content), then probe 1, then probes 3/4 with
+// probe 6 interleaved INSIDE the same per-pattern loop (it must intercept a
+// declared fleet-intent pattern before 3/4 evaluate it), then probe 2b: once
+// every rule file has been visited, probe 2a runs last over CLAUDE.md/
+// AGENTS.md. `grep -n "Probe [0-9]" checker.mjs` therefore surfaces markers
+// in code order (5, 1, 6, 2b, 2a), not numeric order — that is intentional,
+// not drift; do not "fix" it by moving probe 6's marker next to probe 5's.
 // ───────────────────────────────────────────────────────────────────────────
 
 let _picomatchRuleScoping = null;
@@ -642,6 +657,95 @@ function extractFrontmatterBlockBody(content) {
  * foreign-glob probe's discriminator, per Check 9 spec. */
 const FOREIGN_GLOB_TOKEN_RE = /[A-Z][a-z]+[A-Z]/;
 
+// ───────────────────────────────────────────────────────────────────────────
+// Fleet-intent globs (Probe 6) — an exemption for globs that are DELIBERATELY
+// zero-match in THIS repo because the rule ships to consumer repos with a
+// different language convention.
+//
+// Why this exists: `.claude/rules/testing.md` carries `**/*Tests*` — the
+// Java/C#/Swift test-naming convention. This repo is pure `.mjs`
+// (`*.test.mjs`), so the pattern matches 0 tracked files here and the
+// zero-match probe warned on it on every run. On 2026-09-09 an agent acted on
+// exactly that warning and DELETED the glob; `tests/skills/config-reading-glob-rules.test.mjs`
+// (which pins it as fleet intent, #445) went red and the deletion was reverted
+// coordinator-direct. A warning whose only available action is "click away"
+// trains clicking away — and here it had already caused the removal of the
+// thing it was meant to protect (`.claude/rules/host-resources.md` § HR-101).
+//
+// The fix is CATEGORY SEPARATION, not suppression (`development.md` § Guard &
+// Threshold Design): a declared fleet-intent glob is REPORTED in `notes[]`
+// ("0 local matches, declared fleet intent — in order") instead of being
+// warned about. Nothing is silenced; the finding simply stops asking for an
+// action that does not exist.
+//
+// Declaration lives WITH the rule, as a frontmatter list:
+//
+//   ---
+//   globs:
+//     - "**/*Tests*"
+//   fleet-intent-globs:
+//     - "**/*Tests*"   # Java/C#/Swift convention — matches in consumer repos
+//   ---
+//
+// rule-loader.mjs's parseGlobsFrontmatter ignores unknown top-level keys (and
+// skips their indented continuation lines), so the key is inert for rule
+// loading. The declaration is per-pattern on purpose: marking one glob must
+// never amnesty a genuinely dead sibling glob in the same rule.
+const FLEET_INTENT_FM_KEY = 'fleet-intent-globs';
+
+function stripYamlQuotes(s) {
+  return s.replace(/^["']|["']$/g, '');
+}
+
+/**
+ * Parses the `fleet-intent-globs:` frontmatter key out of a raw frontmatter
+ * block body. Accepts block style (`key:` + indented `  - value` lines),
+ * flow style (`key: ["a", "b"]`) and a single inline value.
+ *
+ * @param {string|null} fmBody - output of extractFrontmatterBlockBody()
+ * @returns {string[]} declared patterns (possibly empty)
+ */
+function parseFleetIntentGlobs(fmBody) {
+  if (!fmBody) return [];
+  const out = [];
+  let inBlock = false;
+  for (const raw of fmBody.split(/\r?\n/)) {
+    const line = raw.replace(/\s+$/, '');
+    if (line === '' || /^\s*#/.test(line)) continue;
+    if (inBlock) {
+      const seq = line.match(/^\s+-\s+(.*)$/);
+      if (seq) { out.push(stripYamlQuotes(seq[1].trim())); continue; }
+      inBlock = false;
+    }
+    if (/^\s/.test(line)) continue; // another block's continuation
+    const colonIdx = line.indexOf(':');
+    if (colonIdx === -1) continue;
+    if (line.slice(0, colonIdx).trim() !== FLEET_INTENT_FM_KEY) continue;
+    const value = line.slice(colonIdx + 1).trim();
+    if (value === '') { inBlock = true; continue; }
+    if (value.startsWith('[') && value.endsWith(']')) {
+      const inner = value.slice(1, -1).trim();
+      if (inner) out.push(...inner.split(',').map((s) => stripYamlQuotes(s.trim())));
+      continue;
+    }
+    out.push(stripYamlQuotes(value));
+  }
+  return out.filter(Boolean);
+}
+
+/**
+ * Resolves whether `pattern` is a declared fleet-intent glob. The rule file's
+ * own `fleet-intent-globs:` frontmatter is the ONLY source — knowledge about a
+ * rule stays with the rule. (The one-entry built-in migration seed for the
+ * #445 `testing.md` / `**\/*Tests*` case was removed once that file declared
+ * the key itself; no checker-side exemption list exists any more.)
+ *
+ * @returns {'frontmatter'|null} declaration source, or null
+ */
+function fleetIntentSource(pattern, declaredSet) {
+  return declaredSet.has(pattern) ? 'frontmatter' : null;
+}
+
 /**
  * Extracts bare `<name>.md` tokens from a "## See Also" footer's body lines,
  * skipping any token that carries a path separator (cross-directory
@@ -819,30 +923,60 @@ function main() {
 
   const errors = [];
   const warnings = [];
+  // Informational findings — never block, never count as a warning. Currently
+  // fed only by rule-scoping's fleet-intent-glob probe (see FLEET_INTENT_FM_KEY
+  // above). Additive JSON key: consumers reading `errors`/`warnings` are
+  // unaffected.
+  const notes = [];
   const issueCache = new Map();
 
   // Check 6: session-config-parity (issue #30) — diff top-level keys under
   // `## Session Config` between the canonical template and the local
   // instruction file.
   //
-  // Severity split (issue #785 follow-up — coordinator triage of the initial
-  // #785 fix): a missing MANDATORY key (present in the template's "Full
-  // minimal baseline" — the 7 schema-enforced keys) is an ERROR. A missing
-  // OPT-IN key (present only in the "Full opt-in baseline" — i.e. NOT in the
-  // minimal block) is a WARNING, not an error: a consumer repo that
-  // legitimately does not adopt an opt-in feature (e.g. no `handover-gate`)
-  // must not go red — this repo's own CLAUDE.md deliberately omits 37
-  // opt-in-baseline keys. `mode: hard` only exits non-zero on `errors[]`, so
-  // pure opt-in gaps never block `autonomous-gated` skill-evolution's
-  // `runConfigValidationGate()`.
+  // Three-category split (issue #30 → #785 → #1356):
+  //   · missing MANDATORY key (present in the template's "Full minimal
+  //     baseline" — the schema-enforced keys) → errors[]   (unchanged)
+  //   · missing OPT-IN key (present only in the "Full opt-in baseline")
+  //     → notes[]                                          (#1356)
+  //   · local key UNKNOWN to the template union → warnings[]  (#1356)
+  //
+  // #785's follow-up put the opt-in gap in `warnings[]`. Measured 2026-09-13
+  // @ ff1ed191 that produced 36 of this repo's 36 config-parity warnings — a
+  // whole warning class firing on every single run, each entry saying "not
+  // required" and offering no action. `.claude/rules/host-resources.md`
+  // § HR-101 calls that a broken instrument; the repair is CATEGORY
+  // SEPARATION, never suppression and never a threshold (`development.md`
+  // § Guard & Threshold Design), exactly as the fleet-intent-glob probe did
+  // for rule-scoping (#1312). So a deliberately-unadopted opt-in feature is
+  // now REPORTED in `notes[]` — still emitted, still rendered (session-end's
+  // drift-operations.md renders `notes[]` under its own heading), but no
+  // longer asking for an action that does not exist.
+  //
+  // What replaces it in `warnings[]` is the direction nothing inspected
+  // before: a top-level key in the LOCAL Session Config that the template's
+  // `## Session Config` blocks do not carry. That one IS actionable — it is
+  // either a typo/rename, or the template's baseline blocks have not caught
+  // up, and both are fixed by an edit.
   //
-  // This is a deliberate, coordinator-directed DEVIATION from #785's literal
-  // fix-direction ("plants an opt-in key... asserts a session-config-parity
-  // ERROR") — the mechanism (union template keys via `{ occurrence: 'last' }`)
-  // is unchanged, but the missing-opt-in-key case now lands in `warnings[]`
-  // instead of `errors[]`. Local keys unknown to the template union were
-  // (and remain) never flagged in either direction — no existing code path
-  // inspected that direction before this change either.
+  // NAME THE POPULATION (fix-pass 2026-09-13). This check reads exactly ONE
+  // population: the template's `## Session Config` blocks. It therefore
+  // CANNOT know whether the key is documented elsewhere in the template, nor
+  // whether anything reads it at runtime — and #1356's first wording asserted
+  // both. Measured 2026-09-13 @ ff1ed191 in this repo, it fired on three keys
+  // and was wrong about two of them:
+  //   awk '/^## /{sec=$0} /^auto-skill-dispatch:|^issue-budget:/{print NR,sec}' \
+  //     docs/session-config-template.md
+  //   → auto-skill-dispatch line 87 (## Auto-Skill Dispatch)
+  //   → issue-budget        line 123 (## Issue Budget)
+  //   rg -c "'auto-skill-dispatch'" scripts/  → 4 files, non-zero
+  //   rg -c "'issue-budget'" scripts/         → non-zero
+  // Both are documented in the template FILE and both are read at runtime;
+  // only their absence from the two `## Session Config` blocks (lines 658/676)
+  // was ever true. The message below now asserts only that.
+  //
+  // `mode: hard`/`strict` still keys off `errors[]` only, so neither notes
+  // nor the new warnings can block `runConfigValidationGate()`.
   let configParityRan = false;
   if (!args.skipSessionConfigParity) {
     const templatePath = args.configTemplate
@@ -887,9 +1021,26 @@ function main() {
               extracted: key,
             });
           } else {
+            notes.push({
+              check: 'session-config-parity', probe: 'opt-in-gap', file: rel, line,
+              message: `Session Config omits opt-in top-level key '${key}' (documented in docs/session-config-template.md's opt-in baseline; not required). Reported, not warned.`,
+              extracted: key,
+            });
+          }
+        }
+        // Actionable direction (#1356): a local top-level key the template
+        // union never documents. Only reachable when the template HAS an
+        // opt-in block distinct from the minimal one — a single-block
+        // template (test fixture, or a repo that never split the baselines)
+        // is not a key catalog, so diffing against it would warn on every
+        // legitimately-adopted key.
+        if (tplMinimalBlock && tplBlock.headingLine !== tplMinimalBlock.headingLine) {
+          const tplKeySet = new Set(tplKeys);
+          for (const key of localKeys) {
+            if (tplKeySet.has(key)) continue;
             warnings.push({
               check: 'session-config-parity', file: rel, line,
-              message: `Session Config omits opt-in top-level key '${key}' (documented in docs/session-config-template.md's opt-in baseline; not required)`,
+              message: `Session Config declares top-level key '${key}' which is absent from both '## Session Config' blocks of docs/session-config-template.md (the only population this check reads) — a typo/rename, or template baseline blocks that have not caught up. This check does not inspect the rest of the template file or any runtime reader, so the key may well be documented elsewhere and in use`,
               extracted: key,
             });
           }
@@ -1127,7 +1278,7 @@ function main() {
 
   // Check 9: rule-scoping — validates .claude/rules/*.md frontmatter against
   // the rule-loader.mjs contract (see the doc-comment above the helper
-  // functions for the five probes, incl. unreadable-file). Silently skipped (no id pushed, no
+  // functions for the six probes, incl. unreadable-file and fleet-intent-glob). Silently skipped (no id pushed, no
   // checksSkipped entry) when .claude/rules/ is absent — mirrors Check 8's
   // silent-skip semantics. `--skip-rule-scoping` disables the whole check.
   if (!args.skipRuleScoping) {
@@ -1149,6 +1300,11 @@ function main() {
         const absPath = join(rulesDir, fname);
         const relPath = relative(vaultDir, absPath);
         let content;
+        // --- Probe 5: unreadable-file → warnings[] ---
+        // Runs BEFORE probe 1 despite its higher number: it is the per-file
+        // guard that must decide whether any other probe gets to see this
+        // file's content at all. See the "Rule-scoping family" header
+        // comment above for why the numbering and the code order differ.
         try {
           content = readFileSync(absPath, 'utf8');
         } catch (err) {
@@ -1190,7 +1346,25 @@ function main() {
         const globs = parsed.globs;
         if (Array.isArray(globs) && globs.length > 0) {
           if (trackedFiles === null) trackedFiles = listTrackedFiles(vaultDir);
+          const declaredFleetIntent = new Set(parseFleetIntentGlobs(fmBody));
           for (const pattern of globs) {
+            // --- Probe 6: fleet-intent-glob → notes[] ---
+            // A DECLARED fleet-intent glob is reported, never warned: it is
+            // zero-match here on purpose and serves consumer repos. The
+            // declaration also settles the foreign-glob probe for the same
+            // pattern — a pattern the rule author declared is by definition
+            // not a copy-paste leftover.
+            const fleetSource = fleetIntentSource(pattern, declaredFleetIntent);
+            if (fleetSource !== null) {
+              const matchesLocally = globMatchesAny(pattern, trackedFiles);
+              notes.push({
+                check: 'rule-scoping', probe: 'fleet-intent-glob', file: relPath, line: 1,
+                message: `glob '${pattern}' matches ${matchesLocally ? '≥1' : '0'} tracked files here and is declared FLEET INTENT (${fleetSource}) — it serves consumer repos with a different language convention. Reported, not warned.`,
+                extracted: pattern,
+                source: fleetSource,
+              });
+              continue;
+            }
             if (!globMatchesAny(pattern, trackedFiles)) {
               warnings.push({
                 check: 'rule-scoping', file: relPath, line: 1,
@@ -1415,7 +1589,7 @@ function main() {
       status: 'skipped', mode: args.mode, vault_dir: vaultDir,
       resolved_path: resolvedPath, resolved_kind: resolvedKind,
       files_scanned: 0, checks_run: checksRun, checks_skipped: checksSkipped,
-      errors, warnings, reason: 'no scope files matched',
+      errors, warnings, notes, reason: 'no scope files matched',
     }) + '\n');
     process.exit(errors.length > 0 && args.mode === 'strict' ? 1 : 0);
   }
@@ -1572,11 +1746,29 @@ function main() {
     files_scanned: scopeFiles.length,
     checks_run: checksRun,
     checks_skipped: checksSkipped,
-    errors, warnings,
+    errors, warnings, notes,
   };
   if (actualCommandCount !== null) {
     result.command_count = { actual: actualCommandCount };
   }
+  // --- notes[] human renderer (#1312) ---
+  // `notes[]` is the REPORT-ONLY category the fleet-intent split created
+  // (.claude/rules/development.md § Guard & Threshold Design: separate the
+  // category, never raise the threshold). Built and returned in the JSON since
+  // that split, it had no renderer — so a note reached no human reader, and an
+  // unread category is the state the split replaced, not a weaker warning.
+  // stdout stays pure JSON (the consumer contract); notes leave on stderr as
+  // diagnostics, under their own heading, and never carry the word "warning"
+  // or "error" — that wording IS the category separation at the output edge.
+  if (notes.length > 0) {
+    process.stderr.write(
+      `NOTES (${notes.length}) \u2014 reported, not warned; no action implied:\n`
+        + notes
+          .map((n) => `  \u00b7 [${n.check}/${n.probe}] ${n.file}:${n.line} \u2014 ${n.message}\n`)
+          .join(''),
+    );
+  }
+
   process.stdout.write(JSON.stringify(result) + '\n');
 
   process.exit(errors.length > 0 && args.mode === 'strict' ? 1 : 0);