session-orchestrator 3.16.0

package/scripts/lib/harness-audit/categories/category4.mjs

@@ -0,0 +1,202 @@
+/**
+ * category4.mjs — Category 4: Persistence Health (weight: 10)
+ *
+ * Checks: state-md-schema, sessions-jsonl-recent, learnings-prunable,
+ *         vault-sync-validator, orphaned-session-lock
+ *
+ * Stdlib only: node:fs, node:path.
+ */
+
+import { existsSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+
+import { parseFrontmatter, safeRead, parseJsonl, pass, fail } from './helpers.mjs';
+
+// Default session-lock TTL in hours — mirrors DEFAULT_TTL_HOURS in
+// scripts/lib/session-lock.mjs. Inlined to keep this category stdlib-only
+// (no import of the session-lock barrel into the audit path). Exported
+// (additive-only) so tests/lib/lock-ttl-parity.test.mjs can cross-reference
+// this value against the SSOT and fail loudly on drift.
+export const DEFAULT_LOCK_TTL_HOURS = 4;
+
+/**
+ * Heartbeat-based liveness for a parsed session.lock — a self-contained mirror
+ * of session-lock.mjs `isLockLive` (which is the SSOT for the semantics). A lock
+ * is live when (now - last_heartbeat) < ttl_hours; falls back to started_at for
+ * v1 locks. Returns false for malformed input (→ treated as an orphaned lease).
+ *
+ * Exported (additive-only) so tests/lib/lock-ttl-parity.test.mjs can drive both
+ * this mirror and the SSOT with identical fixtures and assert identical verdicts.
+ *
+ * @param {object|null} lock
+ * @param {number} nowMs
+ * @returns {boolean}
+ */
+export function lockIsLive(lock, nowMs) {
+  if (!lock || typeof lock !== 'object') return false;
+  const hb = (typeof lock.last_heartbeat === 'string' && lock.last_heartbeat.length > 0)
+    ? lock.last_heartbeat
+    : lock.started_at;
+  const ms = Date.parse(hb);
+  if (Number.isNaN(ms)) return false;
+  const ttlHours = typeof lock.ttl_hours === 'number' ? lock.ttl_hours : DEFAULT_LOCK_TTL_HOURS;
+  return (nowMs - ms) < ttlHours * 3600 * 1000;
+}
+
+export function runCategory4(root) {
+  const checks = [];
+
+  // c4.1 state-md-schema
+  {
+    const candidates = [
+      join(root, '.claude/STATE.md'),
+      join(root, '.codex/STATE.md'),
+      join(root, '.cursor/STATE.md'),
+      join(root, '.pi/STATE.md'),
+    ];
+    const found = candidates.find((p) => existsSync(p));
+    const relPath = '.claude/STATE.md';
+    if (!found) {
+      checks.push(fail('state-md-schema', 3, relPath,
+        { missingKeys: ['all'] },
+        'STATE.md not found'));
+    } else {
+      const text = safeRead(found);
+      const fm = text ? parseFrontmatter(text) : null;
+      const requiredKeys = ['schema-version', 'session-type', 'branch', 'status', 'current-wave', 'total-waves'];
+      const missingKeys = fm ? requiredKeys.filter((k) => !(k in fm)) : requiredKeys;
+      if (missingKeys.length === 0) {
+        checks.push(pass('state-md-schema', 3, 3, relative(root, found).split(sep).join('/'),
+          { missingKeys: [] },
+          'STATE.md has all required frontmatter keys'));
+      } else {
+        checks.push(fail('state-md-schema', 3, relative(root, found).split(sep).join('/'),
+          { missingKeys },
+          `STATE.md missing keys: ${missingKeys.join(', ')}`));
+      }
+    }
+  }
+
+  // c4.2 sessions-jsonl-recent
+  {
+    const p = join(root, '.orchestrator/metrics/sessions.jsonl');
+    const text = safeRead(p);
+    const relPath = '.orchestrator/metrics/sessions.jsonl';
+    if (!text) {
+      checks.push(fail('sessions-jsonl-recent', 3, relPath,
+        { latestCompletedAt: null, ageInDays: null },
+        'sessions.jsonl missing'));
+    } else {
+      const lines = text.split('\n').filter((l) => l.trim().length > 0);
+      if (lines.length === 0) {
+        checks.push(fail('sessions-jsonl-recent', 3, relPath,
+          { latestCompletedAt: null, ageInDays: null },
+          'sessions.jsonl is empty'));
+      } else {
+        const lastLine = lines[lines.length - 1];
+        let lastObj = null;
+        try { lastObj = JSON.parse(lastLine); } catch { /* ignore */ }
+        const completedAt = lastObj ? lastObj.completed_at : null;
+        if (!completedAt) {
+          checks.push(fail('sessions-jsonl-recent', 3, relPath,
+            { latestCompletedAt: null, ageInDays: null },
+            'Last sessions.jsonl entry has no completed_at'));
+        } else {
+          const ageMs = Date.now() - new Date(completedAt).getTime();
+          const ageInDays = Math.floor(ageMs / (1000 * 60 * 60 * 24));
+          if (ageInDays <= 30) {
+            checks.push(pass('sessions-jsonl-recent', 3, 3, relPath,
+              { latestCompletedAt: completedAt, ageInDays },
+              `Last session completed ${ageInDays} day(s) ago`));
+          } else {
+            checks.push(fail('sessions-jsonl-recent', 3, relPath,
+              { latestCompletedAt: completedAt, ageInDays },
+              `Last session ${ageInDays} days ago (> 30 day threshold)`));
+          }
+        }
+      }
+    }
+  }
+
+  // c4.3 learnings-prunable
+  {
+    const p = join(root, '.orchestrator/metrics/learnings.jsonl');
+    const text = safeRead(p);
+    const relPath = '.orchestrator/metrics/learnings.jsonl';
+    if (!text) {
+      checks.push(fail('learnings-prunable', 2, relPath,
+        { totalLines: 0, allHaveExpires: false, confidenceInRange: false },
+        'learnings.jsonl missing'));
+    } else {
+      const { lines, validLines } = parseJsonl(text);
+      const allHaveExpires = validLines.length > 0 && validLines.every((l) => typeof l.expires_at === 'string');
+      const confidenceInRange = validLines.length > 0 && validLines.every((l) => typeof l.confidence === 'number' && l.confidence >= 0 && l.confidence <= 1);
+      if (allHaveExpires && confidenceInRange) {
+        checks.push(pass('learnings-prunable', 2, 2, relPath,
+          { totalLines: lines, allHaveExpires, confidenceInRange },
+          `All ${lines} learnings have expires_at and confidence in [0,1]`));
+      } else {
+        checks.push(fail('learnings-prunable', 2, relPath,
+          { totalLines: lines, allHaveExpires, confidenceInRange },
+          `learnings not fully prunable: allHaveExpires=${allHaveExpires}, confidenceInRange=${confidenceInRange}`));
+      }
+    }
+  }
+
+  // c4.4 vault-sync-validator
+  {
+    const relPath = 'skills/vault-sync/validator.mjs';
+    // Parse CLAUDE.md Session Config for vault-integration.enabled
+    const claudeMd = safeRead(join(root, 'CLAUDE.md')) || safeRead(join(root, 'AGENTS.md')) || '';
+    // Extract ## Session Config block
+    const scMatch = /^## Session Config\s*\n([\s\S]*?)(?=^## |\s*$)/m.exec(claudeMd);
+    const scBlock = scMatch ? scMatch[1] : '';
+    const vaultEnabledMatch = /vault-integration\.enabled:\s*true/i.exec(scBlock) ||
+      /vault-integration:\s*\n\s+enabled:\s*true/im.exec(scBlock);
+    const vaultEnabled = Boolean(vaultEnabledMatch);
+
+    if (!vaultEnabled) {
+      checks.push(pass('vault-sync-validator', 2, 2, relPath,
+        { vaultEnabled: false, validatorPresent: null },
+        'vault-integration not enabled — skip'));
+    } else {
+      const validatorPresent = existsSync(join(root, relPath));
+      if (validatorPresent) {
+        checks.push(pass('vault-sync-validator', 2, 2, relPath,
+          { vaultEnabled: true, validatorPresent: true },
+          'vault-integration enabled and validator.mjs present'));
+      } else {
+        checks.push(fail('vault-sync-validator', 2, relPath,
+          { vaultEnabled: true, validatorPresent: false },
+          'vault-integration enabled but skills/vault-sync/validator.mjs missing'));
+      }
+    }
+  }
+
+  // c4.5 orphaned-session-lock
+  {
+    const relPath = '.orchestrator/session.lock';
+    const raw = safeRead(join(root, relPath));
+    if (!raw) {
+      // No lock present → no orphaned lease → healthy.
+      checks.push(pass('orphaned-session-lock', 2, 2, relPath,
+        { present: false, live: null },
+        'No session.lock present (no orphaned lease)'));
+    } else {
+      let lock = null;
+      try { lock = JSON.parse(raw); } catch { /* malformed → treated as stale */ }
+      const live = lockIsLive(lock, Date.now());
+      if (live) {
+        checks.push(pass('orphaned-session-lock', 2, 2, relPath,
+          { present: true, live: true },
+          'session.lock is live (fresh heartbeat)'));
+      } else {
+        checks.push(fail('orphaned-session-lock', 2, relPath,
+          { present: true, live: false },
+          'stale session.lock (dead lease) — run scripts/lock-reaper.mjs'));
+      }
+    }
+  }
+
+  return checks;
+}

package/scripts/lib/harness-audit/categories/category5.mjs

@@ -0,0 +1,152 @@
+/**
+ * category5.mjs — Category 5: Plugin-Root Resolution (weight: 9)
+ *
+ * Checks: parse-config-fallback-chain, hooks-use-plugin-root-var,
+ *         config-reading-doc, bootstrap-gate-doc
+ *
+ * Stdlib only: node:fs, node:path.
+ */
+
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { safeRead, safeJson, pass, fail } from './helpers.mjs';
+
+export function runCategory5(root) {
+  const checks = [];
+
+  // c5.1 parse-config-fallback-chain — verify the plugin-root fallback chain is
+  // wired somewhere in the resolution surface (scripts/lib/**/*.mjs + any
+  // hooks/*.json manifest). Relaxed from the original "all env vars in parse-config.mjs"
+  // rule — plugins typically centralize platform resolution in a helper module
+  // (platform.mjs in session-orchestrator) and branch by env var in per-platform
+  // manifests (hooks.json, hooks-codex.json, hooks-cursor.json).
+  {
+    const envVars = ['CLAUDE_PLUGIN_ROOT', 'CODEX_PLUGIN_ROOT', 'CURSOR_RULES_DIR', 'PI_PLUGIN_ROOT'];
+    const candidatePaths = [
+      'scripts/parse-config.mjs',
+      'scripts/lib/config.mjs',
+      'scripts/lib/platform.mjs',
+    ];
+    // Add all hooks/*.json manifests to the search surface
+    const hooksDir = join(root, 'hooks');
+    if (existsSync(hooksDir)) {
+      try {
+        for (const f of readdirSync(hooksDir)) {
+          if (f.endsWith('.json')) candidatePaths.push(`hooks/${f}`);
+        }
+      } catch { /* dir unreadable — skip */ }
+    }
+    const foundIn = {};
+    for (const rel of candidatePaths) {
+      const text = safeRead(join(root, rel));
+      if (!text) continue;
+      for (const v of envVars) {
+        if (text.includes(v)) {
+          (foundIn[v] = foundIn[v] || []).push(rel);
+        }
+      }
+    }
+    const envVarsFound = envVars.filter((v) => foundIn[v]?.length);
+    const relPath = 'scripts/lib/platform.mjs';
+    if (envVarsFound.length === envVars.length) {
+      checks.push(pass('parse-config-fallback-chain', 3, 3, relPath,
+        { envVarsFound, foundIn },
+        'plugin-root env vars wired across resolution surface'));
+    } else {
+      const missing = envVars.filter((v) => !envVarsFound.includes(v));
+      checks.push(fail('parse-config-fallback-chain', 3, relPath,
+        { envVarsFound, foundIn },
+        `plugin-root env var refs missing from resolution surface: ${missing.join(', ')}`));
+    }
+  }
+
+  // c5.2 hooks-use-plugin-root-var
+  {
+    const p = join(root, 'hooks/hooks.json');
+    const text = safeRead(p);
+    const relPath = 'hooks/hooks.json';
+    const json = safeJson(text);
+    if (!json) {
+      checks.push(fail('hooks-use-plugin-root-var', 3, relPath,
+        { absolutePathCount: 0 },
+        'hooks/hooks.json missing or invalid'));
+    } else {
+      const jsonText = JSON.stringify(json);
+      // Find all "command" values
+      const commandMatches = jsonText.match(/"command"\s*:\s*"[^"]+"/g) || [];
+      let absolutePathCount = 0;
+      for (const m of commandMatches) {
+        const cmd = m.replace(/^"command"\s*:\s*"/, '').replace(/"$/, '');
+        // Check if it uses an absolute path to a .mjs file without env var prefix
+        // A command is "bad" if it contains /hooks/ without $VAR prefix
+        if (/(?<!\$\w+)\/hooks\//.test(cmd) || /^node\s+\//.test(cmd)) {
+          absolutePathCount++;
+        }
+      }
+      if (absolutePathCount === 0) {
+        checks.push(pass('hooks-use-plugin-root-var', 3, 3, relPath,
+          { absolutePathCount: 0 },
+          'All hook commands use env var prefix (no absolute paths)'));
+      } else {
+        checks.push(fail('hooks-use-plugin-root-var', 3, relPath,
+          { absolutePathCount },
+          `${absolutePathCount} hook command(s) use absolute paths instead of env var`));
+      }
+    }
+  }
+
+  // c5.3 config-reading-doc
+  {
+    const p = join(root, 'skills/_shared/config-reading.md');
+    const relPath = 'skills/_shared/config-reading.md';
+    const text = safeRead(p);
+    if (!text) {
+      checks.push(fail('config-reading-doc', 2, relPath,
+        { present: false },
+        'skills/_shared/config-reading.md missing'));
+    } else {
+      const hasPluginRoot = text.includes('PLUGIN_ROOT');
+      if (hasPluginRoot) {
+        checks.push(pass('config-reading-doc', 2, 2, relPath,
+          { present: true },
+          'config-reading.md present and contains PLUGIN_ROOT'));
+      } else {
+        checks.push(fail('config-reading-doc', 2, relPath,
+          { present: true },
+          'config-reading.md exists but does not contain PLUGIN_ROOT'));
+      }
+    }
+  }
+
+  // c5.4 bootstrap-gate-doc
+  {
+    const p = join(root, 'skills/_shared/bootstrap-gate.md');
+    const relPath = 'skills/_shared/bootstrap-gate.md';
+    const text = safeRead(p);
+    if (!text) {
+      checks.push(fail('bootstrap-gate-doc', 1, relPath,
+        { present: false },
+        'skills/_shared/bootstrap-gate.md missing'));
+    } else {
+      // CLAUDE.md is the canonical Claude-Code-side name; AGENTS.md is the
+      // Codex CLI alias (skills/_shared/instruction-file-resolution.md).
+      // bootstrap-gate.md must reference the canonical name; presence of the
+      // alias is checked separately by the alias-coverage sweep test.
+      const required = ['CLAUDE.md', 'Session Config', 'bootstrap.lock'];
+      const found = required.filter((s) => text.includes(s));
+      if (found.length === 3) {
+        checks.push(pass('bootstrap-gate-doc', 1, 1, relPath,
+          { present: true },
+          'bootstrap-gate.md present with all required strings'));
+      } else {
+        const missing = required.filter((s) => !text.includes(s));
+        checks.push(fail('bootstrap-gate-doc', 1, relPath,
+          { present: true },
+          `bootstrap-gate.md missing strings: ${missing.join(', ')}`));
+      }
+    }
+  }
+
+  return checks;
+}

package/scripts/lib/harness-audit/categories/category6.mjs

@@ -0,0 +1,211 @@
+/**
+ * category6.mjs — Category 6: Config Hygiene (weight: 8)
+ *
+ * Checks: claude-md-line-count, no-dead-branch-refs, v2-features-section,
+ *         github-mirror-sync
+ *
+ * Stdlib only: node:fs, node:path, node:child_process.
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+import { safeRead, lineCount, pass, fail } from './helpers.mjs';
+import { resolveInstructionFile } from '../../common.mjs';
+
+export function runCategory6(root) {
+  const checks = [];
+
+  // CLAUDE.md (Claude Code / Cursor) and AGENTS.md (Codex CLI) are transparent
+  // aliases — see skills/_shared/instruction-file-resolution.md. Resolve once
+  // and reuse. relPath stays repo-relative for scorecard output.
+  const instr = resolveInstructionFile(root);
+  const instrPath = instr?.path ?? join(root, 'CLAUDE.md');
+  const instrRel = instr ? (instr.kind === 'agents' ? 'AGENTS.md' : 'CLAUDE.md') : 'CLAUDE.md';
+
+  // c6.1 claude-md-line-count
+  {
+    const p = instrPath;
+    const relPath = instrRel;
+    const text = instr ? safeRead(p) : null;
+    if (!text) {
+      checks.push(fail('claude-md-line-count', 3, relPath,
+        { lineCount: 0 },
+        'CLAUDE.md (or AGENTS.md alias) missing'));
+    } else {
+      const count = lineCount(text);
+      if (count <= 250) {
+        checks.push(pass('claude-md-line-count', 3, 3, relPath,
+          { lineCount: count },
+          `${relPath} is ${count} lines (≤ 250)`));
+      } else {
+        checks.push(fail('claude-md-line-count', 3, relPath,
+          { lineCount: count },
+          `${relPath} is ${count} lines (> 250 limit)`));
+      }
+    }
+  }
+
+  // c6.2 no-dead-branch-refs
+  {
+    const p = instrPath;
+    const relPath = instrRel;
+    const text = instr ? safeRead(p) : null;
+    if (!text) {
+      checks.push(fail('no-dead-branch-refs', 3, relPath,
+        { deadRefsFound: [] },
+        'CLAUDE.md (or AGENTS.md alias) missing'));
+    } else {
+      const deadPatterns = ['windows-native-v3', 'legacy-bash-v2', 'feat/v3-'];
+      const textLower = text.toLowerCase();
+      const deadRefsFound = deadPatterns.filter((pat) => textLower.includes(pat.toLowerCase()));
+      if (deadRefsFound.length === 0) {
+        checks.push(pass('no-dead-branch-refs', 3, 3, relPath,
+          { deadRefsFound: [] },
+          `${relPath} contains no dead branch refs`));
+      } else {
+        checks.push(fail('no-dead-branch-refs', 3, relPath,
+          { deadRefsFound },
+          `${relPath} contains dead branch refs: ${deadRefsFound.join(', ')}`));
+      }
+    }
+  }
+
+  // c6.3 plugin-narrative-section — plugin-repo-specific heading check. Consumer
+  // repos never have this section, so we skip-as-pass when the audit target is
+  // NOT the session-orchestrator plugin repo. Plugin repo is detected by the
+  // presence of skills/session-start/SKILL.md (unique to this plugin).
+  //
+  // Accepts any of: `## Current State` (canonical since v3.x), `## v2.0 Features`
+  // (legacy plugin pre-v3), or `## v<major>.<minor> Features` (future-proofed
+  // version-pinned headings). Pre-v3.0 the plugin pinned a specific v2.0 heading;
+  // post-v3.0 the canonical heading is `## Current State` (the session-narrative
+  // anchor). The check is intentionally version-agnostic so the rubric does not
+  // need updating for every release.
+  {
+    const relPath = instrRel;
+    const isPluginRepo = existsSync(join(root, 'skills/session-start/SKILL.md'));
+    const text = instr ? safeRead(instrPath) : null;
+    const hasNarrativeAnchor = text && (
+      text.includes('## Current State') ||
+      /## v\d+\.\d+ Features/.test(text)
+    );
+    if (!isPluginRepo) {
+      checks.push(pass('plugin-narrative-section', 2, 2, relPath,
+        { isPluginRepo: false, skipped: true },
+        'consumer repo — plugin-specific heading check skipped'));
+    } else if (!text) {
+      checks.push(fail('plugin-narrative-section', 2, relPath,
+        { isPluginRepo: true, present: false },
+        'CLAUDE.md (or AGENTS.md alias) missing'));
+    } else if (hasNarrativeAnchor) {
+      checks.push(pass('plugin-narrative-section', 2, 2, relPath,
+        { isPluginRepo: true, present: true },
+        `${relPath} contains plugin-narrative anchor heading`));
+    } else {
+      checks.push(fail('plugin-narrative-section', 2, relPath,
+        { isPluginRepo: true, present: false },
+        `${relPath} missing plugin-narrative anchor (## Current State or ## v<n>.<n> Features)`));
+    }
+  }
+
+  // c6.4 github-mirror-sync — warns when local commits have not reached the
+  // repo's "github" remote (GitLab-primary / GitHub-mirror setups). A repo
+  // with no github remote is not required to mirror anything, so that state
+  // is skip-as-pass (full points) rather than a failure. Every git call is
+  // wrapped defensively — a missing remote, an unfetched tracking ref, a
+  // non-git root, or any other git-edge-case degrades to skip-as-pass so the
+  // audit never crashes or hard-fails on ambient repo state it can't inspect.
+  //
+  // Mirror-branch resolution tries two strategies, in order:
+  //   1. `github/HEAD` symbolic ref — only populated by an explicit
+  //      `git remote set-head github -a` (or an equivalent fetch). A normal
+  //      `git push github HEAD` does NOT set this ref, so a freshly
+  //      bootstrapped repo that has only ever pushed never resolves here.
+  //   2. Local current branch fallback — resolve the local branch name via
+  //      `git rev-parse --abbrev-ref HEAD`, then verify the mirror actually
+  //      has a matching tracking ref (`github/<local-branch>`). This covers
+  //      the common post-bootstrap case: first `git push github HEAD` done,
+  //      `set-head` never run.
+  // Only skip-as-pass when neither strategy resolves an existing tracking ref
+  // (or there is no github remote at all).
+  {
+    const checkId = 'github-mirror-sync';
+    const relPath = '.git';
+
+    const runGit = (args) => {
+      try {
+        return execFileSync('git', args, { cwd: root, encoding: 'utf8' }).trim();
+      } catch {
+        return null;
+      }
+    };
+
+    const remotesOutput = runGit(['remote']);
+    const hasGithubRemote = remotesOutput !== null &&
+      remotesOutput.split('\n').map((l) => l.trim()).includes('github');
+
+    if (!hasGithubRemote) {
+      checks.push(pass({
+        checkId, points: 2, maxPoints: 2, path: relPath,
+        evidence: { hasGithubRemote: false },
+        message: 'no github mirror remote configured — skipped',
+      }));
+    } else {
+      // Strategy 1: github/HEAD symbolic ref.
+      const headAbbrevRef = runGit(['rev-parse', '--abbrev-ref', 'github/HEAD']);
+      const headBranch = headAbbrevRef ? headAbbrevRef.replace(/^github\//, '') : null;
+      const headVerified = headBranch !== null &&
+        runGit(['rev-parse', '--verify', '--quiet', `github/${headBranch}`]) !== null;
+
+      let mirrorBranch = headVerified ? headBranch : null;
+      let resolvedVia = mirrorBranch ? 'github-head' : null;
+
+      // Strategy 2: local current-branch fallback, only tried when strategy 1
+      // didn't resolve a verified tracking ref.
+      if (!mirrorBranch) {
+        const localBranch = runGit(['rev-parse', '--abbrev-ref', 'HEAD']);
+        const localVerified = localBranch !== null &&
+          runGit(['rev-parse', '--verify', '--quiet', `github/${localBranch}`]) !== null;
+        if (localVerified) {
+          mirrorBranch = localBranch;
+          resolvedVia = 'local-branch-fallback';
+        }
+      }
+
+      if (!mirrorBranch) {
+        checks.push(pass({
+          checkId, points: 2, maxPoints: 2, path: relPath,
+          evidence: { hasGithubRemote: true, mirrorBranch: null },
+          message: 'github mirror ref not fetched locally — skipped',
+        }));
+      } else {
+        const revListOut = runGit(['rev-list', '--count', `github/${mirrorBranch}..HEAD`]);
+        const aheadCount = revListOut !== null ? Number.parseInt(revListOut, 10) : NaN;
+
+        if (Number.isNaN(aheadCount)) {
+          checks.push(pass({
+            checkId, points: 2, maxPoints: 2, path: relPath,
+            evidence: { hasGithubRemote: true, mirrorBranch, resolvedVia, aheadCount: null },
+            message: 'unable to determine ahead-count vs github mirror — skipped',
+          }));
+        } else if (aheadCount === 0) {
+          checks.push(pass({
+            checkId, points: 2, maxPoints: 2, path: relPath,
+            evidence: { hasGithubRemote: true, mirrorBranch, resolvedVia, aheadCount },
+            message: `HEAD is fully mirrored to github/${mirrorBranch}`,
+          }));
+        } else {
+          checks.push(pass({
+            checkId, points: 1, maxPoints: 2, path: relPath,
+            evidence: { hasGithubRemote: true, mirrorBranch, resolvedVia, aheadCount },
+            message: `${aheadCount} local commit(s) not pushed to github mirror (github/${mirrorBranch}). Run: git push github HEAD`,
+          }));
+        }
+      }
+    }
+  }
+
+  return checks;
+}

package/scripts/lib/harness-audit/categories/category7.mjs

@@ -0,0 +1,125 @@
+/**
+ * category7.mjs — Category 7: Policy Freshness (weight: 10)
+ *
+ * Checks: blocked-commands-schema, blocked-commands-min-rules,
+ *         parallel-sessions-rules, ecosystem-schema-optional
+ *
+ * Stdlib only: node:fs, node:path.
+ */
+
+import { existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { safeRead, safeJson, pass, fail } from './helpers.mjs';
+
+export function runCategory7(root) {
+  const checks = [];
+
+  // c7.1 blocked-commands-schema
+  {
+    const p = join(root, '.orchestrator/policy/blocked-commands.json');
+    const relPath = '.orchestrator/policy/blocked-commands.json';
+    const text = safeRead(p);
+    const json = safeJson(text);
+    if (!json) {
+      checks.push(fail('blocked-commands-schema', 3, relPath,
+        { version: null, ruleCount: 0 },
+        'blocked-commands.json missing or invalid JSON'));
+    } else {
+      const version = json.version !== undefined ? json.version : null;
+      const rationale = typeof json.rationale === 'string';
+      const rules = Array.isArray(json.rules);
+      const ruleCount = rules ? json.rules.length : 0;
+      if (version !== null && rationale && rules) {
+        checks.push(pass('blocked-commands-schema', 3, 3, relPath,
+          { version, ruleCount },
+          `blocked-commands.json valid: version=${version}, ${ruleCount} rules`));
+      } else {
+        checks.push(fail('blocked-commands-schema', 3, relPath,
+          { version, ruleCount },
+          `blocked-commands.json missing fields: ${[version === null && 'version', !rationale && 'rationale', !rules && 'rules'].filter(Boolean).join(', ')}`));
+      }
+    }
+  }
+
+  // c7.2 blocked-commands-min-rules
+  {
+    const p = join(root, '.orchestrator/policy/blocked-commands.json');
+    const relPath = '.orchestrator/policy/blocked-commands.json';
+    const text = safeRead(p);
+    const json = safeJson(text);
+    if (!json || !Array.isArray(json.rules)) {
+      checks.push(fail('blocked-commands-min-rules', 3, relPath,
+        { ruleCount: 0, wellFormedCount: 0 },
+        'blocked-commands.json missing or has no rules array'));
+    } else {
+      const rules = json.rules;
+      const validSeverities = ['block', 'warn'];
+      const wellFormedRules = rules.filter((r) =>
+        typeof r.id === 'string' &&
+        typeof r.pattern === 'string' &&
+        typeof r.severity === 'string' &&
+        validSeverities.includes(r.severity)
+      );
+      if (rules.length >= 10 && wellFormedRules.length === rules.length) {
+        checks.push(pass('blocked-commands-min-rules', 3, 3, relPath,
+          { ruleCount: rules.length, wellFormedCount: wellFormedRules.length },
+          `${rules.length} rules, all well-formed`));
+      } else {
+        checks.push(fail('blocked-commands-min-rules', 3, relPath,
+          { ruleCount: rules.length, wellFormedCount: wellFormedRules.length },
+          `${rules.length} rules (need ≥10), ${wellFormedRules.length} well-formed`));
+      }
+    }
+  }
+
+  // c7.3 parallel-sessions-rules
+  {
+    const p = join(root, '.claude/rules/parallel-sessions.md');
+    const relPath = '.claude/rules/parallel-sessions.md';
+    const text = safeRead(p);
+    if (!text || statSync(join(root, relPath), { throwIfNoEntry: false })?.size === 0) {
+      checks.push(fail('parallel-sessions-rules', 2, relPath,
+        { psaCodesFound: [] },
+        'parallel-sessions.md missing or empty'));
+    } else {
+      const psaCodes = ['PSA-001', 'PSA-002', 'PSA-003', 'PSA-004'];
+      const psaCodesFound = psaCodes.filter((c) => text.includes(c));
+      if (psaCodesFound.length === 4) {
+        checks.push(pass('parallel-sessions-rules', 2, 2, relPath,
+          { psaCodesFound },
+          'parallel-sessions.md contains all 4 PSA codes'));
+      } else {
+        const missing = psaCodes.filter((c) => !text.includes(c));
+        checks.push(fail('parallel-sessions-rules', 2, relPath,
+          { psaCodesFound },
+          `parallel-sessions.md missing PSA codes: ${missing.join(', ')}`));
+      }
+    }
+  }
+
+  // c7.4 ecosystem-schema-optional
+  {
+    const p = join(root, '.orchestrator/policy/ecosystem.schema.json');
+    const relPath = '.orchestrator/policy/ecosystem.schema.json';
+    if (!existsSync(p)) {
+      checks.push(pass('ecosystem-schema-optional', 2, 2, relPath,
+        { present: false, valid: null },
+        'ecosystem.schema.json absent (optional) — skip'));
+    } else {
+      const text = safeRead(p);
+      const json = safeJson(text);
+      if (json !== null) {
+        checks.push(pass('ecosystem-schema-optional', 2, 2, relPath,
+          { present: true, valid: true },
+          'ecosystem.schema.json present and valid JSON'));
+      } else {
+        checks.push(fail('ecosystem-schema-optional', 2, relPath,
+          { present: true, valid: false },
+          'ecosystem.schema.json present but invalid JSON'));
+      }
+    }
+  }
+
+  return checks;
+}