@dall337/lore 0.0.0-stage → 0.1.0

package/suite/policies/release.md

@@ -0,0 +1,56 @@
+# Release Policy
+
+Scoped agent-governance procedure (AGENTS.md §1/§2). Load for release
+work: version bumps, bundling, release builds.
+
+## Rule 1 — The Version Lives in N Places; Enumerate Them
+
+Every project carries its version string in more places than the obvious
+manifest: package manifests, lockfiles (often more than once per file),
+platform config, documentation banners. **On adoption, this policy's
+first job is to enumerate every location** *(adopt-time slot)* — and to
+keep the enumeration current, because a bump that follows a stale list
+literally ships with locations stale.
+
+```
+# Fill in on adoption — every file carrying the version string, e.g.:
+# package.json · package-lock.json (root AND packages[""]) ·
+# platform config · Cargo.toml · Cargo.lock · docs banner
+```
+
+- Every bump updates **all locations in the same commit**.
+- **The gate:** a repo-wide search for the OLD version string before
+  committing — zero hits outside ignored directories.
+
+## Rule 2 — Versioning Scheme
+
+*(Adopt-time slot.)* The project declares its scheme here. Recommended
+default: semver, valid for every packaging target the project ships to.
+If the project uses a pre-release iteration suffix (`1.0.1-1`,
+`1.0.1-2`, …), record here what the bare version is reserved for and who
+decides when it's spent.
+
+## Rule 3 — Sequence
+
+Version bumps land **last**: merge code branches first, push docs and
+plans, bump after the release scope is locked (`policies/git.md` §3).
+Release bumps get their own commit.
+
+## Rule 4 — Artifacts and Their Prerequisites
+
+Enumerate here, on adoption: pre-release staging steps (bundled runtimes,
+sidecars, assets), the exact release build command, and any artifacts
+that must be archived per released version (e.g. sourcemaps or debug
+symbols that crash reporting depends on for symbolication). A release
+whose symbols weren't archived is a release whose crash reports can't be
+read.
+
+## Rule 5 — Verify the Release Artifact Is a Release Artifact
+
+Dev-mode configuration leaks into release builds — dev-server URLs,
+debug endpoints, unminified bundles — and the resulting binary looks
+built while being broken standalone. The release artifact is verified by
+**running it in isolation from the dev environment** before it ships. If
+the project's toolchain has a known wrong-command trap (a plain release
+compile that still targets the dev server), name the correct command
+here the first time it burns a session.

package/suite/policies/research.md

