@event4u/agent-config 14.7.0 → 14.9.0

package/dist/agent-src/rules/recurring-criticism.md

@@ -107,4 +107,4 @@ inflate it, so it is not claimed — skipping this rule is caught by nothing.
 - [`decision-revisit-gate`](decision-revisit-gate.md) — the other entrance; owns the five steps and the owner-reserved routing this rule reuses instead of restating. Separate file only because that one sits four lines under the 200-line cap.
 - [`self-repair-loop`](self-repair-loop.md) — the single-occurrence intake; this rule is what its `occurrences` counter is for.
 - [`active-remediation`](active-remediation.md) — the terminal "leave it" this rule does not override (see `collision_ok`).
-- [`/analyze:inbox`](../domains/analysis-workbench/analyze/inbox/command.md) § Phase 4c — the artifact-side detection that routes here.
+- [`/analyze:inbox`](../commands/analyze/inbox.md) § Phase 4c — the artifact-side detection that routes here.

package/dist/agent-src/rules/roadmap-progress-sync.md

@@ -97,6 +97,25 @@ in the estate?**
   [`no-cheap-questions`](no-cheap-questions.md) forbids. The gate protects the
   item, not the maintainer's attention.
 
+### `deferred_policy` — a declared contract removes the round, never the route
+
+An accepted execution contract may declare `deferred_policy`
+([`roadmap-execution-contract § 2b`](../contexts/execution/roadmap-execution-contract.md)).
+It changes **when the round happens**, never **who decides**:
+
+| Declared | Effect on the gate |
+|---|---|
+| absent / `wait` | Unchanged — the synchronous menu runs. |
+| `spawn-follow-up-draft` | The council-routed carry disposition runs **automatically** at closure, with no options round. Legal only because the table above already routes it to the council and Accept pre-authorized the run. |
+| `cancel-with-memo` | The run writes the memo and the recommendation; the `[-]` conversion stays **user**. A declared field never moves a row from user to council. |
+
+Recorded-or-it-did-not-happen applies unchanged to an automatic spawn, and
+fail-closed binds hardest here: a spawn naming a follow-up that does not exist
+yet reaches the user, because a contract cannot pre-authorize a promise.
+Reversible — `wait` is the default, so removing the field restores always-wait
+(`decision 2026-08-20`, AI council 2/2; record
+`agents/evidence/council/drain-blocker-dispositions-a.md`).
+
 ## Later disposition — blocked-for-later roadmaps are parked, never left active
 
 ```

package/dist/agent-src/rules/source-confidentiality.md

@@ -91,7 +91,7 @@ substitute for not writing the attribution in the first place.
 
 ## Why this rule is not path-scoped
 
-Under [ADR-236](../docs/decisions/ADR-236-one-artefact-one-layer.md) this rule is
+Under ADR-236 (`docs/decisions/ADR-236-one-artefact-one-layer.md`) this rule is
 delivered by the PROJECT layer only — it exists to maintain this package, so the
 global layer no longer carries an unscoped twin of it. A `paths:`-scoped rule is
 **not re-injected after `/compact`** (ADR-227:79-80), so scoping it would mean the

package/dist/agent-src/rules/untrusted-input-defense.md

@@ -69,9 +69,15 @@ delegating unbounded execution of everything the task's data happens to say.
 
 No deterministic gate inspects fetched/tool/RAG content for injected
 instructions — the quarantine is carried by the model (ADR-135 lists it in the
-CRITICAL policy class precisely BECAUSE no mechanical backstop exists today;
-a future content-scanning hook would be the first candidate to change this).
-Counting an adjacent lint here would be coverage inflation, so none is counted.
+CRITICAL policy class). Counting an adjacent lint here would be coverage
+inflation, so none is counted.
+
+**A content-scanning hook now exists and this field is unchanged.**
+`injection_scan_hook.ts` is warn-only and default-OFF: it cannot refuse, and a
+hook that cannot refuse does not enforce. This section used to say no such
+backstop existed and that a future one would change the field — the first half
+is now false, the second always was. Detail:
+[`untrusted-input-spotlighting § The content-scanning hook`](../docs/guidelines/agent-infra/untrusted-input-spotlighting.md).
 
 Body migrated to [`guideline:agent-infra/untrusted-input-spotlighting`](../docs/guidelines/agent-infra/untrusted-input-spotlighting.md) (per P4 of `road-to-kernel-and-router.md`) — runtime defense protocol (separate / spotlight / refuse role-takeover / no silent egress / untrusted agent-instruction files), hidden-instruction awareness (invisible Unicode + confusables), injection-signal taxonomy, least-agency → existing-gate OWASP mapping.
 Trigger-set above activates this routing on demand, independent of the discipline profile (ADR-110).

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

@@ -398,10 +398,13 @@ function _regen_dashboard(root: string, dry_run: boolean): void {
     // Python: `_run([sys.executable, str(script)], root)`; the twin spawns the
     // dashboard generator twin through the same `tsx` runtime, cwd=root.
     _runTwin(root, script);
-    const dash = path.join(root, 'agents', 'roadmaps-progress.md');
-    if (_isFile(dash)) {
-        _run(['git', 'add', '--', 'agents/roadmaps-progress.md'], root);
-    }
+    // The dashboard is NOT staged. It is gitignored in this repository, and
+    // `git add -- <ignored-path>` exits 1 with "The following paths are ignored"
+    // -- a code `_run` returns and this call site discarded, so the previous
+    // `git add` here was a silent no-op from the moment the file was untracked
+    // (2026-08-21) and nothing objected. Regenerating it is still correct; the
+    // developer reads it on disk, and `task roadmap-progress-check` compares a
+    // present copy against a fresh render.
 }
 
 /**

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

@@ -0,0 +1,212 @@
+// The `--check` tracked/untracked mode table for the roadmap dashboard.
+//
+// Extracted from `update_roadmap_progress.ts` so the verdict is a pure function
+// over observable state — the generator does the I/O, this decides. It also
+// keeps that script under its per-file size cap.
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+
+/**
+ * Is the dashboard expected to be a committed artefact? Explicit, never
+ * inferred from git state — an unconditional "absent means pass" cannot tell a
+ * correctly-untracked repo from a generator that silently stopped producing
+ * output. `tracked` is the default and the historical behaviour.
+ */
+export type DashboardMode = 'tracked' | 'untracked';
+
+/**
+ * Is `abs` in the git index? Used only by `--check --untracked-mode`, to tell
+ * "correctly absent" from "still committed". No git at all answers `false`,
+ * which is correct: nothing is tracked there.
+ */
+export function isTrackedInGit(abs: string, repo_root: string): boolean {
+    const r = spawnSync('git', ['ls-files', '--error-unmatch', '--', abs], {
+        cwd: repo_root,
+        encoding: 'utf-8',
+        timeout: 10_000,
+    });
+    return r.status === 0;
+}
+
+export interface DashboardStateInput {
+    mode: DashboardMode;
+    /** Is the file on disk? */
+    present: boolean;
+    /** Is the file in the git index? Only consulted in `untracked` mode. */
+    trackedInGit: boolean;
+    /** Does the on-disk content equal a fresh render? Only meaningful if present. */
+    current: boolean;
+    /** Repo-relative path, for the messages. */
+    rel: string;
+    /**
+     * How to regenerate, for the stale/missing messages. Defaults to the
+     * dashboard's own command. A second caller — `build_archive_index --check`
+     * — reuses this table for a different generated artefact, and a message
+     * telling that reader to run the dashboard generator would be wrong.
+     */
+    regen?: string;
+    /**
+     * What the artefact is called in the "deliberately does not commit the X"
+     * hint. Defaults to `dashboard` so every existing message is byte-identical.
+     */
+    noun?: string;
+}
+
+export interface DashboardStateVerdict {
+    /** True when the dashboard half of `--check` fails. */
+    stale: boolean;
+    /** Diagnostic for stderr, or null. */
+    error: string | null;
+    /** Success line for stdout, or null when `stale`. */
+    ok: string | null;
+}
+
+// The SOURCE path, not `.augment/scripts/…`: that tree is a gitignored
+// projection built by `task sync`, so the advice failed outright in a fresh
+// worktree and in any CI step ordered before the sync.
+const REGEN =
+    'Run `./scripts-run src/agent-src/scripts/update_roadmap_progress` ' +
+    'to regenerate (or `task roadmap-progress` in Taskfile projects).';
+
+/**
+ * The mode table:
+ *
+ *   tracked:   absent -> fail | present+stale -> fail | present+current -> pass
+ *   untracked: in-index -> fail | absent -> pass | present+stale -> fail
+ *              | present+current -> pass
+ *
+ * Absence is distinguished ONLY in untracked mode; a present file is
+ * freshness-checked in both, so untracked never means unchecked.
+ */
+export function evaluateDashboardState(inp: DashboardStateInput): DashboardStateVerdict {
+    const { mode, present, trackedInGit, current, rel } = inp;
+    const regen = inp.regen ?? REGEN;
+    const noun = inp.noun ?? 'dashboard';
+
+    if (mode === 'untracked' && trackedInGit) {
+        // Migration incomplete: declared untracked, still carried by git.
+        // Print the fix; never run it — git-index ops are the user's.
+        return {
+            stale: true,
+            error:
+                `❌  ${rel} is still tracked by git, but this repository runs ` +
+                '`--untracked-mode`. Untrack it, keeping the working-tree file:\n' +
+                `      git rm --cached ${rel}\n`,
+            ok: null,
+        };
+    }
+
+    if (!present) {
+        if (mode === 'tracked') {
+            return {
+                stale: true,
+                error:
+                    `❌  ${rel} is missing. ` +
+                    regen.replace('to regenerate', 'to generate it') +
+                    ' If this repository deliberately does not commit the ' +
+                    `${noun}, pass \`--untracked-mode\`.\n`,
+                ok: null,
+            };
+        }
+        // untracked + absent: the declared state. "up to date" would mislead.
+        return {
+            stale: false,
+            error: null,
+            ok: `✅  ${rel} is not committed here (--untracked-mode) and no stale copy is on disk.\n`,
+        };
+    }
+
+    if (!current) {
+        return { stale: true, error: `❌  ${rel} is stale. ${regen}\n`, ok: null };
+    }
+    return { stale: false, error: null, ok: `✅  ${rel} is up to date.\n` };
+}
+
+/**
+ * `evaluateDashboardState` against the real filesystem and git index. The
+ * generator hands over the paths; every read the verdict needs happens here, so
+ * the caller's check branch stays three lines.
+ */
+export function evaluateDashboardOnDisk(opts: {
+    mode: DashboardMode;
+    target: string;
+    repo_root: string;
+    rendered: string;
+    rel: string;
+    regen?: string;
+    noun?: string;
+}): DashboardStateVerdict {
+    const present = fs.existsSync(opts.target);
+    return evaluateDashboardState({
+        mode: opts.mode,
+        present,
+        trackedInGit: opts.mode === 'untracked' && isTrackedInGit(opts.target, opts.repo_root),
+        current: present && fs.readFileSync(opts.target, { encoding: 'utf-8' }) === opts.rendered,
+        rel: opts.rel,
+        ...(opts.regen === undefined ? {} : { regen: opts.regen }),
+        ...(opts.noun === undefined ? {} : { noun: opts.noun }),
+    });
+}
+
+/** One roadmap row, as far as the estate report below needs it. */
+export interface EstateRow {
+    rel: string;
+    done: number;
+    total_active: number;
+    deferred: number;
+}
+
+/**
+ * The `--check` report: the artefact's own verdict, then the estate-wide
+ * conditions — completed-but-unarchived, and Iron Law 3 deferred items.
+ *
+ * `dashboardOnly` drops the estate half. Two obligations with two blast radii:
+ * the artefact verdict is about ONE file and is safe behind a required status
+ * check, while the estate conditions are about roadmaps an unrelated change
+ * never touched, so requiring them turns any pre-existing estate defect into a
+ * merge block on every PR. It did, on 2026-08-22.
+ *
+ * Extracted from the generator so the report is a pure function of the verdict
+ * and two lists — and because the generator sits exactly on its 1500-line
+ * source ceiling, where the honest way to add a feature is to take lines out.
+ */
+export function reportCheckVerdict(inp: {
+    verdict: DashboardStateVerdict;
+    complete: readonly EstateRow[];
+    pending: readonly EstateRow[];
+    dashboardOnly: boolean;
+    warnMergeGated: () => void;
+    gatedCount: number;
+}): { rc: number; stdout: string; stderr: string } {
+    const { verdict, dashboardOnly } = inp;
+    const complete = dashboardOnly ? [] : inp.complete;
+    const pending = dashboardOnly ? [] : inp.pending;
+    let err = verdict.error ?? '';
+    if (complete.length) {
+        err +=
+            '❌  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) err += `      - ${r.rel}  (${r.done}/${r.total_active} done)\n`;
+    }
+    if (pending.length) {
+        err +=
+            '❌  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) {
+            err += `      - ${r.rel}  (${r.done}/${r.total_active} done · ${r.deferred} deferred)\n`;
+        }
+    }
+    if (!dashboardOnly && inp.gatedCount > 0) inp.warnMergeGated();
+    const rc = verdict.stale || complete.length > 0 || pending.length > 0 ? 1 : 0;
+    return { rc, stdout: rc === 0 ? (verdict.ok ?? '') : '', stderr: err };
+}
+
+/** `--tracked-mode` / `--untracked-mode` → the mode, or null for any other token. */
+export function parseModeToken(tok: string): DashboardMode | null {
+    if (tok === '--tracked-mode') return 'tracked';
+    if (tok === '--untracked-mode') return 'untracked';
+    return null;
+}

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

