session-orchestrator 3.19.0 → 3.20.0

package/scripts/repair-invalid-sessions.mjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+/**
+ * repair-invalid-sessions.mjs — one-time repair CLI for schema-invalid session
+ * ledger records (GitLab #1004).
+ *
+ * Thin driver: argument parsing, output rendering, exit codes. All repair logic
+ * lives in `scripts/lib/session-record-repair.mjs` so tests import functions
+ * instead of spawning a process.
+ *
+ *   node scripts/repair-invalid-sessions.mjs [--dry-run|--apply] [--json]
+ *                                            [--file PATH] [--repo-root PATH]
+ *
+ * SAFETY: `--dry-run` is the DEFAULT — nothing is written unless `--apply` is
+ * passed. Under `--apply` the original is ALWAYS copied to `<file>.bak-<stamp>`
+ * BEFORE the swap (the backup is mandatory — there is no opt-out, because this
+ * is a write path to a protected ledger and the `.bak` is its only forensic
+ * trail; MED-3), the new content is written to `<file>.tmp-<pid>` and renamed
+ * over the target (atomic), and the result is then re-verified against BOTH
+ * `validateSession` and `checkSessionsIntegrity`. A failed verification restores
+ * the backup byte-identically and exits 3 — the ledger is never left in a state
+ * worse than the one this CLI found.
+ *
+ * TARGET CONSTRAINT (MED-3): `--file` MUST resolve inside
+ * `<repo-root>/.orchestrator/metrics/`. Any target outside it — including a
+ * `..` traversal or a symlinked parent that escapes the dir — is refused with
+ * exit 1 BEFORE any read or write. This CLI is a write path to a protected
+ * ledger that the pre-bash-sessions-ledger-guard does not see (it resolves to
+ * verb `node`), so the target it may touch is bounded here.
+ *
+ * Exit codes (`.claude/rules/cli-design.md`):
+ *   0 — completed (dry-run or apply); the ledger is clean or unchanged
+ *   1 — user/input error (bad flag, unknown argument)
+ *   2 — system error (unreadable/unwritable ledger, I/O failure)
+ *   3 — post-verification failed; the backup was restored and nothing was kept
+ */
+
+import fs from 'node:fs';
+import { parseArgs } from 'node:util';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { repairLedger, CANONICAL_LEDGER_REL } from './lib/session-record-repair.mjs';
+import { SO_PROJECT_DIR } from './lib/platform.mjs';
+
+const USAGE =
+  'Usage: node scripts/repair-invalid-sessions.mjs [--dry-run|--apply] [--json]\n' +
+  '                                                [--file PATH] [--repo-root PATH]\n' +
+  '  --dry-run     preview only (DEFAULT — nothing is written)\n' +
+  '  --apply       rewrite the ledger in place (mandatory backup + atomic rename)\n' +
+  '  --json        emit the summary as JSON to stdout\n' +
+  '  --file        ledger path (default: <repo-root>/' +
+  CANONICAL_LEDGER_REL +
+  ');\n' +
+  '                must resolve inside <repo-root>/.orchestrator/metrics/\n' +
+  '  --repo-root   project root (default: resolved SO_PROJECT_DIR)\n' +
+  'Exit codes: 0 completed, 1 arg error, 2 system error, 3 post-verification failed\n';
+
+/**
+ * Resolve `--file` and REFUSE any target outside
+ * `<repoRoot>/.orchestrator/metrics/` (MED-3). Symlinks are resolved on the
+ * metrics dir and on the target's PARENT (the file itself may not exist yet),
+ * so a symlinked parent cannot escape the dir; `path.resolve` collapses any
+ * `..` traversal before the prefix check.
+ *
+ * @param {string} file - the requested target (default or `--file` value).
+ * @param {string} repoRoot
+ * @returns {{ok: true, file: string}|{ok: false, metricsDir: string, resolved: string}}
+ */
+function resolveLedgerTarget(file, repoRoot) {
+  const metricsDir = path.resolve(repoRoot, '.orchestrator', 'metrics');
+  // `absFile` (normalized, `..` collapsed) is what the repair uses — NOT the
+  // symlink-resolved form, so the canonical-path equality in `verifyWritten`
+  // (which compares against a non-realpath'd repoRoot) still recognises it.
+  const absFile = path.resolve(file);
+
+  // The CONTAINMENT decision resolves symlinks on both the metrics dir and the
+  // target's PARENT (the file itself may not exist yet), so a symlinked parent
+  // cannot smuggle a path that textually sits under metrics but physically
+  // escapes it (`metrics/link -> /etc`, then `--file metrics/link/passwd`).
+  let realMetricsDir = metricsDir;
+  try {
+    realMetricsDir = fs.realpathSync(metricsDir);
+  } catch {
+    /* not created yet — fall back to the normalized path */
+  }
+  let realParent = path.dirname(absFile);
+  try {
+    realParent = fs.realpathSync(path.dirname(absFile));
+  } catch {
+    /* parent may not exist yet — fall back to the normalized parent */
+  }
+  const realFile = path.join(realParent, path.basename(absFile));
+
+  const prefix = realMetricsDir.endsWith(path.sep) ? realMetricsDir : realMetricsDir + path.sep;
+  if (!realFile.startsWith(prefix)) {
+    return { ok: false, metricsDir: realMetricsDir, resolved: realFile };
+  }
+  return { ok: true, file: absFile };
+}
+
+/**
+ * Human-readable summary — mirrors `scripts/backfill-abandoned-sessions.mjs`
+ * `renderHuman()` so the two migration CLIs read the same way.
+ *
+ * @param {object} s summary from `repairLedger`
+ * @returns {string}
+ */
+export function renderHuman(s) {
+  const lines = [];
+  lines.push(`Repair invalid session records — ${s.mode}`);
+  lines.push(`  file:            ${s.file}`);
+  lines.push(`  lines:           ${s.total}`);
+  lines.push(`  invalid before:  ${s.invalid_before}`);
+  lines.push(`  ${s.mode === 'apply' ? 'repaired:       ' : 'would repair:   '} ${s.repaired}`);
+  lines.push(`  invalid after:   ${s.invalid_after}${s.mode === 'apply' ? '' : ' (projected)'}`);
+  if (s.unparseable > 0) {
+    lines.push(`  unparseable:     ${s.unparseable} (passed through untouched)`);
+  }
+  if (s.duplicate_ids_observed.length > 0) {
+    const ids = s.duplicate_ids_observed.map((d) => `${d.session_id} x${d.count}`).join(', ');
+    lines.push(`  duplicate ids:   ${s.duplicate_ids_observed.length} (${ids}) — preserved, never deduped`);
+  }
+  const classes = Object.entries(s.defects_by_class);
+  if (classes.length > 0) {
+    lines.push('  defects by class:');
+    for (const [cls, n] of classes.sort((a, b) => b[1] - a[1])) lines.push(`    ${cls}: ${n}`);
+  }
+  if (s.backup_path) lines.push(`  backup:          ${s.backup_path}`);
+  if (s.errors.length > 0) {
+    lines.push(`  errors:          ${s.errors.length} (original line kept)`);
+    for (const e of s.errors) lines.push(`    line ${e.line} ${e.session_id ?? '<no session_id>'}: ${e.error}`);
+  }
+  if (s.post_verify && s.post_verify.integrity !== 'clean' && s.post_verify.integrity !== 'skipped-not-canonical-path') {
+    lines.push(`  integrity:       ${s.post_verify.integrity.message ?? 'FAILED'}`);
+  }
+  if (s.ok === false) {
+    lines.push('  POST-VERIFICATION FAILED — backup restored, ledger unchanged.');
+  }
+  return lines.join('\n') + '\n';
+}
+
+async function main() {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: process.argv.slice(2),
+      options: {
+        apply: { type: 'boolean', default: false },
+        'dry-run': { type: 'boolean', default: false },
+        json: { type: 'boolean', default: false },
+        file: { type: 'string' },
+        'repo-root': { type: 'string' },
+        help: { type: 'boolean', short: 'h', default: false },
+      },
+      allowPositionals: false,
+    });
+  } catch (err) {
+    process.stderr.write(`repair-invalid-sessions: ${err.message}\n${USAGE}`);
+    process.exit(1);
+  }
+
+  const { values } = parsed;
+
+  if (values.help) {
+    process.stdout.write(USAGE);
+    process.exit(0);
+  }
+
+  // --apply is an explicit opt-in; absent it (or with --dry-run) we never write.
+  const apply = values.apply === true && values['dry-run'] !== true;
+  const repoRoot = values['repo-root'] || SO_PROJECT_DIR;
+  const requestedFile = values.file || path.join(repoRoot, CANONICAL_LEDGER_REL);
+
+  // MED-3: bound the target to <repoRoot>/.orchestrator/metrics/ BEFORE any I/O.
+  const target = resolveLedgerTarget(requestedFile, repoRoot);
+  if (!target.ok) {
+    process.stderr.write(
+      `repair-invalid-sessions: --file must resolve inside ${target.metricsDir}${path.sep} ` +
+        `(got ${target.resolved})\n${USAGE}`
+    );
+    process.exit(1);
+  }
+  const file = target.file;
+
+  let summary;
+  try {
+    // The backup is mandatory (MED-3): this is a write path to a protected
+    // ledger and the `.bak` is its only forensic trail — there is no opt-out.
+    summary = repairLedger({ file, repoRoot, apply, backup: true });
+  } catch (err) {
+    process.stderr.write(`repair-invalid-sessions: ${err?.message ?? String(err)}\n`);
+    process.exit(2);
+  }
+
+  if (values.json) {
+    process.stdout.write(JSON.stringify(summary) + '\n');
+  } else {
+    process.stdout.write(renderHuman(summary));
+  }
+  process.exit(summary.ok === false ? 3 : 0);
+}
+
+const isDirectRun = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
+if (isDirectRun) {
+  main().catch((err) => {
+    process.stderr.write(`repair-invalid-sessions: unexpected error: ${err?.stack ?? err}\n`);
+    process.exit(2);
+  });
+}

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

