@event4u/agent-config 2.19.0 → 2.20.1

package/docs/contracts/cost-dashboard.md

@@ -0,0 +1,143 @@
+---
+stability: beta
+keep-beta-until: 2026-08-12
+---
+
+# Cost governance dashboard
+
+> **Status:** beta — first draft 2026-05-16 (Phase 2 Item 10 of
+> `step-15-product-refinement`).
+>
+> **Related:** [`config-presets`](config-presets.md) (caps schema) ·
+> [`cost-profile-defaults`](cost-profile-defaults.md) (default
+> selection) · `scripts/cost/budget.mjs` (existing local-store
+> primitive) · `scripts/cost/track.mjs` (session ingest).
+
+The `agent-config cost` subcommand surfaces accumulated spend against
+the active preset's caps. Read-only, CLI-first, no UI. Wraps the
+existing `scripts/cost/*.mjs` primitives behind a single discoverable
+verb so a user can ask "where am I against my budget?" without knowing
+the storage layout.
+
+## Surface
+
+```
+agent-config cost                       # default: status (this period's spend)
+agent-config cost status [--json]       # spend vs caps for daily/weekly/monthly
+agent-config cost ingest                # pull latest session.jsonl → local store
+agent-config cost history [--period=today|week|month] [--limit=N]
+agent-config cost reset --confirm       # truncate sessions.jsonl + budget.json
+```
+
+All subcommands are **read-only by default**. `ingest` writes only to
+`agents/cost-tracking/sessions.jsonl`. `reset` is destructive and
+gated by `--confirm` (Hard-Floor per
+[`non-destructive-by-default`](../../.agent-src/rules/non-destructive-by-default.md)).
+
+## `cost status` — output contract
+
+Human format:
+
+```
+Cost (preset: balanced · profile: developer)
+
+Period       Spent      Cap        Remaining   %   Status
+today        $2.43      $10.00     $7.57       24%  ✅
+week         $14.20     $40.00     $25.80      36%  ✅
+month        $52.10     $150.00    $97.90      35%  ✅
+
+MCP calls:     12 today · 47 this week · 188 this month
+Council calls:  1 today ·  3 this week ·  11 this month
+
+Next threshold notification at 75% (week: $30.00).
+```
+
+`--json` output schema:
+
+```json
+{
+  "preset": "balanced",
+  "profile": "developer",
+  "periods": {
+    "today":   {"spent_usd": 2.43,  "cap_usd": 10.00,  "remaining_usd": 7.57,  "pct": 0.243, "status": "ok"},
+    "week":    {"spent_usd": 14.20, "cap_usd": 40.00,  "remaining_usd": 25.80, "pct": 0.355, "status": "ok"},
+    "month":   {"spent_usd": 52.10, "cap_usd": 150.00, "remaining_usd": 97.90, "pct": 0.347, "status": "ok"}
+  },
+  "calls": {
+    "mcp":     {"today": 12, "week": 47, "month": 188},
+    "council": {"today": 1,  "week": 3,  "month": 11}
+  },
+  "next_threshold": {"period": "week", "pct": 0.75, "trigger_usd": 30.00}
+}
+```
+
+### Status field
+
+| Value | Trigger | Exit code |
+|---|---|---|
+| `ok` | `pct < 0.75` | 0 |
+| `warn` | `0.75 ≤ pct < 1.0` | 0 |
+| `over` | `pct ≥ 1.0` | 1 |
+
+Overall exit = worst-of across the three periods. `--json` always
+emits the full object regardless of exit.
+
+## Data sources
+
+| Field | Source |
+|---|---|
+| `preset` | Active preset id from [`config-presets`](config-presets.md) resolution chain. |
+| `cap_usd` | `preset.cost.{daily,weekly,monthly}_max_usd`. |
+| `spent_usd` | Sum of `cost_usd` field over `agents/cost-tracking/sessions.jsonl` records inside the period window. |
+| `calls.mcp.*` | Sum of `mcp_calls` field in the same records. |
+| `calls.council.*` | Count of records whose `kind` is `council`. |
+| `next_threshold` | Smallest `(period, pct ∈ preset.notifications.threshold_pct)` tuple where `spent_usd < pct × cap_usd`. |
+
+When the active preset declares no `cost.*` cap (legacy installs),
+`cap_usd` is reported as `null` and `status` is `ok`. The tool does
+**not** invent a default cap.
+
+## Enforcement vs surfacing
+
+`agent-config cost` is **read-only**. Enforcement (refuse a council
+or MCP call that would push spend over a cap) lives at the call site
+per the active preset's `cost.enforce` setting (`off`, `advisory`,
+`hybrid`, `hard`). This contract does not change enforcement; it only
+makes the existing local-store data discoverable.
+
+## Refresh model
+
+`sessions.jsonl` is appended to by the Claude Code session hooks
+(see `scripts/cost/track.mjs`). `cost status` reads what's there;
+`cost ingest` triggers a one-shot pull from `~/.claude/projects/`.
+Users running a non-Claude-Code agent surface call `cost ingest`
+manually after a session; users on Claude Code with hooks installed
+never need to.
+
+## Validation
+
+`scripts/lint_cost_dashboard.py` (Phase 2 deliverable — not yet
+shipped) fails CI on:
+
+- Schema drift in `sessions.jsonl` (missing required fields).
+- Preset declaring `cost.*` caps that disagree with this contract's
+  expected period grid.
+- `cost status --json` output diverging from the schema above.
+
+## What this contract does **not** do
+
+- **Does not** ship a UI. CLI-first, by design.
+- **Does not** introduce per-skill or per-command cost attribution
+  beyond `kind` (`council` vs other). Per-skill attribution is a
+  Phase 3 candidate.
+- **Does not** override per-call hard caps from the preset.
+- **Does not** roll up across multiple projects. Each project's
+  `agents/cost-tracking/` is its own scope.
+
+## See also
+
+- [`config-presets`](config-presets.md) — preset caps + `enforce` semantics
+- [`cost-profile-defaults`](cost-profile-defaults.md) — default preset selection
+- [`safety-model`](safety-model.md) — `mcp_call_costly` domain
+- `scripts/cost/budget.mjs`, `scripts/cost/track.mjs` — wrapped primitives
+- `step-15-product-refinement` § Phase 2 Item 10