@@ -0,0 +1,133 @@
+# Research Policy
+
+Scoped agent-governance procedure (AGENTS.md §1/§2). Load **before the
+first tool call** of any task involving research, investigation,
+debugging, architecture discovery, repository exploration, documentation
+review, root-cause analysis, or any task requiring more than a few tool
+calls. Failure to follow this policy is an execution error.
+
+## Bootstrap Checklist
+
+☐ Read this document completely
+☐ Create the research journal
+☐ Record objective and success criteria
+☐ Begin investigation
+
+## Primary Objective
+
+**Research must be resilient to interruption.** Assume execution may stop
+at any time: session expiration, context limits, rate limits, model
+replacement, restart, user interruption, process termination. At no point
+should significant investigative work exist only inside a model's context
+window.
+
+The governing invariant:
+
+> If execution stops unexpectedly, another agent must be able to continue
+> after reading only the journal, without repeating completed work.
+
+This invariant takes priority over convenience and speed.
+
+## Rule 1 — Journal First
+
+Before the first search, grep, file read, or tool call, create the
+journal:
+
+```
+.research/<date>-<short-task-name>.md
+```
+
+(`.research/` is in-tree but gitignored by design.) The journal is the
+authoritative record of the investigation from this moment on.
+
+**Sub-agents create their own journals.** A sub-agent's investigation is
+still an investigation: it gets its own journal, named to show lineage —
+`.research/<date>-<parent-task>--sub-<label>.md`. The parent links every
+sub-journal from its own journal and from its registry file
+(`policies/memory.md` §3), and on the sub-agent's completion absorbs the
+conclusions into its `## Current Findings` — by link and summary, not by
+copy. Sub-journals follow every rule in this policy.
+
+## Rule 2 — Record the Objective
+
+The journal begins with: original request, current objective, success
+criteria, known constraints, assumptions. This section is never
+overwritten.
+
+## Rule 3 — Log Every Investigation Step
+
+Every significant action — searches, greps, file inspections, symbol
+lookups, build/test runs, log and database inspection — gets an entry:
+what was done, why, and **what was learned**. Relevant files and symbols
+by name. Do not merely state that an action occurred.
+
+## Rule 4 — Evidence, Not Chain of Thought
+
+The journal is a technical notebook, not a reasoning dump. Record observed
+facts, supporting code, documentation references, verified behavior,
+rejected hypotheses (with why), confirmed conclusions. It must be
+understandable by another engineer or agent with no access to hidden
+reasoning.
+
+## Rule 5 — Running Sections
+
+Maintain continuously, so no future reader reconstructs state from raw
+log entries:
+
+- `## Current Findings` — every confirmed discovery, summarized.
+- `## Remaining Questions` — unknowns, missing evidence, unverified
+  assumptions, edge cases.
+- `## Next Actions` — an ordered checklist of the next executable work
+  items, always current.
+
+## Rule 6 — Save Continuously
+
+Append and save after every significant step. The maximum work lost to an
+interruption is one investigation step.
+
+## Rule 7 — Resume From the Journal
+
+If interrupted: locate the journal, read it completely, reconstruct state,
+continue from `## Next Actions`. Never restart an investigation blindly.
+
+## Rule 8 — No Duplicate Investigation
+
+Before any search, grep, or inspection, consult the journal. Completed
+findings that remain valid are reused, not re-derived — unless
+verification is explicitly the point.
+
+## Rule 9 — Final Deliverable
+
+A complete journal contains: Objective · Original Request · Investigation
+Log · Evidence · Current Findings · Remaining Questions · Next Actions ·
+Final Conclusions. The report presented to the owner derives from the
+journal.
+
+> **Addendum (2026-10-17, owner-directed policy tags):** Near the top,
+> a journal names the policies loaded for its task on one line:
+> `Policies: research, implementation`. The dispatch table already makes
+> a missed policy an execution error (AGENTS.md §2.2); this line makes
+> the dispatch auditable. The HUD shows declared policies as solid tags
+> and policies a journal only mentions as dotted ones.
+
+## Rule 10 — The Journal Is the Source of Truth
+
+Conversation context is temporary; the journal is persistent. If they
+disagree, prefer the journal. Write for multi-agent compatibility: no
+assumed shared memory, no reliance on prior conversation context —
+everything needed to resume exists inside the journal.
+
+## Rule 11 — Link the Journal Into the Web
+
+> **Erratum (2026-10-02, configurable memory):** Resolve the memory entry
+> point in AGENTS.md §5. The node and ledger instructions below apply to
+> the bundled web. For another provider, record the journal reference in
+> its appropriate repository area, following that provider's conventions.
+> When the provider is private or read-only, use the configured shared
+> handoff location for successor discovery. The journal remains the task's
+> detailed evidence record; a second memory module is not required.
+
+When the investigation touches an area with a memory node
+(`policies/memory.md`), append a link to the journal in that node's link
+table or ledger. The web is how a future agent *finds* the journal; a
+journal only the writing agent knows about has failed half its purpose.

package/suite/policies/reserved/failure-and-recovery.md

@@ -0,0 +1,6 @@
+# Failure And Recovery Policy
+
+Reserved scope (AGENTS.md §4). No rules exist here yet: proceed on
+general judgment and AGENTS.md. When a lesson emerges in this scope,
+codify it here — dated, with the incident that produced it — per the
+accumulation loop (AGENTS.md §3).

package/suite/policies/reserved/migration.md

@@ -0,0 +1,6 @@
+# Migration Policy
+
+Reserved scope (AGENTS.md §4). No rules exist here yet: proceed on
+general judgment and AGENTS.md. When a lesson emerges in this scope,
+codify it here — dated, with the incident that produced it — per the
+accumulation loop (AGENTS.md §3).

package/suite/policies/reserved/planning.md

@@ -0,0 +1,6 @@
+# Planning Policy
+
+Reserved scope (AGENTS.md §4). No rules exist here yet: proceed on
+general judgment and AGENTS.md. When a lesson emerges in this scope,
+codify it here — dated, with the incident that produced it — per the
+accumulation loop (AGENTS.md §3).