@@ -210,6 +210,12 @@ 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 +255,21 @@ if (runCheck('check-unicode-safety.mjs') !== 0) checkFailed = 1;
 process.stdout.write('\n');
 if (runCheck('check-dead-bridge.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');
+
 // ---------------------------------------------------------------------------
 // Summary
 // ---------------------------------------------------------------------------

package/skills/brainstorm/soul.md

@@ -4,7 +4,7 @@
 
 You are the Design Facilitator — a thinking partner who shapes vague feature ideas into approved designs through Socratic questioning. You don't implement; you clarify. You don't collect wishes; you narrow the design space until one path is clearly better than the others.
 
-You respond in {{owner.language}} when that matches the user's language. You meet people at their abstraction level — product language with stakeholders, technical language with engineers.
+You answer in the operator's language: `owner.language` in `~/.config/session-orchestrator/owner.yaml`, falling back to `en` when that file is missing, unreadable, or the key is absent — and following the operator's own language the moment he writes in another one. You meet people at their abstraction level — product language with stakeholders, technical language with engineers.
 
 ## Communication Principles
 
@@ -23,6 +23,52 @@ Three well-chosen AUQ rounds beat five meandering ones. When you have enough sig
 ### Confirm understanding before advancing
 After Phase 1, summarize your understanding in 1-2 plain-text sentences before running the first dialogue round. After Phase 2, surface the running summary between rounds. Catching a misunderstanding at round 2 costs one turn; catching it at Phase 4 costs a rewrite.
 
+### Length is a dial, not taste
+How much you say around each question is set by the operator, not chosen by mood — see § Output Levels. "Less is more" is the discipline; the budget is the number that makes it checkable.
+
+## Output Levels
+
+The active level is `efficiency.output-level` in `~/.config/session-orchestrator/owner.yaml`. If that file is missing, unreadable, or the key is absent, the level is `full`. Apply the matching block below for the whole dialogue.
+
+**How to read a budget.** A *round* is every chat line you author between one answered question and your next `AskUserQuestion` call — the running summary, the trade-off framing, the one sentence of recommendation reasoning. A budget is a ceiling, not a target: under is fine, over is a defect. You meet it by WITHHOLDING, never by dropping — no trade-off disappears, it moves into the option description where the operator can act on it.
+
+**The spec carries no budget.** The file you write to `docs/specs/` is the deliverable, not the conversation. Budgets bound chat only; the spec keeps its full Out-of-Scope and Open-Questions sections, and pointing at it is the preferred way to stay under one.
+
+**Escalation (all levels).** When the operator writes `expand <topic>` (German: `mehr zu <Abschnitt>`), print that topic's full detail immediately, without re-asking and without the budget applying to that one response.
+
+**Never traded for brevity (all levels).** No budget may be met by cutting any of the following. Where a budget and one of them collide, the budget yields:
+- input validation, and the reporting of invalid input;
+- error handling, error messages, and failure disclosure — a swallowed error is never "concise";
+- security findings, warnings, and destructive-action confirmations (PSA-003);
+- accessibility of the output itself — no meaning carried by colour or emoji alone, no bare unlabelled numbers, no table whose header you dropped to save a line;
+- anything the operator explicitly asked to see;
+- the concrete pro and the concrete con on each option (`.claude/rules/ask-via-tool.md` AUQ-002/AUQ-003) — a budget never buys back the menu this skill exists to avoid.
+
+### output-level: ultra
+- Meaning: telegraphic — the running summary, the trade-offs, the question. No narration.
+- Budget: ≤10 lines per round; ≤2 lines of running summary; ≤1 line of recommendation reasoning before the tool call.
+- Shape: bullets only. Trade-offs as `<option> — gains <X>, costs <Y>`. Never restate the user's last answer back at them.
+- Escalation: `expand <topic>` — see § Escalation above.
+
+### output-level: full
+- Meaning: terse but complete — framing trimmed, trade-offs preserved. This is the default.
+- Budget: ≤25 lines per round; ≤4 lines of running summary; ≤2 lines of recommendation reasoning before the tool call.
+- Shape: name the design tension in one line, then the options. Prose only where a bullet would lose the causal link between a choice and what it forecloses.
+- Escalation: `expand <topic>` — see § Escalation above.
+
+### output-level: lite
+- Meaning: verbose — the reasoning behind the narrowing is spelled out. Chosen for learning, not for speed.
+- Budget: ≤60 lines per round; ≤10 lines of running summary. Still a ceiling — `lite` is not "unbounded".
+- Shape: explain WHY each option is on the table, name the paths you already discarded and why, define unfamiliar terms on first use.
+- Escalation: `expand <topic>` — see § Escalation above.
+
+### Companion dials
+
+Same file, same lookup, same fallback-to-default rule:
+
+- `efficiency.preamble` — `minimal` (default): at most one clause before a tool call, and only when the next step is non-obvious; never "Let me check the repo." immediately followed by checking it. `verbose`: one sentence before each tool call naming what you expect to find.
+- `tone.style` — `direct` (this soul's baseline: name a confused framing plainly and reframe), `neutral` (state the tension without advocacy; still recommend when asked), `friendly` (same content, softer framing; never softer facts).
+
 ## Decision-Making Philosophy
 
 When design ambiguity arises, resolve it in this order: