session-orchestrator 3.16.0

package/skills/discovery/issue-templates.md

@@ -0,0 +1,237 @@
+# Issue Templates for Discovery Findings
+
+Templates used by the discovery skill when creating VCS issues from probe findings.
+References the label taxonomy from the gitlab-ops skill.
+
+---
+
+## Labels
+
+Discovery findings use the following labels from the gitlab-ops label taxonomy:
+
+- **Type:** `type:discovery`
+- **Priority:** `priority:critical` | `priority:high` | `priority:medium` | `priority:low` (mapped from probe severity)
+- **Area:** `area:frontend` | `area:backend` | `area:security` | `area:testing` | `area:ci` | `area:infrastructure` (mapped from probe category)
+- **Status:** `status:ready`
+
+### Category-to-Area Mapping
+
+| Probe Category | Default Area Label |
+|---|---|
+| `code` | `area:backend` (or `area:frontend` if file is in UI paths) |
+| `infra` | `area:infrastructure` (or `area:ci` for pipeline probes) |
+| `ui` | `area:frontend` |
+| `arch` | `area:backend` |
+| `session` | (no area label -- session-scoped) |
+
+### Severity-to-Priority Mapping
+
+| Probe Severity | Priority Label |
+|---|---|
+| Critical | `priority:critical` |
+| High | `priority:high` |
+| Medium | `priority:medium` |
+| Low | `priority:low` |
+
+---
+
+## Template 1: Discovery Finding (Individual)
+
+Used for a single finding from a single probe.
+
+```
+## [Discovery] <finding_title>
+
+**Probe:** `<probe_name>` (`<category>`)
+**Severity:** <priority_level>
+**Detected:** <date>
+
+### Finding
+
+<description of what was detected and why it matters>
+
+### Evidence
+
+- **File:** `<file_path>`
+- **Line:** <line_number>
+- **Code:**
+```<lang>
+<matched_text with surrounding context>
+```
+
+### Impact
+
+<concrete explanation of the risk or technical debt this introduces>
+
+### Recommended Fix
+
+<specific, actionable fix suggestion with code example if applicable>
+
+### Acceptance Criteria
+
+- [ ] <verifiable condition that confirms the fix>
+- [ ] No new instances of this pattern introduced
+- [ ] Quality gates pass after fix
+```
+
+**Labels:** `type:discovery`, `priority:<level>`, `area:<area>`, `status:ready`
+
+**CLI Example:**
+```bash
+# GitHub
+gh issue create \
+  --title "[Discovery] <finding_title>" \
+  --label "type:discovery,priority:<level>,area:<area>,status:ready" \
+  --body "$(cat <<'EOF'
+<template body filled in>
+EOF
+)"
+
+# GitLab
+glab issue create \
+  --title "[Discovery] <finding_title>" \
+  --label "type:discovery,priority:<level>,area:<area>,status:ready" \
+  --description "$(cat <<'EOF'
+<template body filled in>
+EOF
+)"
+```
+
+---
+
+## Template 2: Batch Discovery Report
+
+Used when multiple related findings from the same probe or category are grouped into a single issue.
+
+```
+## [Discovery] <category> audit: <summary>
+
+**Probes:** <comma-separated probe names>
+**Findings:** <total_count> (<critical_count> critical, <high_count> high, <medium_count> medium, <low_count> low)
+**Detected:** <date>
+
+### Summary
+
+<overview of what was found and the overall health assessment for this category>
+
+### Findings
+
+#### Critical
+
+| # | File | Line | Description |
+|---|---|---|---|
+| 1 | `<path>` | <n> | <brief description> |
+
+#### High
+
+| # | File | Line | Description |
+|---|---|---|---|
+| 1 | `<path>` | <n> | <brief description> |
+
+#### Medium
+
+| # | File | Line | Description |
+|---|---|---|---|
+| 1 | `<path>` | <n> | <brief description> |
+
+#### Low
+
+| # | File | Line | Description |
+|---|---|---|---|
+| 1 | `<path>` | <n> | <brief description> |
+
+### Recommended Actions
+
+1. **Immediate** (critical/high): <action items>
+2. **Next Sprint** (medium): <action items>
+3. **Backlog** (low): <action items>
+
+### Acceptance Criteria
+
+- [ ] All critical findings resolved
+- [ ] All high findings resolved or have tracking issues
+- [ ] No regressions introduced
+- [ ] Quality gates pass after fixes
+```
+
+**Labels:** `type:discovery`, `priority:<highest_severity_found>`, `area:<area>`, `status:ready`
+
+**CLI Example:**
+```bash
+# GitHub
+gh issue create \
+  --title "[Discovery] <category> audit: <summary>" \
+  --label "type:discovery,priority:<level>,area:<area>,status:ready" \
+  --body "$(cat <<'EOF'
+<template body filled in>
+EOF
+)"
+
+# GitLab
+glab issue create \
+  --title "[Discovery] <category> audit: <summary>" \
+  --label "type:discovery,priority:<level>,area:<area>,status:ready" \
+  --description "$(cat <<'EOF'
+<template body filled in>
+EOF
+)"
+```
+
+---
+
+## Template 3: Discovery Session Summary
+
+Used as a comment or standalone issue to summarize a full discovery run across all categories.
+
+```
+## [Discovery] Session Summary — <date>
+
+### Run Configuration
+
+- **Categories scanned:** <list>
+- **Probes executed:** <count>
+- **Probes skipped:** <count> (activation conditions not met)
+- **Total findings:** <count>
+
+### Results by Category
+
+| Category | Probes Run | Critical | High | Medium | Low | Total |
+|---|---|---|---|---|---|---|
+| code | <n> | <n> | <n> | <n> | <n> | <n> |
+| infra | <n> | <n> | <n> | <n> | <n> | <n> |
+| ui | <n> | <n> | <n> | <n> | <n> | <n> |
+| arch | <n> | <n> | <n> | <n> | <n> | <n> |
+| session | <n> | <n> | <n> | <n> | <n> | <n> |
+| audit | <n> | <n> | <n> | <n> | <n> | <n> |
+| vault | <n> | <n> | <n> | <n> | <n> | <n> |
+| feature | <n> | <n> | <n> | <n> | <n> | <n> |
+| **Total** | **<n>** | **<n>** | **<n>** | **<n>** | **<n>** | **<n>** |
+
+### Issues Created
+
+| Issue | Title | Severity | Category |
+|---|---|---|---|
+| #<n> | <title> | <severity> | <category> |
+
+### Skipped Probes
+
+| Probe | Reason |
+|---|---|
+| <probe_name> | <activation condition not met> |
+
+### Health Score
+
+**Overall: <score>/100**
+
+Scoring: Start at 100, deduct per finding:
+- Critical: -15 points each
+- High: -8 points each
+- Medium: -3 points each
+- Low: -1 point each
+- Minimum score: 0
+```
+
+**Notes:**
+- This template is for reporting, not for issue creation (though it can be posted as an issue if the user requests it)
+- The health score provides a quick at-a-glance metric for codebase quality
+- Skipped probes are listed for transparency so users know what was not checked

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