package/suite/policies/reserved/review.md

@@ -0,0 +1,6 @@
+# Review Policy
+
+Reserved scope (AGENTS.md §4). No rules exist here yet: proceed on
+general judgment and AGENTS.md. When a lesson emerges in this scope,
+codify it here — dated, with the incident that produced it — per the
+accumulation loop (AGENTS.md §3).

package/suite/policies/reserved/test-authoring.md

@@ -0,0 +1,6 @@
+# Test Authoring Policy
+
+Reserved scope (AGENTS.md §4). No rules exist here yet: proceed on
+general judgment and AGENTS.md. When a lesson emerges in this scope,
+codify it here — dated, with the incident that produced it — per the
+accumulation loop (AGENTS.md §3).

package/suite/policies/security.md

@@ -0,0 +1,85 @@
+# Security Policy
+
+Scoped agent-governance procedure (AGENTS.md §1/§2). Load for
+security-relevant work: anything creating a new execution or network
+surface, dependency changes (with `policies/tooling.md`), supply-chain
+features, or audit/review passes.
+
+## Rule 1 — When a Security Review Is Mandatory
+
+- A change introduces a **new execution surface** (anything that
+  downloads, installs, or runs third-party code) or a **new network
+  surface**.
+- A privileged command or IPC boundary touches filesystem, process
+  spawn, or network.
+- Dependencies are added or materially upgraded. (A tooling fast-path
+  addition's recorded condition check satisfies this —
+  `policies/tooling.md` §4.1; everything else takes the full review.)
+- A release or visibility milestone approaches (public flip, external
+  beta).
+- External intel lands — a post-mortem, advisory, or incident relevant
+  to a surface this project has.
+- Periodically, and after any major arc touching the above.
+
+## Rule 2 — Method
+
+- **Classify before designing.** Any "should the project download/run
+  Z?" question starts with the class: (1) **verified artifact** — pin
+  version + hash, verify before use, official distributors only;
+  (2) **reference data** — cache, size-cap, treat as inert;
+  (3) **project-owned execution** — never run it hidden; visible
+  execution is the consent and the audit trail; (4) **system-owned
+  toolchains** — detect and hint, never install.
+- **Primary sources, adversarially verified.** The research policy
+  applies to all security investigation; claims that shape design get
+  verified against primary sources before they're load-bearing.
+- **Standing trust rules:** no silent downloads, ever; pinned exact
+  versions over `latest`; freshness risk gets an age gate; provenance is
+  not a safety signal by itself — valid provenance has appeared on
+  compromised packages.
+- **Name the residual risk in the same breath as the mitigation.** Every
+  posture statement lists what is NOT covered. User-facing safety claims
+  are conservative and, where possible, test-enforced.
+
+## Rule 3 — Deliverables
+
+- **A living audit** is the home of observed security state: dated
+  review ledger ("Last reviewed"), explicit scope line, checklist form,
+  dependency scan results with commit refs, verified strengths, and
+  blocked-upstream items carrying their reason and what unblocks them. A
+  review pass appends a dated entry and refreshed scans — never rewrites
+  history.
+- **Scoped deep-dives** cover one surface each. If a premise dies, the
+  document is parked with a dated banner explaining why and what a
+  revival must re-scope — never silently deleted.
+- **Security decisions that change behavior are ADRs**, not audit
+  entries. The audit records observed state; the ADR records the
+  decision. Cross-link both ways.
+- Findings mid-arc that don't block the arc get journaled and surfaced
+  to the owner with severity honestly stated — flagged where found,
+  fixed before the surface goes live.
+
+## Rule 4 — Chokepoint Exceptions Inherit Every Exemption
+
+When a policy is enforced at a central chokepoint (a write manager, a
+gateway, a validation layer), every ratified exception or bypass of that
+chokepoint silently inherits an exemption from **every rule the
+chokepoint carries — including rules added later.** Therefore:
+
+- **Exceptions live in a register at the chokepoint.** An exception that
+  isn't listed is a bug, not an exception.
+- **Adding a rule to the chokepoint re-triggers an audit of the
+  register.** Each exception either re-applies the new rule locally
+  (documented at its site) or is explicitly recorded as deliberately
+  exempt, with the reason.
+- **Sweep for effect-equivalent paths, not just registered exceptions.**
+  Ask: what user action produces this same effect through different
+  code? (A rename produces a creation; a save-as produces a creation.)
+  The loophole class hides in flows that don't share the guarded verb's
+  name.
+- **Refusals must be visible.** A chokepoint that blocks silently reads
+  as a bug upstream, trains users to route around it, and hides the
+  loophole class from live verification. Every refusal surfaces at
+  whichever layer can show it. Ordering interacts with refusal:
+  `policies/implementation.md` Rule 7 — a chokepoint that can refuse
+  makes any state-first flow a drift trap.

