@event4u/agent-config 9.8.0 → 9.9.0

package/docs/contracts/consumer-bridge.md

@@ -1,73 +0,0 @@
----
-stability: stable
----
-
-# Consumer Bridge Marker (retired)
-
-**Status:** Retired — [`ADR-020 § Amendment 2026-07-13`](../decisions/ADR-020-global-only-consumer-scope.md#amendment--2026-07-13--bridge-marker-retired).
-**Pairs with:** [`ADR-020 — global-only consumer scope`](../decisions/ADR-020-global-only-consumer-scope.md), [`ADR-007 § Amendment 2026-05-13`](../decisions/ADR-007-agent-discovery-scopes.md#amendment-2026-05-13--augment-global-only).
-
-## Why it was retired
-
-The bridge marker `agents/.event4u-bridge.yml` was a per-project file that
-pointed at the global install. It carried **no project-specific data**:
-`global_root` is always the well-known `~/.event4u/agent-config` (one global
-install per machine), and nothing in the codebase ever read the field — the
-loader, doctor, and conformance checks all derive the global root independently
-via `user_global_paths.event4u_root()`. Yet the marker was **committed** to the
-shared project tree and rewrote its volatile `installed_at` / `installer_version`
-fields on every install, so each developer's install produced a diff and
-overwrote every other developer's committed copy. A file whose scope (global)
-did not match its location (per-project, committed) — pure churn.
-
-It is retired: the global root is resolved directly from the well-known path.
-
-## What replaced it
-
-- **Global-root resolution** — `user_global_paths.event4u_root()` returns
-  `~/.event4u/agent-config` (overridable via `EVENT4U_CONFIG_HOME`). Readers fail
-  closed when that path is missing on disk. No per-project pointer is consulted.
-- **Migration-idempotency sentinel** — moved to
-  `agents/.agent-state/install-mode.txt` (written on every full / minimal
-  install), which the installer's legacy-detection and the doctor's
-  "global-only consumer" branch key on. `agents/overrides/` is an equivalent
-  signal.
-- **Project anchor** — a bare consumer `agents/` directory is anchored on
-  `agents/overrides/` (the guaranteed minimal-consumer surface), not the marker.
-- **Cleanup** — the installer and `agent-config refresh --project` delete any
-  legacy `agents/.event4u-bridge.yml` a prior install committed; the managed
-  `.gitignore` block also ignores it so a stale copy is never re-committed.
-
-## Per-tool anchor strategy (still active)
-
-Some AI tools only load rules when an anchor file is **inside** the workspace
-(Windsurf, Cline, Gemini-CLI). For those IDs the installer plants a thin pointer
-file under the tool's per-project directory:
-
-```yaml
-schema: event4u-bridge/v1
-tool: windsurf
-global_root: ~/.event4u/agent-config
-installed_at: 2026-07-13T00:00:00Z
-```
-
-- Files: `.windsurf/agent-config.bridge.yml`, `.clinerules/agent-config.bridge.yml`,
-  `.gemini/agent-config.bridge.yml`.
-- `global_root` is the well-known path (readers expand `~` against the current
-  `$HOME`, never the writer's). There is no `bridge:` back-pointer — the retired
-  marker no longer exists to point at.
-- These anchors are **gitignored**: each developer regenerates them on install,
-  so they never churn in version control. Tools that load purely from user scope
-  (Claude Code, Cursor, Augment) need no per-tool file.
-
-## Legacy reader note
-
-A `v1` marker left in an un-migrated consumer repo still parses as before
-(`schema: event4u-bridge/v1`, `~`-expanded `global_root`). Do not add new readers
-of it — resolve the global root from the well-known path instead. The next
-install removes it.
-
-## References
-
-- [`ADR-020`](../decisions/ADR-020-global-only-consumer-scope.md) — global-only consumer scope + the 2026-07-13 retirement amendment.
-- [`ADR-007`](../decisions/ADR-007-agent-discovery-scopes.md) — scope precedence and the global-default amendment.

package/docs/contracts/context-paths.md

@@ -1,101 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-12
----
-
-# Context-file path conventions
-
-> **Audience:** rule, skill, and command authors who need to extract
-> reasoning material into a `contexts/` file.
-> **Linter:** `scripts/check_context_paths.py`
-> (run via `task check-context-paths`).
-> **Companion:** [`load-context-schema.md`](load-context-schema.md) —
-> frontmatter contract for citing a context from a rule.
-
-This contract defines **where** a context file is allowed to live under
-`.agent-src.uncondensed/contexts/` (the source-of-truth tree). It is the
-DAG root of `road-to-structural-optimization` Phase 0: the file-ownership
-matrix (Phase 0.1) greps for context-file fan-out at the locked tree, and
-several later phases (2A, 2B, 3a/b/c, 6) extract material into specific
-sub-trees named here. Locking the layout up-front keeps the matrix
-deterministic and prevents naming drift across phases.
-
-**Status:** internal-locked. Changes require a contract version bump and
-a roadmap revision (per `road-to-structural-optimization.md` § Definitions).
-
-## Locked path tree
-
-| Sub-tree | Owner phase | Naming convention |
-|---|---|---|
-| `contexts/communication/rules-always/` | Phase 2A | `<rule-name>-mechanics.md` |
-| `contexts/communication/rules-auto/` | Phase 2B | `<rule-name>-mechanics.md` |
-| `contexts/judges/` | Phase 3a | `judge-shared-procedure.md`, `persona-voice-rubric.md`, `no-consolidate-rationale.md` |
-| `contexts/analysis/` | Phase 3b | `project-analysis-core-procedure.md` (+ future siblings) |
-| `contexts/skills/` | Phase 3c | `skill-quality-rules.md` (+ future siblings) |
-| `contexts/chat-history/` | Phase 6 | `cadence.md`, `ownership.md`, `visibility.md` |
-| `contexts/execution/` | PR #34 (existing) | `<topic>-mechanics.md`, `<topic>-detection.md`, `<topic>-examples.md` |
-| `contexts/authority/` | PR #34 (existing) | `<topic>-mechanics.md` |
-| `contexts/contracts/` | road-to-path-fixes Phase 4 | `<topic>-flow.md` (load-bearing flow contracts cited via `load_context:`) |
-
-## Grandfathered files
-
-The six root-level files below predate this contract and stay where they
-are. **No new files at the contexts root** — every new context must live
-in a sub-tree above.
-
-```
-contexts/augment-infrastructure.md
-contexts/documentation-hierarchy.md
-contexts/model-recommendations.md
-contexts/override-system.md
-contexts/skills-and-commands.md
-contexts/subagent-configuration.md
-```
-
-## Rules enforced by `check_context_paths.py`
-
-1. **Sub-tree allow-list.** Every `*.md` under
-   `.agent-src.uncondensed/contexts/` must be either (a) in one of the
-   nine locked sub-trees above, or (b) one of the six grandfathered
-   root-level files. Anything else fails CI.
-2. **No collisions.** No two context files may share the same basename
-   across sub-trees. `judges/persona-voice-rubric.md` and
-   `analysis/persona-voice-rubric.md` are mutually exclusive.
-3. **No orphans.** Every context file must be referenced from at least
-   one rule, skill, command, or other context. References count as either
-   a frontmatter `load_context:` / `load_context_eager:` entry, **or** a
-   markdown body mention of the relative path
-   (`contexts/<sub-tree>/<file>.md` or
-   `.agent-src.uncondensed/contexts/<sub-tree>/<file>.md`).
-
-The linter exits non-zero on any violation and prints a one-line
-diagnostic per offence.
-
-## Adding a new sub-tree
-
-1. Open a roadmap revision proposing the new sub-tree (owner phase,
-   naming convention, expected first-mover file).
-2. Council-review under the same gate as a `load_context:` schema change.
-3. Bump this contract's version line in the roadmap (G2 fan-out: the
-   ownership matrix re-runs after the bump and new cells must remain
-   `READ_ONLY` only).
-4. Update `LOCKED_SUBTREES` in `scripts/check_context_paths.py` and
-   the table above in the same PR.
-
-## Why `check_context_paths.py` carries the orphan check
-
-`road-to-structural-optimization.md` 0.6.3 specified extending
-`scripts/docs-sync.py` for the orphan check. That script does not exist
-in this repo (the cross-reference checker lives in
-`scripts/check_references.py`, scoped to broken refs rather than orphan
-detection). Folding the orphan check into `check_context_paths.py` keeps
-all context-file invariants in one linter and avoids inventing a new
-sync tool. Functionally equivalent to the roadmap intent; the roadmap
-itself is annotated with this deviation.
-
-## See also
-
-- [`load-context-schema.md`](load-context-schema.md) — how a rule cites
-  one of these paths in frontmatter.
-- [`rule-priority-hierarchy.md`](rule-priority-hierarchy.md) — which rule
-  wins when several fire on the same turn (independent of context paths).

package/docs/contracts/context-spine.md

@@ -1,179 +0,0 @@
----
-stability: stable
----
-
-
-# Context-Spine Contract
-
-> **Status:** active · **Stability:** stable · **Owner:** unified-senior-roles Block K1
-> · **Lint gate:** `task lint-skills` (frontmatter shape only — slot semantics are author-side)
-
-Senior skills repeatedly need three slabs of context that the user
-already supplied earlier in the project: **what the product is**,
-**who the team is**, **what the repo looks like**. The context-spine
-mechanic captures those slabs once per project and lets every senior
-skill cite the slot it needs — without re-asking the user, without
-re-reading the manifest tree on every entry.
-
-## § 1 — Purpose
-
-Three failure modes the spine prevents:
-
-1. **Repeat-the-context tax** — every senior skill restates "what is
-   this project / what does the team do / where does the code live"
-   to the user. The spine factors that into shared slots.
-2. **Implicit-read drift** — a skill silently reads `composer.json` /
-   `README.md` / `package.json` to infer context, gets stale
-   information, and bakes it into the artifact. Spine reads are
-   **opt-in via frontmatter**, never implicit.
-3. **Cross-role bikeshed** — Wave-2 personas (Block N) and Wing-3 / 4
-   senior skills argue over whose context-doc is canonical. The spine
-   names three slots and freezes the count.
-
-## § 2 — Slot definitions
-
-The spine has **three cross-wing slots** plus **per-wing extension
-slots** authorized via ADR. Council Q1 verdict (2026-05-05, KEEP-3)
-locks the cross-wing slot count at 3. Per-wing extensions follow § 5.
-
-### Cross-wing slots (locked at 3)
-
-| Slot | Path under `agents/context-spine/` | Owner | Typical content |
-|---|---|---|---|
-| `product` | `product.md` | Product / discovery wing | What the product **is**, who it serves, the problem it solves, the JTBD framing, the bounded scope. Read by Block-L senior PO / discovery skills. |
-| `team` | `team.md` | RevOps / maintainer wing | Who **maintains** this codebase, how decisions are made, review-routing conventions, cadence (release rhythm, planning ritual). Read by review-routing, finishing-a-development-branch, persona overrides. |
-| `repo` | `repo.md` | Engineering wing | What the codebase **is** at the file-tree level: stack one-liner, primary languages, top-level module map, deploy target. Read by analysis skills, blast-radius-analyzer, project-analysis-* skills. |
-
-### Wing-3 slots (GTM and Growth — added 2026-05-13 per [`adr-gtm-context-spine.md`](adr-gtm-context-spine.md))
-
-| Slot | Path under `agents/context-spine/` | Owner | Typical content |
-|---|---|---|---|
-| `channel-stage` | `channel-stage.md` | GTM / Marketing wing | Which channels the GTM motion uses (awareness · consideration · decision · retention · expansion), per-channel maturity, channel-cost band. Read by `positioning-strategy`, `messaging-architecture`, `gtm-launch`, `editorial-calendar`. |
-| `funnel-stage` | `funnel-stage.md` | Growth / RevOps wing | Funnel topology (top / mid / bottom / activation / retention), per-stage definition, exit-criteria for each. Read by `pipeline-strategy`, `funnel-analysis`, `activation-design`, `onboarding-design`. |
-| `customer-segment` | `customer-segment.md` | Sales / CS wing | ICP, persona-by-segment, ARR-band-by-segment. Read by `ICP`, `pipeline-strategy`, `MEDDIC`, `retention-loops`. |
-
-### Wing-4 slots (Money / Strategy / Ops — added 2026-05-13 per [`adr-wing4-context-spine.md`](adr-wing4-context-spine.md))
-
-| Slot | Path under `agents/context-spine/` | Owner | Typical content |
-|---|---|---|---|
-| `fiscal-period` | `fiscal-period.md` | Finance wing | Reporting cadence (monthly · quarterly · annual · multi-year-plan), fiscal-year start, close-window timing. Read by `unit-economics`, `forecasting`, `runway-cognition`, `scenario-modeling`. |
-| `org-stage` | `org-stage.md` | Strategy / People wing | Stage label (seed · series-A · series-B · growth · public), funding posture, headcount band, governance posture. Read by `build-buy-partner`, `vision-articulation`, `org-design`, `comp-banding`, `hiring-loop-design`. |
-| `regulatory-regime` | `regulatory-regime.md` | Strategy wing (legal-absorbed) | Active regimes (none · GDPR · HIPAA · SOC2 · PCI · CCPA), data-residency posture, breach-notification timer. Read by `contracts-cognition`, `privacy-review`, `data-handling-judgment`. |
-
-Slots are markdown files. Each is **≤ 200 lines**; longer means the
-slot is doing two jobs and the author should split or trim. Empty /
-missing slot is allowed — the citing skill MUST handle absence
-gracefully and fall back to its existing read paths.
-
-## § 3 — Frontmatter opt-in
-
-A senior skill declares which slots it reads via the `context_spine`
-frontmatter array:
-
-```yaml
----
-name: customer-research
-tier: senior
-context_spine: [product, team]
-...
----
-```
-
-Rules:
-
-- The key is **optional**. Senior skills MAY ship without it; the
-  default (`[]`) means the skill does not read the spine.
-- Values are restricted to the slot names in § 2: cross-wing
-  (`product`, `team`, `repo`) plus wing-scoped extensions
-  (`channel-stage`, `funnel-stage`, `customer-segment`). Unknown
-  values fail `task lint-skills` with `unknown_context_spine_slot`.
-- Reads MUST be opt-in and explicit. A skill body that says *"reads
-  `agents/context-spine/product.md` if present"* without declaring
-  the slot in frontmatter is **incorrect** — it bypasses the lint
-  gate and the user's expectation that the spine read is visible.
-- The frontmatter value is the **contract**. The skill body cites
-  `agents/context-spine/<slot>.md` once near the top and lets the
-  reader follow the link if they care.
-
-## § 4 — No implicit reads
-
-The spine is a **discipline**, not a runtime. There is no Python
-loader that injects spine content into a skill's prompt. The agent
-loading a senior skill reads the skill body, sees the
-`context_spine: [...]` declaration, and — if the slot files exist
-— quotes them inline before executing the skill's procedure. The
-skill body MUST NOT state a behavior that depends on the spine being
-read; absence is recoverable, presence is a bonus.
-
-This keeps the spine cheap (no orchestration plumbing), explicit
-(every read is in frontmatter), and reversible (deleting the slot
-file does not break the skill).
-
-## § 5 — Slot-add policy
-
-Two tracks: **cross-wing** (locked at 3, citations-first) and
-**wing-scoped** (per-wing ADR, citations prospective).
-
-### Cross-wing track — citations-first
-
-Adding a fourth **cross-wing** slot (one every wing might read) is
-**structurally allowed but procedurally expensive**. Two preconditions:
-
-1. **Citation evidence.** ≥ 2 shipped senior skills declare the new
-   slot in their frontmatter and cite it in the body, with PRs
-   merged to `main`. Drafts and roadmap items do not count.
-2. **ADR.** A new ADR under `docs/contracts/` named
-   `adr-context-spine-slot-<name>.md` documents the cognition gap
-   the existing three slots cannot fill, the slot's owner wing, and
-   the migration plan for the existing senior catalog (do they
-   declare the new slot, do they ignore it, do they get retrofitted).
-
-### Wing-scoped track — per-wing ADR, prospective citations
-
-A wing may add **its own slots** for cognition specific to that wing
-(e.g. Wing-3 `channel-stage`, `funnel-stage`, `customer-segment`).
-Preconditions:
-
-1. **Per-wing ADR.** One ADR under `docs/contracts/` named
-   `adr-<wing>-context-spine.md` names the slots, the cognition gap,
-   the citing-skill chain in the same iteration, and the off-wing
-   migration plan (off-wing skills do **not** retrofit).
-2. **Prospective citations.** The ADR-naming iteration must ship
-   ≥ 2 skills citing each new slot before the iteration closes.
-   Drafts and roadmap items inside the same iteration **do** count
-   for prospective gating; cross-iteration citations do not.
-
-Existing wing-3 reference: [`adr-gtm-context-spine.md`](adr-gtm-context-spine.md).
-
-### Schema and changelog rules — both tracks
-
-The ADR ships with the schema bump (`scripts/schemas/skill.schema.json`
-extends the `context_spine` enum) and a CHANGELOG entry under
-`### Breaking` if the new enum value tightens an existing skill's
-declaration.
-
-This policy mitigates the slot-sprawl failure mode: "cross-wing
-locked at 3 + wing-scoped via per-wing ADR" is the brake. ADRs are
-the single growth lever; no consumer-side override exists.
-
-## § 6 — Author checklist
-
-Before shipping a senior skill that opts into the spine:
-
-- [ ] Frontmatter declares `context_spine:` with values from the
-      cross-wing slots (`product`, `team`, `repo`) and/or wing-scoped
-      slots authorized via per-wing ADR (e.g. Wing-3:
-      `channel-stage`, `funnel-stage`, `customer-segment`).
-- [ ] Skill body cites `agents/context-spine/<slot>.md` near the top
-      (one link per declared slot).
-- [ ] Procedure handles missing-slot gracefully — falls back to the
-      skill's existing read path, never errors out.
-- [ ] `task lint-skills` passes with no `unknown_context_spine_slot`.
-
-## See also
-
-- `.agent-src.uncondensed/rules/skill-quality.md` § Senior-Tier
-  Required Structure — the four blocks every `tier: senior` skill
-  ships independently of spine opt-in.
-- `docs/contracts/cross-wing-handoff.md` — typed handoffs between
-  senior skills; orthogonal to the spine (composition vs context).

package/docs/contracts/cost-dashboard.md

@@ -1,143 +0,0 @@
----
-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`](../../dist/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

@@ -1,134 +0,0 @@
----
-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
-
-- an internal parity roadmap (local-only) — Measurement & Governance Parity roadmap.
-- `docs/contracts/cost-dashboard.md` — companion dashboard contract.
-- `scripts/cost/budget.mjs` — evaluator implementation.
-- `internal/bench/pricing.yaml` — per-model USD pricing table.