package/docs/contracts/cost-enforcement.md

@@ -0,0 +1,134 @@
+---
+stability: stable
+---
+
+# Cost Enforcement Contract
+
+> Status: stable · Owner: `step-11-measurement-governance-parity` · Last reviewed: 2026-05-16
+
+How USD budgets read from `.agent-settings.yml` interact with the
+session-cost ledger (`agents/cost-tracking/sessions.jsonl`) and the
+budget evaluator (`scripts/cost/budget.mjs`).
+
+## Surface
+
+Two files. Settings file declares the budget; ledger file accumulates
+spend. The evaluator joins them and emits a tier.
+
+| File | Role |
+|---|---|
+| `.agent-settings.yml § cost` | Declarative: budgets per period + enforcement mode. |
+| `agents/cost-tracking/sessions.jsonl` | Append-only: per-session cost records (model, tokens, USD). |
+| `scripts/cost/budget.mjs` | Evaluator: joins both, emits `{ level, utilization_pct, enforcement, source }`. |
+| `scripts/cost/preflight.mjs` | Hard-stop hook: wraps `budget.mjs check` and exits non-zero at HARD_STOP when `enforcement: hard-stop`. |
+
+## Settings schema
+
+```yaml
+cost:
+  budgets:
+    daily: 0     # USD ceiling for rolling 24h. 0 = unbudgeted.
+    weekly: 0    # USD ceiling for rolling 7d.  0 = unbudgeted.
+    monthly: 0   # USD ceiling for rolling 30d. 0 = unbudgeted.
+  enforcement: advisory   # advisory | hard-stop
+```
+
+- `0` (or absent) on any period = that period is not enforced. The
+  evaluator falls back to a longer-period budget when checking shorter
+  periods, never the other way around.
+- `enforcement: advisory` is the default. Dashboards surface the
+  breach; the agent keeps working.
+- `enforcement: hard-stop` is opt-in. `scripts/cost/preflight.mjs`
+  exits non-zero at the HARD_STOP tier; wrapping shells / CI / `task`
+  bindings must check this before composing a turn.
+
+## Tier ladder (5-stage)
+
+| Utilization | Level | Emoji | Threshold-pct |
+|---:|---|:---:|---:|
+| `< 50 %` | `OK` | 🟢 | 0 |
+| `50–74 %` | `INFO` | 🟡 | 50 |
+| `75–89 %` | `WARNING` | 🟠 | 75 |
+| `90–99 %` | `CRITICAL` | 🔴 | 90 |
+| `≥ 100 %` | `HARD_STOP` | 🛑 | 100 |
+
+The legacy 4-stage draft (`under / 50 / 75 / 90 / 100`) folded `OK`
+into `under`. Parity-doc Phase 6 maps both forms verbatim.
+
+## Hook surface
+
+`scripts/cost/preflight.mjs` is the **single** turn-start surface.
+It wraps `budget.mjs check` and:
+
+1. Reads `cost.enforcement` from `.agent-settings.yml`.
+2. If `advisory` → always exits `0`, prints the tier as advisory text.
+3. If `hard-stop` and level is `HARD_STOP` → prints a refusal block
+   citing this contract and exits `1`.
+4. If no budget is configured at all → exits `0` (fail-open). Never
+   blocks unbudgeted work.
+
+The hook does **not** rewrite or block individual tool calls. It is a
+process-entry gate, intended to be invoked by:
+
+- `task ci`, `task work:*`, `task roadmap:*` wrappers.
+- The `/onboard` boot path (`scripts/install.py`-side guidance only).
+- Manual `node scripts/cost/preflight.mjs` for shell wrappers.
+
+## Bypass
+
+User-facing bypass mechanism (documented for the refusal block):
+
+- Raise the budget: edit `.agent-settings.yml § cost.budgets.<period>`.
+- Reset the ledger (drops historical spend from the calculation):
+  `node scripts/cost/track.mjs reset --confirm`.
+- Disable enforcement: set `cost.enforcement: advisory`.
+
+No environment-variable override. Bypass must be an explicit edit so
+the change is durable and auditable.
+
+## Default behaviour without a budget
+
+When `cost.budgets.{daily,weekly,monthly}` are all `0`:
+
+- `budget.mjs check` reports cumulative spend, no tier (returns the
+  no-budget JSON shape).
+- `preflight.mjs` exits `0`. Never blocks.
+- `agent-status` panel shows **only** the measured-spend USD figure;
+  the tier table is suppressed.
+
+## Source precedence
+
+`budget.mjs` reads budget config in this order:
+
+1. `.agent-settings.yml § cost` (when any value > 0).
+2. `agents/cost-tracking/budget.json` (legacy single-period JSON).
+3. None → no-budget output shape.
+
+The evaluator output carries `source: 'agent-settings.yml' | 'budget.json'`
+so dashboards can show where the figure came from.
+
+## Period mapping
+
+`BUDGET_PERIOD={today|week|month|all}` selects which budget value
+applies:
+
+| `BUDGET_PERIOD` | Settings key |
+|---|---|
+| `today` | `cost.budgets.daily` |
+| `week` | `cost.budgets.weekly` |
+| `month` | `cost.budgets.monthly` |
+| `all` (default) | First non-zero of `monthly → weekly → daily`. |
+
+## Acceptance fixtures
+
+`tests/fixtures/cost/budget/` carries five reference fixtures:
+`under-50`, `mid-75`, `high-90`, `at-100`, `over-100`. Each fixture
+ships a `sessions.jsonl` slice + an expected JSON output. The fixture
+suite is wired to `task test-cost-budget` per `step-11` Phase 2 Step 5.
+
+## See also
+
+- `step-11-ruflo-parity` — Measurement & Governance Parity roadmap.
+- `docs/contracts/cost-dashboard.md` — companion dashboard contract.
+- `scripts/cost/budget.mjs` — evaluator implementation.
+- `bench/pricing.yaml` — per-model USD pricing table.

