@event4u/agent-config 14.6.0 → 14.8.0

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

@@ -32,8 +32,12 @@
  *
  * Invocation (from project root):
  *   node node_modules/.bin/tsx .augment/scripts/update_roadmap_progress.ts              # rewrite
+ *   node node_modules/.bin/tsx .augment/scripts/update_roadmap_progress.ts --archive    # rewrite + archive completed
  *   node node_modules/.bin/tsx .augment/scripts/update_roadmap_progress.ts --check      # CI: exit 1 if stale
  *
+ * `--archive` is opt-in and `--check` refuses it; the full contract, the
+ * council record and the sweep spawner live in `archival_sweep.ts`.
+ *
  * --- Parity notes (ADR-200) ---
  *
  * - Python `round()` is banker's rounding (round-half-to-even). Percentages and
@@ -59,6 +63,13 @@ import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { run_archival_sweep } from './archival_sweep.js';
+import {
+    evaluateDashboardOnDisk,
+    parseModeToken,
+    reportCheckVerdict,
+    type DashboardMode,
+} from './dashboard_mode.js';
 import type * as YamlModule from 'yaml';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -280,12 +291,21 @@ function is_draft(fm: Record<string, string>): boolean {
     return DRAFT_VALUES.has((fm['status'] ?? '').toLowerCase());
 }
 
