session-orchestrator 4.1.0 → 5.0.0

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);

package/skills/discovery/SKILL.md

@@ -294,137 +294,11 @@ Present both as structured data in your final output. Do not proceed to Phase 5.
 
 ## Phase 5: Interactive Triage (Standalone Mode Only)
 
-### 5.0 Load Triage State & Partition Findings
+Loads persistent triage state, partitions findings into auto-deferred/high-confidence buckets, and walks the user through Critical/High findings individually and Medium/Low findings in a batch before Phase 6 issue creation.
 
-Before auto-defer and before presenting any findings for triage, load the persistent discovery triage state and filter findings through it:
+See [references/discovery-interactive-triage.md](references/discovery-interactive-triage.md).
 
-1. Call `loadTriageState()` from `scripts/lib/discovery/triage-state.mjs` (uses default path `.orchestrator/metrics/discovery-triage.jsonl`). Returns an empty Map if the file does not exist — no error.
-2. Call `filterFindings({ findings: verifiedFindings, stateMap })` to partition findings into three buckets:
-   - `toShow` — state is `open`, `reopened`, or **no prior state entry** (new findings — present for user triage)
-   - `suppressed` — state is `dismissed` or `accepted-as-known` (skip silently)
-   - `tracked` — state is `promoted-to-#NNN` (issue already filed; show as informational)
-
-3. Emit a one-line state banner before the summary table:
-   ```
-   Triage state: [N suppressed] suppressed (dismissed/accepted-as-known), [N tracked] tracked in existing issues. Presenting [N toShow] findings.
-   ```
-   Omit the banner entirely if all three counts are zero (first run).
-
-4. Render `tracked` findings as informational lines in the summary — NOT as interactive triage items:
-   ```
-   [INFO] Finding "<title>" (<file_path>) is tracked in #<issue_id> — not re-triaged.
-   ```
-
-5. Continue Phase 5 triage using only `toShow` findings. The `suppressed` bucket requires no user interaction.
-
-6. After the user completes triage (Steps 1-4 below), append state changes to `.orchestrator/metrics/discovery-triage.jsonl` via `appendTriageEntry()` from `triage-state.mjs`:
-   - User selects "Create issue" → append `{ fingerprint, state: 'promoted-to-#<issue_id>', issue_id: <N>, timestamp, session_id }`
-   - User selects "Dismiss -- intentional" or "Dismiss -- false positive" → append `{ fingerprint, state: 'dismissed', user_decision: '<reason>', timestamp, session_id }`
-   - User selects "Accept all" for batch → append one `{ fingerprint, state: 'open', ... }` entry per finding (so they re-appear next run if not yet promoted)
-
-### 5.1 Auto-Defer Low-Confidence Findings
-
-Before presenting findings for triage, separate by confidence threshold:
-
-1. Findings with confidence >= threshold → present for interactive triage (below)
-2. Findings with confidence < threshold → auto-defer with summary:
-   "Auto-deferred [N] low-confidence findings (score < [threshold]). Review with `/discovery --include-deferred`."
-3. List auto-deferred findings in a collapsed section (not interactive — informational only)
-
-### 5.1 Present High-Confidence Findings
-
-Present findings using AskUserQuestion -- NEVER plain text options. On Codex CLI where AskUserQuestion is unavailable, present as numbered Markdown lists.
-
-Include confidence scores in the presentation:
-```
-[CRITICAL] (confidence: 85) hardcoded-values: API key found in src/config.ts:42
-[HIGH] (confidence: 72) security-basics: eval() usage in src/utils/parser.ts:18
-[MEDIUM] (confidence: 61) orphaned-annotations: TODO without issue in src/lib/auth.ts:55
-```
-
-### Step 1: Summary
-
-Present a findings overview table:
-
-```
-## Discovery Results
-
-Probes run: [N] | Findings verified: [N] | False positives discarded: [N]
-
-| Category | Critical | High | Medium | Low | Total |
-|----------|----------|------|--------|-----|-------|
-| Code     | ...      | ...  | ...    | ... | ...   |
-| Infra    | ...      | ...  | ...    | ... | ...   |
-| UI       | ...      | ...  | ...    | ... | ...   |
-| Arch     | ...      | ...  | ...    | ... | ...   |
-| Session  | ...      | ...  | ...    | ... | ...   |
-| Audit    | ...      | ...  | ...    | ... | ...   |
-| Vault    | ...      | ...  | ...    | ... | ...   |
-| Feature  | ...      | ...  | ...    | ... | ...   |
-```
-
-### Step 2: Critical + High Findings -- Review Individually
-
-For each Critical or High finding, use AskUserQuestion (on Codex CLI where AskUserQuestion is unavailable, present as numbered Markdown lists):
-
-```
-AskUserQuestion({
-  questions: [{
-    question: "<severity> finding in <file_path> — what should happen with it?",
-    header: "Finding",
-    options: [
-      { label: "Create issue (<severity>)", description: "Files it as priority::<severity>, so it is tracked outside this session. The code below is copied into the issue body.",
-        preview: "<finding title>\n\n<file_path>:<line_number>\n```\n<matched_text with +/-3 lines context>\n```\n\n<description>\n\nRecommended fix: <recommended_fix>" },
-      { label: "Adjust priority", description: "Same issue, a priority you pick — this question then comes back with the new label." },
-      { label: "Dismiss -- intentional", description: "The code is deliberate. Nothing is filed, and the finding stays only in this run's report." },
-      { label: "Dismiss -- false positive", description: "The probe misread the code. Nothing is filed; worth reporting if the same probe misfires again." }
-    ],
-    multiSelect: false
-  }]
-})
-```
-
-If user selects "Adjust priority", ask which priority with another AskUserQuestion. On Codex CLI where AskUserQuestion is unavailable, present as numbered Markdown lists.
-
-### Step 3: Medium + Low Findings -- Review Batched
-
-Group remaining findings by category. For each category with medium/low findings (on Codex CLI where AskUserQuestion is unavailable, present as numbered Markdown lists):
-
-```
-AskUserQuestion({
-  questions: [{
-    question: "Create issues for all [N] medium/low findings in [category]?",
-    header: "Findings",
-    options: [
-      { label: "Accept all (Recommended)", description: "Medium and low findings are cheap to file and cheap to close. Cost: [N] issues, roughly one second apart.",
-        preview: "1. [title] -- [file_path]:[line] ([severity])\n2. [title] -- [file_path]:[line] ([severity])\n..." },
-      { label: "Review individually", description: "One question per finding, same options as the critical ones. Cost: [N] more prompts." },
-      { label: "Dismiss all", description: "Nothing is filed for this category. The findings stay in this run's report only." }
-    ],
-    multiSelect: false
-  }]
-})
-```
-
-If "Review individually" selected, walk through each like Step 2.
-
-### Step 4: Batch Confirmation
-
-Before creating any issues (on Codex CLI where AskUserQuestion is unavailable, present as numbered Markdown lists):
-
-```
-AskUserQuestion({
-  questions: [{
-    question: "Ready to create [N] issues?\n\n- [X] critical\n- [Y] high\n- [Z] medium\n- [W] low",
-    header: "Confirm",
-    options: [
-      { label: "Create all [N] issues", description: "Proceed with issue creation" },
-      { label: "Review list first", description: "Show full list before creating" },
-      { label: "Cancel", description: "Do not create any issues" }
-    ]
-  }]
-})
-```
+**Read WHEN:** running in standalone mode (not embedded mode — see Phase 4.6 Embedded Mode Exit above), after Phase 4 scoring completes.
 
 ## Phase 6: Issue Creation & Report
 