package/docs/contracts/file-ownership-matrix.json

@@ -6928,13 +6928,6 @@
       "via": "body_link",
       "depth": 1
     },
-    {
-      "source": ".agent-src.uncompressed/rules/no-cheap-questions.md",
-      "target": ".agent-src.uncompressed/contexts/contracts/frugality-charter.md",
-      "type": "READ_ONLY",
-      "via": "body_link",
-      "depth": 1
-    },
     {
       "source": ".agent-src.uncompressed/rules/no-cheap-questions.md",
       "target": ".agent-src.uncompressed/rules/ask-when-uncertain.md",

package/docs/contracts/mcp-tool-inventory.md

@@ -0,0 +1,53 @@
+---
+stability: beta
+keep-beta-until: 2026-08-14
+---
+
+# MCP tool inventory
+
+> Generated by [`scripts/audit_mcp_tools.py`](../../scripts/audit_mcp_tools.py)
+> from the source-of-truth catalog
+> [`scripts/mcp_server/consumer_tool_catalog.json`](../../scripts/mcp_server/consumer_tool_catalog.json).
+> Do **not** hand-edit; rerun `python3 scripts/audit_mcp_tools.py --write`.
+>
+> Step-11 Phase 5 Step 3 (`step-11-ruflo-parity.md`).
+
+## Summary
+
+- **Total tools:** 20
+- **By transport:** stdio=9
+- **By side-effect:** fs-write=5, ro=12, shell=3
+- **Discovery-only stubs (no implementation):** 11
+
+## Tools
+
+| Tool | Side-effect | Transports | Catalog | Handler |
+|---|---|---|---|---|
+| `lint_skills` | `ro` | stdio | [`consumer_tool_catalog.json:7`](../../scripts/mcp_server/consumer_tool_catalog.json#L7) | [`tools.py:510`](../../scripts/mcp_server/tools.py#L510) |
+| `chat_history_append` | `fs-write` | stdio | [`consumer_tool_catalog.json:24`](../../scripts/mcp_server/consumer_tool_catalog.json#L24) | [`tools.py:535`](../../scripts/mcp_server/tools.py#L535) |
+| `chat_history_read` | `ro` | stdio | [`consumer_tool_catalog.json:43`](../../scripts/mcp_server/consumer_tool_catalog.json#L43) | [`tools.py:571`](../../scripts/mcp_server/tools.py#L571) |
+| `memory_lookup` | `ro` | stdio | [`consumer_tool_catalog.json:59`](../../scripts/mcp_server/consumer_tool_catalog.json#L59) | [`tools.py:590`](../../scripts/mcp_server/tools.py#L590) |
+| `memory_signal` | `fs-write` | _(stub)_ | [`consumer_tool_catalog.json:75`](../../scripts/mcp_server/consumer_tool_catalog.json#L75) | _stub-only_ |
+| `memory_status` | `ro` | stdio | [`consumer_tool_catalog.json:91`](../../scripts/mcp_server/consumer_tool_catalog.json#L91) | [`tools.py:617`](../../scripts/mcp_server/tools.py#L617) |
+| `skill_trigger_eval` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:98`](../../scripts/mcp_server/consumer_tool_catalog.json#L98) | _stub-only_ |
+| `suggest_command` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:114`](../../scripts/mcp_server/consumer_tool_catalog.json#L114) | _stub-only_ |
+| `suggest_skill_for_task` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:129`](../../scripts/mcp_server/consumer_tool_catalog.json#L129) | _stub-only_ |
+| `mine_session` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:144`](../../scripts/mcp_server/consumer_tool_catalog.json#L144) | _stub-only_ |
+| `update_form_request_messages` | `fs-write` | _(stub)_ | [`consumer_tool_catalog.json:158`](../../scripts/mcp_server/consumer_tool_catalog.json#L158) | _stub-only_ |
+| `sync_gitignore` | `fs-write` | _(stub)_ | [`consumer_tool_catalog.json:173`](../../scripts/mcp_server/consumer_tool_catalog.json#L173) | _stub-only_ |
+| `sync_agent_settings` | `fs-write` | _(stub)_ | [`consumer_tool_catalog.json:186`](../../scripts/mcp_server/consumer_tool_catalog.json#L186) | _stub-only_ |
+| `run_tests` | `shell` | _(stub)_ | [`consumer_tool_catalog.json:200`](../../scripts/mcp_server/consumer_tool_catalog.json#L200) | _stub-only_ |
+| `run_quality_checks` | `shell` | _(stub)_ | [`consumer_tool_catalog.json:214`](../../scripts/mcp_server/consumer_tool_catalog.json#L214) | _stub-only_ |
+| `list_skills` | `ro` | stdio | [`consumer_tool_catalog.json:227`](../../scripts/mcp_server/consumer_tool_catalog.json#L227) | [`tools.py:631`](../../scripts/mcp_server/tools.py#L631) |
+| `list_commands` | `ro` | stdio | [`consumer_tool_catalog.json:234`](../../scripts/mcp_server/consumer_tool_catalog.json#L234) | [`tools.py:644`](../../scripts/mcp_server/tools.py#L644) |
+| `list_rules` | `ro` | stdio | [`consumer_tool_catalog.json:241`](../../scripts/mcp_server/consumer_tool_catalog.json#L241) | [`tools.py:657`](../../scripts/mcp_server/tools.py#L657) |
+| `compile_router` | `shell` | _(stub)_ | [`consumer_tool_catalog.json:248`](../../scripts/mcp_server/consumer_tool_catalog.json#L248) | _stub-only_ |
+| `read_resource_body` | `ro` | stdio | [`consumer_tool_catalog.json:261`](../../scripts/mcp_server/consumer_tool_catalog.json#L261) | [`tools.py:670`](../../scripts/mcp_server/tools.py#L670) |
+
+## Glossary
+
+- **Side-effect** — `ro` (read-only) · `fs-write` (filesystem write) · `shell` (spawns processes).
+- **Transports** — `stdio` (`scripts/mcp_server/`) · `worker` (`workers/mcp/`). A tool may live on both.
+- **Stub** — catalog-listed for discovery; returns the `not_implemented` envelope from
+  [`mcp-tool-stub-envelope.md`](mcp-tool-stub-envelope.md) until promoted.
+

package/docs/contracts/measurement-baseline.md

@@ -0,0 +1,102 @@
+---
+stability: stable
+---
+
+# Measurement baseline — contract
+
+> **Status:** locked 2026-05-16 · **Owner:** `step-4-measurement-and-benchmark.md`
+> · **Cited by:** every P2 enforcement roadmap (skill rationalization G0, north-star G1, compression default decision).
+
+Single source of truth for what `task bench` measures, what counts as
+drift, and what unblocks enforcement. Read this before pinning a number
+to a roadmap or PR description.
+
+## What `task bench` measures
+
+Four axes, all numeric, all reproducible from the same input:
+
+| Axis | Source | Definition | Units |
+|---|---|---|---:|
+| **selection accuracy** | [`scripts/bench_runner.py`](../../scripts/bench_runner.py) | Keyword-overlap ranker hits the expected skill in top-K | % |
+| **cost** | [`scripts/cost/track.mjs`](../../scripts/cost/track.mjs) session jsonl | Token+USD per model, captured live | USD |
+| **quality** | regex / rubric assertions per prompt | `quality_assertion` matches in agent output | % |
+| **projection fidelity** | [`scripts/bench_per_tool.py`](../../scripts/bench_per_tool.py) | `accuracy(tool) / accuracy(augment)` for skill-projecting tools | ratio |
+
+Schemas: [`benchmark-report-schema.md`](benchmark-report-schema.md) ·
+[`benchmark-corpus-spec.md`](benchmark-corpus-spec.md). Reports land at
+`bench/reports/<utc-stamp>-<corpus>[-projection].{json,md}` —
+timestamped, never overwritten, content-addressed by run.
+
+## Corpora — frozen for the soak window
+
+| Corpus | Path | Prompts | Purpose |
+|---|---|---:|---|
+| `dev` | [`tests/eval/corpus-dev.yaml`](../../tests/eval/corpus-dev.yaml) | 10 | Developer task surface (Laravel/Symfony/React/CI/PR) |
+| `non-dev` | [`tests/eval/corpus-non-dev.yaml`](../../tests/eval/corpus-non-dev.yaml) | 16 | Founder / agency / content creator surface (Wing-4) |
+
+Total 26 prompts ≥ Acceptance Criteria floor of 25. Mid-window edits
+to either YAML restart the 60-day clock per
+[`compression-default-kill-criterion.md`](compression-default-kill-criterion.md) § 2.
+
+## What counts as drift
+
+[`scripts/bench_drift_check.py`](../../scripts/bench_drift_check.py)
+compares the latest report against a sliding window of the prior N runs
+(default 5) for the same corpus.
+
+| Axis | Threshold | Note |
+|---|---|---|
+| selection accuracy | latest − baseline_mean ≤ −5 pp | always evaluated |
+| cost | latest / baseline_mean ≥ +20 % | only when both sides have `source: captured` |
+| quality | latest − baseline_mean ≤ −10 pp | skipped when latest is `not_collected` |
+| projection fidelity | tool fidelity < 0.85 | exit 1 from `task bench:projection` |
+
+Drift exits with code 2 from `task bench:drift`. **CI posture during
+soak:** all bench-drift steps `continue-on-error: true` and post a
+sticky PR comment — informational only, not a merge gate. Flip to
+required check happens via a separate PR once
+`task bench:baseline-ready` returns 0 (see below).
+
+## What unblocks enforcement (the G1 gate)
+
+```
+TASK bench:baseline-ready EXIT 0 IS THE ONLY AUTHORITY.
+NO ANECDOTE, NO INDIVIDUAL REPORT, NO ROADMAP-SIDE OVERRIDE.
+```
+
+[`scripts/bench_baseline_ready.py`](../../scripts/bench_baseline_ready.py)
+returns exit 0 iff both:
+
+1. **Wall-clock soak:** `today − bench/baseline-start.txt ≥ --min-days` (default 60)
+2. **Report density:** `bench/reports/*-<corpus>.json` count ≥ `--min-reports` (default 30)
+
+Soak start anchored at [`bench/baseline-start.txt`](../../bench/baseline-start.txt)
+= **2026-05-16**. Earliest possible flip: **2026-07-15**, contingent
+on the 30-report floor.
+
+Downstream consumers:
+
+- ``step-99-north-star-restructure.md` § Acceptance G1` — reads this exit code.
+- [`compression-default-kill-criterion.md` § 3](compression-default-kill-criterion.md) — reads the decision table after baseline closes.
+- ``step-2-skill-inventory-rationalization.md` § G0` — usage-data soak floor.
+
+## What the closeout writes
+
+On baseline closure, the step-4 closeout writes the numeric verdict to
+[`docs/parity/bench.json`](../parity/bench.json) — frozen snapshot with
+the 30+ reports averaged, drift verdict, and the compression-default
+decision per the kill-criterion table. That file is the artefact every
+P2 roadmap reads — not the live `bench/reports/` directory.
+
+## Carve-outs
+
+- **Pricing freshness:** [`bench/pricing.yaml`](../../bench/pricing.yaml) rows must carry `sourced_on: YYYY-MM-DD`. Stale prices = stale numbers = no trust (ruflo "measured-vs-claimed" pattern).
+- **Subjective grading excluded:** quality scoring is mechanical via `quality_assertion`. No vibes.
+- **Cursor / Cline / Windsurf:** rules-only surfaces, no SKILL.md projection. `bench:projection` reports them as `not_applicable` — the gap is acknowledged, not silently dropped.
+
+## Cross-references
+
+- [`benchmark-report-schema.md`](benchmark-report-schema.md) · per-report JSON schema
+- [`benchmark-corpus-spec.md`](benchmark-corpus-spec.md) · corpus YAML schema
+- [`compression-default-kill-criterion.md`](compression-default-kill-criterion.md) · decision table read by step-4 closeout
+- `step-4-measurement-and-benchmark.md` · the owning roadmap

package/docs/contracts/namespace.md

@@ -0,0 +1,125 @@
+---
+stability: stable
+---
+
+# Namespace contract — skills, rules, commands, personas
+
+> Every artefact name is a **stable identifier**: routed to from
+> `router.json`, cited from skills, surfaced in `/help`, embedded in
+> command paths, and back-referenced in test fixtures. Drift breaks
+> all five surfaces silently.
+>
+> **Source:** Step-11 Phase 5 Step 1
+> (`step-11-ruflo-parity.md`).
+> **Enforcer:** [`scripts/lint_namespace.py`](../../scripts/lint_namespace.py),
+> wired into `task lint-skills`.
+
+## 1. Shape
+
+```
+<stem>-<intent>    kebab-case, ASCII, lowercase
+```
+
+| Component | Rule |
+|---|---|
+| Charset | `[a-z0-9-]+` only |
+| Separator | single `-` between tokens; never `_`, `.`, or camelCase |
+| Length | skills: 3 ≤ name ≤ 64 · rules / commands / personas: 2 ≤ name ≤ 64 (two-letter slot reserved for intentional acronyms — `pr`, `ci`, `qa`, `me`) |
+| First char | `[a-z]` (digits and `-` forbidden at start) |
+| Last char | `[a-z0-9]` (trailing `-` forbidden) |
+| Run | no consecutive `--` |
+
+The `<stem>` carries the **subject** (`commit`, `eloquent`,
+`livewire`); the `<intent>` (optional) carries the **verb / lens**
+(`-writing`, `-architect`, `-routing`). Single-token names are
+permitted when the stem already encodes both (`commit`, `eloquent`,
+`docker`).
+
+## 2. Reserved names — forbidden as artefact names
+
+| Name | Reason |
+|---|---|
+| `pattern` | Reserved for trigger-pattern fixtures (see `tests/fixtures/triggers/`). |
+| `claude-memories` | Reserved for the `~/.claude/CLAUDE.md` shape — host-agent state, not a package artefact. |
+| `default` | Ambiguous with profile / mode defaults; collides with `.agent-settings.yml` keys. |
+| `index` | Reserved for auto-generated INDEX.md files. |
+| `router` | Reserved for `router.json` and the router contract. |
+
+Reserved names apply at the **top level** of each artefact type. A
+sub-verb under a namespaced group (e.g. `council/default.md` →
+`/council:default`) is **not** a top-level identifier — the group
+prefix disambiguates it, and reserved-name enforcement is skipped
+for sub-verbs by the linter. A future artefact `pattern-foo` at the
+top level is fine; bare `pattern` is not.
+
+`README.md` and `INDEX.md` are documentation, not artefacts, and are
+skipped by the linter.
+
+## 3. Per-type conventions
+
+| Type | Source path | Naming nuance |
+|---|---|---|
+| Skill | `.agent-src.uncompressed/skills/<name>/SKILL.md` | Directory name == frontmatter `name`. |
+| Rule | `.agent-src.uncompressed/rules/<name>.md` | Filename stem == frontmatter `id` (when present). |
+| Command | `.agent-src.uncompressed/commands/<name>.md` or `<group>/<verb>.md` | Slash-command invocation `<name>` or `<group>:<verb>`. |
+| Persona | `.agent-src.uncompressed/personas/<name>.md` | Cited from skill frontmatter `personas:` list. |
+
+Sub-namespacing (`commit/in-chunks.md` →  `/commit:in-chunks`) uses
+the same charset rules per segment; the joining colon is implicit.
+
+## 4. Linter — `scripts/lint_namespace.py`
+
+Walks the four source roots above, asserts each artefact name:
+
+1. Matches the regex `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`.
+2. Length 3 ≤ name ≤ 64.
+3. Not in the reserved-names list.
+4. Skill: directory name matches frontmatter `name`.
+
+Exit codes:
+
+| Exit | Meaning |
+|---|---|
+| `0` | All names valid. |
+| `1` | At least one name fails a rule. |
+| `2` | Linter crashed (filesystem error, malformed frontmatter). |
+
+Diagnostic format: one issue per line — `<path>: <rule> — <detail>`.
+
+## 5. Adding a new artefact
+
+Pick the name; verify locally:
+
+```bash
+python3 scripts/lint_namespace.py --name <candidate>
+# or full run:
+python3 scripts/lint_namespace.py
+```
+
+If the candidate fails, the linter prints the rule it violated.
+**Renames after release are expensive** — touch router.json, every
+skill citing the old name, the bench corpus, and consumer settings.
+Pay the naming cost once, upfront.
+
+## 6. Relationship to the frontmatter contract
+
+The **shape** lives here. The **frontmatter keys** that carry the
+name (`name:` in skills, `id:` in rules) live in
+[`frontmatter-contract.md`](../../agents/docs/frontmatter-contract.md).
+Both contracts share the regex; this file is the source of truth for
+the regex string.
+
+## 7. Why this exists
+
+`router.json` resolves `<kind>:<id>` strings at session start. Any
+artefact rename breaks every routing entry pointing at the old name
+without compile-time error. The linter catches the rename at the PR
+boundary, not at runtime in a consumer.
+
+## 8. Out of scope
+
+- File-system case sensitivity (we rely on lowercase-only names).
+- Cross-tool aliases (Augment / Claude / Cursor all consume the same
+  name — projection is by content, not by alias).
+- Versioning suffixes (`-v2`, `-legacy`). Use `status: superseded`
+  in frontmatter instead; never rename in place.