@event4u/agent-config 2.19.0 → 2.20.1

package/.agent-src/packs/founder-mvp.yml

@@ -0,0 +1,51 @@
+# Seed pack — founder-mvp
+# Schema: docs/contracts/workflow-packs.md
+pack:
+  id: founder-mvp
+  audience:
+    label: "Solo / early-stage founder shipping the MVP and the pitch deck"
+    one_liner: "Ship the MVP and the pitch deck in the same week."
+  composition:
+    profile_id: founder
+    preset_id: fast
+  surface:
+    commands_allowed:
+      - work
+      - feature
+      - challenge-me
+      - council
+      - refine-prompt
+      - commit
+      - create-pr
+    skills_allowed:
+      - refine-prompt
+      - rice-prioritization
+      - vision-articulation
+      - fundraising-narrative
+      - runway-cognition
+      - customer-research
+      - po-discovery
+      - decision-record
+      - minimal-safe-diff
+      - verify-completion-evidence
+    personas:
+      - product-strategist
+      - reviewer
+      - founder-finance
+  rationale:
+    why_this_profile: |
+      Founder profile centres the work loop on framing, prioritization,
+      and narrative — the three artefacts a solo founder produces every
+      week. Engineering skills are not dropped; they are surfaced one
+      level below, accessible via /work but not on the first screen.
+    why_this_preset: |
+      Fast preset trades evidence-floor strictness for momentum. Confidence
+      band lowered to "low"; trivial-question suppression on. Block-on
+      list keeps security and prod-data hard floors intact — the speed
+      gain is in clarifying questions, not in safety.
+    why_these_commands: |
+      /work and /feature drive the build loop; /challenge-me grills the
+      idea before a week is sunk into it; /council polls external models
+      when the founder is the smartest person in their own head. /commit
+      and /create-pr close the loop without ceremony — most founders
+      ship solo and the PR-as-checkpoint is the only review they get.

package/.agent-src/presets/README.md

@@ -0,0 +1,26 @@
+# Presets
+
+Seed presets for the [preset system](../../docs/contracts/config-presets.md).
+Each preset bundles governance knobs (autonomy / confidence / risk /
+council / mcp / cost / notifications) so the user picks a stance, not
+a dozen individual values. Boundary against `profile.id`, `pack.id`,
+and `cost_profile` lives in
+[ADR-010](../../docs/decisions/ADR-010-profile-pack-preset-boundary.md).
+
+## Seed set (v2.x — fixed)
+
+| `preset.id` | Stance | Typical user |
+|---|---|---|
+| `fast` | Lowest friction, widest autonomy | Solo founder, prototype, exploration |
+| `balanced` *(default)* | Moderate friction, per-task autonomy | Day-to-day work |
+| `strict` | Highest friction, ask-by-default | Production paths, regulated work, shared trunks |
+
+Adding a fourth seed preset requires an ADR. User-defined project-local
+presets (any `<id>.yml` not in the seed list above) are allowed without
+an ADR but MUST match the schema enforced by `task lint-config-schema`.
+
+## See also
+
+- [`docs/contracts/config-presets.md`](../../docs/contracts/config-presets.md) — schema, cost enforcement, resolution chain.
+- [`docs/contracts/profile-system.md`](../../docs/contracts/profile-system.md) — profile axis.
+- [`scripts/config/presets.py`](../../scripts/config/presets.py) — loader.

package/.agent-src/presets/balanced.yml

@@ -0,0 +1,34 @@
+# Seed preset — balanced (default)
+# Schema: docs/contracts/config-presets.md
+preset:
+  id: balanced
+  autonomy:
+    default: auto
+    trivial_suppress: true
+  confidence:
+    min_band: medium
+    require_evidence: false
+  risk:
+    block_on:
+      - security
+      - prod_data
+    ask_on:
+      - bulk_delete
+      - schema_change
+  council:
+    auto_consult: false
+    cap_per_consult_usd: 0.50
+  mcp:
+    per_call_max_usd: 0.10
+    per_session_max_usd: 2.00
+  cost:
+    daily_max_usd: 10.00
+    weekly_max_usd: 50.00
+    monthly_max_usd: 150.00
+    enforce: hybrid
+  notifications:
+    threshold_pct:
+      - 50
+      - 75
+      - 90
+      - 100

package/.agent-src/presets/fast.yml

