session-orchestrator 4.1.0 → 5.0.0

package/skills/discovery/probes-supply-chain.md

@@ -21,10 +21,12 @@ if (!sources.includes('discovery')) { console.log('SKIPPED: supply-chain-slopche
 "
 
 # Step 2: Run the probe
-test -f skills/discovery/probes/supply-chain-slopcheck.mjs || { echo "SKIPPED: supply-chain-slopcheck -- probe file 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/supply-chain-slopcheck.mjs" || { echo "SKIPPED: supply-chain-slopcheck -- ${PLUGIN_ROOT}/skills/discovery/probes/supply-chain-slopcheck.mjs not found (PLUGIN_ROOT='${PLUGIN_ROOT}'; empty = unresolved, see skills/_shared/config-reading.md)"; exit 0; }
 
 node --input-type=module -e "
-import probe from './skills/discovery/probes/supply-chain-slopcheck.mjs';
+import probe from '${PLUGIN_ROOT}/skills/discovery/probes/supply-chain-slopcheck.mjs';
 const r = await probe({ repoRoot: process.cwd() });
 for (const f of r.findings) {
   console.log('FINDING:', JSON.stringify(f));

package/skills/discovery/probes-ui.md

@@ -79,14 +79,18 @@ Value: <dimension if applicable>
 
 ### Probe: design-drift
 
+> **Naming collision — unresolved (2026-09-11).** This probe, specified below, is agent-based: Pencil MCP tools, qualitative visual comparison, no fixed detection script. GitLab issue #1300 (`projects-baseline` design-first Pencil-token-contract epic, scope item B3-Wrapper) plans `skills/discovery/probes/design-drift.mjs` — a *second*, mechanical, git-only probe under the identical name `design-drift`, sourced from a staleness script in the sibling `projects-baseline` repo — and explicitly proposes replacing this section (lines 79–107 at the time of writing) with that new spec. Whether the two converge, take distinct names, or one supersedes the other is a naming/design decision for whoever implements #1300; it is not decided here. Resolve the name before writing any code against either contract.
+
 **Activation:** Pencil MCP configured in Session Config (`pencil` path provided, e.g. `pencil: designs/app.pen`).
 
 **Detection Method:**
 
 Use Pencil MCP tools to compare design specifications against implementation:
-1. `get_editor_state` -- check current design file
-2. `batch_get` -- retrieve design node properties (colors, spacing, typography)
-3. `get_screenshot` -- capture design frames for visual comparison
+1. `mcp__pencil__get_app_state` -- check current design file
+2. `mcp__pencil__execute` with a Get visitor (depth 1 for top-level frames, depth 2 for their children) -- retrieve design node properties (colors, spacing, typography). Read the execute tool's input schema for the exact visitor shape; `.pen` files are encrypted, so never `Read`/`Grep` them.
+3. `mcp__pencil__browser` -- view/capture design frames for visual comparison (no direct screenshot tool exists on the current surface)
+
+Tool names have one definition in code: `PENCIL_TOOL_NAMES` in `scripts/lib/ux-grill/pencil-coverage.mjs`. The pre-2026 tool surface it replaced no longer exists (dead names enumerated in that module's JSDoc).
 
 Compare against:
 - CSS custom properties / design tokens in codebase
@@ -142,6 +146,6 @@ fpRisk: low | medium | high
 
 **Default Severity:** Per-rule (high for the absolute-ban tells, low for advisory quality nits). `fpRisk` is reported so triage can weight high-FP rules (`ai-purple-gradient`) more skeptically.
 
-> **Precision boundary (honest):** this regex tier cannot resolve CSS cascade, so `side-stripe-border` flags any ≥2px side accent even when the element is unrounded — `.claude/rules/frontend.md` bans those (>1px accent), but a cascade-aware detector would narrow further. The heavier static-HTML + browser tiers are deliberately omitted (cost ≫ value for a probe/hook). See `scripts/lib/frontend-detect/rules.mjs`.
+> **Precision boundary (honest):** this regex tier cannot resolve CSS cascade, so `side-stripe-border` flags any ≥2px side accent even when the element is unrounded — `rules/opt-in-stack/frontend.md` bans those (>1px accent), but a cascade-aware detector would narrow further. The heavier static-HTML + browser tiers are deliberately omitted (cost ≫ value for a probe/hook). See `scripts/lib/frontend-detect/rules.mjs`.
 
 ---

package/skills/discovery/probes-vault.md

@@ -10,12 +10,14 @@
 
 ```bash
 # Step 1: Verify the probe exists; skip if missing
-test -f skills/discovery/probes/vault-staleness.mjs || { echo "SKIPPED: vault-staleness -- skills/discovery/probes/vault-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/vault-staleness.mjs" || { echo "SKIPPED: vault-staleness -- ${PLUGIN_ROOT}/skills/discovery/probes/vault-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 vault-integration.vault-dir from $CONFIG
 # (passed from the discovery skill) and scans the vault.
 node --input-type=module -e "
-import {runProbe} from './skills/discovery/probes/vault-staleness.mjs';
+import {runProbe} from '${PLUGIN_ROOT}/skills/discovery/probes/vault-staleness.mjs';
 const cfg = JSON.parse(process.env.SO_CONFIG || '{}');
 const r = await runProbe(process.cwd(), cfg);
 for (const f of r.findings) {
@@ -30,6 +32,10 @@ if (r.skipped_reason) console.log('SKIPPED:', r.skipped_reason);
 
 **Default severity:** low (<7d delta), medium (≥7d delta). Missing frontmatter fields → low.
 
+**Denominator:** staleness is `lastCommit - lastSync` — both read from the same `_overview.md` frontmatter — never `now - lastSync`. An overview without `lastCommit` falls back to the probe runtime (`basis: 'probe-runtime'` in the evidence, lower confidence).
+
+**Passive skip (#1238):** a `01-projects/<slug>/` carrying a `_passive.md` marker is skipped BEFORE any staleness comparison — it is excluded from `scanned_projects` and counted instead in `metrics.passive_skipped` — the SAME key in the in-memory metrics and in the JSONL record — so the skip is visible rather than indistinguishable from a healthy project. The marker is checked before the `_overview.md` existence test, so a passive folder without an overview is counted too rather than falling into the silent non-project branch.
+
 ---
 
 ### Probe: vault-narrative-staleness
@@ -39,10 +45,12 @@ if (r.skipped_reason) console.log('SKIPPED:', r.skipped_reason);
 **Detection Method:**
 
 ```bash
-test -f skills/discovery/probes/vault-narrative-staleness.mjs || { echo "SKIPPED: vault-narrative-staleness -- probe file 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/vault-narrative-staleness.mjs" || { echo "SKIPPED: vault-narrative-staleness -- ${PLUGIN_ROOT}/skills/discovery/probes/vault-narrative-staleness.mjs not found (PLUGIN_ROOT='${PLUGIN_ROOT}'; empty = unresolved, see skills/_shared/config-reading.md)"; exit 0; }
 
 node --input-type=module -e "
-import {runProbe} from './skills/discovery/probes/vault-narrative-staleness.mjs';
+import {runProbe} from '${PLUGIN_ROOT}/skills/discovery/probes/vault-narrative-staleness.mjs';
 const cfg = JSON.parse(process.env.SO_CONFIG || '{}');
 const r = await runProbe(process.cwd(), cfg);
 for (const f of r.findings) {

package/skills/discovery/references/discovery-interactive-triage.md

@@ -0,0 +1,139 @@
+# Discovery — Phase 5: Interactive Triage (Standalone Mode Only)
+
+> Reference of the `discovery` 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.
+
+## Phase 5: Interactive Triage (Standalone Mode Only)
+
+### 5.0 Load Triage State & Partition Findings
+
+Before auto-defer and before presenting any findings for triage, load the persistent discovery triage state and filter findings through it:
+
+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" }
+    ]
+  }]
+})
+```
+

package/skills/discovery/references/discovery-triage-state.md

@@ -0,0 +1,54 @@
+# Discovery — Discovery Triage State (#419)
+
+> Reference of the `discovery` 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.
+
+## 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.
+
+### Module
+
+`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}`
+

package/skills/docs-orchestrator/audience-mapping.md

@@ -8,7 +8,7 @@ Rules for mapping session scope to target audiences, content sources, and docume
 
 | Audience | Target files (globs) | Typical update triggers |
 |----------|----------------------|-------------------------|
-| User | `README.md`, `docs/user/**/*.md`, `docs/getting-started.md`, `examples/**/*.md` | new CLI command, breaking API change, install flow change, new user-facing feature, changed example output |
+| User | `README.md`, `docs/user/**/*.md`, `docs/getting-started.md`, `examples/**/*.md` | new CLI command, breaking API change, install flow change, new user-facing feature, changed example output <!-- path-check: example --> |
 | Dev | `CLAUDE.md` (or `AGENTS.md` on Codex CLI), `docs/dev/**/*.md`, `docs/adr/**/*.md` | architecture decision, major refactor, new module/subsystem, test coverage change, dependency upgrade, ADR-worthy choice |
 | Vault/Ops | `<vault>/01-projects/<slug>/context.md`, `<vault>/01-projects/<slug>/decisions.md`, `<vault>/01-projects/<slug>/people.md` | project status change, ownership transition, stack/infra decision, cross-project dependency, migration, archival event |
 

package/skills/eval/rubric-v1.md

@@ -126,6 +126,19 @@ full-gate quality_gate events + `record.total_waves` / `record.waves`.
 | `≥1` full-gate event in window; the **last by timestamp** has `exit_code === 0` | `pass` |
 | `≥1` full-gate event in window; the **last by timestamp** has `exit_code !== 0` | `fail` |
 
+Clarification, not a formula change: a record whose waves are **all**
+coordinator-direct `Housekeeping` waves (the session-end writer rule since
+#1321; predicate `isCoordinatorDirectHousekeeping` in
+`scripts/lib/session-schema/filters.mjs`) counts as "no waves ran". The
+decision keys on that wave shape only, never on `session_type`: a housekeeping
+session that ran real waves stays `cannot-determine`. No record written before
+#1321 has that shape. Measured 2026-09-12 on the working copy (the ledger is
+gitignored, so no commit pins it): `jq -s
+'[.[]|select((.waves|type)=="array" and (.waves|length)>0 and
+all(.waves[]; .role=="Housekeeping" and .coordinator_direct==true))]|length'
+.orchestrator/metrics/sessions.jsonl` → `0` of 427 records. So no historical
+verdict changes, and `RUBRIC_VERSION` stays `rubric-v1`.
+
 Scorer: `scoreGateHealth`. No `score` field.
 
 ### 4. `process-safety`