feat(knowledge): knowledge-refresh — living register, deterministic stale core + web poll (v5.7 Chunk 3)

The 'living' half of the v5.7 living knowledge base. Same hybrid split as the
optimization lens (Chunk 2b): a deterministic, byte-stable, unit-tested core +
a web/judgment command shell.

- scanners/lib/knowledge-refresh.mjs: pure assessFreshness(register,
  {referenceDate, staleAfterDays=90}) — age-based fresh/stale classification of
  source.verified; referenceDate injected (never reads the clock) → fully
  deterministic. 15 tests.
- scanners/knowledge-refresh-cli.mjs: -cli (NOT an orchestrated scanner →
  scanner count stays 15, suite byte-stable). Read-only — never writes the
  register, never hits the network. --reference-date/--stale-after/--dry-run,
  exit 0/1/3. 8 tests.
- commands/knowledge-refresh.md (opus): CLI stale-report → re-verify each stale
  entry by re-reading its source.url → poll CC changelog + Anthropic blog →
  apply ONLY human-approved writes, then re-validate the register. No unverified
  claim is ever auto-written (Verifiseringsplikt). Web-driven → not byte-stable.

No new agent, no new orchestrated scanner. Docs/badges: commands 19→20,
tests 1068→1091 (20 lib + 32 scanner test files). self-audit A/A, readmeCheck passed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

scanners/knowledge-refresh-cli.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+/**
+ * knowledge-refresh CLI — feeds the v5.7 `/config-audit knowledge-refresh` command
+ * (Chunk 3: the "living" half of the living knowledge base).
+ *
+ * This is the DETERMINISTIC half of the hybrid motor: it loads the best-practices
+ * register and classifies every entry as `fresh` or `stale` by the age of its
+ * `source.verified` stamp (via the pure `assessFreshness` core). It is READ-ONLY —
+ * it NEVER writes the register and NEVER touches the network. Candidate discovery
+ * (polling the CC changelog + Anthropic blog) and the human-approved writes live in
+ * the command layer (Verifiseringsplikt). `--dry-run` is implicit and the only mode;
+ * the flag is accepted for explicitness and echoed back.
+ *
+ * Naming: `-cli` suffix → NOT an orchestrated scanner (the scan-orchestrator only
+ * loads scanner modules), so the scanner count is unchanged and the snapshot suite
+ * stays byte-stable.
+ *
+ * Usage:
+ *   node knowledge-refresh-cli.mjs [--output-file <path>] [--stale-after <N>]
+ *                                  [--reference-date <YYYY-MM-DD>] [--dry-run]
+ *
+ * Exit codes: 0 = every entry fresh, 1 = one or more stale (advisory), 3 = error.
+ */
+
+import { resolve } from 'node:path';
+import { writeFile } from 'node:fs/promises';
+import { loadRegister, REGISTER_PATH } from './lib/best-practices-register.mjs';
+import { assessFreshness, STALE_AFTER_DAYS_DEFAULT } from './lib/knowledge-refresh.mjs';
+
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+function fail(message) {
+  process.stderr.write(`Error: ${message}\n`);
+  process.exit(3);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  let outputFile = null;
+  let staleAfterDays = STALE_AFTER_DAYS_DEFAULT;
+  let referenceDate = null; // null → today
+  let dryRun = false;
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--dry-run') dryRun = true;
+    else if (a === '--output-file' && args[i + 1]) outputFile = args[++i];
+    else if (a === '--stale-after' && args[i + 1] !== undefined) {
+      const n = Number.parseInt(args[++i], 10);
+      if (!Number.isInteger(n) || n < 0) fail('--stale-after must be a non-negative integer (days)');
+      staleAfterDays = n;
+    } else if (a === '--reference-date' && args[i + 1]) {
+      referenceDate = args[++i];
+      if (!DATE_RE.test(referenceDate)) fail('--reference-date must be YYYY-MM-DD');
+    }
+  }
+
+  // The clock is read here ONLY — the core takes an injected date and stays pure.
+  const ref = referenceDate || new Date();
+
+  let register;
+  try {
+    register = loadRegister();
+  } catch (err) {
+    fail(`could not load register at ${REGISTER_PATH}: ${err.message}`);
+  }
+
+  let assessment;
+  try {
+    assessment = assessFreshness(register, { referenceDate: ref, staleAfterDays });
+  } catch (err) {
+    fail(err.message);
+  }
+
+  const payload = {
+    status: 'ok',
+    registerPath: REGISTER_PATH,
+    version: register.version,
+    dryRun: true, // this CLI never writes; the flag is informational
+    requestedDryRun: dryRun,
+    referenceDate: assessment.referenceDate,
+    staleAfterDays: assessment.staleAfterDays,
+    counts: assessment.counts,
+    stale: assessment.stale,
+    fresh: assessment.fresh,
+  };
+
+  const json = JSON.stringify(payload, null, 2);
+  if (outputFile) await writeFile(outputFile, json, 'utf-8');
+  else process.stdout.write(json + '\n');
+
+  process.exit(assessment.counts.stale > 0 ? 1 : 0);
+}
+
+const isDirectRun =
+  process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname);
+if (isDirectRun) {
+  main().catch((err) => {
+    process.stderr.write(`Fatal: ${err.message}\n`);
+    process.exit(3);
+  });
+}

