@event4u/agent-config 2.19.0 → 2.20.1

package/docs/adrs/caveman/0001-default-off-until-bench.md

@@ -0,0 +1,93 @@
+# ADR 0001 — Caveman compression default stays OFF until `task bench`
+
+> Area: `caveman` · Status: accepted · Date: 2026-05-16 · Type: retrospective
+> Roadmap: `agents/roadmaps/step-11-ruflo-parity.md` Phase 4 Step 3
+> Supersedes: —
+
+## Context
+
+Caveman-speak is a turn-time compression dialect that trades English
+grammar for tokens. The dialect is documented in
+[`caveman-speak`](../../../.agent-src.uncompressed/rules/caveman-speak.md);
+the question this ADR records is **whether the dialect should default
+ON for all consumers**.
+
+The North-Star council ([`council-synthesis.md` § 7](../../../agents/audit-2026-05-14-north-star/council-synthesis.md))
+landed split: two voices (token-efficiency, ops) argued default-ON
+saves 40 %+ tokens on long sessions; two voices (UX, governance)
+argued default-ON degrades novice readability and locks in a dialect
+nobody has measured against the real benchmark corpus.
+
+## Decision
+
+**`caveman.speak_scope` defaults `off`**. Carve-outs (security ·
+destructive · multi-step · code blocks · paths · numbered options ·
+Iron-Law markers) stay in the rule body so the dialect is **defined**
+even when **inactive**. The default flips only when `task bench`
+produces measured win/loss numbers against the locked 25-prompt corpus.
+
+Authoritative kill-criterion:
+[`docs/contracts/compression-default-kill-criterion.md`](../../contracts/compression-default-kill-criterion.md)
+§ Rule lines 8–11.
+
+### Decision owner
+
+`step-4-measurement-and-benchmark.md` closeout phase. Not this doc.
+Not `step-99`. Not the North-Star council. The closeout reads
+`docs/parity/bench.json` and applies exactly one of three branches
+defined in the kill-criterion.
+
+### Default-ON gates (all required)
+
+1. ≥ 30 % token reduction averaged across the 25-prompt corpus.
+2. ≤ 5 % regression on the readability score from the same run.
+3. Reversibility check passes (caveman → English round-trip ≥ 95 %
+   semantic preservation per the bench scorer).
+
+Any gate fails → default stays OFF. Re-bench after the next dialect
+edit.
+
+## Considered alternatives
+
+### Alt 1 — Default ON now (rejected)
+
+Flip the default immediately; let consumers opt out.
+
+**Why rejected:** no measured baseline exists. The two pro voices'
+40 % claim is from informal turn-snippet comparisons, not the locked
+corpus. Default-on without measurement is exactly the Ruflo-style
+"trust me it's faster" pattern the audit calls out.
+
+### Alt 2 — Default ON for cost-profile `lean`, OFF for `default` (rejected)
+
+Couple the default to the cost profile.
+
+**Why rejected:** cost profiles already carry profile-specific budget
+ladders and smoke contracts. Adding a dialect coupling makes the
+matrix `2 × N` instead of `1 × N`. The kill-criterion measurement is
+the same regardless of profile — make the decision once.
+
+### Alt 3 — Keep default OFF, measure first (accepted)
+
+The chosen path. Dialect ships, stays dormant, gets benched, then
+either ships default-on or gets deprecated. No middle state.
+
+## Consequences
+
+- **Positive:** new consumers get standard English by default; the
+  novice-onboarding path is unaffected; the dialect is auditable and
+  measurable before it becomes the default cost vector.
+- **Negative:** the 40 %+ token savings are leave-on-table for any
+  consumer who doesn't explicitly opt in. Mitigated by surfacing the
+  flag in `/onboard` once `task bench` lands.
+- **Reversal cost:** flip the default in
+  [`.agent-settings.yml`](../../../.agent-settings.yml.example)
+  template; existing user settings unaffected by template change.
+
+## References
+
+- [`docs/contracts/compression-default-kill-criterion.md`](../../contracts/compression-default-kill-criterion.md) — kill-criterion contract.
+- [`.agent-src.uncompressed/rules/caveman-speak.md`](../../../.agent-src.uncompressed/rules/caveman-speak.md) — dialect definition.
+- [`agents/roadmaps/step-4-measurement-and-benchmark.md`](../../../agents/roadmaps/step-4-measurement-and-benchmark.md) — bench owner.
+- [`agents/audit-2026-05-14-north-star/council-synthesis.md`](../../../agents/audit-2026-05-14-north-star/council-synthesis.md) § 7 — council split.
+- [`agents/roadmaps/step-11-ruflo-parity.md`](../../../agents/roadmaps/step-11-ruflo-parity.md) Phase 4 Step 3 — origin.