@@ -0,0 +1,31 @@
+# Seed preset — fast
+# Schema: docs/contracts/config-presets.md
+preset:
+  id: fast
+  autonomy:
+    default: on
+    trivial_suppress: true
+  confidence:
+    min_band: low
+    require_evidence: false
+  risk:
+    block_on:
+      - security
+      - prod_data
+    ask_on:
+      - bulk_delete
+  council:
+    auto_consult: false
+    cap_per_consult_usd: 0.25
+  mcp:
+    per_call_max_usd: 0.25
+    per_session_max_usd: 5.00
+  cost:
+    daily_max_usd: 25.00
+    weekly_max_usd: 100.00
+    monthly_max_usd: 300.00
+    enforce: hybrid
+  notifications:
+    threshold_pct:
+      - 75
+      - 100

package/.agent-src/presets/strict.yml

@@ -0,0 +1,38 @@
+# Seed preset — strict
+# Schema: docs/contracts/config-presets.md
+preset:
+  id: strict
+  autonomy:
+    default: off
+    trivial_suppress: false
+  confidence:
+    min_band: high
+    require_evidence: true
+  risk:
+    block_on:
+      - security
+      - prod_data
+      - bulk_delete
+      - schema_change
+      - financial_paths
+    ask_on:
+      - code_paths
+      - infra_change
+  council:
+    auto_consult: true
+    cap_per_consult_usd: 1.00
+  mcp:
+    per_call_max_usd: 0.05
+    per_session_max_usd: 1.00
+  cost:
+    daily_max_usd: 5.00
+    weekly_max_usd: 20.00
+    monthly_max_usd: 60.00
+    enforce: hybrid
+  notifications:
+    threshold_pct:
+      - 25
+      - 50
+      - 75
+      - 90
+      - 100

package/.agent-src/profiles/README.md

@@ -0,0 +1,29 @@
+# Profiles
+
+Seed profiles for the [profile system](../../docs/contracts/profile-system.md).
+Each profile answers *who is the user?* — audience identity that
+selects the default skill/command surface, README entry-paragraph,
+and persona pre-selection. Boundary against `preset.id`, `pack.id`,
+and `cost_profile` lives in
+[ADR-010](../../docs/decisions/ADR-010-profile-pack-preset-boundary.md).
+
+## Seed set (v2.x — fixed)
+
+| `profile.id` | Audience | Default preset |
+|---|---|---|
+| `founder` | Solo / early-stage founder | `fast` |
+| `developer` | IC engineer | `balanced` |
+| `content_creator` | Writers, ghostwriters, marketers | `balanced` |
+| `agency` | Multi-client delivery shop | `strict` |
+| `finance` | CFO / fractional finance / FP&A | `strict` |
+| `ops` | RevOps, support, SRE-adjacent | `strict` |
+
+Adding a seventh seed profile requires an ADR. User-defined project-local
+profiles (any `<id>.yml` not in the seed list above) are allowed without
+an ADR but MUST match the schema enforced by `task lint-config-schema`.
+
+## See also
+
+- [`docs/contracts/profile-system.md`](../../docs/contracts/profile-system.md) — schema and loader contract.
+- [`docs/contracts/config-presets.md`](../../docs/contracts/config-presets.md) — preset axis.
+- [`scripts/config/profiles.py`](../../scripts/config/profiles.py) — loader.

package/.agent-src/profiles/agency.yml

@@ -0,0 +1,27 @@
+# Seed profile — agency
+# Schema: docs/contracts/profile-system.md
+profile:
+  id: agency
+  audience:
+    label: "Multi-client delivery shop"
+    readme_anchor: "agency"
+  defaults:
+    preset_id: strict
+    personas:
+      - reviewer
+      - product-strategist
+      - editor
+    skills_hint:
+      - doc-coauthoring
+      - decision-record
+      - refine-ticket
+      - estimate-ticket
+      - perf-feedback-craft
+  surface:
+    commands_hint:
+      - work
+      - implement-ticket
+      - refine-ticket
+      - feature
+      - roadmap
+    docs_first_pointer: "docs/getting-started-by-role.md#agency"

package/.agent-src/profiles/content_creator.yml

@@ -0,0 +1,25 @@
+# Seed profile — content_creator
+# Schema: docs/contracts/profile-system.md
+profile:
+  id: content_creator
+  audience:
+    label: "Writers, ghostwriters, marketers"
+    readme_anchor: "content_creator"
+  defaults:
+    preset_id: balanced
+    personas:
+      - editor
+      - brand-voice
+    skills_hint:
+      - voice-and-tone-design
+      - messaging-architecture
+      - editorial-calendar
+      - release-comms
+      - prompt-engineering-patterns
+  surface:
+    commands_hint:
+      - work
+      - post-as
+      - ghostwriter
+      - optimize-prompt
+    docs_first_pointer: "docs/getting-started-by-role.md#content_creator"

