@event4u/agent-config 2.19.0 → 2.20.0

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.

package/docs/contracts/profile-system.md

@@ -0,0 +1,142 @@
+---
+stability: beta
+keep-beta-until: 2026-08-14
+---
+
+# Profile System — Contract
+
+> **Status:** beta · **Owner:** package maintainer · **Last reviewed:** 2026-05-16
+>
+> Schema and semantics for the **Profile** axis introduced in step-15
+> Phase 1 item 1. Profile answers *who is the user?* — audience
+> taxonomy that selects the default skill/command surface, README
+> entry-paragraph, and persona pre-selection. Boundary against
+> `preset.id`, `pack.id`, and `cost_profile`:
+> [`ADR-010`](../decisions/ADR-010-profile-pack-preset-boundary.md).
+
+## Decision
+
+A **profile** declares the user's audience identity. Six seed profiles
+ship; users can declare their own under
+`.agent-src.uncompressed/profiles/<id>.yml`.
+
+| `profile.id` | Audience | README entry-paragraph | Default `preset.id` |
+|---|---|---|---|
+| `founder` | Solo / early-stage founder; wears every hat | "Ship the company, not the codebase" | `fast` |
+| `developer` | IC engineer; primary day-to-day user today | "Pair with a senior reviewer that never sleeps" | `balanced` |
+| `content_creator` | Writers, ghostwriters, marketers | "Your voice, my hands" | `balanced` |
+| `agency` | Multi-client delivery shop | "Same playbook across every client repo" | `strict` |
+| `finance` | CFO / fractional finance / FP&A | "Forecasts and memos with the receipts attached" | `strict` |
+| `ops` | RevOps, support, SRE-adjacent | "Procedures that get followed, not skipped" | `strict` |
+
+The seed set is **fixed for v2.x**. Adding a seventh profile requires
+an ADR — the contract surface that ships in the wizard
+(`/onboard` role-selection) treats this set as exhaustive.
+
+## Profile shape
+
+```yaml
+profile:
+  id: developer
+  audience:
+    label: "IC engineer"
+    readme_anchor: "developer"          # selects README first-screen block
+  defaults:
+    preset_id: balanced                  # may be overridden by .agent-settings.yml
+    personas: [reviewer, security]       # pre-selected persona ids
+    skills_hint: [developer-like-execution, verify-before-complete, minimal-safe-diff]
+  surface:
+    commands_hint: [work, implement-ticket, review-changes, fix]
+    docs_first_pointer: "docs/getting-started-by-role.md#developer"
+```
+
+Per [ADR-010](../decisions/ADR-010-profile-pack-preset-boundary.md), a
+profile **MAY** set `defaults.preset_id` but **MAY NOT** set any
+preset-owned knob directly. The lint task (`task lint-config-schema`)
+enforces this.
+
+## Loader contract
+
+The Phase 1 loader lives at `scripts/config/profiles.py`. Resolution
+chain (last writer wins):
+
+1. `pack.profile_id` (if pack active) → `profile.id`.
+2. `.agent-settings.yml` top-level `profile:` block → `profile.id`
+   and any user overrides for `audience` / `defaults` / `surface`.
+3. Environment variable `AGENT_CONFIG_PROFILE_ID` → `profile.id`.
+4. Runtime CLI flag `--profile=<id>` → `profile.id`, single session.
+
+If no profile resolves, the loader **does not pick a default
+silently** — it falls back to `developer` only when
+`.agent-settings.yml` is missing entirely (fresh install before
+`/onboard`). With a settings file present but no `profile:` block,
+the loader raises a structured warning pointing to `/onboard`.
+
+```
+RATIONALE: a silent default would hide the "I never picked an audience"
+state from the wizard, breaking the council v3 observation that audience
+choice must be a deliberate act of the user, not an agent inference.
+```
+
+## Resolution outcome
+
+After the loader runs, the session has:
+
+```python
+{
+  "id": "developer",
+  "audience": {"label": "IC engineer", "readme_anchor": "developer"},
+  "preset_id": "balanced",
+  "personas": ["reviewer", "security"],
+  "skills_hint": ["developer-like-execution", ...],
+  "commands_hint": ["work", "implement-ticket", ...],
+  "source": "user-settings | env | runtime | pack | default",
+}
+```
+
+The `source` field is mandatory and feeds the
+`/agent-config explain`
+command (Phase 1 item 3).
+
+## User-defined profiles
+
+A consumer project MAY ship a custom profile under
+`.agent-src.uncompressed/profiles/<id>.yml`. Constraints:
+
+- `id` MUST be unique across seed + user-defined profiles.
+- Shape MUST match the seed contract above (audience / defaults / surface).
+- `defaults.preset_id` MUST reference an existing preset
+  ([`config-presets.md`](config-presets.md)).
+- The lint task hard-fails on schema violations.
+
+User-defined profiles do **not** require an ADR — they are project-local.
+Only changes to the **seed set** require an ADR.
+
+## Drift detection
+
+`task lint-config-schema` (added in Phase 1) hard-fails when:
+
+- A profile YAML names a preset-owned knob (cost cap, autonomy,
+  confidence, risk).
+- A profile YAML references a non-existent `preset_id`.
+- The seed-profile count diverges from this contract's table.
+- `defaults.personas` references a persona id that does not exist
+  under `.agent-src.uncompressed/personas/`.
+
+## Non-goals
+
+- This contract does **not** define preset knobs. See
+  [`config-presets.md`](config-presets.md).
+- It does **not** define packs. See `workflow-packs.md` (Phase 2 item 7).
+- It does **not** override `cost_profile`. The rule-tier loader keeps
+  its independent axis per
+  [`cost-profile-defaults.md`](cost-profile-defaults.md).
+- It does **not** ship a UI. Profile selection happens in `/onboard`
+  (step-15 Phase 1 item 2).
+
+## See also
+
+- [`ADR-010`](../decisions/ADR-010-profile-pack-preset-boundary.md) — axis boundary.
+- [`config-presets.md`](config-presets.md) — preset knobs.
+- [`cost-profile-defaults.md`](cost-profile-defaults.md) — rule-tier axis (orthogonal).
+- `step-15-product-refinement` — Phase 1 item 1.