package/docs/adrs/caveman/README.md

@@ -0,0 +1,9 @@
+# ADRs — `caveman`
+
+> Caveman-speak compression, decompression, reversibility guards.
+
+Contract: [`docs/contracts/compression-default-kill-criterion.md`](../../../docs/contracts/compression-default-kill-criterion.md).
+
+| # | Title | Status | Date | Supersedes |
+|---|---|---|---|---|
+| [0001](0001-default-off-until-bench.md) | Default Off Until Bench | — | — | — |

package/docs/adrs/cost/0001-hard-stop-hook.md

@@ -0,0 +1,114 @@
+# ADR 0001 — Hard-stop hook surface
+
+> Area: `cost` · Status: accepted · Date: 2026-05-16 · Type: retrospective
+> Roadmap: `agents/roadmaps/step-11-ruflo-parity.md` Phase 2 Step 3
+
+## Context
+
+`step-11-measurement-governance-parity` Phase 2 lands a 5-tier budget
+ladder (`OK / INFO / WARNING / CRITICAL / HARD_STOP`) evaluated by
+[`scripts/cost/budget.mjs`](../../../scripts/cost/budget.mjs). The
+roadmap requires that the `HARD_STOP` tier fail closed when the user
+opts into `cost.enforcement: hard-stop` — without changing the
+default-on advisory experience.
+
+This package is a governance layer, not a runtime orchestrator (see
+[`step-11`](../../../agents/roadmaps/step-11-ruflo-parity.md) scope
+boundary). The hook must therefore live at a **process-entry seam**,
+not inside the rule-loader, agent dispatcher, or per-tool-call
+interceptor — none of those exist in this codebase by design.
+
+## Decision
+
+Land a single shell-entry preflight script:
+[`scripts/cost/preflight.mjs`](../../../scripts/cost/preflight.mjs).
+
+### Surface
+
+- **Where it fires:** any shell or CI wrapper that opts in by calling
+  `task cost:preflight` (or `node scripts/cost/preflight.mjs`) before
+  composing a turn. Not auto-injected anywhere.
+- **What it does:** wraps `budget.mjs check`. Reads `cost.enforcement`
+  from `.agent-settings.yml`. Exits non-zero **only** when
+  `enforcement: hard-stop` **and** `level: HARD_STOP`.
+- **Refusal output:** human-readable refusal block citing
+  [`docs/contracts/cost-enforcement.md`](../../contracts/cost-enforcement.md)
+  with the three bypass paths (raise budget · reset ledger · disable
+  enforcement). Machine-readable equivalent on `PREFLIGHT_QUIET=1`.
+
+### Default behaviour without a budget
+
+When `cost.budgets.{daily,weekly,monthly}` are all `0`:
+
+- `preflight.mjs` exits `0`. Always.
+- This is the **fail-open default**. Unconfigured projects never get
+  blocked.
+
+### Bypass
+
+Three options, all documented in the refusal block and the contract:
+
+1. **Raise the budget** — edit `.agent-settings.yml § cost.budgets`.
+2. **Reset the ledger** — `node scripts/cost/track.mjs reset` (drops
+   historical spend from utilization).
+3. **Disable enforcement** — set `cost.enforcement: advisory`.
+
+No env-var override. Bypass is durable and auditable.
+
+## Considered alternatives
+
+### Alt 1 — Rule-loader hook (rejected)
+
+Refuse to compose the turn-start preamble in the kernel-rule loader.
+
+**Why rejected:** the kernel-rule loader is a static-projection step
+(`scripts/sync.py` writes `.agent-src/rules/` from
+`.agent-src.uncompressed/`). There is no live loader at turn-start to
+hook — Claude / Augment / etc. read the projected files directly. A
+"refusal" would have to be baked into the file content, which mixes
+policy enforcement with documentation. Out of scope.
+
+### Alt 2 — `/onboard` boot path (rejected)
+
+Block `/onboard` when over budget.
+
+**Why rejected:** `/onboard` is a one-shot install path. Blocking it
+when the **historical** spend exceeds the **new** budget creates a
+chicken-and-egg lock-out. Onboarding must never fail-closed.
+
+### Alt 3 — Per-tool-call interceptor (rejected)
+
+Wrap every tool call with a budget check.
+
+**Why rejected:** this package doesn't intercept tool calls. Building
+that would require a runtime engine — the explicit Non-goal of
+`step-11` (see scope boundary). This is the Ruflo-style runtime
+absorption we ruled out.
+
+### Alt 4 — Single-shell-entry preflight (accepted)
+
+The chosen surface. Opt-in by wrapper invocation; predictable; no
+runtime, no projection coupling, no chicken-and-egg edges. Matches the
+governance-layer charter.
+
+## Consequences
+
+- **Positive:** consumers who want fail-closed behaviour get it with
+  one settings flip + one task invocation. The default-on experience
+  is unchanged. No runtime is introduced. The hook composes with `task
+  ci`, `task work:*`, or any shell wrapper the consumer chooses.
+- **Negative:** the hook is **opt-in by wrapper**. A consumer who sets
+  `enforcement: hard-stop` but never invokes `task cost:preflight`
+  gets no enforcement. Documented as a known limitation; mitigated by
+  surfacing the gap in `agent-status`.
+- **Reversal cost:** flip `cost.enforcement: advisory` globally, or
+  remove the `task cost:preflight` call from wrappers. Hook becomes
+  inert with no code change.
+
+## References
+
+- [`docs/contracts/cost-enforcement.md`](../../contracts/cost-enforcement.md) — contract surface.
+- [`scripts/cost/budget.mjs`](../../../scripts/cost/budget.mjs) — evaluator.
+- [`scripts/cost/preflight.mjs`](../../../scripts/cost/preflight.mjs) — this hook.
+- [`agents/roadmaps/step-11-ruflo-parity.md`](../../../agents/roadmaps/step-11-ruflo-parity.md) Phase 2 Step 3 — origin.
+- [`agents/audit-2026-05-14-north-star/external-findings.md`](../../../agents/audit-2026-05-14-north-star/external-findings.md) § 2 row "hard stop" — upstream Ruflo pattern this absorbs.

