session-orchestrator 3.19.0 → 3.21.0

package/scripts/sweep-expired-learnings.mjs

@@ -1,39 +1,56 @@
 #!/usr/bin/env node
 /**
- * sweep-expired-learnings.mjs — CLI for the mechanical expiry/archive sweep
- * (Epic #723 B4).
+ * sweep-expired-learnings.mjs — CLI for the two mechanical archive-safe writers
+ * over `learnings.jsonl`: the time-driven expiry sweep (Epic #723 B4, default)
+ * and the decision-driven prune (`--prune`, issue #1017).
  *
- * Moves `learnings.jsonl` entries that have been expired for longer than the
- * grace period into an append-only archive sidecar. NEVER deletes data —
- * archived entries remain readable in the archive file, tagged with
- * `_archived_at` / `_archive_reason: "expired"`.
+ * Both move records OUT of the active store and INTO an append-only archive
+ * sidecar. NEVER deletes data — archived entries remain readable in the archive
+ * file, tagged with `_archived_at` and an `_archive_reason` from the closed
+ * enum `expired | pruned | superseded | merged`.
  *
  * All read/partition/write logic lives in
- * `scripts/lib/learnings/expiry-sweep.mjs` (`sweepExpiredLearnings`), which
- * delegates the destructive store rewrite to `rewriteLearnings()` from
- * `scripts/lib/learnings/io.mjs` — automatic `.bak-<ISO>` backup + keep-3
- * rotation (#721) protects every `--apply` run.
+ * `scripts/lib/learnings/expiry-sweep.mjs` (`sweepExpiredLearnings` /
+ * `pruneLearnings`), which delegates the destructive store rewrite to
+ * `rewriteLearnings()` from `scripts/lib/learnings/io.mjs` — automatic
+ * `.bak-<ISO>` backup + keep-3 rotation (#721) protects every `--apply` run.
+ *
+ * Why `--prune` is a subcommand here and not an inline `node -e` block in
+ * `skills/evolve/SKILL.md`: a mechanism that lives inside prose has no test, no
+ * `--help`, and no exit-code contract. `/evolve` names this command; the
+ * mechanism stays in code.
  *
  * Usage:
- *   node scripts/sweep-expired-learnings.mjs [--dry-run|--apply] [--json]
- *     [--grace-days N] [--file PATH] [--archive PATH]
+ *   node scripts/sweep-expired-learnings.mjs [--prune] [--dry-run|--apply] [--json]
+ *     [--grace-days N] [--entries PATH] [--file PATH] [--archive PATH]
  *
  * Flags:
- *   --dry-run         Preview counts; write nothing (DEFAULT)
- *   --apply           Archive stale-expired entries + rewrite the store
+ *   --prune           Decision-driven prune+consolidate+rewrite instead of the
+ *                      time-driven expiry sweep (issue #1017)
+ *   --dry-run         Preview counts; write nothing (DEFAULT, both modes)
+ *   --apply           Perform the archive append + store rewrite
  *   --json            Emit a single machine-parseable JSON summary line
  *                      (default: human-readable one-liner)
- *   --grace-days N    Days past expiry before archiving (default: 14)
+ *   --grace-days N    Days past expiry before archiving (default: 14).
+ *                      SWEEP ONLY — `--prune` has no grace window by design.
+ *   --entries PATH    JSONL sidecar holding the caller's next store generation.
+ *                      PRUNE ONLY. Must exist, parse cleanly, and hold at least
+ *                      one record — absent/malformed/empty all exit 1 untouched.
+ *                      Omitted ⇒ a pure prune+consolidate pass over the on-disk
+ *                      store.
  *   --file PATH       Learnings store (default: .orchestrator/metrics/learnings.jsonl)
  *   --archive PATH    Archive sidecar (default: .orchestrator/metrics/learnings-archive.jsonl)
  *
  * Exit codes:
  *   0  Success (including no-op when nothing is archive-eligible)
- *   1  Usage error (bad flag/value)
- *   2  Sweep error (I/O or validation failure inside sweepExpiredLearnings)
+ *   1  Usage/input error (bad flag/value, flag used in the wrong mode, or an
+ *      absent/malformed/empty `--entries` sidecar)
+ *   2  Sweep/prune error (I/O or validation failure inside the lib)
  */
 
