@event4u/agent-config 2.18.0 → 2.20.0

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 | — | — | — |

package/docs/adrs/smoke/0001-per-tier-smoke-scripts.md

@@ -0,0 +1,99 @@
+# ADR 0001 — Per-tier smoke scripts (kernel · router · schema · skills)
+
+> Area: `smoke` · Status: accepted · Date: 2026-05-16 · Type: retrospective
+> Roadmap: `agents/roadmaps/step-11-ruflo-parity.md` Phase 4 Step 3
+> Supersedes: —
+
+## Context
+
+The North-Star audit
+([`external-findings.md § 5`](../../../agents/audit-2026-05-14-north-star/external-findings.md))
+flagged "smoke contracts" as an absorbed Ruflo pattern: every
+high-traffic tier needs a fast, deterministic, measurable check that
+runs in CI and surfaces regressions before they reach the rules /
+router / schema / skill linter pipelines.
+
+The full `task ci` run is ≥ 90 s and exercises every linter. That's
+fine for merge gates; it's too slow for path-change feedback on PRs
+that touch one tier in isolation.
+
+## Decision
+
+**One smoke script per tier, each ≤ 30 s, each emitting a baseline
+declaration as its last stdout line.** Scripts live under
+[`scripts/smoke/`](../../../scripts/smoke/):
+
+| Tier | Script | Validates | Path-trigger globs |
+|---|---|---|---|
+| Kernel | [`kernel.sh`](../../../scripts/smoke/kernel.sh) | 9 kernel rules present, char-budget respected | `.agent-src.uncompressed/rules/**`, `docs/contracts/kernel-membership.md` |
+| Router | [`router.sh`](../../../scripts/smoke/router.sh) | `router.json` compiles, all `routes_to:` resolve | `router.json`, `.agent-src.uncompressed/rules/**` |
+| Schema | [`schema.sh`](../../../scripts/smoke/schema.sh) | Random skill / rule sample validates against JSON Schema | `scripts/schemas/**`, `.agent-src.uncompressed/{rules,skills}/**` |
+| Skills | [`skills.sh`](../../../scripts/smoke/skills.sh) | 5 random skills pass frontmatter + `name == dir` | `.agent-src.uncompressed/skills/**` |
+
+### Runtime contract
+
+Per [`smoke-contracts.md`](../../contracts/smoke-contracts.md) § 1:
+
+| Limit | Value |
+|---|---:|
+| Wall time | ≤ 30 s |
+| External I/O | filesystem only — no network, no MCP |
+| Output | last stdout line = baseline declaration |
+| Exit code | non-zero on baseline regression |
+
+### CI wiring
+
+[`.github/workflows/smoke.yml`](../../../.github/workflows/smoke.yml)
+dispatches each smoke independently on path-trigger match. Local
+aggregator: `task smoke` (sub-tasks `task smoke:{kernel,router,schema,skills}`)
+wired in [`taskfiles/engine.yml`](../../../taskfiles/engine.yml).
+
+### Baseline declarations (lock-in 2026-05-16)
+
+- Kernel: `9 rules · 23 / 26 kB used (88 %) · 0 fence breaches`.
+- Router: `tier_1: N · tier_2: M · 0 unresolved routes`.
+- Schema: deterministic seed = epoch day · 10 random files validated.
+- Skills: deterministic seed = epoch day · `210 skills · 5/5 pass`.
+
+## Considered alternatives
+
+### Alt 1 — One monolithic smoke (rejected)
+
+Single `task smoke` running every check.
+
+**Why rejected:** path-change PRs pay the full cost every time;
+flaky tier-X regression masks tier-Y signal; output is harder to
+diff. The per-tier split costs four files and saves CI minutes.
+
+### Alt 2 — Inline-in-`task ci` only (rejected)
+
+Skip the smoke layer; rely on `task ci` for everything.
+
+**Why rejected:** `task ci` is the merge gate, not the feedback
+loop. Smokes are the cheap-and-fast layer between push and review.
+
+### Alt 3 — Per-tier, ≤ 30 s budget, baseline-declaring (accepted)
+
+The chosen path. One script per tier, declared budget, declared
+baseline, CI-dispatched on path-trigger.
+
+## Consequences
+
+- **Positive:** PRs touching one tier get tier-specific feedback in
+  ≤ 30 s; baseline declarations are diff-readable so regressions
+  surface in PR descriptions; the `task ci` merge gate stays the
+  authoritative full-run.
+- **Negative:** four scripts to maintain, one workflow file, one
+  taskfile entry. Mitigated by the runtime contract — a smoke that
+  approaches 30 s gets split, not optimised in place.
+- **Reversal cost:** delete `smoke.yml`; the scripts stay as opt-in
+  local checks (`task smoke:*`). No contract churn.
+
+## References
+
+- [`docs/contracts/smoke-contracts.md`](../../contracts/smoke-contracts.md) — runtime + path-trigger contract.
+- [`scripts/smoke/`](../../../scripts/smoke/) — four scripts.
+- [`.github/workflows/smoke.yml`](../../../.github/workflows/smoke.yml) — CI dispatch.
+- [`taskfiles/engine.yml`](../../../taskfiles/engine.yml) — local aggregator.
+- [`agents/audit-2026-05-14-north-star/external-findings.md`](../../../agents/audit-2026-05-14-north-star/external-findings.md) § 5 — origin pattern.
+- [`agents/roadmaps/step-11-ruflo-parity.md`](../../../agents/roadmaps/step-11-ruflo-parity.md) Phase 3 (delivery) + Phase 4 Step 3 (this ADR).

package/docs/adrs/smoke/README.md

@@ -0,0 +1,9 @@
+# ADRs — `smoke`
+
+> Per-tier smoke contracts, baseline locks, regression gates.
+
+Contract: [`docs/contracts/smoke-contracts.md`](../../../docs/contracts/smoke-contracts.md).
+
+| # | Title | Status | Date | Supersedes |
+|---|---|---|---|---|
+| [0001](0001-per-tier-smoke-scripts.md) | Per Tier Smoke Scripts | — | — | — |