package/suite/policies/tooling.md

@@ -0,0 +1,153 @@
+# Tooling Policy
+
+Scoped agent-governance procedure (AGENTS.md §1/§2). Load at repository
+birth, and afterward for any dependency addition, upgrade, replacement,
+framework adoption, or language question. This policy owns the former
+standalone dependency-change scope.
+
+Tooling has two arms: **bootstrap** (the repo is being born) and
+**steady state** (the stack evolves). Both arms end in the same place —
+the tooling register.
+
+## 1. Bootstrap — the research arm at repo birth
+
+The user wants to make a thing. The path from that want to a stack:
+
+1. **PRD first.** Take the owner's PRD if one exists; if not, create one
+   with the owner before any tooling research
+   (`policies/documentation.md` for the document kind). The PRD is the
+   constraint set — platforms, performance envelope, team shape,
+   licensing posture, longevity expectations. Tooling serves the PRD,
+   never the reverse.
+2. **Load `policies/research.md`.** Journal-first: tooling selection is an
+   investigation and follows every research rule.
+3. **Enumerate candidates** for each layer the PRD implies: language(s),
+   framework(s), runtime dependencies, build tooling, test tooling.
+4. **Evaluate each candidate against the criteria in §3.** Primary
+   sources — repos, changelogs, advisories, license texts — not model
+   memory. Claims that will shape the stack get verified before they are
+   load-bearing.
+5. **Build the tooling proposal and give it to the user:** per layer, the
+   candidates considered, tradeoffs stated honestly, a recommendation
+   with its reasoning, and every license named. The owner decides; the
+   agent recommends.
+6. **The owner's decisions birth the tooling register** (§2). Rejected
+   candidates stay in the proposal with the reason — a future "should we
+   switch to X?" starts by reading why X lost the first time.
+
+## 2. The Tooling Register
+
+`docs/TOOLING.md` — the living, authoritative record of what this project
+builds with and why. All future stack questions reference it first.
+
+- **The first entry is the license allowlist** *(adopt-time slot — the
+  owner declares it: e.g. permissive-only such as MIT/Apache-2.0, or a
+  broader compatibility rule)*, together with the exception procedure
+  (§4).
+- Every subsequent entry records: item, role in the stack, version and
+  pinning policy, license, decision date, and a link to the rationale
+  (proposal, journal, or ADR).
+- The register follows amendment discipline
+  (`policies/documentation.md`): dated addenda, struck-and-stamped
+  supersessions, never silent rewrites. A register you can read
+  chronologically is a register you can trust.
+
+## 3. Selection Criteria
+
+Weigh every candidate — bootstrap or steady state — on:
+
+- **License** against the allowlist. A disqualifying license ends the
+  evaluation unless the exception procedure is invoked.
+- **Maintenance health** — release cadence, issue responsiveness, bus
+  factor, governance. A brilliant abandoned library is a future
+  migration.
+- **Security posture** — advisory history, supply-chain surface,
+  install-time behavior. Standing trust rules apply
+  (`policies/security.md`): no silent downloads, pinned exact versions
+  over `latest`, provenance is not by itself a safety signal.
+- **Fit with the existing stack** — steady state only. The register says
+  what already exists; a candidate that duplicates a capability already
+  on the register needs a reason beyond preference.
+- **Cost** — size, build-time impact, cognitive complexity, transitive
+  dependency load.
+- **Exit cost** — how hard is it to leave? Prefer candidates whose
+  boundaries the project can wrap.
+
+## 4. Steady State
+
+Any future need — new dependency, major upgrade, replacement, new
+framework or language — follows one loop:
+
+1. **Register first.** Read what exists and why before proposing what's
+   new. Weigh the initial tooling decisions; they are precedent, not
+   scripture.
+2. **Evaluate options** per §3, research-policy discipline for anything
+   nontrivial.
+3. **Present options and tradeoffs to the owner** — including "do
+   nothing" and "build it" where they are real options. Help the owner
+   weigh options and practices; do not pre-decide by presenting one
+   candidate.
+4. **Owner decides; register updated in the same unit of work** as the
+   change itself. A dependency in the lockfile that the register doesn't
+   explain is a defect.
+
+**When no allowlist-compliant option exists,** the options are, in order
+of preference: build the needed piece, vendor or wrap a compliant
+alternative, or the owner grants an exception — dated, reasoned, and
+recorded in the register. Exceptions are owner decisions only; an agent
+never self-grants one.
+
+### 4.1 Fast Path — Trivial Dev-Only Additions
+
+The full loop is the default, not a tax on every test matcher. An
+addition may take the fast path when **all** of the following hold:
+
+- **License is on the allowlist** — no exception needed.
+- **Dev-time only** — build, test, lint, or type tooling that ships in
+  no production artifact.
+- **No new execution or network surface** — in particular, no
+  install-time script execution. Check the package's install hooks: a
+  dependency that runs code at install time is an execution surface and
+  exits the fast path regardless of how trivial it looks.
+- **Pinned exact version.**
+
+Fast path procedure: the agent adds the dependency and its register
+entry in the same unit of work, the entry marked `fast path` and
+recording the condition check. That recorded check stands as the
+security review for the addition (`policies/security.md` Rule 1), and
+the owner's PR review is the decision — no separate proposal round.
+
+Any condition unclear or failing → the full loop, and
+`policies/security.md` loads. When in doubt, the doubt is the answer:
+full loop.
+
+## 5. Research Standards
+
+Tooling claims decay fast. Verify against primary sources at decision
+time — repository activity, changelogs, advisory databases, the actual
+license file in the actual repo — and record in the journal *how* each
+load-bearing claim was verified. "Widely used" and "well maintained" are
+hypotheses until checked.
+
+## 6. Brownfield Adoption
+
+An existing project adopting this suite does not audit its way to a
+complete register on day one — a mature repository's transitive
+dependency census is a project in itself, and most of the output would be
+dead information.
+
+- **Seed the register with the load-bearing decisions only:** the
+  license allowlist, the language(s), framework(s), build and test
+  tooling, and the top-level runtime dependencies a real stack question
+  would reference. Each entry is stamped
+  `recorded from existing state, <date>` in place of a decision
+  rationale — an honest "this predates the register" beats a
+  reconstructed justification.
+- **Everything else registers by contact.** When steady-state work (§4)
+  touches a dependency not yet on the register, it is added then, with
+  whatever rationale is recoverable — or
+  `pre-register, rationale unrecorded`.
+- The register reaches completeness through work, not census. §4's "a
+  dependency the register doesn't explain is a defect" applies **after**
+  an area has been worked under this suite; before contact, it is merely
+  not registered yet.