-function is_roadmap_candidate(p: string): boolean {
-    const name = path.basename(p);
+/**
+ * The NAME half of the candidate test. Split out because the parked inventory
+ * reads `later/` on purpose and `is_roadmap_candidate` rejects any path carrying
+ * an excluded component — `later` included. Sharing this half keeps
+ * `later/README.md` excluded from both sides by one rule rather than two.
+ */
+function is_roadmap_name(name: string): boolean {
     if (EXCLUDE_NAMES.has(name)) {
         return false;
     }
-    if (EXCLUDE_PREFIXES.some((pre) => name.startsWith(pre))) {
+    return !EXCLUDE_PREFIXES.some((pre) => name.startsWith(pre));
+}
+
+function is_roadmap_candidate(p: string): boolean {
+    if (!is_roadmap_name(path.basename(p))) {
         return false;
     }
     // path.parts — every component of the path; exclude if any is an excluded dir.
@@ -741,6 +761,140 @@ function collect(roadmap_root: string): RoadmapStats[] {
     return results;
 }
 
+/** One parked roadmap, as the inventory needs it. */
+interface ParkedRoadmap {
+    rel: string;
+    resume: string | null;
+    /** Only the linter's looser marker matched — CI passes, the cell cannot quote. */
+    unlabelled: boolean;
+    /** Open blockers still carried by the parked file. */
+    open_blockers: number;
+    /** Of those, the ones whose owner is the user. */
+    needs_user: number;
+}
+
+/**
+ * A line that STATES when the roadmap comes back. Two tiers exist because
+ * `lint_roadmap_later_disposition` accepts a bare `trigger`, which is too loose to
+ * quote from — measured over the live tree it matched a `Source:` path containing
+ * `mixed-trigger-cleanup`, producing cells that were wrong rather than short.
+ */
+const RESUME_STATEMENT = /\b(blocked until|resume when|resume-when|blocked-until)\b/i;
+
+/**
+ * The linter's looser vocabulary. A file matching only this DOES carry a resume
+ * condition as far as CI is concerned, so reporting it as missing would make the
+ * dashboard contradict a gate that already passed.
+ */
+const RESUME_LOOSE = /\btrigger\b/i;
+
+/**
+ * Parked roadmaps, with the resume condition each one records.
+ *
+ * A view over existing data, NOT a new governance mechanism: nothing here gates,
+ * counts toward a ratchet, or changes what `collect()` scans. It exists because
+ * `later/` is excluded from `collect()` and from `/roadmap:process-*` — correct,
+ * parked work is not backlog — and that exclusion had no counterweight, so a
+ * roadmap moved there left the dashboard entirely.
+ */
+function collect_parked(roadmap_root: string): ParkedRoadmap[] {
+    const dir = path.join(roadmap_root, 'later');
+    let names: string[];
+    try {
+        names = fs.readdirSync(dir).sort();
+    } catch {
+        return [];
+    }
+    const out: ParkedRoadmap[] = [];
+    for (const name of names) {
+        const full = path.join(dir, name);
+        // The NAME half only: the full predicate rejects every path under `later`.
+        if (!_isFile(full) || !is_roadmap_name(name)) {
+            continue;
+        }
+        let text: string;
+        try {
+            text = fs.readFileSync(full, { encoding: 'utf-8' });
+        } catch {
+            continue;
+        }
+        if (is_draft(parse_frontmatter(text))) {
+            continue;
+        }
+        const cell = resume_cell(text);
+        // Parked blockers are still open blockers — counting them here is what stops
+        // this section becoming the surface where a park reads as a resolution.
+        const open = parse_blockers(text).filter((b) => !blocker_is_resolved(b));
+        out.push({
+            rel: name,
+            resume: cell.stated,
+            unlabelled: cell.unlabelled,
+            open_blockers: open.length,
+            needs_user: open.filter((b) => blocker_needs_user(b.owner)).length,
+        });
+    }
+    return out;
+}
+
+/**
+ * What brings a parked roadmap back, as one table cell. Both fields false means the
+ * file records nothing — said outright, because an empty cell reads as "nothing to
+ * wait for".
+ *
+ * The PARAGRAPH is joined, not the matched line: roadmap prose wraps at ~80
+ * columns, and quoting one line ended 39 of 52 cells mid-clause. A cell stopping at
+ * "the pair for" is not a shorter sentence, it is a different claim.
+ *
+ * Both tiers are tested over the SAME lines. Testing the loose one whole-file while
+ * the strict one ran per line made `unlabelled` fire on any file using the word
+ * "trigger" anywhere.
+ */
+function resume_cell(text: string): { stated: string | null; unlabelled: boolean } {
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i] as string;
+        if (!RESUME_STATEMENT.test(raw)) {
+            continue;
+        }
+        const parts: string[] = [raw];
+        // Continuation lines of the same paragraph: non-blank, and not the start of
+        // a new block (list item, heading, fence, table row).
+        for (let j = i + 1; j < lines.length; j++) {
+            const next = (lines[j] as string).replace(/^\s*>\s?/, '').trim();
+            if (next === '' || /^([-*+]\s|#{1,6}\s|```|\||>\s*$)/.test(next)) {
+                break;
+            }
+            parts.push(next);
+        }
+        const joined = cell_text(parts.join(' '));
+        if (joined === '') {
+            continue;
+        }
+        return { stated: joined, unlabelled: false };
+    }
+    return { stated: null, unlabelled: lines.some((l) => RESUME_LOOSE.test(l)) };
+}
+
+/**
+ * One roadmap sentence, safe between two pipes. ORDER IS LOAD-BEARING: truncate
+ * before escaping, because cutting an escaped string severs a `\|` and leaves a
+ * dangling backslash. HTML comments are removed, not escaped — a `<!--` reaching a
+ * cell comments out the rest of the document, and one already did.
+ */
+function cell_text(raw: string): string {
+    let out = raw
+        .replace(/^\s*>\s?/, '')
+        .replace(/<!--[\s\S]*?-->/g, '')
+        .replace(/<!--|-->/g, '')
+        .replace(/\*\*/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (out.length > 200) {
+        out = `${out.slice(0, 197).trimEnd()}...`;
+    }
+    return out.replace(/\|/g, '\\|');
+}
+
 function unarchived_complete(roadmaps: RoadmapStats[]): RoadmapStats[] {
     return roadmaps.filter((r) => r.total_active > 0 && r.open_ === 0 && r.deferred === 0);
 }
@@ -812,7 +966,7 @@ function collect_bundles(repo_root: string): Bundle[] {
     return out;
 }
 
-function render(roadmaps: RoadmapStats[], bundles: Bundle[] | null = null): string {
+function render(roadmaps: RoadmapStats[], bundles: Bundle[] | null, roadmap_root: string): string {
     const total_done = roadmaps.reduce((s, r) => s + r.done, 0);
     const total_active = roadmaps.reduce((s, r) => s + r.total_active, 0);
     const overall_pct = total_active ? _pyRound((total_done * 100) / total_active) : 0;
@@ -836,6 +990,7 @@ function render(roadmaps: RoadmapStats[], bundles: Bundle[] | null = null): stri
         '[skipped/](roadmaps/skipped/) · [later/](roadmaps/later/)' +
         (total_open_blockers > 0
             ? ` · **${total_open_blockers}** open blocker${total_open_blockers !== 1 ? 's' : ''}` +
+              ' in the active tree' +
               (user_open_blockers > 0
                   ? `, **${user_open_blockers}** need you → \`agent-config gates\``
                   : '')
@@ -849,8 +1004,9 @@ function render(roadmaps: RoadmapStats[], bundles: Bundle[] | null = null): stri
         // script name covers the rest.
         '> Auto-generated — do not edit. Regenerate with `task roadmap-progress` ' +
             'or by running the `update_roadmap_progress` script for your install; ' +
-            'rewritten on every roadmap create / execute / completion change ' +
-            '(timestamp lives in git history).\n>\n' +
+            'rewritten on every roadmap create / execute / completion change. ' +
+            'A repository that does not commit this file has no git history for ' +
+            'it — regenerate to see the current state.\n>\n' +
             header_meta,
     );
     lines.push('## Overall\n');
@@ -939,6 +1095,58 @@ function render(roadmaps: RoadmapStats[], bundles: Bundle[] | null = null): stri
     });
     lines.push('');
     lines.push('---\n');
+
+    // Listed under the active table so the two are read together. Parked work
+    // carries no counts here; what a reader needs is what brings it back.
+    const parked = collect_parked(roadmap_root);
+    if (parked.length > 0) {
+        lines.push(
+            `## Parked — \`later/\` (${parked.length} roadmap` +
+                `${parked.length !== 1 ? 's' : ''}, not active backlog)\n`,
+        );
+        lines.push(
+            '> Excluded from the table above and from `/roadmap:process-*` by ' +
+                'design. Listed here so a resume condition is visible without ' +
+                'opening the file.\n',
+        );
+        const parked_open = parked.reduce((n, r) => n + r.open_blockers, 0);
+        const parked_user = parked.reduce((n, r) => n + r.needs_user, 0);
+        if (parked_open > 0) {
+            lines.push(
+                `> Carrying **${parked_open}** open blocker` +
+                    `${parked_open !== 1 ? 's' : ''}` +
+                    (parked_user > 0 ? `, **${parked_user}** owned by you` : '') +
+                    ' — parking resolves nothing, so these are NOT in the ' +
+                    'active-tree count above.\n',
+            );
+        }
+        lines.push('| Roadmap | Open blockers | Resume when |');
+        lines.push('|---|---:|---|');
+        for (const r of parked) {
+            const cell =
+                r.resume ??
+                (r.unlabelled
+                    ? '_condition present but unlabelled — see file_'
+                    : '_no resume line recorded_');
+            const blockers =
+                r.open_blockers === 0
+                    ? '0'
+                    : `${r.open_blockers}${r.needs_user > 0 ? ` (${r.needs_user} you)` : ''}`;
+            // `<!-- ref-ignore -->` per row — a correctness fix, not a suppression. A
+            // resume condition NAMES WHAT DOES NOT EXIST YET ("when `x.md` exists" is
+            // the commonest shape in `later/`), so checking these quoted paths as live
+            // references fires the gate on correct content. It fired immediately. The
+            // authoritative copy of each path is the roadmap file; this table quotes
+            // it, and that gate does not walk `later/` either way.
+            lines.push(
+                `| [${r.rel}](roadmaps/later/${r.rel}) | ${blockers} | ${cell} |` +
+                    ' <!-- ref-ignore -->',
+            );
+        }
+        lines.push('');
+        lines.push('---\n');
+    }
+
     lines.push('## Per-roadmap phase breakdown\n');
     for (const r of roadmaps) {
         lines.push(`### [${r.rel}](roadmaps/${r.rel})\n`);
@@ -1013,16 +1221,32 @@ class ArgparseExit extends Error {
 const _PROG = 'update_roadmap_progress.py';
 
 function _usage(): string {
-    return `usage: ${_PROG} [-h] [--check] [--repo-root REPO_ROOT]\n`;
+    return (
+        `usage: ${_PROG} [-h] [--check] [--tracked-mode | --untracked-mode]\n` +
+        `       [--archive | --no-archive] [--repo-root REPO_ROOT] [--dashboard-only]\n`
+    );
 }
 
 interface Args {
     check: boolean;
+    mode: DashboardMode;
+    archive: boolean;
     repo_root: string;
+    /**
+     * Assert ONLY this artefact's own state — tracked / absent / stale — not
+     * the estate-wide conditions `--check` also carries. Two obligations, two
+     * blast radii: why that split exists, and what it cost when it did not,
+     * is on the `roadmap-dashboard-untracked-check` task in
+     * `taskfiles/content.yml`.
+     */
+    dashboard_only: boolean;
 }
 
 function _parseArgs(argv: readonly string[]): Args {
     let check = false;
+    let mode: DashboardMode = 'tracked';
+    let archive = false;
+    let dashboard_only = false;
     let repo_root = process.cwd();
     const emitError = (msg: string): never => {
         process.stderr.write(_usage());
@@ -1038,6 +1262,18 @@ function _parseArgs(argv: readonly string[]): Args {
         } else if (tok === '--check') {
             check = true;
             i += 1;
+        } else if (parseModeToken(tok) !== null) {
+            mode = parseModeToken(tok) as DashboardMode;
+            i += 1;
+        } else if (tok === '--dashboard-only') {
+            dashboard_only = true;
+            i += 1;
+        } else if (tok === '--archive') {
+            archive = true;
+            i += 1;
+        } else if (tok === '--no-archive') {
+            archive = false;
+            i += 1;
         } else if (tok === '--repo-root') {
             const val = argv[i + 1];
             if (val === undefined) {
@@ -1052,7 +1288,16 @@ function _parseArgs(argv: readonly string[]): Args {
             emitError(`unrecognized arguments: ${tok}`);
         }
     }
-    return { check, repo_root };
+    if (check && archive) {
+        // A gate that mutates the tree it is checking cannot be trusted by CI
+        // (council 2026-08-20, both seats). Refuse the combination outright
+        // rather than silently letting one win.
+        emitError('argument --archive: not allowed with --check');
+    }
+    if (dashboard_only && !check) {
+        emitError('argument --dashboard-only: only meaningful with --check');
+    }
+    return { check, mode, archive, repo_root, dashboard_only };
 }
 
 /**
@@ -1094,15 +1339,35 @@ function main(argv?: readonly string[]): number {
         process.stdout.write(`ℹ️  No roadmaps directory at ${roadmap_root} — nothing to do.\n`);
         return 0;
     }
+    // Archive before rendering, so the dashboard describes the tree the sweep
+    // leaves behind rather than the one it found. `--check` never archives: a
+    // gate that mutates the tree it is checking cannot be trusted by CI.
+    let sweep_out = '';
+    if (!args.check && args.archive && unarchived_complete(collect(roadmap_root)).length > 0) {
+        const swept = run_archival_sweep(repo_root);
+        sweep_out = swept.stdout;
+        if (swept.stderr) {
+            process.stderr.write(swept.stderr);
+        }
+        if (!swept.ok) {
+            // A half-finished sweep leaves the tree in a shape the dashboard
+            // would describe as if it were intentional. Report and stop before
+            // writing (council 2026-08-20: "archival failures must prevent
+            // dashboard rendering so partially updated state is not presented
+            // as current").
+            process.stderr.write(
+                '❌  The archival sweep failed — dashboard NOT regenerated. ' +
+                    'Fix the tree, then re-run.\n',
+            );
+            return 1;
+        }
+    }
     const roadmaps = collect(roadmap_root);
-    const new_text = render(roadmaps, collect_bundles(repo_root));
-    const current = fs.existsSync(target) ? fs.readFileSync(target, { encoding: 'utf-8' }) : '';
+    const new_text = render(roadmaps, collect_bundles(repo_root), roadmap_root);
     const complete = unarchived_complete(roadmaps);
     const pending = pending_iron_law_3(roadmaps);
     const gated = merge_gated_pending(roadmaps);
 
-    const _relToRepo = (p: string): string => _relPosix(repo_root, p);
-
     const _warn_merge_gated = (): void => {
         process.stderr.write(
             '⏳  Merge-gated roadmaps (every open item gated on a PR) — ' +
@@ -1119,54 +1384,32 @@ function main(argv?: readonly string[]): number {
     };
 
     if (args.check) {
-        const stale = current !== new_text;
-        if (stale) {
-            process.stderr.write(
-                `❌  ${_relToRepo(target)} is stale. ` +
-                    'Run `node node_modules/.bin/tsx .augment/scripts/update_roadmap_progress.ts` ' +
-                    'to regenerate (or `task roadmap-progress` in Taskfile ' +
-                    'projects).\n',
-            );
-        }
-        if (complete.length) {
-            process.stderr.write(
-                '❌  Completed roadmaps are still in `agents/roadmaps/` — ' +
-                    'move them to `agents/roadmaps/archive/` (per the ' +
-                    '`roadmap-progress-sync` rule):\n',
-            );
-            for (const r of complete) {
-                process.stderr.write(`      - ${r.rel}  (${r.done}/${r.total_active} done)\n`);
-            }
-        }
-        if (pending.length) {
-            process.stderr.write(
-                '❌  Iron Law 3 — roadmaps with unresolved `[~]` deferred ' +
-                    'items must NOT auto-archive. Resolve via `roadmap-management § 4b` ' +
-                    '(spawn follow-up, restore, or cancel):\n',
-            );
-            for (const r of pending) {
-                process.stderr.write(
-                    `      - ${r.rel}  (${r.done}/${r.total_active} done · ` +
-                        `${r.deferred} deferred)\n`,
-                );
-            }
-        }
-        if (gated.length) {
-            _warn_merge_gated();
-        }
-        if (stale || complete.length || pending.length) {
-            return 1;
-        }
-        process.stdout.write(`✅  ${_relToRepo(target)} is up to date.\n`);
-        return 0;
+        const rel = _relPosix(repo_root, target);
+        const r = reportCheckVerdict({
+            verdict: evaluateDashboardOnDisk({ mode: args.mode, target, repo_root, rendered: new_text, rel }),
+            complete,
+            pending,
+            dashboardOnly: args.dashboard_only,
+            warnMergeGated: _warn_merge_gated,
+            gatedCount: gated.length,
+        });
+        if (r.stderr) process.stderr.write(r.stderr);
+        if (r.stdout) process.stdout.write(r.stdout);
+        return r.rc;
     }
     fs.writeFileSync(target, new_text, { encoding: 'utf-8' });
     process.stdout.write(
-        `✅  Wrote ${_relToRepo(target)} · ` +
+        `✅  Wrote ${_relPosix(repo_root, target)} · ` +
             `${roadmaps.length} roadmap(s) · ` +
             `${roadmaps.reduce((s, r) => s + r.done, 0)}/${roadmaps.reduce((s, r) => s + r.total_active, 0)} steps done.\n`,
     );
+    if (sweep_out) {
+        process.stdout.write(sweep_out);
+    }
     if (complete.length) {
+        // Whatever survived the sweep is complete but NOT archivable — the
+        // sweep already said why on stderr (an open blocker outlives its
+        // steps). Without `--archive` this is every complete roadmap.
         process.stderr.write(
             '⚠️   Completed roadmaps not yet archived — move to ' +
                 '`agents/roadmaps/archive/`:\n',

package/dist/agent-src/skills/adr-create/SKILL.md

@@ -45,6 +45,33 @@ Do NOT use when:
   supersede it instead of duplicating.
 - A skill, rule, or guideline is the better home (use those skills).
 
+## Admission gate — classify before you create
+
+Run this **before** picking a surface or a number. An ADR is warranted only
+when the decision is architecturally significant on at least one axis:
+
+1. **Hard or costly to reverse** — a one-way door: public API shape, DB
+   schema, wire format, published identifier, migration.
+2. **Broadly constraining** — it binds work outside the module that made it.
+3. **Crosses a governed surface** — consumer contract, API, security or
+   privacy floor, package structure.
+
+None of the three holds → it is **not** an ADR. Route it to its real home: a
+decision note in `agents/decisions/`, a config value, a measurement record in
+`docs/CLAIMS.md`, an experiment, or a roadmap item.
+
+Explicitly **not** ADRs: a temporary numeric threshold · a benchmark value ·
+a model mapping · one-off release sequencing · a reversible local
+implementation detail.
+
+**The tree's own reference case.** ADR-002 encodes `25 000 → 26 000` and a
+`4.0k` override ceiling as architecture law (`ADR-002:55`, `:62`), and
+ADR-114 then had to add another override while recording that 7 of 9 kernel
+rules already carry them (`ADR-114:74`). The *principle* — a kernel budget
+exists, is measured, and is capped — is the ADR. The numbers belong in a
+versioned budget contract with a regression gate, so a recalibration stops
+needing an architecture supersession.
+
 ## Goal
 
 - Sequential `ADR-NNN-<slug>.md` numbering with no gaps.
@@ -114,6 +141,11 @@ Use the surface-specific template. All sections are required; "—"
 is acceptable for genuinely empty Alternatives or References blocks
 but never for Status, Context, Decision, or Consequences.
 
+`## Evidence` and `## Assumptions` are required headings too, with one
+carve-out each: `## Evidence` may be empty only when the record grades itself
+`E0` and says so in the section, and `## Assumptions` may be "—" only when
+every load-bearing claim in the rationale carries a basis ref.
+
 **`review_trigger` is required and it names a CONDITION, not a date.** A
 decision is a call made under conditions that held at the time; the trigger
 records which change would make it worth re-deciding. "Review annually" is
@@ -124,11 +156,52 @@ the event: *"when a second consumer reports the same preservation surprise"*,
 below the pre-registered threshold"*. Enforced from 2026-07-25 forward; earlier
 ADRs are grandfathered by date.
 
+**Staged — and `terminal` is not one of the stages.** A new or materially
+amended accepted ADR needs a substantive trigger now. An *existing* accepted
+record may carry `review_trigger: unclassified` while the migration runs, and
+that exception count only ever decreases. `terminal`, `none`, an empty value
+and permanence phrasing ("forever", "never revisit", "settled forever") are
+invalid at **every** stage — `check_adr_frontmatter.ts` rejects them, because
+"no trigger — terminal decision" is permanence with softer wording. `terminal`
+is not a migration state; it is the thing the staging exists to stop becoming
+permanent. Superseded, rejected and deprecated records are historical and need
+no active trigger.
+
 When you later reopen one, say which **premise moved** and what evidences the
 move — not "we were wrong". If the original was right under its own conditions,
 record that too. A premise that turns out false while the decision stays correct
 gets a logged correction block, never a silent edit.
 
+**Three descriptive axes ship on a new record** — `provenance`, `evidence`,
+`authority_basis`. Vocabulary, defaults and the mutation policy are owned by
+[`adr-layout § Provenance and evidence`](../../../docs/contracts/adr-layout.md);
+`check_adr_frontmatter.ts` validates the shape. What the author has to get
+right while drafting:
+
+- Every load-bearing factual claim in the rationale either **points at a basis
+  ref** — `file:line`, a URL, a `docs/CLAIMS.md` claim id, a benchmark id — or
+  is **labelled an assumption** under `## Assumptions`. There is no third
+  state, and an unlabelled guess reads as a finding to the next reader.
+- **An empty `## Evidence` section means `E0` by construction, and the record
+  says so.** An honest E0 is publishable, exactly as an honest null is; a
+  confident grade over an empty section is not.
+- `discovery: incomplete` is the honest default on E0 and stays that value
+  until a defined evidence search has run and found nothing. `complete`
+  asserts absence — a claim the author owns.
+- **A grade of E2 or above must name a `basis`.** The validator rejects an
+  E2/E3/E4 with an empty basis list; grade it lower rather than asserting a
+  source you cannot cite.
+- **A council attribution never lifts a grade above E0.** N models agreeing is
+  `provenance: agentic` with `agentic_mode: council` — sources and
+  measurements raise `strength`, consensus does not. A council is deliberately
+  not its own `kind`.
+- A human product decision records `strength: E0` with
+  `authority_basis: owner_intent` and does **not** fake a grade. Its authority
+  comes from owning the purpose.
+- **A grade prices review burden, never authority.** Nothing about writing
+  `E0` makes the record cheaper to overturn *by whom* — see
+  [`adr-layout § The reopen record`](../../../docs/contracts/adr-layout.md).
+
 **Flat-surface template** (`docs/decisions/ADR-NNN-<slug>.md`):
 
 ```markdown
@@ -145,6 +218,17 @@ phase: <roadmap> · <phase-id>
 review_trigger: <the CONDITION that would reopen this decision>
 protected_dimensions: [...]  # optional — purpose | security_floor | privacy_floor | external_commitment | governance | none
 reopen_policy: directional | owner | unclassified   # optional; absent → unclassified
+
+provenance:
+  kind: human | agentic | mixed | unknown
+  decision_makers: [...]          # who actually selected it
+  human_directed: true | false | unknown
+  agentic_mode: single | council | delegated   # optional, descriptive only
+evidence:
+  strength: E0 | E1 | E2 | E3 | E4
+  discovery: complete | incomplete    # required when strength is E0
+  basis: [...]                        # file:line | URL | CLAIMS id | benchmark id
+authority_basis: evidence | owner_intent      # optional; absent → evidence
 ---
 
 # ADR-NNN — <Decision Title>
@@ -153,24 +237,59 @@ reopen_policy: directional | owner | unclassified   # optional; absent → uncla
 
 **<Proposed | Accepted | …>** · YYYY-MM-DD.
 
-## Context / Decision / Consequences / Alternatives / References
+## Context / Decision / Evidence / Assumptions / Consequences / Alternatives / References
 ```
 
+`## Evidence` carries one line per basis ref backing a load-bearing claim.
+`## Assumptions` carries every load-bearing claim that has no basis ref — that
+is what makes the grade honest rather than decorative.
+
 **Per-area template** (`docs/adrs/<area>/NNNN-<slug>.md`):
 
 ```markdown
+---
+adr: NNNN
+area: <area>
+status: proposed | accepted | superseded | deprecated
+date: YYYY-MM-DD
+decision: <slug>
+supersedes: —
+superseded_by: —
+type: retrospective | prospective
+review_trigger: <the CONDITION that would reopen this decision>
+
+provenance:
+  kind: human | agentic | mixed | unknown
+  decision_makers: [...]
+  human_directed: true | false | unknown
+  agentic_mode: single | council | delegated   # optional, descriptive only
+evidence:
+  strength: E0 | E1 | E2 | E3 | E4
+  discovery: complete | incomplete    # required when strength is E0
+  basis: [...]                        # file:line | URL | CLAIMS id | benchmark id
+authority_basis: evidence | owner_intent      # optional; absent → evidence
+---
+
 # ADR NNNN — <Decision Title>
 
 > Area: `<area>` · Status: accepted · Date: YYYY-MM-DD · Type: retrospective | new
 > Roadmap: `agents/roadmaps/<file>.md` <phase-id>
 > Supersedes: —
 
-## Context / Decision / Considered alternatives / Consequences / References
+## Context / Decision / Evidence / Assumptions / Considered alternatives / Consequences / References
 ```
 
-Per-area ADRs use a quote-style header (no YAML frontmatter) so
-`audit_adr_coverage.ts`'s permissive parser can index them. Cite
-the area's contract from the README in
+The frontmatter block is the same shape as the flat surface — the contract
+says so ([`adr-layout § Frontmatter`](../../../docs/contracts/adr-layout.md):
+"identical across both surfaces"), and `audit_adr_coverage.ts`'s parser reads
+it when present. The quote-style header stays as the human-readable banner,
+and every existing per-area record now carries frontmatter beside it, so their
+generated README tables render real values — see
+[`docs/adrs/telegraph/README.md`](../../../docs/adrs/telegraph/README.md),
+whose rows read `accepted` / `2026-05-16`. A record carrying the banner alone
+is not blank either: `parse_blockquote_meta` reads the
+`> Area: … · Status: … · Date: …` line as a fallback, and only a record with
+neither renders "—". Cite the area's contract from the README in
 [`docs/adrs/<area>/README.md`](../../../docs/adrs/).
 
 ### 5. Regenerate the index