@@ -64,6 +64,12 @@ 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);
@@ -998,8 +1004,9 @@ function render(roadmaps: RoadmapStats[], bundles: Bundle[] | null, roadmap_root
         // 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');
@@ -1214,18 +1221,32 @@ class ArgparseExit extends Error {
 const _PROG = 'update_roadmap_progress.py';
 
 function _usage(): string {
-    return `usage: ${_PROG} [-h] [--check] [--archive | --no-archive] [--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());
@@ -1241,6 +1262,12 @@ 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;
@@ -1267,7 +1294,10 @@ function _parseArgs(argv: readonly string[]): Args {
         // rather than silently letting one win.
         emitError('argument --archive: not allowed with --check');
     }
-    return { check, archive, repo_root };
+    if (dashboard_only && !check) {
+        emitError('argument --dashboard-only: only meaningful with --check');
+    }
+    return { check, mode, archive, repo_root, dashboard_only };
 }
 
 /**
@@ -1334,13 +1364,10 @@ function main(argv?: readonly string[]): number {
     }
     const roadmaps = collect(roadmap_root);
     const new_text = render(roadmaps, collect_bundles(repo_root), roadmap_root);
-    const current = fs.existsSync(target) ? fs.readFileSync(target, { encoding: 'utf-8' }) : '';
     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) — ' +
@@ -1357,50 +1384,22 @@ 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`,
     );

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