package/.agent-src/profiles/developer.yml

@@ -0,0 +1,26 @@
+# Seed profile — developer
+# Schema: docs/contracts/profile-system.md
+profile:
+  id: developer
+  audience:
+    label: "IC engineer"
+    readme_anchor: "developer"
+  defaults:
+    preset_id: balanced
+    personas:
+      - reviewer
+      - security
+    skills_hint:
+      - developer-like-execution
+      - verify-completion-evidence
+      - minimal-safe-diff
+      - systematic-debugging
+      - test-driven-development
+  surface:
+    commands_hint:
+      - work
+      - implement-ticket
+      - review-changes
+      - fix
+      - commit
+    docs_first_pointer: "docs/getting-started-by-role.md#developer"

package/.agent-src/profiles/finance.yml

@@ -0,0 +1,24 @@
+# Seed profile — finance
+# Schema: docs/contracts/profile-system.md
+profile:
+  id: finance
+  audience:
+    label: "CFO / fractional finance / FP&A"
+    readme_anchor: "finance"
+  defaults:
+    preset_id: strict
+    personas:
+      - finance-partner
+      - reviewer
+    skills_hint:
+      - dcf-modeling
+      - forecasting
+      - scenario-modeling
+      - unit-economics-modeling
+      - runway-cognition
+  surface:
+    commands_hint:
+      - work
+      - council
+      - challenge-me
+    docs_first_pointer: "docs/getting-started-by-role.md#finance"

package/.agent-src/profiles/founder.yml

@@ -0,0 +1,25 @@
+# Seed profile — founder
+# Schema: docs/contracts/profile-system.md
+profile:
+  id: founder
+  audience:
+    label: "Solo / early-stage founder"
+    readme_anchor: "founder"
+  defaults:
+    preset_id: fast
+    personas:
+      - product-strategist
+      - reviewer
+    skills_hint:
+      - refine-prompt
+      - rice-prioritization
+      - vision-articulation
+      - fundraising-narrative
+      - runway-cognition
+  surface:
+    commands_hint:
+      - work
+      - feature
+      - challenge-me
+      - council
+    docs_first_pointer: "docs/getting-started-by-role.md#founder"

package/.agent-src/profiles/ops.yml

@@ -0,0 +1,25 @@
+# Seed profile — ops
+# Schema: docs/contracts/profile-system.md
+profile:
+  id: ops
+  audience:
+    label: "RevOps, support, SRE-adjacent"
+    readme_anchor: "ops"
+  defaults:
+    preset_id: strict
+    personas:
+      - reviewer
+      - security
+    skills_hint:
+      - incident-commander
+      - dashboard-design
+      - logging-monitoring
+      - threat-modeling
+      - launch-readiness
+  surface:
+    commands_hint:
+      - work
+      - threat-model
+      - review-changes
+      - fix
+    docs_first_pointer: "docs/getting-started-by-role.md#ops"

package/.agent-src/rules/no-cheap-questions.md

@@ -8,7 +8,7 @@ source: package
 
 # No Cheap Questions
 
-A question is **cheap** when context already answers, an option breaches an Iron Law, choices differ only in sequencing / format, or one option is dominant. Mode-independent — `off`, `auto`, `on`. Autonomy never lifts the floor.
+A question is **cheap** when context already answers it, an option breaches an Iron Law, choices differ only in sequencing / format, or one option is dominant. Mode-independent. Autonomy never lifts the floor.
 
 ## The Iron Laws
 