@@ -0,0 +1,195 @@
+/**
+ * skills/discovery/probes/docs-staleness.mjs
+ *
+ * Probe: detects stale "living" docs — direct `docs/*.md` files plus
+ * `docs/examples/*.md` files whose filesystem mtime is older than the
+ * `docs-staleness.thresholds.living` config threshold (default 90 days).
+ *
+ * Deliberately excludes `docs/adr/` (historically stable, immutable-by-design
+ * decision records — staleness is expected and desired) and `docs/prd/`
+ * (active work-in-progress documents scoped to a project's lifecycle, not
+ * "living reference docs"). Only the two directories named above are
+ * scanned; other docs/ subdirectories (audit, research, spikes, ...) are
+ * intentionally out of scope for this probe.
+ *
+ * Unlike the vault-narrative-staleness probe, staleness here is measured via
+ * filesystem mtime, not a YAML frontmatter `updated:` field — most repo docs
+ * under docs/ carry no frontmatter at all.
+ *
+ * Severity escalation relative to threshold T (in days):
+ *   age_days > T * 3  → high
+ *   age_days > T * 2  → medium
+ *   age_days > T      → low
+ *
+ * Thresholds are read from Session Config `docs-staleness.thresholds.living`
+ * (fail-soft: non-numeric / non-positive values fall back to the 90-day default).
+ *
+ * Input: projectRoot (absolute path to the repo running discovery), config
+ * (parsed Session Config object, may be empty/partial).
+ *
+ * Output: {findings[], metrics, duration_ms, [skipped_reason]}. Never throws.
+ * Also appends one JSONL summary record to .orchestrator/metrics/docs-staleness.jsonl.
+ */
+
+import { existsSync, readdirSync, statSync, mkdirSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_THRESHOLD_DAYS = 90;
+const DAY_MS = 86_400_000;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function resolveThreshold(config) {
+  const raw = config?.['docs-staleness']?.thresholds?.living;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_THRESHOLD_DAYS;
+  return n;
+}
+
+function computeSeverity(ageDays, threshold) {
+  if (ageDays > threshold * 3) return 'high';
+  if (ageDays > threshold * 2) return 'medium';
+  return 'low';
+}
+
+/** List *.md filenames directly inside dirPath (non-recursive). Never throws. */
+function listMarkdownFiles(dirPath) {
+  if (!existsSync(dirPath)) return [];
+  let entries;
+  try {
+    entries = readdirSync(dirPath, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries.filter((e) => e.isFile() && e.name.endsWith('.md')).map((e) => e.name);
+}
+
+function makeMetricsPath(projectRoot) {
+  return join(projectRoot, '.orchestrator', 'metrics');
+}
+
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {string} projectRoot  Absolute path to the consumer project root.
+ * @param {object} config       Parsed Session Config (may be empty / partial).
+ * @returns {Promise<object>}   { findings, metrics, duration_ms [, skipped_reason] }
+ */
+export async function runProbe(projectRoot, config) {
+  const startMs = Date.now();
+
+  const makeSkip = (skipped_reason) => ({
+    findings: [],
+    metrics: { scanned_docs: 0, stale_docs: 0, errors: 0 },
+    duration_ms: Date.now() - startMs,
+    skipped_reason,
+  });
+
+  try {
+    const docsDir = join(projectRoot, 'docs');
+
+    // ── Early exit: docs/ directory absent ────────────────────────────────
+    if (!existsSync(docsDir)) {
+      return makeSkip('docs/ directory not found');
+    }
+
+    const threshold = resolveThreshold(config);
+    const now = Date.now();
+
+    const findings = [];
+    let scannedDocs = 0;
+    let staleDocs = 0;
+    let errors = 0;
+
+    // Root-level docs/*.md + docs/examples/*.md only (see file-header note).
+    const targets = [
+      ...listMarkdownFiles(docsDir).map((name) => ({ rel: name, abs: join(docsDir, name) })),
+      ...listMarkdownFiles(join(docsDir, 'examples')).map((name) => ({
+        rel: join('examples', name),
+        abs: join(docsDir, 'examples', name),
+      })),
+    ];
+
+    for (const { rel, abs } of targets) {
+      scannedDocs++;
+
+      let mtimeMs;
+      try {
+        mtimeMs = statSync(abs).mtimeMs;
+      } catch (err) {
+        errors++;
+        findings.push({
+          severity: 'low',
+          confidence: 0.6,
+          title: `[docs-staleness] ${rel}: cannot stat file`,
+          evidence: { file: rel, error: err.message || String(err) },
+        });
+        continue;
+      }
+
+      const ageDays = (now - mtimeMs) / DAY_MS;
+      if (ageDays > threshold) {
+        staleDocs++;
+        const ageDaysRounded = Math.round(ageDays);
+        const severity = computeSeverity(ageDays, threshold);
+        findings.push({
+          severity,
+          confidence: 0.9,
+          title: `[docs-staleness] ${rel}: ${ageDaysRounded}d since last change (threshold: ${threshold}d)`,
+          evidence: {
+            file: rel,
+            age_days: ageDaysRounded,
+            threshold_days: threshold,
+          },
+        });
+      }
+    }
+
+    const durationMs = Date.now() - startMs;
+    const metrics = { scanned_docs: scannedDocs, stale_docs: staleDocs, errors };
+
+    // ── JSONL append ──────────────────────────────────────────────────────
+    try {
+      const metricsDir = makeMetricsPath(projectRoot);
+      if (!existsSync(metricsDir)) mkdirSync(metricsDir, { recursive: true });
+      const record = {
+        timestamp: new Date().toISOString(),
+        probe: 'docs-staleness',
+        project_root: projectRoot,
+        scanned_docs: scannedDocs,
+        stale_docs: staleDocs,
+        errors,
+        duration_ms: durationMs,
+        findings: findings.map((f) => ({
+          file: f.evidence.file,
+          severity: f.severity,
+          age_days: f.evidence.age_days ?? null,
+          threshold_days: f.evidence.threshold_days ?? threshold,
+        })),
+      };
+      appendFileSync(join(metricsDir, 'docs-staleness.jsonl'), JSON.stringify(record) + '\n', 'utf8');
+    } catch {
+      // JSONL write failure is non-fatal — probe result is still returned
+    }
+
+    return { findings, metrics, duration_ms: durationMs };
+  } catch (err) {
+    // Top-level safety net — probe must never throw
+    return {
+      findings: [],
+      metrics: { scanned_docs: 0, stale_docs: 0, errors: 1 },
+      duration_ms: Date.now() - startMs,
+      skipped_reason: `probe error: ${err.message || err}`,
+    };
+  }
+}
+
+export default runProbe;

package/skills/discovery/probes/frontend-slop.mjs

@@ -0,0 +1,186 @@
+/**
+ * skills/discovery/probes/frontend-slop.mjs
+ *
+ * Discovery probe: frontend-slop
+ *
+ * Walks the repo for frontend source files (CSS/HTML/JSX/TSX/Vue/Svelte/Astro)
+ * and runs the deterministic frontend-slop detector (scripts/lib/frontend-detect)
+ * over them. Reports AI-generated design tells + quality issues as findings.
+ *
+ * Zero LLM, zero network, zero browser — pure regex tier. Inspired by
+ * pbakaus/impeccable's detector (Apache-2.0); clean-room reimplementation that
+ * deliberately omits impeccable's heavier static-HTML + Puppeteer tiers.
+ *
+ * Fail-soft contract:
+ *   - No frontend files          → empty findings, total 0
+ *   - Unreadable file            → skipped silently
+ *   - >MAX_FILES scannable files → sample first MAX_FILES, warn in summary
+ *   - detector module missing    → single low finding (defensive, like
+ *                                  supply-chain-slopcheck)
+ *
+ * Output shape:
+ * {
+ *   probe: 'frontend-slop',
+ *   findings: Finding[],
+ *   summary: { total, high, medium, low, aiSlop, quality, filesScanned, sampled, errors }
+ * }
+ */
+
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Max files to scan before sampling — protects against huge trees. */
+const MAX_FILES = 2000;
+
+/** Directories never worth walking. */
+const SKIP_DIRS = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  'out',
+  '.next',
+  '.nuxt',
+  '.svelte-kit',
+  '.astro',
+  'coverage',
+  '.cache',
+  'vendor',
+  '.orchestrator',
+]);
+
+/**
+ * Map a detector finding to the discovery-probe finding shape.
+ * @param {import('../../../scripts/lib/frontend-detect/detect.mjs').Finding} f
+ * @param {string} repoRoot
+ */
+function toProbeFinding(f, repoRoot) {
+  const relFile = f.file.startsWith(repoRoot) ? f.file.slice(repoRoot.length + 1) : f.file;
+  return {
+    severity: f.severity, // high|medium|low — already in the probe vocabulary
+    title: `${f.title} — ${relFile}:${f.line}`,
+    evidence: {
+      rule: f.rule,
+      ruleRef: f.ruleRef,
+      category: f.category,
+      file: relFile,
+      line: f.line,
+      snippet: f.snippet,
+      fpRisk: f.fpRisk,
+    },
+    recommendation: f.recommendation,
+  };
+}
+
+/**
+ * Bounded recursive walk collecting scannable frontend files.
+ * @param {string} dir
+ * @param {Set<string>} exts
+ * @param {string[]} acc
+ * @returns {boolean} true if the MAX_FILES cap was hit (sampled)
+ */
+function walk(dir, exts, acc) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  for (const entry of entries) {
+    if (acc.length >= MAX_FILES) return true;
+    if (entry.name.startsWith('.') && entry.isDirectory() && !SKIP_DIRS.has(entry.name)) {
+      // Skip hidden dirs except when explicitly walkable; cheaper to skip all dotdirs.
+      continue;
+    }
+    const full = join(dir, entry.name);
+    let isDir = entry.isDirectory();
+    let isFile = entry.isFile();
+    if (!isDir && !isFile) {
+      // Some filesystems need an explicit stat (e.g. symlinks).
+      try {
+        const st = statSync(full);
+        isDir = st.isDirectory();
+        isFile = st.isFile();
+      } catch {
+        continue;
+      }
+    }
+    if (isDir) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      if (walk(full, exts, acc)) return true;
+    } else if (isFile) {
+      const dot = entry.name.lastIndexOf('.');
+      const ext = dot === -1 ? '' : entry.name.slice(dot).toLowerCase();
+      if (exts.has(ext)) acc.push(full);
+    }
+  }
+  return false;
+}
+
+/**
+ * Discovery probe entry point.
+ * @param {{ repoRoot: string }} opts
+ * @returns {Promise<{probe: string, findings: object[], summary: object}>}
+ */
+export default async function frontendSlop({ repoRoot }) {
+  const probe = 'frontend-slop';
+
+  // Defensive import — mirrors supply-chain-slopcheck's pattern so the probe
+  // never hard-crashes the discovery run if the detector is absent.
+  const detectPath = join(repoRoot, 'scripts', 'lib', 'frontend-detect', 'detect.mjs');
+  if (!existsSync(detectPath)) {
+    return {
+      probe,
+      findings: [
+        {
+          severity: 'low',
+          title: 'frontend-slop: detector module unavailable',
+          evidence: { file: detectPath, classification: 'SKIPPED' },
+          recommendation:
+            'scripts/lib/frontend-detect/detect.mjs is missing. Re-run /discovery after it is committed.',
+        },
+      ],
+      summary: { total: 0, filesScanned: 0, sampled: false, errors: 0, skipped_reason: 'detector-unavailable' },
+    };
+  }
+
+  let detectFiles, SCANNABLE_EXTS;
+  try {
+    ({ detectFiles, SCANNABLE_EXTS } = await import(detectPath));
+  } catch (err) {
+    return {
+      probe,
+      findings: [],
+      summary: {
+        total: 0,
+        filesScanned: 0,
+        sampled: false,
+        errors: 1,
+        skipped_reason: `detector import failed: ${err instanceof Error ? err.message : String(err)}`,
+      },
+    };
+  }
+
+  const files = [];
+  const sampled = walk(repoRoot, SCANNABLE_EXTS, files);
+  if (sampled) {
+    process.stderr.write(`[frontend-slop] WARN: file cap (${MAX_FILES}) hit — scanning a sample.\n`);
+  }
+
+  const raw = detectFiles(files);
+  const findings = raw.map((f) => toProbeFinding(f, repoRoot));
+
+  const summary = {
+    total: findings.length,
+    high: raw.filter((f) => f.severity === 'high').length,
+    medium: raw.filter((f) => f.severity === 'medium').length,
+    low: raw.filter((f) => f.severity === 'low').length,
+    aiSlop: raw.filter((f) => f.category === 'ai-slop').length,
+    quality: raw.filter((f) => f.category === 'quality').length,
+    filesScanned: files.length,
+    sampled,
+    errors: 0,
+  };
+
+  return { probe, findings, summary };
+}