package/docs/adrs/cost/README.md

@@ -0,0 +1,9 @@
+# ADRs — `cost`
+
+> Budget ladder, hard-stop hook, cost reporting and dashboards.
+
+Contract: [`docs/contracts/cost-enforcement.md`](../../../docs/contracts/cost-enforcement.md).
+
+| # | Title | Status | Date | Supersedes |
+|---|---|---|---|---|
+| [0001](0001-hard-stop-hook.md) | Hard Stop Hook | — | — | — |

package/docs/adrs/memory/0001-consumer-side-snapshot.md

@@ -0,0 +1,111 @@
+# ADR 0001 — Consumer-side snapshot of the agent-memory contract
+
+> Area: `memory` · Status: accepted · Date: 2026-05-16 · Type: retrospective
+> Roadmap: `agents/roadmaps/step-11-ruflo-parity.md` Phase 4 Step 3
+> Supersedes: —
+
+## Context
+
+`@event4u/agent-memory` is a sibling package owned by this team. It
+provides MCP-server semantic-retrieval plus a v1 retrieval envelope
+(`id`, `type`, `source`, `confidence`, `body`, …). The spec-side
+source-of-truth lives in
+[`agents/roadmaps/archive/agent-memory/`](../../../agents/roadmaps/archive/agent-memory/);
+the implementation lives in the sibling repo.
+
+The question this ADR records is: **what surface does `agent-config`
+freeze internally**, given the package ships independently and the
+two repos can drift between releases?
+
+## Decision
+
+**Maintain a consumer-side snapshot at
+[`docs/contracts/agent-memory-contract.md`](../../contracts/agent-memory-contract.md)** —
+a point-in-time pin of the interface `agent-config`'s wired code
+**currently assumes**.
+
+### Three expected backend states
+
+Probed by [`scripts/memory_status.py`](../../../scripts/memory_status.py):
+
+| Status | Meaning | Agent-config behaviour |
+|---|---|---|
+| `absent` | Package not installed / CLI not on PATH | File fallback only |
+| `misconfigured` | Installed; `health()` fails within 2 s | Warn once per session, fall back to file |
+| `present` | Installed; healthy within 2 s | Route retrieval through package |
+
+Detection is **bounded** (≤ 2 s cold probe), **cached per process**,
+**non-raising** on probe failure.
+
+### CLI candidates
+
+Probed in `_CLI_CANDIDATES`: `memory` (canonical, v1.1+) ·
+`agent-memory` (planned alias) · `agentmem` (legacy). If the released
+package diverges from these names, this file updates — never the
+other way round.
+
+### Retrieval envelope (v1)
+
+Mandatory per entry: `id`, `type`, `source ∈ {repo, operational}`,
+`confidence`, `body`. Optional: `trust`, `last_validated`,
+`shadowed_by`. Envelope: `contract_version`, `status ∈ {ok, partial,
+error}`, `entries`, `slices`, `errors`. Source-of-truth:
+[`scripts/memory_lookup.py`](../../../scripts/memory_lookup.py)
+lines 320–345.
+
+### Refresh policy
+
+The snapshot doc carries a `Last refreshed:` line. On every sibling
+package release that touches the CLI or envelope shape, the
+maintainer:
+
+1. Runs the sibling package's CLI against `agent-config`'s test
+   fixtures.
+2. Updates this contract doc with the new shape, bumps
+   `Last refreshed:`, files the diff as a PR.
+3. Updates `_CLI_CANDIDATES` and any consumer skills only if the
+   shape diff is breaking.
+
+## Considered alternatives
+
+### Alt 1 — No internal pin; trust the sibling spec (rejected)
+
+Read the sibling package's spec at runtime / docs time.
+
+**Why rejected:** the two repos release on independent cadences. A
+mid-iteration sibling-package change would silently break consumer
+code. The internal pin makes the divergence point a diffable doc.
+
+### Alt 2 — Submodule the sibling spec (rejected)
+
+Git submodule pulls `agent-memory/docs/` into `agent-config/`.
+
+**Why rejected:** submodules complicate consumer installs (npx /
+shell installer must handle nested clones); the spec is fast-moving
+and submodule churn dwarfs the consumer-side surface this package
+actually wires.
+
+### Alt 3 — Consumer-side snapshot (accepted)
+
+The chosen path. One readable doc, refreshed on sibling-package
+release, citable from every consumer skill that touches memory.
+
+## Consequences
+
+- **Positive:** drift between sibling spec and consumer wiring lands
+  in one diffable file; the `present` / `misconfigured` / `absent`
+  contract is one citation away; new consumer skills don't have to
+  re-derive the envelope shape.
+- **Negative:** the snapshot can lag the sibling package. Mitigated
+  by the explicit `Last refreshed:` line and the refresh policy in §
+  "Refresh policy" above.
+- **Reversal cost:** delete the contract doc; consumers fall back to
+  reading the sibling spec directly. No code change required.
+
+## References
+
+- [`docs/contracts/agent-memory-contract.md`](../../contracts/agent-memory-contract.md) — the consumer-side snapshot.
+- [`scripts/memory_status.py`](../../../scripts/memory_status.py) — three-state probe.
+- [`scripts/memory_lookup.py`](../../../scripts/memory_lookup.py) — retrieval envelope source.
+- [`agents/roadmaps/archive/agent-memory/`](../../../agents/roadmaps/archive/agent-memory/) — sibling-package spec.
+- [`agents/roadmaps/step-11-ruflo-parity.md`](../../../agents/roadmaps/step-11-ruflo-parity.md) Phase 4 Step 3 — origin.