@@ -18,9 +18,20 @@ NEVER PRESENT AN OPTION THAT VIOLATES AN IRON LAW.
 NEVER OFFER NUMBERED CHOICES WITHOUT A REAL TRADE-OFF.
 ```
 
-## What counts as cheap
+## Cheap classes
 
-Ten classes — sequencing · format-only · commit asks · CI / test asks · fenced-step re-asks · Iron-Law option · context-derived · dominant option · re-ask after decline · **paternalistic state-assuming option** (Iron Law 3 below). Per-class detail + governing rule: [`asking-and-brevity-examples § cheap-question-catalog`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md#cheap-question-class-catalog--extended-examples).
+Sequencing · format-only · commit asks · CI / test asks · fenced re-ask · Iron-Law option · context-derived · dominant option · re-ask after decline · paternalistic (Iron Law 3) · continuation under mandate (Iron Law 4). Catalog: [`asking-and-brevity-examples`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md#cheap-question-class-catalog--extended-examples).
+
+## Iron Law 4 — No Continuation Prompts Under Autonomous Mandate
+
+```
+WHEN A STANDING AUTONOMOUS MANDATE IS ACTIVE — /roadmap:process-full,
+/roadmap:process-phase, EXPLICIT "ENTSCHEIDE SELBST / DECIDE AND DON'T
+ASK" — NEVER ASK "WEITER? / NEXT STEP? / SHALL I CONTINUE?".
+A CLEAN EDIT-BATCH IS NOT A HALT CONDITION. THE ONLY HALTS ARE THE
+FIVE NAMED IN THE INVOKING COMMAND (HARD-FLOOR, COUNCIL-OFF +
+AMBIGUITY, SECURITY-SENSITIVE, SCOPE-OUT-OF-ROADMAP, TEST/QUALITY RED).
+```
 
 ## Iron Law 3 — No Paternalistic State-Assuming Options
 
@@ -30,30 +41,27 @@ NEVER FABRICATE USER STATE TO JUSTIFY AN OPTION.
 THE USER DECIDES WHEN TO STOP. THE AGENT DECIDES WHAT TO BUILD NEXT.
 ```
 