scanners/lib/knowledge-refresh.mjs

@@ -0,0 +1,94 @@
+/**
+ * knowledge-refresh — deterministic freshness core for the best-practices register.
+ *
+ * The "living" half of the v5.7 living knowledge base (Chunk 3). This module is the
+ * PURE, deterministic part of the hybrid `/config-audit knowledge-refresh` motor: given a
+ * register and an injected reference date, it classifies each entry as `fresh` or `stale`
+ * by the age of its `source.verified` stamp. It NEVER touches the network and NEVER writes
+ * — candidate discovery (polling CC changelog + Anthropic blog) and the human-approved
+ * writes live in the command layer (Verifiseringsplikt: no unverified claim is auto-written).
+ *
+ * `referenceDate` is injected (not read from the clock here) so the function is fully
+ * deterministic and unit-testable; the CLI passes today's date. See
+ * docs/v5.7-optimization-lens-plan.md.
+ */
+
+/** Default re-verify cadence: a confirmed best-practice older than this needs a re-check. */
+export const STALE_AFTER_DAYS_DEFAULT = 90;
+
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const DAY_MS = 86_400_000;
+
+/**
+ * Normalize a reference date (Date or YYYY-MM-DD string) to a UTC-midnight {iso, ms}.
+ * Throws TypeError on anything else — the reference date is required and must be valid.
+ */
+function normalizeReferenceDate(value) {
+  let iso;
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) throw new TypeError('referenceDate is an invalid Date');
+    iso = value.toISOString().slice(0, 10);
+  } else if (typeof value === 'string' && DATE_RE.test(value)) {
+    iso = value;
+  } else {
+    throw new TypeError('referenceDate must be a Date or a YYYY-MM-DD string');
+  }
+  const ms = Date.parse(`${iso}T00:00:00Z`);
+  if (Number.isNaN(ms)) throw new TypeError(`referenceDate is not a real calendar date: ${iso}`);
+  return { iso, ms };
+}
+
+/** Parse an entry's `source.verified` to UTC-midnight ms, or null if missing/unparseable. */
+function verifiedMs(entry) {
+  const v = entry && entry.source && entry.source.verified;
+  if (typeof v !== 'string' || !DATE_RE.test(v)) return null;
+  const ms = Date.parse(`${v}T00:00:00Z`);
+  return Number.isNaN(ms) ? null : ms;
+}
+
+/**
+ * Classify every register entry as fresh or stale by the age of its source.verified stamp.
+ *
+ * @param {{entries:object[]}} register
+ * @param {{ referenceDate: string|Date, staleAfterDays?: number }} opts
+ * @returns {{
+ *   referenceDate: string,
+ *   staleAfterDays: number,
+ *   stale: Array<{id:string, verified:string|undefined, ageDays:number|null, url:string|undefined, claim:string|undefined}>,
+ *   fresh: Array<{id:string, verified:string|undefined, ageDays:number}>,
+ *   counts: { total:number, stale:number, fresh:number }
+ * }}
+ */
+export function assessFreshness(register, opts = {}) {
+  const ref = normalizeReferenceDate(opts.referenceDate);
+  const staleAfterDays =
+    typeof opts.staleAfterDays === 'number' ? opts.staleAfterDays : STALE_AFTER_DAYS_DEFAULT;
+
+  const entries = (register && Array.isArray(register.entries)) ? register.entries : [];
+  const stale = [];
+  const fresh = [];
+
+  for (const e of entries) {
+    const verified = e && e.source ? e.source.verified : undefined;
+    const vms = verifiedMs(e);
+    if (vms === null) {
+      // No re-checkable date → needs attention. Stale with ageDays null.
+      stale.push({ id: e && e.id, verified, ageDays: null, url: e && e.source && e.source.url, claim: e && e.claim });
+      continue;
+    }
+    const ageDays = Math.floor((ref.ms - vms) / DAY_MS);
+    if (ageDays > staleAfterDays) {
+      stale.push({ id: e.id, verified, ageDays, url: e.source && e.source.url, claim: e.claim });
+    } else {
+      fresh.push({ id: e.id, verified, ageDays });
+    }
+  }
+
+  return {
+    referenceDate: ref.iso,
+    staleAfterDays,
+    stale,
+    fresh,
+    counts: { total: entries.length, stale: stale.length, fresh: fresh.length },
+  };
+}