@@ -515,52 +389,11 @@ After Phase 6 (Issue Creation) completes, prepare discovery statistics for sessi
 
 ## Discovery Triage State (#419)
 
-Persistent triage state prevents re-presenting the same finding on every `/discovery` run. State is stored in an append-only JSONL file and keyed by a stable fingerprint.
-
-### State File
-
-**Location:** `.orchestrator/metrics/discovery-triage.jsonl` (gitignored via `.orchestrator/metrics/*.jsonl` pattern — machine-local, never committed)
-
-**Format:** One JSON object per line:
-```json
-{"fingerprint":"aabb1122ccdd3344","state":"dismissed","user_decision":"intentional — debug log","timestamp":"2026-05-17T10:00:00.000Z","session_id":"deep-2"}
-{"fingerprint":"eeff5566aabb7788","state":"promoted-to-#119","issue_id":119,"timestamp":"2026-05-17T10:01:00.000Z","session_id":"deep-2"}
-```
-
-### Fingerprint
-
-`computeFingerprint({probe, file, severity, ruleId})` → 16-char hex (sha256 prefix).
-
-`line_number` is **intentionally excluded** — it drifts on refactoring without the underlying issue changing. A finding is considered "the same" as long as the probe, file path, severity, and ruleId match.
-
-### State Enum
-
-| State | Meaning |
-|---|---|
-| `open` | Actively needs triage or was explicitly marked for re-review |
-| `dismissed` | User dismissed as intentional or false positive — suppressed on future runs |
-| `accepted-as-known` | Known issue, accepted without creating a VCS issue — suppressed on future runs |
-| `reopened` | Previously suppressed but re-surfaced by user decision — shown again |
-| `promoted-to-#NNN` | VCS issue created; shown informational ("tracked in #NNN") on future runs |
-
-### Re-run Semantics
-
-On each `/discovery` run, Phase 5 loads the state file and partitions findings before presenting them:
-
-- **New findings** (no fingerprint entry) → always shown
-- **`open` or `reopened`** → shown for triage
-- **`dismissed` or `accepted-as-known`** → suppressed (silent — no user interaction needed)
-- **`promoted-to-#NNN`** → informational line only ("tracked in #NNN")
-
-A suppressed finding re-appears only if its fingerprint changes — i.e., the probe, file path, severity, or ruleId changes. No TTL on dismissed state.
+The JSONL schema (`.orchestrator/metrics/discovery-triage.jsonl`), fingerprint derivation, state enum (`open`/`dismissed`/`accepted-as-known`/`reopened`), re-run semantics, and the `scripts/lib/discovery/triage-state.mjs` module API that Phase 5 above reads and writes.
 