package/suite/policies/verification.md

@@ -0,0 +1,60 @@
+# Verification Policy
+
+Scoped agent-governance procedure (AGENTS.md §1/§2). Load when preparing
+any PR, completing a milestone or slice, or changing an API or
+architecture boundary.
+
+## Rule 1 — The Standard Check Suite
+
+*(Adopt-time slot.)* The project enumerates its actual check commands
+here — this list, not an agent's recollection of it, is what "run the
+checks" means. The suite should cover, where the stack supports each:
+
+- **Structural enforcement** — architecture/boundary guards, import
+  rules, contract checks, whatever enforcement code exists.
+- **The full test suite** — and this policy names where the tests live,
+  so "all tests pass" is a verifiable claim, not a vibe.
+- **A production build** — dev servers hide build-only failures.
+- **Zero-warning compilation** where the toolchain distinguishes
+  warnings — warnings are the floor (`policies/implementation.md`
+  Rule 5).
+
+```
+# Fill in on adoption, e.g.:
+# node scripts/memory-lint.mjs   — memory web form (ships with the suite)
+# node scripts/provider-memory.mjs check <memory-dir>   — provider memory hub (ships with the suite)
+# node scripts/agents-md-budget.mjs   — AGENTS.md chain under 30 KiB (ships with the suite)
+# npm run check        — guards + build
+# npm run test         — full suite
+# cargo build && cargo test   — zero warnings required
+```
+
+## Rule 2 — When to Run
+
+Run the suite whenever any of the following is true: a milestone or
+refactor slice is completed; a new module/domain is added; any change
+affects an existing API, command, selector, or behavior; any
+architecture boundary or import rule changes; any PR is being prepared.
+
+Record pass/fail evidence in the related plan or checklist doc when one
+exists.
+
+## Rule 3 — Verify the Commit, Not Just the Tree
+
+After committing, read the commit summary and check the files-changed
+count against intent **before pushing**. Two silent failure modes this
+catches in seconds:
+
+- A pathspec commit (`git commit -m "..." <path>`) commits ONLY that
+  pathspec and silently drops the rest of the staged index.
+- A commit made on the wrong branch lands there silently.
+
+Read the summary line; run `git status`; every time.
+
+## Rule 4 — Verification Is Evidence, Not Ceremony
+
+A check that was run but whose output wasn't read verifies nothing. When
+a check fails, the failure is investigated under
+`policies/research.md` discipline if nontrivial — never rerun-until-
+green, never skipped with intent to fix later unless the owner has
+explicitly accepted that debt, dated, in the relevant plan.