package/docs/adrs/memory/README.md

@@ -0,0 +1,9 @@
+# ADRs — `memory`
+
+> Memory MCP, propose / promote / poison flow, runtime-trust scoring.
+
+Contract: [`docs/contracts/agent-memory-contract.md`](../../../docs/contracts/agent-memory-contract.md).
+
+| # | Title | Status | Date | Supersedes |
+|---|---|---|---|---|
+| [0001](0001-consumer-side-snapshot.md) | Consumer Side Snapshot | — | — | — |

package/docs/adrs/router/0001-three-tier-routing.md

@@ -0,0 +1,119 @@
+# ADR 0001 — Three-tier rule router (kernel · tier-1 · tier-2)
+
+> Area: `router` · Status: accepted · Date: 2026-05-16 · Type: retrospective
+> Roadmap: `agents/roadmaps/step-11-ruflo-parity.md` Phase 4 Step 3
+> Supersedes: —
+
+## Context
+
+Every rule in `.agent-src.uncompressed/rules/` loads into a host
+agent's system prompt. Loading them all is wasteful (the workspace
+budget is finite) and noisy (irrelevant rules degrade attention).
+The kernel-membership work
+([`docs/contracts/kernel-membership.md`](../../contracts/kernel-membership.md))
+proved 9 rules are unconditionally relevant; the rest are
+situational.
+
+The router question is: **how does a non-kernel rule declare when it
+fires, what artefacts carry its body, and how does the host agent
+look that up cheaply at session start**.
+
+## Decision
+
+**Three tiers, declared in rule frontmatter, compiled into a single
+[`router.json`](../../../router.json) at the repo root.** Host agents
+read `router.json` once per session.
+
+### Tier semantics
+
+| Tier | Load behaviour | Workspace cost |
+|---|---|---|
+| `kernel` | Body injected verbatim every turn | High (capped per ADR-002 · ≤ 26k chars) |
+| `tier-1` | Description stub injected; body loaded on trigger | Low (stub only) |
+| `tier-2` | No injection; loaded only on explicit trigger match | Zero (until activated) |
+
+The tier value sits in the rule's `tier:` frontmatter key; the
+schema enforces the enum (`scripts/schemas/rule.schema.json`).
+
+### Trigger vocabulary
+
+Six match kinds, OR-combined across entries, AND-combined within an
+entry's qualifier object (full grammar:
+[`rule-router.md`](../../contracts/rule-router.md) § `triggers:` shape):
+
+`keyword` · `phrase` · `intent` · `file_pattern` · `path_prefix` ·
+`command`. Kernel rules **forbid** `triggers:` — they are
+unconditional by definition.
+
+### Compilation pipeline
+
+1. `scripts/sync.py` projects `.agent-src.uncompressed/` → `.agent-src/`.
+2. `scripts/compile_router.py` walks rule frontmatter, validates the
+   `routes_to:` targets exist on disk, writes `router.json`.
+3. `scripts/skill_linter.py` runs the bidirectional check: every
+   `routes_to:` target has a matching `triggered_by:` back-ref.
+
+### `routes_to:` resolution
+
+Plain `<kind>:<id>` strings; kinds are `skill`, `guideline`,
+`command`, `contract`. Resolution paths are pinned in
+[`rule-router.md`](../../contracts/rule-router.md) lines 73–77 and
+enforced by the linter.
+
+## Considered alternatives
+
+### Alt 1 — Single flat list (rejected)
+
+All rules `always`-load.
+
+**Why rejected:** the rules tree is ~70 entries; even with caveman
+compression the workspace budget blows past the kernel cap. Static
+loading wastes attention on rules irrelevant to the current turn.
+
+### Alt 2 — Pure-runtime semantic search (rejected)
+
+Embed every rule, semantic-match the turn against the index, load
+top-k.
+
+**Why rejected:** introduces a runtime (this package is a governance
+layer, not a runtime — see step-11 scope boundary); index drift adds
+a non-trivial maintenance surface; first-turn cold-start is slow.
+
+### Alt 3 — Two tiers (kernel + load-on-trigger, rejected)
+
+Skip the `tier-1` description-stub layer.
+
+**Why rejected:** the stub layer carries 70 % of the "does this turn
+need this rule?" signal at < 5 % of the body cost. Removing it
+forces the host agent to either over-load (cost spike) or
+mis-trigger (correctness loss).
+
+### Alt 4 — Three-tier with frontmatter declaration (accepted)
+
+The chosen path. Kernel + tier-1 stubs (balanced + full profiles) +
+tier-2 (full profile only). Cost stays bounded; trigger declarations
+diff cleanly in PRs.
+
+## Consequences
+
+- **Positive:** every rule declares its activation cost; the kernel
+  cap is enforceable; the host agent's session-start cost is one
+  JSON read; the `routes_to:` link makes "where does this rule's
+  body live?" answerable without grep.
+- **Negative:** two layers of indirection (rule → stub → body)
+  raise the bar for new contributors. Mitigated by
+  [`rule-router.md`](../../contracts/rule-router.md) being the
+  single citable contract and the linter catching shape errors.
+- **Reversal cost:** flatten by removing tier-1 / tier-2 distinction
+  in the compiler — `router.json` becomes a list of all rules. The
+  rule frontmatter stays valid (extra fields are tolerated by
+  Draft-07 once `additionalProperties` is relaxed).
+
+## References
+
+- [`docs/contracts/rule-router.md`](../../contracts/rule-router.md) — frontmatter contract.
+- [`docs/contracts/kernel-membership.md`](../../contracts/kernel-membership.md) — kernel cap.
+- [`router.json`](../../../router.json) — compiled output.
+- [`scripts/compile_router.py`](../../../scripts/compile_router.py) — compiler.
+- [`scripts/schemas/rule.schema.json`](../../../scripts/schemas/rule.schema.json) — schema.
+- [`agents/roadmaps/step-11-ruflo-parity.md`](../../../agents/roadmaps/step-11-ruflo-parity.md) Phase 4 Step 3 — origin.