-### Module
+See [references/discovery-triage-state.md](references/discovery-triage-state.md).
 
-`scripts/lib/discovery/triage-state.mjs` — pure ESM, Node stdlib only. Exports:
-- `computeFingerprint({probe, file, severity, ruleId}): string`
-- `loadTriageState(stateFilePath?): Promise<Map<fingerprint, entry>>`
-- `appendTriageEntry(stateFilePath, entry): Promise<void>`
-- `filterFindings({findings, stateMap}): {toShow, suppressed, tracked}`
+**Read WHEN:** implementing or debugging Phase 5 triage persistence, or investigating why a finding was suppressed/re-shown across runs.
 
 ## Anti-Patterns
 

package/skills/discovery/probes/vault-staleness.mjs

@@ -21,6 +21,15 @@
  * reported "stale", 26 of them >7d, with a demonstrably healthy sync chain —
  * because the clock, not the repo, was the denominator.
  *
+ * Passive projects (GitLab #1238 point 2): a `01-projects/<slug>/` carrying a
+ * `_passive.md` marker is one nobody syncs on purpose (vault convention
+ * `_meta/conventions.md`; the same marker is already honoured by
+ * `scripts/lib/context-coverage-banner.mjs` via its `COVERAGE_FILES` check).
+ * Such a folder is skipped BEFORE any staleness comparison and counted in
+ * `metrics.passive_skipped`, so the skip is visible rather than silent — a probe
+ * that quietly ignored folders would be indistinguishable from one that found
+ * them healthy.
+ *
  * Fallback: an overview WITHOUT `lastCommit` carries no repo-activity signal at
  * all, so the wall-clock comparison is the only thing left. It is retained for
  * that case only, marked `basis: 'probe-runtime'` in the evidence and carried at
@@ -67,6 +76,12 @@ function parseFrontmatter(text) {
 // Helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Marker file that declares a `01-projects/<slug>/` deliberately un-synced.
+ * Same filename `scripts/lib/context-coverage-banner.mjs` accepts as coverage.
+ */
+const PASSIVE_MARKER = '_passive.md';
+
 const HOURS_24 = 24 * 60 * 60 * 1000;
 const HOURS_168 = 7 * 24 * 60 * 60 * 1000; // 7 days
 
@@ -89,7 +104,7 @@ export async function runProbe(projectRoot, config) {
 
   const makeSkip = (skipped_reason) => ({
     findings: [],
-    metrics: { scanned_projects: 0, stale_count: 0, errors: 0 },
+    metrics: { scanned_projects: 0, stale_count: 0, errors: 0, passive_skipped: 0 },
     duration_ms: Math.round(Date.now() - start),
     skipped_reason,
   });
@@ -114,7 +129,7 @@ export async function runProbe(projectRoot, config) {
     // --- Scan loop ---
 
     const findings = [];
-    const metrics = { scanned_projects: 0, stale_count: 0, errors: 0 };
+    const metrics = { scanned_projects: 0, stale_count: 0, errors: 0, passive_skipped: 0 };
     const now = Date.now();
 
     let entries;
@@ -129,7 +144,7 @@ export async function runProbe(projectRoot, config) {
           description: err.message,
           evidence: {},
         }],
-        metrics: { scanned_projects: 0, stale_count: 0, errors: 1 },
+        metrics: { scanned_projects: 0, stale_count: 0, errors: 1, passive_skipped: 0 },
         duration_ms: Math.round(Date.now() - start),
         error: err.message,
       };
@@ -138,7 +153,21 @@ export async function runProbe(projectRoot, config) {
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
 
-      const overviewPath = join(projectsDir, entry.name, '_overview.md');
+      const projectDir = join(projectsDir, entry.name);
+
+      // #1238 point 2 — a `_passive.md` marker means "nobody syncs this on
+      // purpose". Skipped before any comparison, but COUNTED so the skip shows
+      // up in the metrics instead of looking like a healthy project. Checked
+      // BEFORE the `_overview.md` existence test: a passive folder that carries
+      // no overview is still a deliberate skip, and the earlier ordering dropped
+      // it into the silent non-project branch, under-reporting the metric. The
+      // finding population is unchanged either way — neither branch can emit one.
+      if (existsSync(join(projectDir, PASSIVE_MARKER))) {
+        metrics.passive_skipped++;
+        continue;
+      }
+
+      const overviewPath = join(projectDir, '_overview.md');
       if (!existsSync(overviewPath)) continue; // non-project dir, skip silently
 
       metrics.scanned_projects++;
@@ -254,6 +283,7 @@ export async function runProbe(projectRoot, config) {
       scanned_projects: metrics.scanned_projects,
       stale_count: metrics.stale_count,
       errors: metrics.errors,
+      passive_skipped: metrics.passive_skipped,
       duration_ms,
       findings: findings.map(f => ({
         slug: f.evidence.slug,
@@ -286,7 +316,7 @@ export async function runProbe(projectRoot, config) {
         description: err.message,
         evidence: {},
       }],
-      metrics: { scanned_projects: 0, stale_count: 0, errors: 1 },
+      metrics: { scanned_projects: 0, stale_count: 0, errors: 1, passive_skipped: 0 },
       duration_ms: Math.round(Date.now() - start),
       error: err.message,
     };

package/skills/discovery/probes-docs.md

@@ -10,13 +10,15 @@
 
 ```bash
 # Step 1: Verify the probe exists; skip if missing
-test -f skills/discovery/probes/docs-staleness.mjs || { echo "SKIPPED: docs-staleness -- skills/discovery/probes/docs-staleness.mjs not found"; exit 0; }
+# Probes live in the PLUGIN, not the project: ${PLUGIN_ROOT} is resolved per
+# skills/_shared/config-reading.md. The probe still scans process.cwd() (project root).
+test -f "${PLUGIN_ROOT}/skills/discovery/probes/docs-staleness.mjs" || { echo "SKIPPED: docs-staleness -- ${PLUGIN_ROOT}/skills/discovery/probes/docs-staleness.mjs not found (PLUGIN_ROOT='${PLUGIN_ROOT}'; empty = unresolved, see skills/_shared/config-reading.md)"; exit 0; }
 
 # Step 2: Run the probe. It reads docs-staleness.thresholds.living from $CONFIG
 # (passed from the discovery skill) and scans docs/*.md (root level) +
 # docs/examples/*.md for filesystem-mtime staleness.
 node --input-type=module -e "
-import {runProbe} from './skills/discovery/probes/docs-staleness.mjs';
+import {runProbe} from '${PLUGIN_ROOT}/skills/discovery/probes/docs-staleness.mjs';
 const cfg = JSON.parse(process.env.SO_CONFIG || '{}');
 const r = await runProbe(process.cwd(), cfg);
 for (const f of r.findings) {
@@ -49,14 +51,16 @@ if (r.skipped_reason) console.log('SKIPPED:', r.skipped_reason);
 
 ```bash
 # Step 1: Verify the probe exists; skip if missing
-test -f skills/discovery/probes/ssot-code-diff.mjs || { echo "SKIPPED: ssot-code-diff -- skills/discovery/probes/ssot-code-diff.mjs not found"; exit 0; }
+# Probes live in the PLUGIN, not the project: ${PLUGIN_ROOT} is resolved per
+# skills/_shared/config-reading.md. The probe still scans process.cwd() (project root).
+test -f "${PLUGIN_ROOT}/skills/discovery/probes/ssot-code-diff.mjs" || { echo "SKIPPED: ssot-code-diff -- ${PLUGIN_ROOT}/skills/discovery/probes/ssot-code-diff.mjs not found (PLUGIN_ROOT='${PLUGIN_ROOT}'; empty = unresolved, see skills/_shared/config-reading.md)"; exit 0; }
 
 # Step 2: Run the probe. It reads no config keys — it diffs a hand-curated
 # registry of doc "count" claims (blocked-commands.json rules, .claude/rules/
 # file count, skills/ user-facing directory count, commands/ file count)
 # against the live code/filesystem value each claim describes.
 node --input-type=module -e "
-import {runProbe} from './skills/discovery/probes/ssot-code-diff.mjs';
+import {runProbe} from '${PLUGIN_ROOT}/skills/discovery/probes/ssot-code-diff.mjs';
 const cfg = JSON.parse(process.env.SO_CONFIG || '{}');
 const r = await runProbe(process.cwd(), cfg);
 for (const f of r.findings) {