package/suite/scripts/agents-md-budget.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// agents-md-budget.mjs — keeps the AGENTS.md chain inside what Codex reads
+// (AGENTS.md §3 and §5, provider memory table).
+//
+// Codex reads at most one instruction file per directory, AGENTS.override.md
+// before AGENTS.md, skipping empty files, from the project root down to its
+// working directory, and stops adding files once the combined size reaches
+// project_doc_max_bytes (32 KiB by default). Guidance past that point is
+// never read. This guard measures every root-to-directory chain in the
+// repository against a 30 KiB budget, which leaves room for a global
+// ~/.codex/AGENTS.md:
+//
+//   E1  a chain of instruction files over budget
+//
+// A directory holding its own .git (a worktree or submodule) is a separate
+// project root with its own chain, so the walk does not enter it. Fallback
+// filenames configured in Codex (project_doc_fallback_filenames) are not
+// covered.
+//
+// Zero dependencies. Usage:
+//   node scripts/agents-md-budget.mjs [repo-root] [--max <bytes>]
+// Exit 1 when any chain is over budget.
+// The checks are the policy; the implementation is fungible.
+
+import { readdirSync, statSync, existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+const args = process.argv.slice(2);
+const maxAt = args.indexOf('--max');
+const MAX = maxAt >= 0 ? Number(args[maxAt + 1]) : 30 * 1024;
+const ROOT = args.find((a, i) => !a.startsWith('--') && (maxAt < 0 || i !== maxAt + 1)) ?? '.';
+const SKIP = new Set(['.git', 'node_modules']);
+
+function instructionFile(dir) {
+  for (const name of ['AGENTS.override.md', 'AGENTS.md']) {
+    const p = join(dir, name);
+    if (existsSync(p) && statSync(p).isFile() && statSync(p).size > 0) {
+      return { path: relative(ROOT, p).replace(/\\/g, '/'), size: statSync(p).size };
+    }
+  }
+  return null;
+}
+
+const chains = [];
+function walk(dir, chain) {
+  const file = instructionFile(dir);
+  const here = file ? [...chain, file] : chain;
+  if (file) chains.push(here);
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || SKIP.has(entry.name)) continue;
+    const sub = join(dir, entry.name);
+    if (existsSync(join(sub, '.git'))) continue;
+    walk(sub, here);
+  }
+}
+walk(ROOT, []);
+
+if (chains.length === 0) {
+  console.log('agents-md-budget: no AGENTS.md found — nothing to check.');
+  process.exit(0);
+}
+
+const total = (chain) => chain.reduce((sum, f) => sum + f.size, 0);
+const over = chains.filter((c) => total(c) > MAX);
+for (const chain of over) {
+  console.error(`ERROR E1  ${chain.at(-1).path} — chain is ${total(chain)} bytes, over the ${MAX}-byte budget: ` +
+    chain.map((f) => `${f.path} (${f.size})`).join(' + '));
+}
+const largest = chains.reduce((a, b) => (total(b) > total(a) ? b : a));
+console.log(`agents-md-budget: largest chain ${total(largest)} / ${MAX} bytes (${largest.at(-1).path}); ${over.length} over budget`);
+process.exit(over.length > 0 ? 1 : 0);