@event4u/agent-config 14.12.0 → 14.14.0

package/src/agent-src/scripts/update_roadmap_progress.ts

@@ -12,7 +12,7 @@
  * `archive_completed_roadmaps` can consume it the same way Python does. snake_case
  * is kept on the public surface.
  *
- * Scans every roadmap under `agents/roadmaps/` (excluding `archive/`, `skipped/`,
+ * Scans every roadmap under `agents/roadmaps/` (excluding `archive/`, `skipped/`,  code-comment-allow provenance-comment -- the path is this script's operand, not where the code came from
  * `template.md`, `README.md`, `open-questions*.md`), counts checkbox states per
  * phase, and writes a dashboard at `agents/roadmaps-progress.md` (outside the
  * `roadmaps/` folder to keep it clean) with:
@@ -71,6 +71,8 @@ import {
     type DashboardMode,
 } from './dashboard_mode.js';
 import type * as YamlModule from 'yaml';
+import { headerFragment as stubHeaderFragment } from './stubs_due.js';
+import { reportGuardedBaselines } from './guarded_baseline.js'; // third step state; contract lives there
 
 const _HERE = fileURLToPath(import.meta.url);
 const _require = createRequire(import.meta.url);
@@ -94,7 +96,7 @@ const EXCLUDE_DIRS: ReadonlySet<string> = new Set(['archive', 'skipped', 'stubs'
 
 // FRONTMATTER_RE = re.compile(r"\A---\n(.*?)\n---\s*\n", re.DOTALL)
 const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---[ \t\n\r\f\v]*\n/;
-const DRAFT_VALUES: ReadonlySet<string> = new Set(['draft']);
+const UNSCHEDULED_VALUES: ReadonlySet<string> = new Set(['draft', 'carrier']);
 
 const MERGE_GATED_RE = /merge-gated/i;
 // PR_NUM_RE = re.compile(r"pr\s*[=#:]?\s*#?\s*(\d+)", re.IGNORECASE)
@@ -287,8 +289,8 @@ function _stripQuotes(s: string): string {
     return out;
 }
 
-function is_draft(fm: Record<string, string>): boolean {
-    return DRAFT_VALUES.has((fm['status'] ?? '').toLowerCase());
+function is_unscheduled(fm: Record<string, string>): boolean {
+    return UNSCHEDULED_VALUES.has((fm['status'] ?? '').toLowerCase());
 }
 
 /**
@@ -750,7 +752,7 @@ function collect(roadmap_root: string): RoadmapStats[] {
             continue;
         }
         const text = fs.readFileSync(p, { encoding: 'utf-8' });
-        if (is_draft(parse_frontmatter(text))) {
+        if (is_unscheduled(parse_frontmatter(text))) {
             continue;
         }
         const stats = parse_roadmap(p, roadmap_root);
@@ -818,7 +820,7 @@ function collect_parked(roadmap_root: string): ParkedRoadmap[] {
         } catch {
             continue;
         }
-        if (is_draft(parse_frontmatter(text))) {
+        if (is_unscheduled(parse_frontmatter(text))) {
             continue;
         }
         const cell = resume_cell(text);
@@ -995,6 +997,8 @@ function render(roadmaps: RoadmapStats[], bundles: Bundle[] | null, roadmap_root
                   ? `, **${user_open_blockers}** need you → \`agent-config gates\``
                   : '')
             : '') +
+        // Two integers, never a row — see `stubs_due.headerFragment`.
+        stubHeaderFragment(path.join(roadmap_root, 'stubs')) +
         '\n';
     lines.push(
         // Honest provenance (road-to-roadmap-archival-robustness, gap C): name a
@@ -1301,7 +1305,7 @@ function _parseArgs(argv: readonly string[]): Args {
 }
 
 /**
- * When the default cwd carries no `agents/roadmaps/`, fall back to the git
+ * When the default cwd carries no `agents/roadmaps/`, fall back to the git  code-comment-allow provenance-comment -- the path is this script's operand, not where the code came from
  * toplevel — hook and IDE invocations often run from a subdirectory, and a
  * cwd-only resolution silently skipped the dashboard there. An explicit
  * `--repo-root` always wins; a cwd that has the directory is used as-is
@@ -1362,8 +1366,8 @@ function main(argv?: readonly string[]): number {
             return 1;
         }
     }
-    const roadmaps = collect(roadmap_root);
-    const new_text = render(roadmaps, collect_bundles(repo_root), roadmap_root);
+    const roadmaps = collect(roadmap_root), guarded = reportGuardedBaselines(roadmaps, repo_root);
+    const new_text = render(roadmaps, collect_bundles(repo_root), roadmap_root) + guarded.section;
     const complete = unarchived_complete(roadmaps);
     const pending = pending_iron_law_3(roadmaps);
     const gated = merge_gated_pending(roadmaps);
@@ -1395,7 +1399,7 @@ function main(argv?: readonly string[]): number {
         });
         if (r.stderr) process.stderr.write(r.stderr);
         if (r.stdout) process.stdout.write(r.stdout);
-        return r.rc;
+        return guarded.problems > 0 ? 1 : r.rc;
     }
     fs.writeFileSync(target, new_text, { encoding: 'utf-8' });
     process.stdout.write(
@@ -1431,7 +1435,7 @@ function main(argv?: readonly string[]): number {
     if (gated.length) {
         _warn_merge_gated();
     }
-    return 0;
+    return guarded.problems > 0 ? 1 : 0;
 }
 
 function _isCliEntry(): boolean {
@@ -1475,7 +1479,7 @@ export {
     TITLE_RE,
     FRONTMATTER_RE,
     parse_frontmatter,
-    is_draft,
+    is_unscheduled,
     is_roadmap_candidate,
     count_checkboxes,
     parse_blockers,

package/src/agent-src/templates/scripts/check_memory.ts

@@ -1,17 +1,36 @@
 #!/usr/bin/env tsx
+/*
+ * TEMPLATE COPY — reconciled with `src/scripts/check_memory.ts` on 2026-08-26
+ * (`road-to-memory-twin-reconciliation` 2.2, verdict `dev-side-correct`).
+ *
+ * TWO differences remain, and both are `keep-duplicated` for the same
+ * STRUCTURAL reason rather than by preference: the installed consumer tree has
+ * no `scripts/_lib/`, so a template script may import node built-ins, `yaml`
+ * and its own installed siblings — nothing else.
+ *
+ *   - `assertScanned` (`_lib/scan_scope.js`), the dead-scope guard. Not
+ *     importable here, and its absence is safe in the direction that matters:
+ *     a consumer with no `agents/memory/` scans zero and passes, which is the
+ *     correct reading for a project that keeps no memory.
+ *   - `asOf` (`_lib/as_of.js`), the reproducible-clock pin behind this
+ *     repository's own `AC_AS_OF` discipline. A consumer has no such pin, so
+ *     `new Date()` is the right substitute rather than a downgrade.
+ *
+ * Everything else is identical, INCLUDING the validations this copy used to
+ * lack entirely: the `priority` enum, the critical-stale SLA, the one-fact
+ * length limit, relative-date discipline, per-type caps, tier-0 inflation, and
+ * `status: superseded`.
+ */
 /**
  * Engineering Memory validator.
  *
- * TypeScript twin of `src/agent-src/templates/scripts/check_memory.py`
- * (ADR-200, Phase 1 — consumer-shipped template). Adapted from the dev-side
- * `src/scripts/check_memory.ts` twin: the template `.py` is the leaner
- * consumer surface — it has NO `--shadow-report`, NO `priority`/date-discipline/
- * critical-stale/tier-0-inflation checks. Those are stripped here so this twin
- * matches the template `.py` exactly. The CLI contract mirrors the Python
- * original EXACTLY — same flags (`--path`, `--format`, `--append-only`,
- * `--base`), same exit codes, same stdout/stderr split, byte-identical finding
- * messages, same scan scope and ordering. No behaviour changes — latent bugs
- * are replicated and flagged in the porting report, not fixed.
+ * Ported from the retired Python `src/scripts/check_memory.py` (ADR-200, Phase 4 /
+ * Wave 4a). The CLI contract pins the historical contract exactly — same
+ * flags (`--path`, `--format`, `--append-only`, `--base`), same exit
+ * codes, same stdout/stderr split,
+ * byte-identical finding messages, same scan scope and ordering. No
+ * behaviour changes — latent bugs are replicated and flagged in the
+ * porting report, not fixed.
  *
  * Validates YAML files under `agents/memory/<type>/**\/*.yml` against the
  * schema documented in `guidelines/agent-infra/engineering-memory-data-format`.
@@ -39,7 +58,7 @@
  *     check_memory --append-only       # CI: diff vs origin/main
  *     check_memory --append-only --base HEAD~1
  *
- * Note on YAML date typing: the Python original relies on PyYAML's
+ * Note on YAML date typing: the retired Python implementation relies on PyYAML's
  * `safe_load` converting unquoted `YYYY-MM-DD` scalars to `datetime.date`
  * (and `YYYY-MM-DD HH:MM:SS` to `datetime.datetime`). The `yaml` npm
  * package parses every scalar to a string, so this twin re-implements
@@ -56,6 +75,7 @@ import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import YAML, { parseDocument } from 'yaml';
 
+
 type Severity = 'error' | 'warning' | 'info';
 
 const REQUIRED_KEYS: ReadonlySet<string> = new Set([
@@ -67,14 +87,48 @@ const REQUIRED_KEYS: ReadonlySet<string> = new Set([
     'last_validated',
     'review_after_days',
 ]);
-const VALID_STATUS: ReadonlySet<string> = new Set(['active', 'deprecated', 'archived']);
+const VALID_STATUS: ReadonlySet<string> = new Set(['active', 'deprecated', 'archived', 'superseded']);
 const VALID_CONFIDENCE: ReadonlySet<string> = new Set(['low', 'medium', 'high']);
+// `priority` is optional (default `normal`); enum is the smallest set that
+// solves the tier-0 surfacing use case. See the Phase 2 council brief for why
+// the `high` tier was rejected.
+const VALID_PRIORITY: ReadonlySet<string> = new Set(['critical', 'normal', 'low']);
+// Soft-cap on `priority: critical` entries per memory type. Tier-0 inflation
+// is the failure mode: when too many entries claim "always surface", the
+// slice loses signal. Warn (not fail) when the cap is exceeded so curators
+// notice without being blocked.
+const CRITICAL_WARN_THRESHOLD = 10;
+// Stale-critical guard: a `priority: critical` entry that hasn't been
+// re-validated in this many days emits a warning. Surfaced separately
+// from the generic `stale:` info so reviewers see it before merge.
+const CRITICAL_STALE_DAYS = 90;
 const KNOWN_TYPES: ReadonlySet<string> = new Set([
     'domain-invariants',
+    'historical-patterns',
     'incident-learnings',
+    'ownership',
     'product-rules',
 ]);
 
+// Per-type soft entry cap (size-bounding without a decay engine). Over-cap →
+// warning, never a hard fail: the right answer to bloat is a consolidation pass
+// (prune archived, merge duplicates), not CI failure. See
+// road-to-memory-pipeline-consolidation.md Phase 7.
+const PER_TYPE_CAPS: Readonly<Record<string, number>> = {
+    ownership: 50,
+    'domain-invariants': 150,
+    'product-rules': 100,
+    'incident-learnings': 150,
+    'historical-patterns': 150,
+};
+const DEFAULT_TYPE_CAP = 150;
+// One-durable-fact-per-entry: a content field longer than this reads as a
+// transcript / narrative blob, not a single durable fact → warning.
+const ONE_FACT_MAX_CHARS = 600;
+const ONE_FACT_FIELDS = ['rule', 'pattern', 'statement', 'observation', 'body', 'decision', 'note'] as const;
+// Per-type entry tally, populated during validation, consumed by main().
+const _TYPE_COUNTS: Record<string, number> = {};
+
 // Redaction heuristics — plain-regex, deliberately conservative.
 // False positives are fixed by quoting the line differently; false
 // negatives are a curator responsibility.
@@ -90,6 +144,15 @@ const REDACTION_PATTERNS: ReadonlyArray<readonly [RegExp, string]> = [
     [/\b192\.168\.\d{1,3}\.\d{1,3}\b/, 'internal ipv4 range'],
 ];
 
+// Date-discipline — relative-date phrases without an ISO YYYY-MM-DD anchor
+// within ±20 chars are rejected. Memory entries that say "yesterday" or
+// "last week" rot the moment the file is re-read on another day; the
+// anchor pins meaning.
+const RELATIVE_DATE_PATTERN =
+    /\b(yesterday|today|tomorrow|last\s+(?:week|month|year)|next\s+(?:week|month|year)|this\s+(?:week|month|year))\b/gi;
+const ISO_DATE_PATTERN = /\b\d{4}-\d{2}-\d{2}\b/;
+const DATE_ANCHOR_WINDOW = 20;
+
 // PyYAML timestamp implicit-resolver. A *plain* (unquoted) scalar matching
 // this is constructed as datetime.date / datetime.datetime — both pass
 // `isinstance(value, datetime.date)`. Source: yaml/resolver.py.
@@ -246,6 +309,15 @@ function _isInteger(v: unknown): v is number {
     return typeof v === 'number' && Number.isInteger(v);
 }
 
+/** Mirror Python len(str) — code-point count, not UTF-16 unit count. */
+function _pyLen(s: string): number {
+    let n = 0;
+    for (const _ of s) {
+        n += 1;
+    }
+    return n;
+}
+
 function _memoryType(p: string): string {
     // Supports `memory/<type>.yml`, `memory/<type>/<hash>.yml`, and
     // `memory/<type>.example.yml` template filenames.
@@ -270,7 +342,13 @@ function _stem(name: string): string {
     return base.slice(0, dot);
 }
 
-function _validateEntry(entry: Entry, p: string, seenIds: Set<string>, findings: Finding[]): void {
+function _validateEntry(
+    entry: Entry,
+    p: string,
+    seenIds: Set<string>,
+    findings: Finding[],
+    criticalCounts: Record<string, number> | null,
+): void {
     const eid = typeof entry['id'] === 'string' ? (entry['id'] as string) : entry['id'] != null ? String(entry['id']) : '';
     const eidStr = entry['id'] == null ? '' : eid;
     const present = new Set(Object.keys(entry));
@@ -292,6 +370,22 @@ function _validateEntry(entry: Entry, p: string, seenIds: Set<string>, findings:
     if (confidence && typeof confidence === 'string' && !VALID_CONFIDENCE.has(confidence)) {
         findings.push(new Finding(p, 0, 'error', `invalid confidence '${confidence}'`, eidStr));
     }
+    // Priority is optional (defaults to `normal` at read time). When present
+    // it MUST be one of the three-tier enum — see VALID_PRIORITY for the
+    // rationale on rejecting a fourth `high` tier.
+    const priority = entry['priority'];
+    if (priority !== undefined && priority !== null && !(typeof priority === 'string' && VALID_PRIORITY.has(priority))) {
+        const sortedPri = [...VALID_PRIORITY].sort();
+        findings.push(
+            new Finding(
+                p,
+                0,
+                'error',
+                `invalid priority '${_pyStr(priority)}' (expected one of [${sortedPri.map((x) => `'${x}'`).join(', ')}])`,
+                eidStr,
+            ),
+        );
+    }
     const sources = (entry['source'] ?? []) as unknown;
     if (!Array.isArray(sources) || sources.length < 1) {
         findings.push(new Finding(p, 0, 'error', 'source must be a list with ≥1 entry', eidStr));
@@ -309,6 +403,71 @@ function _validateEntry(entry: Entry, p: string, seenIds: Set<string>, findings:
             findings.push(new Finding(p, 0, 'info', `stale: last_validated ${age} days ago (limit ${days})`, eidStr));
         }
     }
+    // Critical-stale guard: a `priority: critical` entry that has not been
+    // re-validated within CRITICAL_STALE_DAYS surfaces as a warning, even
+    // when the entry's own `review_after_days` is more lenient. Critical
+    // entries surface on every /memory:load — they have a tighter SLA.
+    if (priority === 'critical' && entry['status'] === 'active' && lv instanceof PyDate) {
+        const critAge = _dateDiffDays(_today(), lv);
+        if (critAge > CRITICAL_STALE_DAYS) {
+            findings.push(
+                new Finding(
+                    p,
+                    0,
+                    'warning',
+                    `critical-stale: last_validated ${critAge} days ago (critical SLA is ${CRITICAL_STALE_DAYS} days)`,
+                    eidStr,
+                ),
+            );
+        }
+    }
+    // One-durable-fact-per-entry: reject transcript/narrative blobs. A single
+    // content field over ONE_FACT_MAX_CHARS is the bloat signal.
+    for (const fld of ONE_FACT_FIELDS) {
+        const val = entry[fld];
+        if (typeof val === 'string' && _pyLen(val) > ONE_FACT_MAX_CHARS) {
+            findings.push(
+                new Finding(
+                    p,
+                    0,
+                    'warning',
+                    `one-fact: \`${fld}\` is ${_pyLen(val)} chars (limit ${ONE_FACT_MAX_CHARS}) — split into separate durable facts, not a narrative blob`,
+                    eidStr,
+                ),
+            );
+            break;
+        }
+    }
+    // Tier-0 inflation tracking — increment per memory type. The aggregate
+    // warning is emitted in main() after all files are validated.
+    if (criticalCounts !== null && priority === 'critical' && entry['status'] === 'active') {
+        const mtype = _memoryType(p);
+        criticalCounts[mtype] = (criticalCounts[mtype] ?? 0) + 1;
+    }
+    // Per-type entry-count tracking — aggregate cap warning in main().
+    if (criticalCounts !== null) {
+        const mt = _memoryType(p);
+        _TYPE_COUNTS[mt] = (_TYPE_COUNTS[mt] ?? 0) + 1;
+    }
+}
+
+/** Mirror Python's `str(value)` for the priority error message. */
+function _pyStr(value: unknown): string {
+    if (value === null) {
+        return 'None';
+    }
+    if (value === true) {
+        return 'True';
+    }
+    if (value === false) {
+        return 'False';
+    }
+    if (value instanceof PyDate) {
+        const mm = String(value.month).padStart(2, '0');
+        const dd = String(value.day).padStart(2, '0');
+        return `${value.year}-${mm}-${dd}`;
+    }
+    return String(value);
 }
 
 function _checkRedaction(p: string, findings: Finding[]): void {
@@ -328,6 +487,38 @@ function _checkRedaction(p: string, findings: Finding[]): void {
     });
 }
 
+function _checkDateDiscipline(p: string, findings: Finding[]): void {
+    // Reject relative-date phrases without an ISO YYYY-MM-DD anchor.
+    const text = fs.readFileSync(p, 'utf-8');
+    const lines = _splitlines(text);
+    lines.forEach((line, idx) => {
+        const lineNo = idx + 1;
+        const stripped = line.trimStart();
+        if (stripped.startsWith('#') || stripped.startsWith('last_validated')) {
+            return;
+        }
+        RELATIVE_DATE_PATTERN.lastIndex = 0;
+        let match: RegExpExecArray | null;
+        while ((match = RELATIVE_DATE_PATTERN.exec(line)) !== null) {
+            const start = Math.max(0, match.index - DATE_ANCHOR_WINDOW);
+            const end = Math.min(line.length, match.index + match[0].length + DATE_ANCHOR_WINDOW);
+            const windowStr = line.slice(start, end);
+            if (ISO_DATE_PATTERN.test(windowStr)) {
+                continue;
+            }
+            const phrase = match[0];
+            findings.push(
+                new Finding(
+                    p,
+                    lineNo,
+                    'error',
+                    `relative date '${phrase}' without an ISO YYYY-MM-DD anchor within ±${DATE_ANCHOR_WINDOW} chars (re-anchor before commit)`,
+                ),
+            );
+        }
+    });
+}
+
 /** Mirror Python str.splitlines() for the line-numbering used above. */
 function _splitlines(text: string): string[] {
     if (text === '') {
@@ -342,12 +533,17 @@ function _splitlines(text: string): string[] {
     return lines;
 }
 
-function _validateFile(p: string, findings: Finding[]): void {
+function _validateFile(
+    p: string,
+    findings: Finding[],
+    criticalCounts: Record<string, number> | null,
+): void {
     const mtype = _memoryType(p);
     if (!KNOWN_TYPES.has(mtype)) {
         findings.push(new Finding(p, 0, 'warning', `unknown memory type '${mtype}'`));
     }
     _checkRedaction(p, findings);
+    _checkDateDiscipline(p, findings);
     let data: unknown;
     try {
         data = pyYamlSafeLoad(fs.readFileSync(p, 'utf-8'));
@@ -369,7 +565,7 @@ function _validateFile(p: string, findings: Finding[]): void {
     if (Array.isArray(entries)) {
         for (const entry of entries) {
             if (_isPlainObject(entry)) {
-                _validateEntry(entry as Entry, p, seenIds, findings);
+                _validateEntry(entry as Entry, p, seenIds, findings, criticalCounts);
             }
         }
     }
@@ -549,8 +745,53 @@ function main(): number {
         }
         return 0;
     }
-    for (const yml of _rglobYmlSorted(root)) {
-        _validateFile(yml, findings);
+    // An ABSENT root stays a pinned exit-0 no-op (the branch above; the memory
+    // tree is an optional surface and `task check-memory` short-circuits it).
+    // A root that EXISTS but walks to zero `*.yml` is the case nothing covered:
+    // entries moved to a subtree this walk does not reach, and the validator
+    // reported "0 error(s)" over an empty read. No `allowEmpty` for that half —
+    // a present-but-unreadable corpus is blindness, not a clean bill of health.
+    // Exit 1 is this gate's only failure code (see `_emit`).
+    // No dead-scope guard: `_lib/scan_scope.js` is not installed with the
+    // template, and a consumer with no `agents/memory/` legitimately scans zero.
+    const ymls = _rglobYmlSorted(root);
+
+    const criticalCounts: Record<string, number> = {};
+    for (const key of Object.keys(_TYPE_COUNTS)) {
+        delete _TYPE_COUNTS[key];
+    }
+    for (const yml of ymls) {
+        _validateFile(yml, findings, criticalCounts);
+    }
+    // Tier-0 inflation warning — soft cap on `priority: critical` per type.
+    // Council convergence (Phase 2 B2): warn rather than block, because the
+    // right answer to "too many criticals" is curator review, not CI failure.
+    for (const [mtype, count] of Object.entries(criticalCounts).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+        if (count > CRITICAL_WARN_THRESHOLD) {
+            findings.push(
+                new Finding(
+                    `agents/memory/${mtype}`,
+                    0,
+                    'warning',
+                    `tier-0 inflation: ${count} active 'priority: critical' entries (threshold ${CRITICAL_WARN_THRESHOLD}) — review whether all still warrant always-surface treatment`,
+                ),
+            );
+        }
+    }
+    // Per-type entry-count cap (size-bounding, Phase 7). Warn, never block —
+    // over-cap signals a consolidation pass is due (prune archived, merge dups).
+    for (const [mtype, count] of Object.entries(_TYPE_COUNTS).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+        const cap = PER_TYPE_CAPS[mtype] ?? DEFAULT_TYPE_CAP;
+        if (count > cap) {
+            findings.push(
+                new Finding(
+                    `agents/memory/${mtype}`,
+                    0,
+                    'warning',
+                    `entry-cap: ${count} entries (soft cap ${cap}) — run a consolidation pass (prune archived, merge duplicates)`,
+                ),
+            );
+        }
     }
     return _emit(findings, args.format);
 }

package/src/agent-src/templates/scripts/check_memory_proposal.ts

@@ -217,6 +217,7 @@ interface ParsedArgs {
     intake_id: string | null;
     proposal: string | null;
     format: 'text' | 'json';
+    quiet: boolean;
 }
 
 function _argparse_error(message: string): never {
@@ -228,6 +229,7 @@ function parse_args(argv: readonly string[]): ParsedArgs {
     let intake_id: string | null = null;
     let proposal: string | null = null;
     let format: 'text' | 'json' = 'text';
+    let quiet = false;
     // argparse reports a mutually-exclusive conflict against the SECOND-seen
     // arg at the point it is parsed (order-sensitive), so check inline rather
     // than after the loop.
@@ -248,10 +250,12 @@ function parse_args(argv: readonly string[]): ParsedArgs {
             format = _checkFormat(v);
         } else if (arg.startsWith('--format=')) {
             format = _checkFormat(arg.slice('--format='.length));
+        } else if (arg === '--quiet') {
+            quiet = true;
         } else if (arg === '-h' || arg === '--help') {
             process.stdout.write(
                 'usage: check_memory_proposal [-h] (--intake-id INTAKE_ID | --proposal PROPOSAL)\n' +
-                    '                             [--format {text,json}]\n',
+                    '                             [--format {text,json}] [--quiet]\n',
             );
             process.exit(0);
         } else {
@@ -261,7 +265,7 @@ function parse_args(argv: readonly string[]): ParsedArgs {
     if (intake_id === null && proposal === null) {
         _argparse_error('one of the arguments --intake-id --proposal is required');
     }
-    return { intake_id, proposal, format };
+    return { intake_id, proposal, format, quiet };
 }
 
 function _need(argv: readonly string[], i: number, flag: string): string {
@@ -322,7 +326,9 @@ function main(argv?: readonly string[]): number {
                 process.stdout.write(`  🔴 ${f}\n`);
             }
         } else {
-            process.stdout.write(`✅  ${source} — gate passed\n`);
+            if (!args.quiet) {
+                process.stdout.write(`✅  ${source} — gate passed\n`);
+            }
         }
     }
     return failures.length > 0 ? 1 : 0;

package/src/agent-src/templates/scripts/memory_lookup.ts

@@ -246,6 +246,74 @@ function _pad2(v: string): string {
  * (`agents/memory/<type>.yml` or `<type>/entries.yml` with an `entries:`
  * list), so consumers can adopt either.
  */
+const _CURATED_STATUS_EXCLUDE: ReadonlySet<string> = new Set(['deprecated', 'archived', 'superseded']);
+
+/** Mirror Python `entry.get("status") in _CURATED_STATUS_EXCLUDE`. */
+function _statusExcluded(entry: Record<string, unknown>): boolean {
+    const status = entry['status'];
+    return typeof status === 'string' && _CURATED_STATUS_EXCLUDE.has(status);
+}
+
+
+/*
+ * Staleness, ported from `src/scripts/memory_lookup.ts` on 2026-08-26
+ * (`road-to-memory-twin-reconciliation` 2.2, verdict `dev-side-correct`).
+ *
+ * The template previously had NO staleness handling at all — `grep -c stale`
+ * returned 0 — so a consumer retrieved curated entries whose own
+ * `review_after_days` window had expired, with nothing saying so. `check_memory`
+ * required both fields on every entry the whole time; only retrieval ignored
+ * them.
+ *
+ * Portable by construction: Date math and a regex, no `_lib` import.
+ */
+function _today(): Date {
+    const now = new Date();
+    return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+}
+
+function _parseIsoDate(s: string): Date | null {
+    const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(s);
+    if (!m) {
+        return null;
+    }
+    const y = Number(m[1]);
+    const mo = Number(m[2]);
+    const d = Number(m[3]);
+    if (mo < 1 || mo > 12 || d < 1 || d > 31) {
+        return null;
+    }
+    const date = new Date(Date.UTC(y, mo - 1, d));
+    // Reject overflow (e.g. 2026-02-31 → March), matching fromisoformat's strictness.
+    if (date.getUTCFullYear() !== y || date.getUTCMonth() !== mo - 1 || date.getUTCDate() !== d) {
+        return null;
+    }
+    return date;
+}
+
+function _pyStrDateLike(lv: unknown): string {
+    if (lv instanceof PyTimestamp) {
+        return lv.pyStr;
+    }
+    return _pyStr(lv);
+}
+
+function _isStale(entry: Record<string, unknown>, today: Date): boolean {
+    const lv = entry['last_validated'];
+    const rad = entry['review_after_days'];
+    // Python: `not lv or not isinstance(rad, int)`. PyYAML ints land as JS
+    // numbers; booleans are int in Python but excluded here as the common path.
+    if (!lv || typeof rad !== 'number' || !Number.isInteger(rad)) {
+        return false;
+    }
+    const validated = _parseIsoDate(_pyStrDateLike(lv));
+    if (validated === null) {
+        return false;
+    }
+    const days = Math.round((today.getTime() - validated.getTime()) / 86_400_000);
+    return days > rad;
+}
+
 function* _iter_curated_entries(mtype: string): Generator<[string, Record<string, unknown>]> {
     const type_dir = path.join(MEMORY_ROOT, mtype);
     const single_file = path.join(MEMORY_ROOT, `${mtype}.yml`);
@@ -254,6 +322,9 @@ function* _iter_curated_entries(mtype: string): Generator<[string, Record<string
         const entries = _isPlainObject(data) ? data['entries'] : null;
         for (const e of Array.isArray(entries) ? entries : []) {
             if (_isPlainObject(e)) {
+                if (_statusExcluded(e)) {
+                    continue;
+                }
                 yield [single_file, e];
             }
         }
@@ -266,11 +337,17 @@ function* _iter_curated_entries(mtype: string): Generator<[string, Record<string
             if (Array.isArray(entries)) {
                 for (const e of entries) {
                     if (_isPlainObject(e)) {
+                        if (_statusExcluded(e)) {
+                            continue;
+                        }
                         yield [yml, e];
                     }
                 }
             } else if (_isPlainObject(data) && data['id']) {
                 // Flat, one-entry-per-file layout (content-addressed).
+                if (_statusExcluded(data)) {
+                    continue;
+                }
                 yield [yml, data];
             }
         }
@@ -454,6 +531,7 @@ function _cross_repo_hits(keys: string[], limit: number): Hit[] {
  */
 export function retrieve(types: string[], keys: string[], limit = 5): Hit[] {
     const repo_hits: Hit[] = [];
+    const today = _today();
     for (const mtype of types) {
         if (mtype === KNOWLEDGE_TYPE) {
             for (const [p, entry] of _iter_knowledge_entries()) {
@@ -488,6 +566,14 @@ export function retrieve(types: string[], keys: string[], limit = 5): Hit[] {
             continue;
         }
         for (const [p, entry] of _iter_curated_entries(mtype)) {
+            // A curated entry past its own `review_after_days` window is not
+            // retrieved. The dev side additionally reports it under `skipped`;
+            // this copy has no `retrieve_with_meta`, so it filters silently —
+            // the exclusion is the behaviour that matters, the report is the
+            // richer surface.
+            if (_isStale(entry, today)) {
+                continue;
+            }
             repo_hits.push(new Hit(String(entry['id'] ?? ''), mtype, 'curated', String(p), _score(entry, keys), entry));
         }
         for (const [p, entry] of _iter_intake_entries(mtype)) {