session-orchestrator 3.16.0 → 3.19.0

package/scripts/lib/pi-hook-bridge.mjs

@@ -205,20 +205,132 @@ export function selectPiHooks(manifest, piEventName, event = {}) {
 }
 
 /**
- * @param {string} stdout
- * @returns {Record<string, unknown>|null}
+ * Substrings that identify a line as an *attempted* decision envelope even when
+ * it no longer parses — the tell-tale of a truncated `emitDeny` payload.
  */
-function parseLastJsonLine(stdout) {
-  const lines = stdout.split('\n').map((l) => l.trim()).filter(Boolean);
-  for (let i = lines.length - 1; i >= 0; i--) {
+const DECISION_MARKERS = Object.freeze(['permissionDecision', 'hookSpecificOutput']);
+
+/**
+ * Decide whether an unparseable stdout line is corrupt hook PROTOCOL output
+ * (fail closed) or merely human-facing chatter (fail open).
+ *
+ * The discriminator is deliberately narrow. "stdout is non-empty but nothing
+ * parsed ⇒ block" — the obvious fail-closed rule — would turn every third-party
+ * hook that prints a progress line or a debug trace into a permanent blocker,
+ * because the Pi bridge spawns whatever the manifest points at. A line that
+ * OPENS A JSON OBJECT, or that name-drops a decision field, is by contrast
+ * malformed by its own protocol's standard; no legitimate log line looks like
+ * that.
+ *
+ * `[` is deliberately NOT an opener here even though it opens a JSON array: a
+ * decision envelope is always an object, so an array line can never be a
+ * truncated one — while `[####----] 50%` is a perfectly ordinary progress bar.
+ * Treating `[` as protocol output blocked that hook in an earlier cut of this
+ * function; `tests/lib/pi-hook-bridge.test.mjs` pins the carve-out.
+ *
+ * @param {string} line  Trimmed, non-empty stdout line that failed JSON.parse.
+ * @returns {boolean}
+ */
+function looksLikeBrokenEnvelope(line) {
+  if (line.startsWith('{')) return true;
+  return DECISION_MARKERS.some((marker) => line.includes(marker));
+}
+
+/**
+ * Pull `{decision, reason}` out of ONE parsed envelope, accepting both
+ * generations of the deny protocol.
+ *
+ * @param {unknown} parsed
+ * @returns {{ decision: string|null, reason: string|null }}
+ */
+function decisionFromEnvelope(parsed) {
+  const envelope = objectOrEmpty(parsed);
+  const hookSpecific = objectOrEmpty(envelope.hookSpecificOutput);
+
+  const decision = typeof hookSpecific.permissionDecision === 'string'
+    ? hookSpecific.permissionDecision
+    : (typeof envelope.permissionDecision === 'string' ? envelope.permissionDecision : null);
+
+  const reason = typeof hookSpecific.permissionDecisionReason === 'string'
+    ? hookSpecific.permissionDecisionReason
+    : (typeof envelope.reason === 'string' ? envelope.reason : null);
+
+  return { decision, reason };
+}
+
+/**
+ * Extract the permission decision + reason from a hook's stdout, accepting BOTH
+ * generations of the deny protocol.
+ *
+ * - **Current** (`scripts/lib/io.mjs#emitDeny`, exit 0):
+ *   `{ hookSpecificOutput: { hookEventName, permissionDecision, permissionDecisionReason } }`
+ * - **Legacy** (pre-#906 in-repo hooks, and third-party hooks outside this repo
+ *   that still emit the deprecated flat shape): `{ permissionDecision, reason }`
+ *
+ * Legacy support is NOT optional: the bridge spawns whatever commands the Pi
+ * manifest points at, including hooks this repo does not own. Dropping the flat
+ * form would silently stop honouring their denies.
+ *
+ * Reading the reason out of the envelope also avoids the failure mode where the
+ * caller falls through to `stdout.trim()` and surfaces the raw JSON string as
+ * the human-readable block reason.
+ *
+ * ## Why this reads raw stdout, and why the FIRST envelope wins
+ *
+ * Since #906 every in-repo PreToolUse hook denies with **exit 0** plus this
+ * envelope, so on the Pi lane `status === 2` no longer fires and the stdout read
+ * is the ONLY surviving block signal. Two ways the previous last-parseable-line
+ * scan dropped that signal:
+ *
+ * 1. **Anything printed after the envelope shadowed it.** `emitSystemMessage`,
+ *    or any third-party hook's trailing JSON, became "the" decision line and the
+ *    deny read as "no decision" ⇒ allow. Scanning forward and keeping the first
+ *    line that actually carries a `permissionDecision` removes that shadowing:
+ *    non-decision JSON lines are now skipped rather than mistaken for a verdict.
+ * 2. **A truncated envelope parsed as nothing at all** ⇒ allow. `malformed`
+ *    reports that case up to {@link runPiHookCommand}, which fails closed for
+ *    PreToolUse. It stays set even when a later line does carry a decision:
+ *    garbage interleaved with a verdict is a protocol violation, and a mangled
+ *    line is exactly as likely to have been a deny as an allow.
+ *
+ * @param {unknown} input  Raw hook stdout (preferred), or an already-parsed
+ *        envelope object. Non-string input skips the line scan and can never
+ *        report `malformed`.
+ * @returns {{ decision: string|null, reason: string|null, deny: boolean, malformed: boolean }}
+ */
+export function readHookDecision(input) {
+  if (typeof input !== 'string') {
+    const { decision, reason } = decisionFromEnvelope(input);
+    return { decision, reason, deny: decision === 'deny', malformed: false };
+  }
+
+  let found = null;
+  let malformed = false;
+
+  for (const rawLine of input.split('\n')) {
+    const line = rawLine.trim();
+    if (line === '') continue;
+
+    let parsed;
     try {
-      const parsed = JSON.parse(lines[i]);
-      if (parsed && typeof parsed === 'object') return parsed;
+      parsed = JSON.parse(line);
     } catch {
-      // Try the previous line.
+      if (looksLikeBrokenEnvelope(line)) malformed = true;
+      continue;
     }
+
+    if (found !== null) continue;
+    const candidate = decisionFromEnvelope(parsed);
+    if (candidate.decision !== null) found = candidate;
   }
-  return null;
+
+  const decision = found?.decision ?? null;
+  return {
+    decision,
+    reason: found?.reason ?? null,
+    deny: decision === 'deny',
+    malformed,
+  };
 }
 
 /**
@@ -261,19 +373,36 @@ export function runPiHookCommand(hook, payload, options) {
 
   const stdout = result.stdout ?? '';
   const stderr = result.stderr ?? '';
-  const parsed = parseLastJsonLine(stdout);
+  const decision = readHookDecision(stdout);
   const isPreToolUse = payload.hook_event_name === 'PreToolUse';
+  // Since #906 in-repo hooks deny with exit 0, so `status` alone carries no block
+  // signal any more and `decision` is load-bearing on its own. `decision.malformed`
+  // is therefore counted as an infrastructure failure: a hook whose decision
+  // channel is corrupt has told us nothing, and for a PreToolUse guard "nothing"
+  // must not read as "allow".
   const infraFailure = Boolean(result.error) ||
     result.status === null ||
-    (result.status !== 0 && result.status !== 2);
+    (result.status !== 0 && result.status !== 2) ||
+    decision.malformed;
+  // `status === 2` stays: legacy/third-party hooks still signal a block that way.
+  // `decision.deny` covers both the current exit-0 envelope and the legacy flat form.
   const blocked = result.status === 2 ||
-    parsed?.permissionDecision === 'deny' ||
+    decision.deny ||
     (isPreToolUse && infraFailure);
-  const reason = typeof parsed?.reason === 'string'
-    ? parsed.reason
-    : (blocked
-        ? (result.error?.message || stdout.trim() || stderr.trim() || `Hook command blocked: ${command}`)
-        : null);
+
+  let reason = decision.reason;
+  if (reason === null && blocked) {
+    // Prefer a diagnosis over echoing the corrupt payload: `stdout.trim()` on a
+    // truncated envelope would surface the whole mangled JSON blob as the
+    // operator-facing block reason.
+    reason = result.error?.message
+      || (decision.malformed
+        ? `Hook stdout is not a parseable decision envelope (possible truncated output) — failing closed: ${command}`
+        : '')
+      || stdout.trim()
+      || stderr.trim()
+      || `Hook command blocked: ${command}`;
+  }
 
   return {
     command,

package/scripts/lib/product-repo-detect.mjs

@@ -7,6 +7,7 @@
 
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { findSessionConfigBlock } from './config/section-extractor.mjs';
 
 const FRAMEWORK_DEPS = [
   'next',
@@ -110,12 +111,12 @@ export function hasVaultConfig(configFilePath) {
     return false;
   }
   // Scan only within the Session Config section (bounded by the next ## heading).
-  const startMatch = text.match(/^## Session Config[ \t]*(?:\r?\n|$)/m);
-  if (!startMatch || startMatch.index === undefined) return false;
-  const afterBlock = text.slice(startMatch.index + startMatch[0].length);
-  const nextHeadingMatch = afterBlock.match(/^## /m);
-  const blockContent = nextHeadingMatch
-    ? afterBlock.slice(0, nextHeadingMatch.index)
-    : afterBlock;
-  return /^\s*vault\s*:/m.test(blockContent);
+  // Heading + span both come from the SSOT (#968): the previous local regex
+  // `/^## Session Config[ \t]*(?:\r?\n|$)/m` accepted a heading with trailing
+  // spaces/tab that `_extractConfigSection` rejects, so a `vault:` key under
+  // `## Session Config␠` was reported as configured while the runtime read
+  // nothing at all from that block.
+  const block = findSessionConfigBlock(text);
+  if (!block) return false;
+  return /^\s*vault\s*:/m.test(block.body);
 }

package/scripts/lib/project-hygiene.mjs

@@ -0,0 +1,432 @@
+/**
+ * project-hygiene.mjs — Project-hygiene probe family (housekeeping canon).
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * session-start Phase 4 runs 13 probes. Exactly one of them (`ci-status`)
+ * inspects the PROJECT; the rest inspect the orchestrator's own substrate
+ * (vault, peer-cards, loop readiness, instruction budget, its own ledger).
+ * A read-only diagnostic run of the housekeeping flow across six real
+ * consumer repos (9 to 2099 tracked files) found the checks the flow does
+ * NOT perform outscored the ones it does in every single repo — by up to 7x.
+ *
+ * This module adds the highest-yield missing checks. Each one was selected by
+ * measured hit rate across those six repos, not by intuition:
+ *
+ *   releaseHygiene   6/6 repos    tags/CHANGELOG vs. commits since
+ *   ignoredBallast   6/6 repos    ignored-and-untracked working-tree mass
+ *   staleArtifacts   5/6 repos    aged .orchestrator/ artifacts
+ *   ciConfig         5/6 repos    pipeline present, audit job, image pinning
+ *
+ * DELIBERATE OMISSIONS (documented so nobody "completes" the set later):
+ *
+ *   docs-drift (6/6 hit rate) is NOT reimplemented here. `claude-md-drift-check`
+ *   already covers it with ten checks; it merely runs at session-END, i.e.
+ *   after the work. The fix is scheduling, not a second implementation.
+ *
+ *   env-hygiene (5/6 hit rate) is NOT implemented as a dead-variable list.
+ *   The naive approach — diff `process.env.X` reads against `.env.example` —
+ *   produced a 100% false-positive rate in the largest repo tested, because
+ *   variables were read centrally through a Zod schema rather than at their
+ *   use sites. This module reports only the falsifiable part: whether an
+ *   `.env.example` exists at all when env vars are read. Counting or naming
+ *   "dead" variables requires resolving indirection and is left to the
+ *   per-repo parity tests that some repos already implement correctly.
+ *
+ * CONTRACT
+ * --------
+ * Mirrors the established banner-probe shape (see ci-status-banner.mjs):
+ * returns `null` for a silent no-op, or `{ severity, message, findings }`.
+ * Never throws, never writes, never blocks. Every finding carries `fixable`
+ * so a caller can split mechanical work from work needing human judgement.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Commits past the newest tag before release hygiene is worth mentioning. */
+export const DEFAULT_RELEASE_DRIFT_COMMITS = 50;
+/** Megabytes of ignored working-tree mass before it is worth mentioning. */
+export const DEFAULT_BALLAST_MB = 500;
+/** Days before an .orchestrator/ artifact counts as aged. */
+export const DEFAULT_ARTIFACT_AGE_DAYS = 30;
+
+/**
+ * Run a git command, returning trimmed stdout or null on any failure.
+ * Never throws — a missing repo, missing ref, or absent git all yield null.
+ * @param {string[]} args
+ * @param {string} cwd
+ * @returns {string|null}
+ */
+function git(args, cwd) {
+  try {
+    return execFileSync('git', args, {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 10_000,
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * H1 — Release hygiene.
+ *
+ * Measured 6/6. The severe real-world case: 980 commits, live in production,
+ * zero release tags, CHANGELOG frozen 460 commits back — no rollback anchor.
+ * Distinguishes "no tags at all" from "tags exist but HEAD has run far past
+ * the newest one", because the remedies differ.
+ *
+ * @param {string} repoRoot
+ * @param {number} driftCommits
+ * @returns {object|null}
+ */
+export function checkReleaseHygiene(repoRoot, driftCommits = DEFAULT_RELEASE_DRIFT_COMMITS) {
+  const totalCommits = Number(git(['rev-list', '--count', 'HEAD'], repoRoot));
+  if (!Number.isFinite(totalCommits) || totalCommits === 0) return null;
+
+  const tags = git(['tag', '--list'], repoRoot);
+  if (tags === null) return null;
+  const tagList = tags.split('\n').filter(Boolean);
+
+  // A young repo without tags is normal, not a finding.
+  if (tagList.length === 0) {
+    if (totalCommits < driftCommits) return null;
+    return {
+      check: 'release-hygiene',
+      fixable: false,
+      message: `no release tags across ${totalCommits} commits — no rollback anchor and no deploy identity`,
+    };
+  }
+
+  // `describe` fails when no ANNOTATED tag is reachable; fall back to any tag.
+  const described = git(['describe', '--tags', '--abbrev=0'], repoRoot);
+  if (!described) {
+    return {
+      check: 'release-hygiene',
+      fixable: false,
+      message: `${tagList.length} tag(s) exist but none is reachable from HEAD (git describe fails) — releases are not anchored to this history`,
+    };
+  }
+
+  const since = Number(git(['rev-list', '--count', `${described}..HEAD`], repoRoot));
+  if (!Number.isFinite(since) || since < driftCommits) return null;
+
+  return {
+    check: 'release-hygiene',
+    fixable: false,
+    message: `${since} commits since the newest tag (${described}) — release identity is ${since} commits stale`,
+  };
+}
+
+/**
+ * H2 — Ignored working-tree ballast.
+ *
+ * Measured 6/6. Largest observed: a 7.4 GB working tree carrying 30.8 MB of
+ * tracked content (factor 240), entirely invisible to `git status`, which
+ * reported clean, and to `git count-objects`, which reported a healthy pack.
+ *
+ * Also reports files that are NEITHER tracked NOR ignored — the state where a
+ * `.gitignore` intends to version something that was never committed. In one
+ * repo this hid 23 rule files the `.gitignore` explicitly un-ignored.
+ *
+ * @param {string} repoRoot
+ * @param {number} ballastMb
+ * @returns {object[]}
+ */
+export function checkIgnoredBallast(repoRoot, ballastMb = DEFAULT_BALLAST_MB) {
+  const findings = [];
+
+  const ignored = git(
+    ['status', '--ignored=matching', '--porcelain', '--untracked-files=all'],
+    repoRoot,
+  );
+  if (ignored === null) return findings;
+
+  const ignoredPaths = [];
+  let untrackedUnignored = 0;
+  for (const line of ignored.split('\n').filter(Boolean)) {
+    if (line.startsWith('!! ')) ignoredPaths.push(line.slice(3));
+    else if (line.startsWith('?? ')) untrackedUnignored++;
+  }
+
+  // Size only the top-level ignored entries — recursing every path would cost
+  // more than the finding is worth on a large tree.
+  let totalBytes = 0;
+  const heaviest = [];
+  for (const p of ignoredPaths) {
+    const abs = join(repoRoot, p);
+    const bytes = duBytes(abs);
+    if (bytes === null) continue;
+    totalBytes += bytes;
+    heaviest.push({ path: p, bytes });
+  }
+
+  const totalMb = Math.round(totalBytes / (1024 * 1024));
+  if (totalMb >= ballastMb) {
+    heaviest.sort((a, b) => b.bytes - a.bytes);
+    const top = heaviest
+      .slice(0, 3)
+      .map((h) => `${h.path} ${Math.round(h.bytes / (1024 * 1024))}MB`)
+      .join(', ');
+    findings.push({
+      check: 'ignored-ballast',
+      fixable: true,
+      message: `${totalMb} MB of ignored files in the working tree (largest: ${top}) — invisible to git status`,
+    });
+  }
+
+  if (untrackedUnignored > 0) {
+    findings.push({
+      check: 'untracked-unignored',
+      fixable: false,
+      message: `${untrackedUnignored} file(s) are neither tracked nor ignored — either commit them or add them to .gitignore, since nothing currently decides`,
+    });
+  }
+
+  return findings;
+}
+
+/**
+ * Directory/file size in bytes via `du -sk`, or null when unavailable.
+ * `du` is POSIX and present on macOS and Linux; Windows yields null, which
+ * degrades the ballast check to a silent skip rather than a crash.
+ * @param {string} absPath
+ * @returns {number|null}
+ */
+function duBytes(absPath) {
+  try {
+    if (!existsSync(absPath)) return null;
+    const out = execFileSync('du', ['-sk', absPath], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 10_000,
+    });
+    const kb = Number(out.trim().split(/\s+/)[0]);
+    return Number.isFinite(kb) ? kb * 1024 : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * H3 — Aged orchestrator artifacts.
+ *
+ * Measured 5/6. Largest observed: 184 MB under .orchestrator/, of which
+ * 147 MB were Playwright test-run captures dating back seven weeks, plus
+ * 592 files older than 30 days.
+ *
+ * @param {string} repoRoot
+ * @param {number} ageDays
+ * @param {number} now
+ * @returns {object|null}
+ */
+export function checkStaleArtifacts(repoRoot, ageDays = DEFAULT_ARTIFACT_AGE_DAYS, now = Date.now()) {
+  const dir = join(repoRoot, '.orchestrator');
+  if (!existsSync(dir)) return null;
+
+  const cutoff = now - ageDays * 24 * 60 * 60 * 1000;
+  let aged = 0;
+  let scanned = 0;
+
+  /** @param {string} d @param {number} depth */
+  const walk = (d, depth) => {
+    // Bounded: a runaway scan on a huge artifact tree would cost more than
+    // the finding. 20k entries is far above any healthy .orchestrator/.
+    if (depth > 6 || scanned > 20_000) return;
+    let entries;
+    try {
+      entries = readdirSync(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const full = join(d, e.name);
+      if (e.isDirectory()) {
+        walk(full, depth + 1);
+      } else if (e.isFile()) {
+        scanned++;
+        try {
+          if (statSync(full).mtimeMs < cutoff) aged++;
+        } catch {
+          /* vanished mid-scan — ignore */
+        }
+      }
+    }
+  };
+  walk(dir, 0);
+
+  if (aged === 0) return null;
+
+  const mb = Math.round((duBytes(dir) ?? 0) / (1024 * 1024));
+  return {
+    check: 'stale-artifacts',
+    fixable: true,
+    message: `${aged} file(s) under .orchestrator/ older than ${ageDays}d${mb > 0 ? ` (${mb} MB total)` : ''} — candidates for pruning`,
+  };
+}
+
+/**
+ * H4 — CI configuration hygiene.
+ *
+ * Measured 5/6. Reports only what is decidable by presence, never by parsing
+ * pipeline semantics. The dependency-audit gap is the load-bearing one: three
+ * of the tested repos carried known-vulnerable dependencies that no pipeline
+ * would ever surface.
+ *
+ * @param {string} repoRoot
+ * @returns {object[]}
+ */
+export function checkCiConfig(repoRoot) {
+  const findings = [];
+  const gitlabCi = join(repoRoot, '.gitlab-ci.yml');
+  const ghWorkflows = join(repoRoot, '.github', 'workflows');
+  const hasGitlab = existsSync(gitlabCi);
+  const hasGithub = existsSync(ghWorkflows);
+
+  // Only meaningful for repos that actually build something.
+  const hasManifest = ['package.json', 'pyproject.toml', 'Cargo.toml', 'go.mod'].some((m) =>
+    existsSync(join(repoRoot, m)),
+  );
+  if (!hasManifest) return findings;
+
+  if (!hasGitlab && !hasGithub) {
+    findings.push({
+      check: 'ci-config',
+      fixable: false,
+      message: 'no CI pipeline configured (.gitlab-ci.yml / .github/workflows) — nothing verifies commits',
+    });
+    return findings;
+  }
+
+  let ciText = '';
+  if (hasGitlab) ciText += safeRead(gitlabCi);
+  if (hasGithub) {
+    try {
+      for (const f of readdirSync(ghWorkflows)) {
+        if (f.endsWith('.yml') || f.endsWith('.yaml')) ciText += safeRead(join(ghWorkflows, f));
+      }
+    } catch {
+      /* unreadable workflows dir — fall through with what we have */
+    }
+  }
+
+  if (ciText && !/\b(npm|pnpm|yarn) audit\b|pip-audit|cargo audit|osv-scanner|dependency.?check/i.test(ciText)) {
+    findings.push({
+      check: 'ci-audit-job',
+      fixable: true,
+      message: 'CI runs no dependency-audit step — known-vulnerable dependencies cannot surface in the pipeline',
+    });
+  }
+
+  return findings;
+}
+
+/** @param {string} p @returns {string} */
+function safeRead(p) {
+  try {
+    return readFileSync(p, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * H5 — Env documentation presence (deliberately narrow; see module header).
+ *
+ * Reports ONLY the falsifiable case: code reads environment variables and no
+ * `.env.example` exists anywhere. Does NOT attempt to name dead or missing
+ * variables — that requires resolving indirection (central schema modules,
+ * injected config objects) and produced a 100% false-positive rate when
+ * attempted naively during the diagnostic runs.
+ *
+ * @param {string} repoRoot
+ * @returns {object|null}
+ */
+export function checkEnvDocumentation(repoRoot) {
+  const tracked = git(['ls-files'], repoRoot);
+  if (!tracked) return null;
+
+  const files = tracked.split('\n').filter((f) => /\.(mjs|cjs|js|ts|tsx|py|go|rs)$/.test(f));
+  if (files.length === 0) return null;
+
+  const hasExample = ['.env.example', '.env.sample', '.env.template'].some((n) =>
+    existsSync(join(repoRoot, n)),
+  );
+  if (hasExample) return null;
+
+  // Sample rather than read every file — one hit is enough to decide.
+  let readsEnv = false;
+  for (const f of files.slice(0, 400)) {
+    const text = safeRead(join(repoRoot, f));
+    if (/process\.env\.\w|os\.environ|std::env::var|os\.Getenv/.test(text)) {
+      readsEnv = true;
+      break;
+    }
+  }
+  if (!readsEnv) return null;
+
+  return {
+    check: 'env-documentation',
+    fixable: false,
+    message: 'code reads environment variables but no .env.example/.env.sample exists — required configuration is undiscoverable',
+  };
+}
+
+/**
+ * Aggregate the project-hygiene family into one banner result.
+ *
+ * Returns a SINGLE result rather than one banner per check: Phase 4 already
+ * renders 13 banners, and the diagnostic runs showed a flat list stops being
+ * read past roughly 25 findings. The caller renders the summary plus the top
+ * findings and can use `mechanical` to route the fixable subset separately.
+ *
+ * @param {{ repoRoot: string, now?: number, thresholds?: object }} opts
+ * @returns {{ severity: 'warn', message: string, findings: object[], mechanical: number } | null}
+ */
+export function checkProjectHygiene({ repoRoot, now = Date.now(), thresholds = {} } = {}) {
+  if (!repoRoot || typeof repoRoot !== 'string') return null;
+  if (!existsSync(join(repoRoot, '.git'))) return null;
+
+  const {
+    releaseDriftCommits = DEFAULT_RELEASE_DRIFT_COMMITS,
+    ballastMb = DEFAULT_BALLAST_MB,
+    artifactAgeDays = DEFAULT_ARTIFACT_AGE_DAYS,
+  } = thresholds;
+
+  const findings = [];
+  try {
+    const release = checkReleaseHygiene(repoRoot, releaseDriftCommits);
+    if (release) findings.push(release);
+
+    findings.push(...checkIgnoredBallast(repoRoot, ballastMb));
+
+    const stale = checkStaleArtifacts(repoRoot, artifactAgeDays, now);
+    if (stale) findings.push(stale);
+
+    findings.push(...checkCiConfig(repoRoot));
+
+    const env = checkEnvDocumentation(repoRoot);
+    if (env) findings.push(env);
+  } catch {
+    // Probe family is advisory — a partial result beats a crashed session-start.
+    if (findings.length === 0) return null;
+  }
+
+  if (findings.length === 0) return null;
+
+  const mechanical = findings.filter((f) => f.fixable).length;
+  const head = findings.slice(0, 3).map((f) => `• ${f.message}`).join('\n');
+  const rest = findings.length > 3 ? `\n  …and ${findings.length - 3} more.` : '';
+
+  return {
+    severity: 'warn',
+    message:
+      `⚠ project-hygiene: ${findings.length} finding(s), ${mechanical} mechanically fixable:\n${head}${rest}`,
+    findings,
+    mechanical,
+  };
+}