session-orchestrator 5.3.0 → 5.4.0

package/scripts/lib/validate/check-learnings-shell-writes.mjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+/**
+ * Check: no instruction prose tells an agent to write `learnings.jsonl` with a
+ * shell redirect (GitLab #1446 / GitHub #69). BLOCKING.
+ *
+ * ## Why
+ *
+ * The store is gitignored, so a bad write has no VCS restore. The sanctioned
+ * write paths — `scripts/apply-session-learnings.mjs` (session-end, retro) and
+ * `scripts/sweep-expired-learnings.mjs --prune` (`/evolve`) — validate every
+ * record, snapshot `.bak-<ISO>`, and archive what leaves the store. A shell
+ * `>` / `>>` does none of that. The prose producers this change closed, all
+ * measured at ebf63bd1:
+ *
+ *   - `skills/session-end/learning-patterns.md` Phase 3.6 step 4g ("atomic
+ *     rewrite with `>`") — the path that wrote a file PATH into `scope` (GH#69);
+ *   - `skills/plan/mode-retro.md` § 3.3 — an unnamed "Append new patterns to
+ *     `learnings.jsonl`" with no mechanism at all;
+ *   - `.cursor/rules/060-evolve.mdc` — three sites ("Write entire result back
+ *     with `>`", "write all with `>`" twice). None of the three names
+ *     `learnings.jsonl` on its own line, which is why R2 is windowed.
+ *
+ * ## Rules
+ *
+ *   R1 shell redirect  — `>`/`>>` directly in front of a `…learnings.jsonl`
+ *                        target on the same line. The leading boundary (start,
+ *                        whitespace, `|`, `;`, `&`, `(`) is load-bearing:
+ *                        without it 9 of 12 hits were `<state-dir>/…`
+ *                        placeholders. A Markdown blockquote marker (`> ` at
+ *                        line start, outside a fence) is not a redirect and is
+ *                        stripped first; inside a fence it IS a truncation.
+ *   R3 tee             — `tee [-a] …learnings.jsonl` on the same line.
+ *   R2 prose operator  — a backticked `` `>` `` / `` `>>` `` within ±3 lines
+ *                        (WINDOW) of an anchor: `learnings.jsonl`, "the store",
+ *                        "learnings store", "result back", "atomic rewrite".
+ *                        The last two are the retired producers' own wording.
+ *                        An operator inside an ASCII double-quoted span is a
+ *                        quotation of former prose, not an instruction.
+ *
+ * Exempt (per operator): a prohibition keyword (NEVER / do not / FORBIDDEN /
+ * verboten …) BEFORE the operator in the same sentence — a keyword after it
+ * (`… > learnings.jsonl # never run this twice`) or in an earlier sentence
+ * (`Never skip review. Then run: … >> learnings.jsonl`) does not count.
+ * Exempt (whole line): the last sentence of the previous non-empty line states
+ * a prohibition before any operator, an empty-file create (`: > file`), or the
+ * marker `<!-- learnings-write-check: prohibition -->` on the line or the
+ * previous non-empty line. Fenced blocks ARE scanned — a fenced shell snippet
+ * is exactly a shell write.
+ *
+ * @module scripts/lib/validate/check-learnings-shell-writes
+ */
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { enumerateRepoFiles } from './enumerate-repo-files.mjs';
+import { isMainModule } from '../is-main-module.mjs';
+
+/** Instruction corpora that tell an agent what to run. */
+export const SCAN_DIRS = Object.freeze(['skills', 'commands', 'agents', 'docs', '.claude/rules', '.cursor/rules']);
+
+/** Lines on either side of an R2 operator searched for an anchor. */
+const WINDOW = 3;
+
+const MENTION_RE = /learnings\.jsonl/;
+const ANCHOR_RE = /learnings\.jsonl|\b(?:the|learnings) store\b|\bresult back\b|\batomic rewrite\b/i;
+const SHELL_REDIRECT_RE = /(?:^|[\s|;&(])(>{1,2})[ \t]*["'`]?[^\s"'`<>]*learnings\.jsonl\b/dg;
+const TEE_RE = /\btee\b(?:[ \t]+-{1,2}[\w-]+)*[ \t]+["'`]?[^\s"'`|]*learnings\.jsonl\b/g;
+const PROSE_OPERATOR_RE = /`>{1,2}`/g;
+const ANY_OPERATOR_RE = /`>{1,2}`|(?:^|[\s|;&(])>{1,2}|\btee\b/;
+const PROHIBITION_RE = /\b(NEVER|[Nn]ever|DO NOT|[Dd]o not|[Dd]on't|FORBIDDEN|forbidden|verboten)\b/;
+// A sentence ends at `.`/`!`/`?` + whitespace + a capital (markup allowed):
+// `jq . next` and `jq | ... >` are not sentence breaks.
+const SENTENCE_BREAK_RE = /[.!?]\s+(?=[*_`"']*[A-Z])/;
+const EMPTY_CREATE_RE = /^\s*:\s*>/;
+const BLOCKQUOTE_RE = /^\s*(?:>[ \t])+/;
+const FENCE_RE = /^\s*(?:```|~~~)/;
+const MARKER = '<!-- learnings-write-check: prohibition -->';
+
+/** The sentence a position sits in, cut off at that position. */
+function clauseBefore(text, pos) {
+  return text.slice(0, pos).split(SENTENCE_BREAK_RE).pop();
+}
+
+/** True when a prohibition keyword precedes `pos` within its own sentence. */
+function prohibitedBefore(text, pos) {
+  return PROHIBITION_RE.test(clauseBefore(text, pos));
+}
+
+/** True when the last sentence of `line` states a prohibition before any operator. */
+function isProhibitionSentence(line) {
+  const last = line.replace(BLOCKQUOTE_RE, '').trimEnd().split(SENTENCE_BREAK_RE).pop();
+  const k = last.search(PROHIBITION_RE);
+  if (k < 0) return false;
+  const o = last.search(ANY_OPERATOR_RE);
+  return o < 0 || k < o;
+}
+
+/** True when `pos` sits inside an ASCII double-quoted span of `text`. */
+function insideDoubleQuotes(text, pos) {
+  return (text.slice(0, pos).match(/"/g) ?? []).length % 2 === 1;
+}
+
+/**
+ * Every operator on the line as `{rule, pos}`, positions relative to `body`.
+ * R2 candidates are returned only when the ±WINDOW neighbourhood holds an anchor.
+ */
+function operatorsOf(body, lines, i) {
+  const ops = [];
+  if (MENTION_RE.test(body)) {
+    for (const m of body.matchAll(SHELL_REDIRECT_RE)) ops.push({ rule: 'R1', pos: m.indices[1][0] });
+    for (const m of body.matchAll(TEE_RE)) ops.push({ rule: 'R3', pos: m.index });
+  }
+  const prose = [...body.matchAll(PROSE_OPERATOR_RE)];
+  if (prose.length > 0) {
+    const from = Math.max(0, i - WINDOW);
+    const anchored = lines.slice(from, i + WINDOW + 1).some((l) => ANCHOR_RE.test(l));
+    if (anchored) {
+      for (const m of prose) {
+        if (!insideDoubleQuotes(body, m.index)) ops.push({ rule: 'R2', pos: m.index });
+      }
+    }
+  }
+  return ops;
+}
+
+/**
+ * Scan the instruction corpora for shell writes to `learnings.jsonl`.
+ *
+ * @param {{ pluginRoot: string, dirs?: readonly string[] }} opts
+ * @returns {{ ok: boolean, findings: {file: string, line: number, rule: string, text: string}[],
+ *   summary: { filesScanned: number, mentions: number, exempt: number } }}
+ */
+export function scanLearningsShellWrites({ pluginRoot, dirs = SCAN_DIRS }) {
+  const files = enumerateRepoFiles({ repoRoot: pluginRoot, dirs: [...dirs], exts: ['.md', '.mdc'] });
+  const findings = [];
+  let mentions = 0;
+  let exempt = 0;
+  for (const abs of files) {
+    const lines = readFileSync(abs, 'utf8').split('\n');
+    const rel = path.relative(pluginRoot, abs);
+    let inFence = false;
+    let prev = '';
+    lines.forEach((text, i) => {
+      const prevNonEmpty = prev;
+      if (text.trim().length > 0) prev = text;
+      if (FENCE_RE.test(text)) {
+        inFence = !inFence;
+        return;
+      }
+      if (MENTION_RE.test(text)) mentions += 1;
+      const body = inFence ? text : text.replace(BLOCKQUOTE_RE, '');
+      const ops = operatorsOf(body, lines, i);
+      if (ops.length === 0) return;
+      const lineExempt =
+        EMPTY_CREATE_RE.test(body) ||
+        text.includes(MARKER) ||
+        prevNonEmpty.includes(MARKER) ||
+        isProhibitionSentence(prevNonEmpty);
+      const failing = lineExempt ? [] : ops.filter((op) => !prohibitedBefore(body, op.pos));
+      if (failing.length === 0) {
+        exempt += 1;
+        return;
+      }
+      const rule = ['R1', 'R3', 'R2'].find((r) => failing.some((op) => op.rule === r));
+      findings.push({ file: rel, line: i + 1, rule, text: text.trim() });
+    });
+  }
+  return { ok: findings.length === 0, findings, summary: { filesScanned: files.length, mentions, exempt } };
+}
+
+const RULE_TEXT = Object.freeze({
+  R1: 'shell redirect into learnings.jsonl',
+  R2: 'redirect operator near a learnings.jsonl / store-write mention',
+  R3: 'tee into learnings.jsonl',
+});
+
+/**
+ * Run the human-readable validator CLI.
+ *
+ * @param {string} pluginRoot absolute plugin root
+ * @returns {number} 0 = clean, 1 = findings
+ */
+export function runCheckLearningsShellWrites(pluginRoot) {
+  console.log('--- Check: no shell-redirect writes to learnings.jsonl in instruction prose ---');
+  const inspection = scanLearningsShellWrites({ pluginRoot });
+  for (const f of inspection.findings) {
+    console.log(
+      `  FAIL: [${f.rule}] ${f.file}:${f.line} ${RULE_TEXT[f.rule]} — route the write through ` +
+        '`scripts/apply-session-learnings.mjs` or `sweep-expired-learnings.mjs --prune`',
+    );
+  }
+  const s = inspection.summary;
+  if (inspection.ok) {
+    console.log(
+      `  PASS: ${s.mentions} learnings.jsonl mention(s) in ${s.filesScanned} file(s), ` +
+        `${s.exempt} exempt as prohibition`,
+    );
+  }
+  console.log('');
+  console.log(`Results: ${inspection.ok ? 1 : 0} passed, ${inspection.findings.length} failed`);
+  return inspection.ok ? 0 : 1;
+}
+
+if (isMainModule(import.meta.url)) {
+  const args = process.argv.slice(2).filter((arg) => arg !== '--json');
+  const root = path.resolve(args[0] || process.cwd());
+  if (process.argv.includes('--json')) {
+    const inspection = scanLearningsShellWrites({ pluginRoot: root });
+    process.stdout.write(`${JSON.stringify(inspection, null, 2)}\n`);
+    process.exitCode = inspection.ok ? 0 : 1;
+  } else {
+    process.exitCode = runCheckLearningsShellWrites(root);
+  }
+}

package/scripts/lib/validate/check-test-value-bans.mjs

@@ -93,7 +93,8 @@
  *                     pure input→output date function is out of scope by
  *                     construction rather than by exception list.
  *
- *                     NOT flagged: blocks that control the clock (`now:` arg,
+ *                     NOT flagged: blocks that control the clock (`now:`, `{ now }`
+ *                     or a positional `now` — wider than the seam proof, #1478 —
  *                     `vi.useFakeTimers` / `vi.setSystemTime`); date literals in
  *                     INPUT position (only `.toBe`/`.toEqual`/`.toStrictEqual`
  *                     expected values are read), which leaves the passthrough
@@ -335,18 +336,68 @@ const keyLiteralRe = (key) => new RegExp(`["'\\\\]+${key}["'\\\\]+\\s*:`);
  * An absolute date pinned as the EXPECTED value of an equality assertion.
  * Input-position date literals (`created_at: '2026-06-21T…'`) do not match —
  * that is what keeps the passthrough class (input date === output date) out.
+ *
+ * CEILING (#1473): a fixed INPUT date that a production TTL ages out later is
+ * not flagged either, on purpose. Measured 2026-09-29 with a shim that moves
+ * `Date.now()` and `new Date()` forward in every vitest worker: the 34 test
+ * files (plus one fixture module) holding a fixed `created_at: '2026-05…09'`
+ * (1,211 tests) stayed green at +120, +365 and +3,650 days, so a rule keyed on
+ * fixed input dates would have reported false positives only. The one real
+ * bomb of that shape, the phase-skip fixture before 6670149c, was green at
+ * -60 days and red at +0 and +120 days under the same shim — and
+ * scanClockBombs() reaches that file since #1476 (alias imports are read) but
+ * stays silent on it: the file hands no clock argument to anything. REVISIT when a
+ * second fixed-input-date bomb lands on main: the class then recurs, and a
+ * clock-shift run of the suite is the check that finds it without guessing.
  */
 const DATE_EXPECTATION =
   /\.(?:toBe|toEqual|toStrictEqual)\(\s*(['"`])(\d{4}-\d{2}-\d{2}(?:[T ][^'"`]*)?)\1\s*\)/;
 
-/** An explicit clock handed to a callee — the seam this ban asks tests to use. */
-const CLOCK_ARG = /\b(?:now|nowMs|nowIso|clock|currentDate)\s*:/;
+/** A clock-named token not read off an object (`Date.now`, `opts.now`) — shared head of the two below. */
+const CLOCK_NAME = String.raw`(?<![.\w$])(?:now|nowMs|nowIso|clock|currentDate)\s*`;
+
+/**
+ * Pass 1, the seam PROOF: a NAMED clock key (`{ now: … }`) — only that shape says
+ * the callee's API takes a clock. Every line it matches also matches
+ * CONTROL_CLOCK_ARG, so a block that proves a seam is never flagged itself.
+ */
+const SEAM_CLOCK_ARG = new RegExp(`${CLOCK_NAME}:`);
+
+/**
+ * Pass 2, is this block clock-CONTROLLED: any clock handover. Property shorthand
+ * (`{ now }`, `{ repoRoot, now }`) and a positional `now` count too; `Date.now()`
+ * and `const now =` do not. Wider is the safe direction here — it can only
+ * remove findings.
+ *
+ * CEILING (#1478): pass 1 reads only the named form, because the wide form also
+ * turns helpers into seams — +20 seamed (file, id) pairs in 15 files
+ * (172 → 192, measured 2026-10-01 @ ffc5929f), e.g. `expectDeny` via a
+ * `{ manifestMtimeMs: now }` fixture. Cost: a file whose ONLY clock handover is
+ * `{ now }` or a positional `now` loses its seam proof and its bombs go unseen.
+ * REVISIT on the first B5 finding whose subject is a helper, or the first CI
+ * `test-value-bans` B5 finding the ±days clock-shift probe shows to be false.
+ */
+const CONTROL_CLOCK_ARG = new RegExp(String.raw`${CLOCK_NAME}(?::|,|\}|\))`);
 
 /** Freezing the global clock — equally valid control, but not a seam PROOF. */
 const FAKE_TIMER = /\b(?:useFakeTimers|setSystemTime|advanceTimersByTime|runAllTimers)\b/;
 
-/** `import { a, b as c } from './rel.mjs'` — SUT candidates live behind these. */
-const RELATIVE_IMPORT = /import\s+([^;]+?)\s+from\s+['"](\.[^'"]+)['"]/g;
+/**
+ * Vitest aliases that resolve to the repo's own modules — source of truth is
+ * `resolve.alias` in vitest.config.mjs (today only `@lib`). CEILING: one entry
+ * per alias, kept by hand; REVISIT when vitest.config.mjs gains an alias — the
+ * parametrised B5 test reads that config and goes red until the key is listed
+ * here. Dynamic imports (`await import('@lib/…')`) are not read in either form.
+ */
+const ALIAS_PREFIXES = ['@lib/'];
+
+/** `import { a, b as c } from './rel.mjs'` or `'@lib/x.mjs'` — SUT candidates live behind these. */
+const LOCAL_IMPORT = new RegExp(
+  String.raw`import\s+([^;]+?)\s+from\s+['"]((?:\.|` +
+    ALIAS_PREFIXES.map((p) => p.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&')).join('|') +
+    String.raw`)[^'"]+)['"]`,
+  'g',
+);
 
 // ---------------------------------------------------------------------------
 // File enumeration
@@ -588,17 +639,17 @@ function testBlocks(lines) {
 }
 
 /**
- * Identifiers this test file imports from the repo's OWN modules (relative
- * specifiers). These are the subject-under-test candidates for B5; framework
- * (`vitest`) and stdlib (`node:*`) imports are structurally excluded because
- * their specifiers are not relative.
+ * Identifiers this test file imports from the repo's OWN modules (relative or
+ * vitest-alias specifiers). These are the subject-under-test candidates for B5;
+ * framework (`vitest`) and stdlib (`node:*`) imports are structurally excluded
+ * because their specifiers match neither form.
  * @param {string} content
  * @returns {string[]}
  */
 function importedLocalIdentifiers(content) {
   /** @type {Set<string>} */
   const ids = new Set();
-  for (const m of content.matchAll(RELATIVE_IMPORT)) {
+  for (const m of content.matchAll(LOCAL_IMPORT)) {
     const clause = m[1];
     // `{ a, b as c }` → c ; `x` / `* as ns` → x / ns
     for (const part of clause.replace(/[{}]/g, ',').split(',')) {
@@ -623,8 +674,9 @@ function callsIdentifier(lines, id) {
  *
  * Two passes over the file's `it`/`test` blocks:
  *   1. PROVE the seam — an imported id called from a block that also hands over
- *      an explicit clock argument is clock-seamed. A public API only grows a
- *      `now` parameter because the function reads the clock on its main path.
+ *      a NAMED clock key (SEAM_CLOCK_ARG) is clock-seamed. A public API only
+ *      grows a `now` parameter because the function reads the clock on its
+ *      main path.
  *   2. FLAG — in blocks with NO clock control at all, any equality assertion
  *      pinning an absolute date against such a subject is a time bomb.
  *
@@ -648,7 +700,8 @@ function scanClockBombs(relPath, content, lines) {
     return {
       start,
       body,
-      hasClockArg: live.some((l) => CLOCK_ARG.test(l)),
+      provesSeam: live.some((l) => SEAM_CLOCK_ARG.test(l)),
+      hasClockArg: live.some((l) => CONTROL_CLOCK_ARG.test(l)),
       hasFakeTimer: live.some((l) => FAKE_TIMER.test(l)),
     };
   });
@@ -656,19 +709,39 @@ function scanClockBombs(relPath, content, lines) {
   /** @type {Set<string>} */
   const seamed = new Set();
   for (const b of blocks) {
-    if (!b.hasClockArg) continue;
+    if (!b.provesSeam) continue;
     for (const id of sutIds) if (callsIdentifier(b.body, id)) seamed.add(id);
   }
   if (seamed.size === 0) return findings;
 
+  // Where an echo may come from: the finding's own block, or the setup every
+  // block shares (helpers, constants, beforeEach). Never a sibling test — its
+  // assertions, titles and clock literals say nothing about this block's inputs.
+  // A block without its own `});` (a one-line it) runs on to the next sibling
+  // and takes the setup lines in between out of sharedSetup — that direction can
+  // only add a finding, never hide one (1.4% of blocks, measured 2026-09-30).
+  /** @type {Set<number>} */
+  const inBlock = new Set();
+  for (const b of blocks) for (let q = b.start; q < b.start + b.body.length; q++) inBlock.add(q);
+  const sharedSetup = lines.filter((_, q) => !inBlock.has(q));
+
   for (const b of blocks) {
     if (b.hasClockArg || b.hasFakeTimer) continue;
     const subject = [...seamed].find((id) => callsIdentifier(b.body, id));
     if (!subject) continue;
+    const echoSources = [...b.body, ...sharedSetup].filter(
+      (l) => !isCommentLine(l) && !DATE_EXPECTATION.test(l),
+    );
     b.body.forEach((line, k) => {
       if (isCommentLine(line)) return;
       const m = DATE_EXPECTATION.exec(line);
       if (!m) return;
+      // Echo: the pinned value is also an input of this block or its shared setup,
+      // not a clock reading (the CEILING above keeps fixed INPUT dates unflagged on
+      // purpose). CEILING: a real bomb whose date also stands in its own block or
+      // the shared setup (its title, a trailing comment, a helper fixture) is
+      // swallowed; REVISIT when a clock-shift run finds a bomb this scan missed.
+      if (echoSources.some((l) => l.includes(m[2]))) return;
       findings.push({
         file: relPath,
         line: b.start + k + 1,

package/scripts/lib/validate/check-unicode-safety.mjs

@@ -204,6 +204,7 @@ const ALLOWED_EMOJI_CODEPOINTS = new Set([
   0x1f5a5, // 🖥
   0x1f6a6, // 🚦
   0x1f6a8, // 🚨
+  0x1f9ed, // 🧭 (navigator banner line in hooks/on-session-start.mjs — #1462)
   0x2139, //  ℹ
   0x2194, //  ↔
   0x26a0, //  ⚠

package/scripts/lib/validate/check-unwired-features.mjs

@@ -74,7 +74,7 @@
  * a backlog, printed as an aggregate like S4 and enumerated under `--list`.
  *
  * S6 carries no camelCase fallback ON PURPOSE: adding one re-hides both reaper
- * keys, whose camelCase names exist in `orphan-reaper.mjs` as that module's own
+ * keys, whose camelCase names exist in `orphan-reaper/defaults.mjs` as that module's own
  * defaults. A name is not a read.
  *
  * S2 applies to TOP-LEVEL keys only — a nested key reaches code through its