package/docs/contracts/safety-model.md

@@ -0,0 +1,129 @@
+---
+stability: beta
+keep-beta-until: 2026-08-12
+---
+
+# Universal safety model
+
+> **Status:** beta — first draft 2026-05-16 (Phase 2 Item 9 of
+> `step-15-product-refinement`).
+>
+> **Baseline:** [`docs/architecture/current-safety-behavior.md`](../architecture/current-safety-behavior.md)
+> documents the pre-step-15 surface this contract replaces.
+
+A **per-profile, per-domain safety policy** declared as a single
+machine-readable table. Replaces the legacy "one autonomy switch for
+everything" model documented in the baseline. Does **not** weaken the
+four non-overridable floors — those keep their universal scope and
+are referenced by id, not redeclared here.
+
+## The Iron Floor
+
+```
+NO POLICY ENTRY MAY WIDEN AN EXISTING FLOOR.
+ANY ENTRY THAT WOULD ALLOW A FLOOR-BLOCKED ACTION IS REJECTED AT LINT.
+```
+
+The four floors are listed in
+[`current-safety-behavior § The four non-overridable floors`](../architecture/current-safety-behavior.md#the-four-non-overridable-floors):
+`non-destructive-by-default`, `scope-control § git-ops`,
+`commit-policy`, `security-sensitive-stop`. Floor membership is
+maintained in [`kernel-membership`](kernel-membership.md); a domain
+listed there cannot be set to `allow` here.
+
+## Schema
+
+```yaml
+# .agent-src.uncompressed/profiles/<id>.yml — new top-level key
+profile:
+  id: <profile.id>
+  # ... existing fields ...
+  safety:
+    domains:
+      <domain-id>:
+        policy: <deny | ask | allow>
+        rationale: "<= 280 chars — why this policy for this profile>"
+```
+
+### Domain registry
+
+Domains are declared in this contract, **not** invented per profile.
+A profile may only reference an id from the table below.
+
+| Domain id | What it gates | Floor reference |
+|---|---|---|
+| `prod_data` | Reads / writes against production data stores. | `non-destructive-by-default` |
+| `prod_infra` | Terraform / k8s / cloud config touching prod. | `non-destructive-by-default` |
+| `secrets` | Secret values in env, config, or output. | `security-sensitive-stop` |
+| `auth_changes` | Auth, session, tenant-boundary, IAM edits. | `security-sensitive-stop` |
+| `billing` | Pricing, invoicing, refund, payout logic. | `security-sensitive-stop` |
+| `bulk_delete` | `rm -rf`, `DROP`, `TRUNCATE`, ≥ 5-file deletion. | `non-destructive-by-default` |
+| `git_push` | `git push` to any remote. | `scope-control § git-ops` |
+| `git_branch` | branch create / switch / delete. | `scope-control § git-ops` |
+| `commit` | Any git commit. | `commit-policy` |
+| `mcp_call_costly` | MCP / web / model call ≥ preset's `per_call_max_usd`. | — (advisory) |
+| `pii_redact` | PII redaction in support / finance / recruiting / marketing outputs. | `domain-safety-pii-*` |
+| `pii_log` | Logging of raw PII. | `domain-safety-logging-pii-floor` |
+| `legal_advice` | Output shaped as legal advice. | `domain-safety-disclaimer-legal` |
+| `medical_advice` | Output shaped as medical advice. | `domain-safety-disclaimer-medical` |
+| `financial_advice` | Investment / tax / valuation positions. | `domain-safety-disclaimer-financial` |
+| `pr_create` | Pull-request open / close / retarget. | `scope-control § git-ops` |
+| `deploy` | Deploy / release / tag / pipeline trigger. | `non-destructive-by-default` |
+
+### Policy semantics
+
+| Policy | Behaviour | Floor interaction |
+|---|---|---|
+| `deny` | The agent refuses. Numbered-option block surfaces the refusal and the rationale field; no override path. | `deny` is the default for every floor domain — it cannot be relaxed. |
+| `ask` | The agent stops and asks a single numbered question per [`user-interaction`](../../.agent-src/rules/user-interaction.md). One question per turn. | `ask` is the default for every floor domain in a profile that has not opted out — the floor remains operative even when `policy=allow` is set elsewhere. |
+| `allow` | The agent proceeds without asking. Trivial-question suppression applies. | `allow` is **forbidden** on any domain whose `Floor reference` column is non-empty. Linter rejects it. |
+
+The legacy single switch (`personal.autonomy`) is preserved as a
+**fallback** for any domain a profile does not declare — keeping
+existing installs functional while profiles migrate.
+
+## Resolution
+
+Order (last writer wins, subject to the Iron Floor):
+
+1. Domain default = `ask` for floor domains, `allow` otherwise.
+2. Profile `safety.domains.<id>.policy`.
+3. Active pack's profile (if `--pack <id>` is active).
+4. `.agent-settings.yml` user override under `profile.safety.domains`.
+
+The explain command at [`explain config`](../../.agent-src/scripts/agent-config)
+(Phase 1 Item 3 deliverable) surfaces the resolved policy per domain,
+with the writer source per row.
+
+## Validation
+
+`scripts/lint_safety_model.py` (Phase 2 deliverable — not yet
+shipped) fails CI on:
+
+- Unknown domain id.
+- `allow` on a floor-referenced domain.
+- Missing `rationale` (≤ 280 chars, plain prose).
+- Profile declaring `safety` without at least one entry.
+
+Until the linter lands, profiles are reviewed by hand at PR time.
+
+## What this contract does **not** do
+
+- **Does not** introduce new safety rules. Every domain row maps to
+  an existing rule or to advisory cost guidance.
+- **Does not** ship the loader. `scripts/config/safety.py` is a
+  Phase 2 deliverable deferred to its own step.
+- **Does not** override domain-safety output floors. PII redaction
+  and disclaimer rules apply regardless of `safety.domains.*` —
+  `policy=allow` on `pii_redact` means "do not ask before redacting",
+  not "skip redaction".
+- **Does not** authorize per-tool MCP overrides. Cost caps live in
+  [`config-presets`](config-presets.md).
+
+## See also
+
+- [`current-safety-behavior`](../architecture/current-safety-behavior.md) — pre-step-15 baseline (what this replaces)
+- [`config-presets`](config-presets.md) — cost caps and enforcement
+- [`profile-system`](profile-system.md) — profile axis
+- [`workflow-packs`](workflow-packs.md) — pack-level overrides
+- `step-15-product-refinement` § Phase 2 Item 9