-import { sweepExpiredLearnings } from './lib/learnings/expiry-sweep.mjs';
+import { existsSync } from 'node:fs';
+import { sweepExpiredLearnings, pruneLearnings } from './lib/learnings/expiry-sweep.mjs';
+import { readLearnings } from './lib/learnings/io.mjs';
 
 const DEFAULT_FILE = '.orchestrator/metrics/learnings.jsonl';
 const DEFAULT_ARCHIVE = '.orchestrator/metrics/learnings-archive.jsonl';
@@ -41,32 +58,51 @@ const DEFAULT_GRACE_DAYS = 14;
 
 function printHelp() {
   process.stdout.write(
-    `Usage: node scripts/sweep-expired-learnings.mjs [--dry-run|--apply] [--json] [--grace-days N] [--file PATH] [--archive PATH]
+    `Usage: node scripts/sweep-expired-learnings.mjs [--prune] [--dry-run|--apply] [--json] [--grace-days N] [--entries PATH] [--file PATH] [--archive PATH]
+
+Modes:
+  (default)         Expiry sweep — archive entries expired past the grace window
+  --prune           Prune + consolidate + rewrite (issue #1017): archives
+                    expired / zero-confidence / superseded / caller-dropped
+                    records instead of deleting them
 
 Options:
   --dry-run         Preview counts; write nothing (default)
-  --apply           Archive stale-expired entries + rewrite the store
+  --apply           Perform the archive append + store rewrite
   --json            Emit a single machine-parseable JSON summary line
-  --grace-days N    Days past expiry before archiving (default: ${DEFAULT_GRACE_DAYS})
+  --grace-days N    Days past expiry before archiving (default: ${DEFAULT_GRACE_DAYS}); sweep only
+  --entries PATH    JSONL sidecar with the next store generation; prune only.
+                    Must exist, parse cleanly, and hold >= 1 record
   --file PATH       Learnings store (default: ${DEFAULT_FILE})
   --archive PATH    Archive sidecar (default: ${DEFAULT_ARCHIVE})
 
-Exit codes:  0 success  1 usage error  2 sweep error
+Exit codes:  0 success  1 usage/input error  2 sweep/prune error
 `
   );
 }
 
+/** Exit 1 with a diagnostic on stderr (usage/input errors). */
+function usageError(message) {
+  process.stderr.write(`sweep-expired-learnings: ${message}\n`);
+  process.exit(1);
+}
+
 function parseArgs(argv) {
   const args = {
+    prune: false,
     dryRun: true,
     json: false,
     graceDays: DEFAULT_GRACE_DAYS,
+    graceDaysExplicit: false,
+    entries: null,
     file: DEFAULT_FILE,
     archive: DEFAULT_ARCHIVE,
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === '--apply') {
+    if (a === '--prune') {
+      args.prune = true;
+    } else if (a === '--apply') {
       args.dryRun = false;
     } else if (a === '--dry-run') {
       args.dryRun = true;
@@ -76,12 +112,12 @@ function parseArgs(argv) {
       const raw = argv[++i];
       const v = Number(raw);
       if (!Number.isFinite(v) || v < 0) {
-        process.stderr.write(
-          `sweep-expired-learnings: --grace-days requires a non-negative number, got: ${raw}\n`
-        );
-        process.exit(1);
+        usageError(`--grace-days requires a non-negative number, got: ${raw}`);
       }
       args.graceDays = v;
+      args.graceDaysExplicit = true;
+    } else if (a === '--entries') {
+      args.entries = argv[++i];
     } else if (a === '--file') {
       args.file = argv[++i];
     } else if (a === '--archive') {
@@ -90,16 +126,29 @@ function parseArgs(argv) {
       printHelp();
       process.exit(0);
     } else {
-      process.stderr.write(`sweep-expired-learnings: unknown argument: ${a}\n`);
-      process.exit(1);
+      usageError(`unknown argument: ${a}`);
     }
   }
+
+  // Mode/flag mismatches are usage errors, never silent no-ops: a `--grace-days`
+  // that the prune path ignores would read as "the grace window applied" in a
+  // transcript, and an `--entries` the sweep ignores would read as "my next
+  // generation was written".
+  if (args.prune && args.graceDaysExplicit) {
+    usageError('--grace-days is not valid with --prune (the prune path has no grace window)');
+  }
+  if (!args.prune && args.entries !== null) {
+    usageError('--entries is only valid with --prune');
+  }
   return args;
 }
 
-async function main() {
-  const args = parseArgs(process.argv.slice(2));
-
+/**
+ * Time-driven expiry sweep (Epic #723 B4) — the default mode.
+ *
+ * @param {ReturnType<typeof parseArgs>} args
+ */
+async function runSweep(args) {
   let result;
   try {
     result = await sweepExpiredLearnings({
@@ -129,6 +178,117 @@ async function main() {
   }
 }
 
+/**
+ * Resolve the `--entries` sidecar into the caller's next store generation.
+ *
+ * Fails closed on THREE input conditions, all of which yield the same lethal
+ * value — an empty next generation, which makes `pruneLearnings()` treat the
+ * ENTIRE store as caller-dropped:
+ *
+ *   1. **absent file** — `readLearnings()` returns `{entries: [], malformed: []}`
+ *      for a missing path, so one mistyped path would archive every active
+ *      learning. A path the operator named and the filesystem does not have is
+ *      an input error, not an empty set.
+ *   2. **malformed line** — a half-written sidecar reads as a SHORTER next
+ *      generation, pruning every record the truncated tail omitted.
+ *   3. **parses to zero records** — a 0-byte or blank-line-only file. Guard (1)
+ *      closes ABSENCE, which is a different condition: an empty file EXISTS, so
+ *      it sails past `existsSync` and parses to a legitimate-looking empty
+ *      generation. Measured on a 3-record fixture before this guard: a 0-byte
+ *      `--entries` archived all 3 and exited 0.
+ *
+ * Condition 3 is REJECTED rather than obeyed because at a file boundary an
+ * empty parse is indistinguishable from a truncated write, a failed producer,
+ * or a typo that landed on an unrelated empty file — and no caller expresses
+ * "archive the whole corpus" through this flag: `/evolve`'s next generation
+ * always carries the survivors. The cost of rejecting a genuinely-intended
+ * empty generation is one re-run; the cost of obeying a corrupt one is the
+ * active store. Note this guard is deliberately NOT in `pruneLearnings()`: an
+ * explicit `entries: []` written in CODE is a statement, and the lib keeps it
+ * expressible. Only the FILE is ambiguous, so only the file is guarded.
+ *
+ * @param {string} entriesPath
+ * @returns {Promise<object[]>} the validated, non-empty next generation
+ */
+async function loadEntriesSidecar(entriesPath) {
+  if (!existsSync(entriesPath)) {
+    usageError(
+      `--entries sidecar not found: ${entriesPath} (refusing to prune — an absent ` +
+        `next generation would archive the whole store)`
+    );
+  }
+  let read;
+  try {
+    read = await readLearnings(entriesPath);
+  } catch (err) {
+    usageError(`--entries sidecar unreadable: ${entriesPath}: ${err.message}`);
+  }
+  if (read.malformed.length > 0) {
+    usageError(
+      `refusing to prune — ${read.malformed.length} malformed line(s) in ${entriesPath}`
+    );
+  }
+  if (read.entries.length === 0) {
+    usageError(
+      `--entries sidecar holds no records: ${entriesPath} (refusing to prune — an empty ` +
+        `next generation would archive every record in the store; omit --entries for a ` +
+        `pure prune+consolidate pass)`
+    );
+  }
+  return read.entries;
+}
+
+/**
+ * Decision-driven prune + consolidate + rewrite (issue #1017).
+ *
+ * @param {ReturnType<typeof parseArgs>} args
+ */
+async function runPrune(args) {
+  const entries = args.entries === null ? undefined : await loadEntriesSidecar(args.entries);
+
+  let result;
+  try {
+    result = await pruneLearnings({
+      filePath: args.file,
+      archivePath: args.archive,
+      entries,
+      dryRun: args.dryRun,
+    });
+  } catch (err) {
+    process.stderr.write(`sweep-expired-learnings: prune failed: ${err.message}\n`);
+    process.exit(2);
+  }
+
+  const summary = {
+    file: args.file,
+    entries_from: args.entries,
+    ...result,
+  };
+
+  if (args.json) {
+    process.stdout.write(JSON.stringify(summary) + '\n');
+  } else {
+    const byReason =
+      Object.entries(summary.byReason)
+        .map(([reason, n]) => `${reason}:${n}`)
+        .join(',') || '-';
+    process.stdout.write(
+      `sweep-expired-learnings: prune scanned=${summary.scanned} kept=${summary.kept} ` +
+        `archived=${summary.archived} by_reason=${byReason} dry_run=${summary.dryRun} ` +
+        `archive=${summary.archivePath}\n`
+    );
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.prune) {
+    await runPrune(args);
+    return;
+  }
+  await runSweep(args);
+}
+
 main().catch((err) => {
   process.stderr.write(`sweep-expired-learnings: unexpected error: ${err?.stack ?? err}\n`);
   process.exit(2);

package/scripts/validate-plugin.mjs

@@ -204,12 +204,28 @@ if (runCheck('check-agents.mjs') !== 0) checkFailed = 1;
 process.stdout.write('\n');
 if (runCheck('check-commands.mjs') !== 0) checkFailed = 1;
 
+// FAIL-capable from day one: every rule this check enforces (frontmatter present,
+// parses as YAML, kebab-case name matching the directory, non-empty description)
+// was measured at 0 violations across all 46 SKILL.md files at the commit that
+// added it — so unlike the WARN-only censuses further down, it cannot be red on
+// arrival. It sits next to check-commands.mjs because it shares that check's
+// posture: a real js-yaml parse, not the line-regex approach of check-agents.mjs
+// that let 12 unparseable SKILL.md frontmatter blocks go unnoticed.
+process.stdout.write('\n');
+if (runCheck('check-skills.mjs') !== 0) checkFailed = 1;
+
 process.stdout.write('\n');
 if (runDriftCheck() !== 0) checkFailed = 1;
 
 process.stdout.write('\n');
 if (runCheck('check-hooks-symmetry.mjs') !== 0) checkFailed = 1;
 
+process.stdout.write('\n');
+if (runCheck('check-guard-requires-parity.mjs') !== 0) checkFailed = 1;
+
+process.stdout.write('\n');
+if (runCheck('check-banner-parity.mjs') !== 0) checkFailed = 1;
+
 process.stdout.write('\n');
 if (runCheck('check-playwright-mcp-canary.mjs') !== 0) checkFailed = 1;
 
@@ -249,6 +265,72 @@ if (runCheck('check-unicode-safety.mjs') !== 0) checkFailed = 1;
 process.stdout.write('\n');
 if (runCheck('check-dead-bridge.mjs') !== 0) checkFailed = 1;
 
+// FAIL-capable, unlike the WARN-only censuses below: R2+R4 were measured at
+// 1 hit / 1 TP / 0 FP each against the full test corpus, so this check cannot be
+// red on arrival for anything but a real instance of the class. The alternatives
+// (R1 at 67 FP, R3 at 47 FP) are exactly the shape that gets demoted to WARN and
+// then ignored — see the rule table in the check's header.
+process.stdout.write('\n');
+if (runCheck('check-untracked-test-deps.mjs') !== 0) checkFailed = 1;
+
+// WARN-only (v1): the unwired-config-key census reports but never fails the
+// build — see the rationale in the check's header (a blocking gate on today's
+// inventory would be red from day one and get disabled). Exit code is
+// deliberately ignored; only a tool error (2) would be worth escalating later.
+process.stdout.write('\n');
+runCheck('check-unwired-features.mjs');
+
+// WARN-only (#1017), same rationale as the census above: 11 of 13 provenance
+// pointers in .claude/rules/ dangle at the time this check landed, so a blocking
+// gate would be red on arrival. The exit code is deliberately ignored; a tool
+// error still surfaces because that path prints FAIL: lines, which runCheck
+// tallies into totalFail.
+process.stdout.write('\n');
+runCheck('check-learning-provenance.mjs');
+
+// WARN-only (#971), same rationale as the two censuses above: a `gh`/`glab` call
+// without `--repo`/`-R` resolves its target project from the ambient cwd remote —
+// silently the wrong project in a sibling worktree, an /autopilot child, or a repo
+// whose origin is a fork — and a gate that blocks on a backlog no single pass can
+// drain gets switched off rather than obeyed. What WARN buys is that each newly
+// added bare call site shows up in every validator run while the sweep drains the
+// rest. No headcount is quoted here on purpose: the live number moves with every
+// commit, and only the check's own `--json` summary can state it as of a SHA. The
+// exit code is deliberately ignored; a tool error still surfaces because that path
+// prints FAIL: lines, which runCheck tallies into totalFail.
+process.stdout.write('\n');
+runCheck('check-vcs-repo-flag.mjs');
+
+// WARN-only (#1023): a `gh`/`glab` command cited in docs that no released CLI
+// ever had — `glab repo edit --visibility`, `glab group list` — costs an
+// operator a failed command and a re-derivation. The oracle is the CLI's own
+// `--help` COMMANDS section, never an exit code (`glab repo <anything> --help`
+// exits 0). WARN rather than FAIL because that oracle is the LOCALLY installed
+// binary: a version skew must not red an unrelated commit, and a missing binary
+// SKIPs. The exit code is deliberately ignored; a tool error still surfaces
+// because that path prints FAIL: lines, which runCheck tallies into totalFail.
+process.stdout.write('\n');
+runCheck('check-doc-cli-commands.mjs');
+
+// WARN-only: a state-mutating `git` call in tests/ that names no target resolves
+// its destination from the ambient cwd (or an inherited GIT_DIR) — the 2026-08-19
+// incident, where fixture commits, a fixture remote and a fixture identity landed
+// in the REAL .git and two commits reached both remotes with the wrong author.
+// WARN rather than FAIL is a MEASURED posture, not caution: the v1 rule reported
+// 11 findings against tests/ and all 11 were false positives (`git init <dir>`,
+// whose positional IS the target). After that refinement the live corpus reports
+// 0 findings — i.e. zero measured true positives to weigh against a textual
+// detector's residual false-positive surface (the variable argv arrays it cannot
+// judge; the live count is in its own PASS line, never restated here).
+// check-untracked-test-deps.mjs above earned FAIL-capability on a
+// measured 1 TP / 0 FP; this check has not, and a single FAIL: line here reds the
+// whole validator. Ratchet to FAIL once a live true positive has been observed
+// and the GIT_DIR-inheritance gap (reported as `gitDirInheritable`) is closed
+// centrally. The exit code is deliberately ignored; a tool error still surfaces
+// because that path prints FAIL: lines, which runCheck tallies into totalFail.
+process.stdout.write('\n');
+runCheck('check-test-git-config-target.mjs');
+
 // ---------------------------------------------------------------------------
 // Summary
 // ---------------------------------------------------------------------------