session-orchestrator 3.16.0

package/skills/discovery/probes-docs.md

@@ -0,0 +1,76 @@
+> See probes-intro.md for confidence scoring reference.
+
+## Category: `docs`
+
+### Probe: docs-staleness
+
+**Activation:** `docs/` directory present in the repo root **AND** Session Config `docs-staleness.enabled: true`.
+
+**Detection Method:**
+
+```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; }
+
+# 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';
+const cfg = JSON.parse(process.env.SO_CONFIG || '{}');
+const r = await runProbe(process.cwd(), cfg);
+for (const f of r.findings) {
+  console.log('FINDING:', JSON.stringify(f));
+}
+console.log('METRICS:', JSON.stringify(r.metrics));
+if (r.skipped_reason) console.log('SKIPPED:', r.skipped_reason);
+"
+```
+
+**Output:** one `FINDING:` line per finding, one `METRICS:` line per run. Summary JSONL record appended to `.orchestrator/metrics/docs-staleness.jsonl`.
+
+**Default severity:** low (within 2× the `living` threshold), medium (within 3×), high (beyond 3×). mtime-cannot-be-read errors → low.
+
+**Threshold (days):** `living` = 90 (default). Configurable via Session Config `docs-staleness.thresholds.living`; non-numeric or non-positive values fall back to the default.
+
+**Scope:** only `docs/*.md` (root level, non-recursive) and `docs/examples/*.md` are scanned. `docs/adr/` (historically stable, immutable-by-design decision records) and `docs/prd/` (active work-in-progress documents scoped to a project's lifecycle) are deliberately excluded — staleness there is expected and not a defect. Other `docs/` subdirectories are out of scope for this probe.
+
+---
+
+**Config-only gate (no scope token):** `docs-staleness` follows the same pattern as the supply-chain probe — activation is config-gated (`docs-staleness.enabled: true`), not exposed as a `/discovery` `scope` argument value. See `skills/discovery/SKILL.md` Phase 2 marker table and Phase 3 dispatch bullet.
+
+---
+
+### Probe: ssot-code-diff
+
+**Activation:** `CLAUDE.md` or `README.md` present in the repo root. No Session Config gate — this probe always runs when the docs category is dispatched.
+
+**Detection Method:**
+
+```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; }
+
+# 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';
+const cfg = JSON.parse(process.env.SO_CONFIG || '{}');
+const r = await runProbe(process.cwd(), cfg);
+for (const f of r.findings) {
+  console.log('FINDING:', JSON.stringify(f));
+}
+console.log('METRICS:', JSON.stringify(r.metrics));
+if (r.skipped_reason) console.log('SKIPPED:', r.skipped_reason);
+"
+```
+
+**Output:** one `FINDING:` line per finding, one `METRICS:` line per run. Summary JSONL record appended to `.orchestrator/metrics/ssot-code-diff.jsonl`.
+
+**Default severity:** high for the `blocked-commands.json` rule-count registry entry (policy/security-relevant — Destructive-Command Guard); medium for the other three registry entries (`.claude/rules/*.md` count, `skills/` user-facing count, `commands/*.md` count). All findings carry confidence 0.9.
+
+**Threshold:** none (this is an exact-match diff, not a staleness window) — any claimed count that does not equal the live code/filesystem count is a finding.
+
+**Scope:** a deliberately conservative, hand-curated claim registry (v1, four entries) over a fixed small set of known doc sources (`CLAUDE.md`, `AGENTS.md`, `.orchestrator/steering/structure.md`, `skills/hook-development/SKILL.md` for the policy-related entries; `README.md`, `docs/components.md`, `.orchestrator/steering/structure.md` for the inventory entries). `CHANGELOG.md`, `docs/adr/`, `docs/prd/`, and `docs/retro/` are never scanned — same principle as the docs-staleness probe (historical/immutable documents are not "living" claims to re-verify). A missing code/filesystem source (e.g. `blocked-commands.json` absent) gracefully skips that one registry entry only; it never throws.

package/skills/discovery/probes-feature.md

@@ -0,0 +1,150 @@
+> See probes-intro.md for confidence scoring reference.
+
+## Category: `feature`
+
+### Probe: intent-drift
+
+**Activation:** Documentation exists that makes behavioral or security claims (`README*`, `docs/architecture*`, or `docs/**` permission/authz files present).
+
+**Detection Method:**
+
+1. Extract claim sentences from documentation files:
+```bash
+# Grep for claim-marker sentences in docs (behavior/constraint assertions)
+Grep pattern: \b(MUST|always|never|required|enforced|blocks|validates)\b
+  --glob "README*" --glob "docs/architecture*" --glob "docs/**/*permission*"
+  --glob "docs/**/*authz*" --glob "docs/**/*auth*" --glob "!**/CHANGELOG*"
+  --glob "!**/node_modules/**"
+```
+
+2. For each matched sentence, extract the subject/verb phrase immediately around the claim marker (e.g. "requires authentication", "never exposes the service_role key", "blocks unauthenticated requests") and derive candidate code-enforcement tokens from it (e.g. `requireAuth`, `authorize`, `validate`, `guard`, `enforce`, or an identifier named explicitly in the sentence).
+
+3. Direction A — `documented-but-unenforced`: grep source for the derived enforcement token(s):
+```bash
+# Grep source for the enforcement token(s) derived from step 2's claim keyword
+Grep pattern: <derived_token>\s*\(
+  --glob "*.{ts,tsx,js,jsx,mjs,py,go,rs}" --glob "!**/test/**" --glob "!**/tests/**"
+  --glob "!**/fixtures/**" --glob "!**/mocks/**" --glob "!*.test.*" --glob "!*.spec.*"
+```
+Zero matches across the source tree => flag `documented-but-unenforced`. Anchor `file_path`/`line_number` to the DOC line found in step 1 — never to an absent code location — and set `matched_text` to the exact doc sentence.
+
+4. Direction B — `undocumented-but-enforced`: grep source directly for known enforcement call patterns, independent of any doc claim:
+```bash
+# Grep source for enforcement calls that constitute a de-facto contract
+Grep pattern: (requireAuth|checkPermission|assertPermission|authorize|validateInput|enforce\w*)\s*\(
+  --glob "*.{ts,tsx,js,jsx,mjs}" --glob "!**/test/**" --glob "!**/tests/**"
+  --glob "!**/fixtures/**" --glob "!**/mocks/**"
+```
+For each match, search the step 1 doc-claim corpus for the same identifier or an equivalent phrase. Zero matches => flag `undocumented-but-enforced`. Anchor `file_path`/`line_number` to the CODE line and set `matched_text` to the code line containing the enforcement call.
+
+**Evidence Format:**
+```
+Direction: documented-but-unenforced | undocumented-but-enforced
+File: <path> Line: <n>
+Matched Text: <doc claim sentence | code enforcement line>
+Claim Keyword: <matched claim-marker or enforcement token>
+Counterpart: <doc_file:line or code_file:line of the missing counterpart, or NONE>
+```
+
+**Default Severity:** High for security/permission claims (auth, permission, access-control, secret-handling keywords); Medium for general feature/behavior claims.
+
+---
+
+### Probe: stubbed-dead-feature
+
+**Activation:** Any project with source files exposing routes, handlers, or feature-flagged code paths.
+
+**Detection Method:**
+
+1. Not-implemented stubs:
+```bash
+# Grep for explicit not-implemented throws
+Grep pattern: throw\s+.*[Nn]ot\s+[Ii]mplemented
+  --glob "*.{ts,tsx,js,jsx,mjs,py,go,rs}" --glob "!**/test/**" --glob "!**/tests/**"
+  --glob "!**/fixtures/**" --glob "!**/mocks/**" --glob "!*.test.*" --glob "!*.spec.*"
+```
+```bash
+# Grep for TODO-tagged stub returns (placeholder return adjacent to a TODO/implement note)
+Grep pattern: (TODO.*(stub|placeholder|implement)|return\s+(null|undefined|\[\]|\{\})\s*;?\s*//\s*TODO)
+  --glob "*.{ts,tsx,js,jsx,mjs,py,go,rs}" --glob "!**/test/**" --glob "!**/tests/**"
+  --glob "!**/fixtures/**" --glob "!**/mocks/**"
+```
+
+2. Permanently-off feature flags:
+```bash
+# Grep for hardcoded-false flag/config keys
+Grep pattern: (enabled|feature\w*)\s*[:=]\s*false
+  --glob "*.{ts,tsx,js,jsx,mjs,json,yaml,yml}" --glob "!**/test/**" --glob "!**/tests/**"
+  --glob "!**/fixtures/**" --glob "!**/mocks/**"
+```
+For each matched flag/config key name, verify it is never toggled on elsewhere in the codebase:
+```bash
+# Zero matches confirms the flag is permanently off; any match means it is still toggleable -- do not flag
+Grep pattern: <flag_name>\s*[:=]\s*true
+  --glob "*.{ts,tsx,js,jsx,mjs,json,yaml,yml}"
+```
+
+3. Commented-out routes/handlers:
+```bash
+# Grep for commented-out route/handler registrations
+Grep pattern: ^\s*(//|#).*(route|router\.|app\.(get|post|put|delete))
+  --glob "*.{ts,tsx,js,jsx,mjs,py}" --glob "!**/test/**" --glob "!**/tests/**"
+  --glob "!**/fixtures/**" --glob "!**/mocks/**"
+```
+
+**Evidence Format:**
+```
+Type: not-implemented-stub | permanently-off-flag | commented-out-route
+File: <path> Line: <n>
+Matched Text: <matched_text>
+Export Status: exported/public | internal
+```
+
+**Default Severity:** Medium; High when the stub, flag, or commented-out route sits on an exported/public path.
+
+---
+
+### Probe: feature-request-cluster
+
+**Activation:** A VCS platform is configured (`vcs: gitlab` or `vcs: github` in Session Config) — the probe queries the issue tracker directly rather than the source tree, so it activates whenever a VCS remote is resolvable.
+
+**Detection Method:**
+
+1. List open feature/enhancement issues via the VCS CLI (syntax reference: `skills/gitlab-ops/SKILL.md` § "Common CLI Commands" — do not duplicate CLI flags here beyond what's needed to name the call):
+```bash
+# GitLab
+glab issue list --label "feature" --per-page 100
+glab issue list --label "enhancement" --per-page 100
+# GitHub
+gh issue list --label "feature" --limit 100
+gh issue list --label "enhancement" --limit 100
+```
+
+2. Extract theme keywords from each issue's title (and first paragraph of body where available): lowercase, strip stop-words, tokenize on non-alphanumeric boundaries. Group issues that share two or more significant keywords (e.g. "export", "csv", "invoice") into a candidate cluster.
+
+3. For each candidate cluster with 3 or more issues, check whether ANY member issue is already linked to an epic (`epic` label, a GitLab Epic relationship, or an in-body reference such as `part of #<epic-iid>` / `Epic: #<epic-iid>`):
+```bash
+# GitLab -- inspect labels + description for epic linkage
+glab issue view <IID>
+  Grep pattern: (^Labels:.*\bepic\b|part of #|Epic:\s*#)
+# GitHub -- same check against issue body/labels
+gh issue view <NUMBER>
+  Grep pattern: (^labels:.*\bepic\b|part of #|Epic:\s*#)
+```
+
+4. The largest cluster (by issue count) with ZERO epic-linked members is the finding. Ties are broken by the lowest minimum issue number (the oldest cluster wins).
+
+**Evidence Format:**
+```
+Cluster Theme: <shared keyword(s)>
+Location: <comma-separated issue IDs, e.g. #142, #156, #171 -- an issue-ID set, not a file:line>
+Cluster Size: <n>
+Sample Titles: <up to 3 issue titles as evidence>
+verification_method: vcs-issue
+```
+
+**Default Severity:** Medium; High when cluster size >= 5 (a recurring, unaddressed theme at that size signals systemic backlog drift).
+
+---
+
+**Labels for auto-created issues:** `type:discovery`, `area:skills`, `priority:high` (High/Critical severity) or `priority:medium` (Medium severity), `status:ready`.

package/skills/discovery/probes-infra.md

@@ -0,0 +1,138 @@
+> See probes-intro.md for confidence scoring reference.
+
+## Category: `infra`
+
+### Probe: ci-pipeline-health
+
+**Activation:** CI config exists (`.gitlab-ci.yml`, `.github/workflows/`, `Jenkinsfile`, etc.).
+
+**Detection Method:**
+
+```bash
+# GitLab: query recent pipeline status
+glab pipeline list --per-page 10
+
+# GitHub: query recent workflow runs
+gh run list --limit 10
+
+# Parse output for:
+# - Repeated failures (same pipeline failing 3+ times in a row)
+# - Long-running failures (pipeline failed >24h ago with no subsequent success)
+# - Currently failing pipelines
+```
+
+**Evidence Format:**
+```
+Pipeline: <pipeline_id or run_id>
+Status: failed | success
+Duration: <time>
+Failed Since: <timestamp>
+Consecutive Failures: <count>
+```
+
+**Default Severity:** High. Critical if failed >24h with no fix.
+
+---
+
+### Probe: env-config-drift
+
+**Activation:** `.env.example` exists.
+
+**Detection Method:**
+
+```bash
+# Extract keys from .env.example
+grep -E '^\s*[A-Za-z_][A-Za-z0-9_]*\s*=' .env.example | sed 's/=.*//' | sort > /tmp/env_example_keys
+
+# Extract keys from .env (if exists)
+grep -E '^\s*[A-Za-z_][A-Za-z0-9_]*\s*=' .env 2>/dev/null | sed 's/=.*//' | sort > /tmp/env_keys
+
+# Extract keys from .env.local (if exists)
+grep -E '^\s*[A-Za-z_][A-Za-z0-9_]*\s*=' .env.local 2>/dev/null | sed 's/=.*//' | sort > /tmp/env_local_keys
+
+# Keys in .env.example but NOT in .env — missing config
+comm -23 /tmp/env_example_keys /tmp/env_keys
+
+# Keys in .env but NOT in .env.example — undocumented config
+comm -13 /tmp/env_example_keys /tmp/env_keys
+```
+
+**Evidence Format:**
+```
+Key: <ENV_VAR_NAME>
+Status: missing-from-env | undocumented | missing-from-env-local
+Source: .env.example
+```
+
+**Default Severity:** Medium. High if key name contains SECRET, KEY, TOKEN, PASSWORD.
+
+---
+
+### Probe: outdated-dependencies
+
+**Activation:** Package manager detected (`package.json`, `requirements.txt`, `Pipfile`, `Cargo.toml`, `go.mod`).
+
+**Detection Method:**
+
+```bash
+# Node.js
+npm outdated --json 2>/dev/null
+npm audit --json 2>/dev/null
+
+# Python
+pip list --outdated --format=json 2>/dev/null
+pip-audit --format json 2>/dev/null
+
+# Go
+go list -u -m all 2>/dev/null
+
+# Rust
+cargo outdated --format json 2>/dev/null
+cargo audit --json 2>/dev/null
+```
+
+Parse JSON output. Flag:
+- Major version bumps (current major != latest major)
+- Known CVEs from audit output
+
+**Evidence Format:**
+```
+Package: <name>
+Current: <version>
+Latest: <version>
+Bump Type: major | minor | patch
+CVE: <CVE-ID or NONE>
+CVE Severity: <critical|high|medium|low|none>
+```
+
+**Default Severity:** Low (outdated minor/patch), Medium (outdated major), Critical (known CVE).
+
+---
+
+### Probe: deployment-health
+
+**Activation:** `health-endpoints` configured in Session Config.
+
+**Detection Method:**
+
+```bash
+# For each endpoint in health-endpoints:
+curl -s -o /dev/null -w "%{http_code} %{time_total}" <endpoint>
+
+# Flag:
+# - Non-200 status codes
+# - Response time > 2s
+# - Connection timeouts
+```
+
+**Evidence Format:**
+```
+Endpoint: <url>
+Status Code: <code>
+Response Time: <seconds>s
+Healthy: true | false
+```
+
+**Default Severity:** High.
+
+---

package/skills/discovery/probes-intro.md

@@ -0,0 +1,25 @@
+# Discovery Probes Reference
+
+This document defines all discovery probes used by the discovery skill. It is a reference
+document -- not a skill. The main SKILL.md references probes by name and category.
+
+Each probe specifies: activation conditions, exact detection commands, evidence format,
+and default severity. All Grep patterns and Bash commands are copy-pasteable.
+
+## Confidence Scoring Reference
+
+Each probe category has typical confidence factors. Use these as guidance when scoring findings:
+
+**Code probes:** Pattern specificity is the primary driver. Hardcoded secrets (API key regex) score high (+20); generic URL matches score low (+0). Findings in test fixtures or example files always get low file context (+0).
+
+**Infra probes:** CI failures and known CVEs score high (objective, verifiable signals). Outdated minor version bumps score low. Deployment health failures score high.
+
+**UI probes:** WCAG Level A violations (img-no-alt, html-no-lang) score high. Responsive heuristics (fixed widths, absolute positioning) score medium — context-dependent.
+
+**Arch probes:** Circular dependencies with short cycles (2-3 files) score high. Deep nesting in generated/vendored files scores low. Complexity hotspots in frequently-changed files score higher.
+
+**Session probes:** Hallucination checks score high (objective, commit-verifiable). Stale issues with no priority label score low. Gap analysis on planned items scores high.
+
+**Feature probes:** Doc claims with exact enforcement-token matches score high (objective, grep-verifiable); heuristic keyword-to-token guesses score low. Flag-name pattern matches in generated/vendored files score low; hits on exported/public routes score higher.
+
+---