package/docs/adrs/router/README.md

@@ -0,0 +1,9 @@
+# ADRs — `router`
+
+> router.json shape, tier semantics, dispatch precedence.
+
+Contract: [`docs/contracts/rule-router.md`](../../../docs/contracts/rule-router.md).
+
+| # | Title | Status | Date | Supersedes |
+|---|---|---|---|---|
+| [0001](0001-three-tier-routing.md) | Three Tier Routing | — | — | — |

package/docs/adrs/schema/0001-json-schema-frontmatter.md

@@ -0,0 +1,102 @@
+# ADR 0001 — JSON Schema as the frontmatter source of truth
+
+> Area: `schema` · Status: accepted · Date: 2026-05-16 · Type: retrospective
+> Roadmap: `agents/roadmaps/step-11-ruflo-parity.md` Phase 4 Step 3
+> Supersedes: —
+
+## Context
+
+Skills, rules, commands, and personas all declare YAML frontmatter
+with required and optional keys. Validation needs to be:
+
+1. Machine-checkable on every PR (no "guideline" enforcement).
+2. Diff-readable so the contract drift is visible.
+3. Tool-agnostic — the same artefacts ship to Claude, Cursor, Cline,
+   Windsurf, and Augment, all of which parse the same YAML.
+
+The contract is documented for humans in
+[`agents/docs/frontmatter-contract.md`](../../../agents/docs/frontmatter-contract.md);
+the question this ADR records is **how that contract is enforced**.
+
+## Decision
+
+**JSON Schema (Draft-07) files in
+[`scripts/schemas/`](../../../scripts/schemas/) are the
+machine-readable source of truth.** The human contract document
+defers to the schema (`$comment` in each schema file pins
+`agents/docs/frontmatter-contract.md` as the source).
+
+### Schema files
+
+| Type | Schema | Validator entry-point |
+|---|---|---|
+| Skill | `scripts/schemas/skill.schema.json` | `scripts/skill_linter.py` |
+| Rule | `scripts/schemas/rule.schema.json` | `scripts/skill_linter.py` |
+| Command | `scripts/schemas/command.schema.json` | `scripts/validate_frontmatter.py` |
+| Persona | `scripts/schemas/persona.schema.json` | `scripts/validate_frontmatter.py` |
+
+### Required-key threshold
+
+A key is **required** (in the schema's `required:` array) if ≥ 95 %
+of files in the type declare it. Everything else is optional. The
+threshold is documented inline in
+[`frontmatter-contract.md`](../../../agents/docs/frontmatter-contract.md)
+§ "Definition of required". Re-derive counts with
+`python3 scripts/inventory_frontmatter.py`.
+
+### Validation hooks
+
+- `task lint-skills` — runs `skill_linter.py` against all skills + rules.
+- `task ci` — wraps `lint-skills` plus router + smoke smokes.
+- Smoke contract `scripts/smoke/schema.sh` — fast random-sample check
+  for PRs touching `.agent-src.uncompressed/**` (see
+  [`docs/contracts/smoke-contracts.md`](../../contracts/smoke-contracts.md)).
+
+## Considered alternatives
+
+### Alt 1 — Inline regex in the linter (rejected)
+
+Hard-code shape checks in `skill_linter.py`.
+
+**Why rejected:** the linter becomes the contract, the contract is
+hidden in Python, and the artefacts can't be validated by external
+tools (CI, editors, IDE plugins). Cross-tool portability is the
+whole point of YAML frontmatter — the schema must be portable too.
+
+### Alt 2 — Pydantic / dataclass models (rejected)
+
+Validate via typed Python models.
+
+**Why rejected:** ties validation to Python runtime, prevents
+JS/TS / Node tooling from reusing the same contract, and forces a
+non-trivial dependency on every consumer that wants to validate
+their own artefacts. JSON Schema is the lingua franca.
+
+### Alt 3 — JSON Schema Draft-07 (accepted)
+
+The chosen path. One source-of-truth file per artefact type,
+referenced by Python linter today, reusable by Node / VS Code /
+JetBrains / any JSON-Schema-aware tool tomorrow.
+
+## Consequences
+
+- **Positive:** schemas are diffable; new keys land via PR with
+  reviewable shape changes; non-Python tools can validate the same
+  contract; the linter stays thin.
+- **Negative:** Draft-07 is older than Draft-2020-12; some keyword
+  niceties (`unevaluatedProperties`, conditional `then`/`else`) are
+  awkward. Mitigated by `additionalProperties: false` plus
+  `oneOf` / `if`-then composition where needed.
+- **Reversal cost:** the linter is the only consumer today; replacing
+  the schema with Pydantic models would be a one-PR swap. The choice
+  is reversible without contract churn.
+
+## References
+
+- [`scripts/schemas/skill.schema.json`](../../../scripts/schemas/skill.schema.json) — skill contract.
+- [`scripts/schemas/rule.schema.json`](../../../scripts/schemas/rule.schema.json) — rule contract.
+- [`scripts/schemas/command.schema.json`](../../../scripts/schemas/command.schema.json) — command contract.
+- [`scripts/schemas/persona.schema.json`](../../../scripts/schemas/persona.schema.json) — persona contract.
+- [`agents/docs/frontmatter-contract.md`](../../../agents/docs/frontmatter-contract.md) — human-readable contract.
+- [`scripts/skill_linter.py`](../../../scripts/skill_linter.py) — primary validator.
+- [`agents/roadmaps/step-11-ruflo-parity.md`](../../../agents/roadmaps/step-11-ruflo-parity.md) Phase 4 Step 3 — origin.

package/docs/adrs/schema/README.md

@@ -0,0 +1,9 @@
+# ADRs — `schema`
+
+> Frontmatter schemas, v2 rigor, lint behaviour for skills / rules / commands.
+
+Contract: [`agents/docs/frontmatter-contract.md`](../../../agents/docs/frontmatter-contract.md).
+
+| # | Title | Status | Date | Supersedes |
+|---|---|---|---|---|
+| [0001](0001-json-schema-frontmatter.md) | Json Schema Frontmatter | — | — | — |