-Every numbered option = technical / scope / sequencing choice with real trade-off, not mood-management nudge. Forbidden patterns + carve-outs: [`asking-and-brevity-examples § iron-law-3`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md#no-cheap-questions--iron-law-3-detail-paternalistic-state-options).
-
 ## Pre-Send Self-Check — MANDATORY before every question
 
-Run silently before any numbered-options block:
+Silent, before any numbered-options block:
 
 1. Answer already in stated context?
-2. Any option violates `commit-policy`, `scope-control § git-ops`, or `non-destructive-by-default`?
-3. Options pure sequencing / format, no trade-off?
+2. Option violates `commit-policy`, `scope-control § git-ops`, or `non-destructive-by-default`?
+3. Pure sequencing / format, no trade-off?
 4. One option obviously dominant?
-5. User fenced next step (*"plan only"*, *"review first"*) → deliver + handback per `scope-control § fenced step`.
-6. User already declined? Re-ask forbidden per `scope-control § decline = silence`.
-7. Any option assumes user fatigue / frustration / "had enough" without in-message citation? Iron Law 3 — drop it.
+5. User fenced step (*"plan only"*, *"review first"*) → deliver + handback.
+6. User already declined? Re-ask forbidden.
+7. Option assumes user fatigue / frustration without in-message citation? Iron Law 3 — drop.
+8. Standing autonomous mandate + "weiter? / continue?" — Iron Law 4, drop; pick next item.
 
-Any "yes" → **do not ask**. Pick the dominant path, state assumption inline (*"assuming X — adjust if wrong"*), hand back. One-question-per-turn from [`ask-when-uncertain`](ask-when-uncertain.md) still applies when the question is genuine.
+Any "yes" → don't ask. Pick dominant path, state inline assumption, hand back. Genuine ambiguity → [`ask-when-uncertain`](ask-when-uncertain.md).
 
 ## When asking IS allowed
 
 - Real architectural / scope decision with non-obvious trade-offs.
-- Vague-request trigger per [`ask-when-uncertain § vague-triggers`](ask-when-uncertain.md#vague-request-triggers--must-ask).
-- Security-sensitive path per [`security-sensitive-stop`](security-sensitive-stop.md).
-- Hard Floor per [`non-destructive-by-default`](non-destructive-by-default.md) — confirmation mandatory.
+- Vague-request trigger ([`ask-when-uncertain`](ask-when-uncertain.md)).
+- Security-sensitive ([`security-sensitive-stop`](security-sensitive-stop.md)).
+- Hard Floor ([`non-destructive-by-default`](non-destructive-by-default.md)).
 - Two genuinely-equivalent paths; user preference is the tiebreaker.
 
 In doubt → ask. This rule narrows asking, never widens silence.
-
-Cross-rule index: [`frugality-charter § cross-references`](../contexts/contracts/frugality-charter.md#cross-references--frugality-canon-rules).

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

@@ -44,42 +44,63 @@ Do NOT use when:
 
 ## Preconditions
 
-- An ADR directory exists (default `docs/adr/`; `docs/decisions/` is
-  the recognised alias used in this package and many older projects).
-- The decision is **already made** — ADRs record outcomes, they do
-  not run the decision process. For unresolved trade-offs, run the
-  council or consult `adversarial-review` first.
+- ADR directory exists. Two layouts coexist (see
+  [`docs/contracts/adr-layout.md`](../../../docs/contracts/adr-layout.md)):
+  - **Flat** — `docs/decisions/` (or `docs/adr/` alias): cross-cutting
+    governance ADRs, 3-digit numbering (`ADR-NNN-<slug>.md`).
+  - **Per-area** — `docs/adrs/<area>/`: sub-area ADRs, 4-digit
+    numbering (`NNNN-<slug>.md`); `<area>` must match canonical
+    inventory in [`scripts/audit_adr_coverage.py`](../../../scripts/audit_adr_coverage.py).
+- Decision **already made** — ADRs record outcomes, not run the
+  decision process. For unresolved trade-offs, run council or
+  consult `adversarial-review` first.
 
 ## Procedure
 
-### 1. Inspect and resolve the ADR directory
+### 1. Inspect and pick the surface
 
-Identify the canonical directory in this order:
+Ask one question only if both are plausible:
 
-1. `docs/adr/` — default per spec.
-2. `docs/decisions/` — accepted alias if `docs/adr/` is missing.
-3. Anything else — fail, ask the user to pick one of the two
-   canonical paths. Do not invent a third location.
+1. **Flat surface** — decision constrains package's contract with
+   consumers (kernel composition, rule taxonomy, package-wide
+   architecture). Directory: `docs/decisions/` (fallback
+   `docs/adr/`). Filename: `ADR-NNN-<slug>.md`.
+2. **Per-area surface** — decision constrains code inside one area
+   folder (one runtime module, one contract group, one CLI surface).
+   Directory: `docs/adrs/<area>/`. Filename: `NNNN-<slug>.md`
+   (4-digit, no `ADR-` prefix).
+3. **Unknown area** — `<area>` not in inventory: refuse with hint
+   to add area to `AREAS` in `scripts/audit_adr_coverage.py` in
+   same PR. Do not invent.
+4. **In doubt** → per-area (cheaper to surface, easier to relocate).
 
 ### 2. Pick the next ADR number
 
-Scan the directory for `ADR-*.md`, parse the leading 3-digit number,
-take `max + 1` (zero-padded). For an empty directory, start at `001`.
-Reject re-use of an existing number — the index regenerator treats
-duplicates as a hard failure.
+- **Flat surface** — scan `docs/decisions/` (or `docs/adr/`) for
+  `ADR-*.md`, parse leading 3-digit number, take `max + 1`
+  (zero-padded to 3). Empty directory → start at `001`.
+- **Per-area surface** — scan `docs/adrs/<area>/` for
+  `[0-9][0-9][0-9][0-9]-*.md`, parse leading 4-digit number, take
+  `max + 1` (zero-padded to 4). Empty area → start at `0001`.
+  `README.md` is **not** an ADR — skip it.
+
+Reject re-use of existing number — index regeneration treats
+duplicates as hard failure on both surfaces.
 
 ### 3. Pick a slug
 
 Short, hyphen-lowercase, scope-revealing. Match peer ADRs in the
 directory. Examples: `kernel-swap-deferred`, `flat-cluster-subs`,
-`http-bridge-deferred-with-trigger`. Reject slugs longer than 60 chars.
+`http-bridge-deferred-with-trigger`,
+`per-tier-smoke-scripts`. Reject slugs longer than 60 chars.
 
 ### 4. Author the ADR
 
-Use the standard template (frontmatter + body). All sections are
-required; "n/a" is acceptable for genuinely empty Alternatives or
-References blocks but never for Status, Context, Decision, or
-Consequences.
+Use surface-specific template. All sections required; "—" acceptable
+for genuinely empty Alternatives or References blocks but never for
+Status, Context, Decision, or Consequences.
+
+**Flat-surface template** (`docs/decisions/ADR-NNN-<slug>.md`):
 
 ```markdown
 ---
@@ -98,73 +119,62 @@ phase: <roadmap> · <phase-id>
 
 **<Proposed | Accepted | …>** · YYYY-MM-DD.
 
-## Context
-
-What problem forced this decision? What constraints applied? What
-alternatives were on the table at decision time?
-
-## Decision
-
-The chosen variant, in one paragraph. Concrete enough that a reader
-six months later knows what was actually picked.
-
-## Consequences
-
-### Accepted
-
-- Hard guarantees we now make.
-
-### Trade-offs
-
-- What we gave up. Mitigations, if any.
+## Context / Decision / Consequences / Alternatives / References
+```
 
-## Alternatives considered
+**Per-area template** (`docs/adrs/<area>/NNNN-<slug>.md`):
 
-- **Variant X — <name>.** Rejected because <reason>.
-- **Variant Y — <name>.** Rejected because <reason>.
+```markdown
+# ADR NNNN — <Decision Title>
 
-## References
+> Area: `<area>` · Status: accepted · Date: YYYY-MM-DD · Type: retrospective | new
+> Roadmap: `agents/roadmaps/<file>.md` <phase-id>
+> Supersedes: —
 
-- Linked roadmap, contract, prior ADR, council session id.
+## Context / Decision / Considered alternatives / Consequences / References
 ```
 
-### 5. Regenerate the index
-
-Run the dispatcher:
+Per-area ADRs use quote-style header (no YAML frontmatter) so
+`audit_adr_coverage.py`'s permissive parser can index them. Cite
+the area's contract from the README in
+[`docs/adrs/<area>/README.md`](../../../docs/adrs/).
 
-```bash
-python3 scripts/runtime_dispatcher.py run --skill adr-create
-# or directly:
-python3 scripts/adr/regenerate_index.py --dir docs/adr/
-```
+### 5. Regenerate the index
 
-The script scans `ADR-*.md`, reads frontmatter (`adr`, `status`,
-`date`, `decision`, `supersedes`), and writes `INDEX.md` with one
-table row per ADR plus broken-supersede warnings on stderr.
+- **Flat surface** — `python3 scripts/adr/regenerate_index.py
+  --dir docs/decisions/` writes `INDEX.md` from `ADR-*.md`.
+- **Per-area surface** — `python3 scripts/audit_adr_coverage.py
+  --regen-area-readme <area>` rewrites `docs/adrs/<area>/README.md`.
+  Coverage gate: run `python3 scripts/audit_adr_coverage.py` (no
+  args) — exit 0 only when every canonical area has ≥ 1 ADR.
 
 ### 6. Validate
 
-- `python3 scripts/adr/regenerate_index.py --check` exits 0
-  (index is up to date, no number gaps, no broken supersedes).
-- The project's CI / quality pipeline passes locally.
+- Flat: `python3 scripts/adr/regenerate_index.py --check` exits 0.
+- Per-area: `python3 scripts/audit_adr_coverage.py --check` exits 0.
+- Project's CI / quality pipeline passes locally.
 
 ## Output format
 
-1. Path of the new `ADR-NNN-<slug>.md` file.
-2. Path of the regenerated `INDEX.md`.
+1. Path of the new ADR file.
+2. Path of the regenerated index / README.
 3. One-line summary of the decision.
 4. Linked roadmap or phase, if any.
 
 ## Gotchas
 
-- `docs/adr/` is the default path; some projects use
-  `docs/decisions/` (this package included). Pass `--dir` to the
-  index regenerator when running outside the default.
-- Frontmatter `adr:` is the canonical number; the filename prefix
-  must match. The index regenerator fails on mismatch.
-- ADRs are append-only history. To revise a decision, write a new
-  ADR with `supersedes: ADR-MMM` and flip the old one's status to
-  `superseded`.
+- **Flat default path** is `docs/decisions/` in this package; some
+  projects use `docs/adr/`. Pass `--dir` when running outside default.
+- **Per-area numbering is 4-digit** (`NNNN-<slug>.md`); flat surface
+  stays 3-digit (`ADR-NNN-<slug>.md`). Do not mix.
+- **Area inventory closed** — `<area>` must already exist in `AREAS`
+  in `scripts/audit_adr_coverage.py`. Adding new area is separate
+  PR with explicit reviewer sign-off.
+- Frontmatter `adr:` (flat) is canonical number; filename prefix
+  must match. Flat regenerator fails on mismatch.
+- ADRs are append-only history. To revise, write new ADR with
+  `supersedes: ADR-MMM` (flat) or `Supersedes:` line in header
+  quote-block (per-area) and flip old one's status to `superseded`.
 - Never delete an ADR file — supersede it. Deletion breaks
   historical links and round-trips through git history checks.