@event4u/agent-config 2.19.0 → 2.20.1

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

package/docs/contracts/smoke-contracts.md

@@ -0,0 +1,144 @@
+---
+stability: beta
+keep-beta-until: 2026-08-14
+---
+
+# Smoke Contracts — Phase 3 of step-11-ruflo-parity
+
+> **Status:** active · **Owner:** step-11 Phase 3 · **Sibling:**
+> [`measurement-baseline.md`](measurement-baseline.md) (snapshot semantics)
+> · [`cost-enforcement.md`](cost-enforcement.md) (cost ladder)
+
+Per-tier smoke scripts validate the system's structural baselines on
+every PR that touches the tier. Each script is **fast** (≤ 30 s wall),
+**deterministic** (same input → same exit), and **measured** (baseline
+numbers come from `task smoke:*` on `main` at lock-in, not from claims).
+
+## § 1 — Runtime budget
+
+Every `scripts/smoke/<tier>.sh` honours:
+
+| Limit | Value | Rationale |
+|---|---:|---|
+| Wall time | ≤ 30 s | CI matrix slot; local dev iteration |
+| External I/O | none beyond filesystem | no network, no MCP |
+| Output | last line is the **baseline declaration** | parseable by CI summary |
+
+A smoke that approaches 30 s should be split into sub-smokes, not
+optimised in place.
+
+## § 2 — Path-trigger globs
+
+CI's `.github/workflows/smoke.yml` dispatches the right scripts based on
+the paths touched in the PR:
+
+| Tier | Globs that trigger | Script |
+|---|---|---|
+| kernel | `.agent-src.uncompressed/rules/**`, `.agent-src/rules/**`, `router.json`, `scripts/measure_rule_budget.py` | `scripts/smoke/kernel.sh` |
+| router | `router.json`, `.agent-src.uncompressed/rules/**`, `.agent-src.uncompressed/skills/**`, `docs/contracts/**`, `docs/guidelines/**` | `scripts/smoke/router.sh` |
+| schema | `.agent-src.uncompressed/skills/**`, `.agent-src.uncompressed/rules/**`, `scripts/schemas/**`, `scripts/skill_linter.py`, `scripts/validate_frontmatter.py` | `scripts/smoke/schema.sh` |
+| skills | `.agent-src.uncompressed/skills/**` | `scripts/smoke/skills.sh` |
+
+`task smoke` runs all four locally regardless of paths.
+
+## § 3 — Baseline declarations (locked 2026-05-16)
+
+Smoke baselines are **measured today**, not aspirational. They lock
+**regression**: a smoke goes red only if the count drifts the wrong way.
+Drift toward the ideal (fewer breaches, more fences) updates the
+constant in the script body and the row below.
+
+### § 3.1 — Kernel (`scripts/smoke/kernel.sh`)
+
+```
+9 kernel rules · 8 carry Iron-Law fences · 1 dispatch index · ≤ 2 budget breaches
+```
+
+- **9 kernel rules** — fixed by [`kernel-membership.md`](kernel-membership.md).
+- **8 carry Iron-Law fences** — measured 2026-05-16. `agent-authority`
+  is the **dispatch index** (priority table pointing at the other four
+  authority rules); it is structurally exempt from the Iron-Law-fence
+  requirement and listed in the script's `EXEMPT_FROM_FENCE` set.
+- **≤ 2 budget breaches** — `python3 scripts/measure_rule_budget.py
+  --kernel-budget-check` currently reports 2 breaches
+  (`kernel-bucket > 26000`, `no-cheap-questions > 4000`). The smoke
+  asserts the count does not grow; reductions update `EXPECTED_BREACHES`
+  in `scripts/smoke/kernel.sh`. See
+  `road-to-kernel-and-router.md`
+  for the path back to zero.
+
+### § 3.2 — Router (`scripts/smoke/router.sh`)
+
+```
+75 router ids · 0 broken rule pointers · 35 routes_to refs · 2 missing contracts
+```
+
+- **75 ids** — 9 kernel + 24 tier_1 + 42 tier_2; every id resolves to
+  `.agent-src/rules/<id>.md`.
+- **0 broken rule pointers** — hard assertion; smoke fails on any miss.
+- **35 routes_to refs** across tier_1 + tier_2; resolver honours the
+  four prefixes (`skill:`, `command:`, `guideline:`, `contract:`).
+- **2 missing contracts** — measured 2026-05-16:
+  `contract:artifact-engagement-flow`,
+  `contract:command-suggestion-flow`. Tracked separately under
+  ``step-11` Phase 4 (ADR layout)`;
+  smoke asserts the count is `≤ EXPECTED_MISSING_CONTRACTS=2`.
+
+### § 3.3 — Schema (`scripts/smoke/schema.sh`)
+
+```
+438 lintable artefacts · 0 schema FAILs · ≤ 92 warns
+```
+
+- **0 FAILs** — hard assertion. `scripts/skill_linter.py --all` returns
+  exit 0/1 (warns) but never 2 (fail).
+- **≤ 92 warns** — measured 2026-05-16; locks regression. Warns
+  trending down updates the constant.
+- **v2 schema (step-5) deferred** — when
+  `step-5-schema-rigor.md`
+  Phase 1 closes, this smoke gains a `model_tier` presence assertion;
+  Phase 3 adds `schema_version: "2"`. Until then, v1 schema in
+  `scripts/schemas/skill.schema.json` is the contract.
+
+### § 3.4 — Skills (`scripts/smoke/skills.sh`)
+
+```
+5/5 random skills resolve · frontmatter parses · name matches directory
+```
+
+- **5 random skills** picked deterministically (seed = epoch day) from
+  `.agent-src.uncompressed/skills/*/SKILL.md` and re-validated via
+  `scripts/validate_frontmatter.py`. `agent-config explain skill` is
+  **not** invoked — `explain` only supports `{config,rule,route}` today
+  ([`scripts/agent-config/cmd_explain.py`](../../scripts/agent-config/cmd_explain.py));
+  filesystem-resolution is the contract.
+
+## § 4 — Local invocation
+
+```bash
+task smoke            # all four
+task smoke:kernel     # individual tiers
+task smoke:router
+task smoke:schema
+task smoke:skills
+```
+
+Every script honours `SMOKE_QUIET=1` (suppresses table output, keeps
+the final baseline line) for CI summary parsing.
+
+## § 5 — Failure modes
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `kernel.sh` reports > 8 missing fences | Kernel rule lost its Iron Law block during edit | Restore the fence; update `EXEMPT_FROM_FENCE` only for new dispatch indexes |
+| `router.sh` reports > 0 broken pointers | `router.json` references an id without a rule file | Add the rule or remove the route — never edit the smoke baseline up |
+| `schema.sh` reports FAILs | A skill / rule lost a required field | Restore via [`scripts/schemas/skill.schema.json`](../../scripts/schemas/skill.schema.json) |
+| `skills.sh` 5/5 random sample fails | Hand-edit broke frontmatter or renamed directory without updating `name:` | Restore filename ↔ slug coupling |
+
+## § 6 — See also
+
+- [`measurement-baseline.md`](measurement-baseline.md) — measurement substrate.
+- [`cost-enforcement.md`](cost-enforcement.md) — cost ladder, sibling smoke surface.
+- [`kernel-membership.md`](kernel-membership.md) — the 9-rule kernel set.
+- [`rule-router.md`](rule-router.md) — router contract.
+- `road-to-kernel-and-router.md` — kernel budget reduction path.

package/docs/contracts/workflow-packs.md

@@ -0,0 +1,121 @@
+---
+stability: beta
+keep-beta-until: 2026-08-12
+---
+
+# Workflow packs
+
+> **Status:** beta — first draft 2026-05-16 (Phase 2 Item 7 of
+> `step-15-product-refinement`).
+
+A **workflow pack** bundles a `(profile + preset + command-set +
+skill-allowlist)` combination into a single YAML so a user can adopt
+the full opinionated stance for their role without picking five
+independent settings.
+
+Packs do **not** introduce new commands, skills, or rules. They are
+a **composition contract** — every reference must resolve to an
+existing artefact that has already passed its own contract / linter
+gates.
+
+## Schema
+
+```yaml
+# .agent-src.uncompressed/packs/<pack-id>.yml
+pack:
+  id: <pack-id>                      # kebab-case, file name without .yml
+  audience:
+    label: "<human-readable>"
+    one_liner: "<= 120 chars, what the pack does for the user>"
+  composition:
+    profile_id: <profile.id>         # MUST exist in profiles/
+    preset_id: <preset.id>           # MUST exist in presets/
+  surface:
+    commands_allowed:                # ≤ 12 — slash-command names without leading slash
+      - <command>
+    skills_allowed:                  # ≤ 15 — skill IDs from skills-catalog
+      - <skill>
+    personas:                        # ≤ 4 — persona IDs from personas/
+      - <persona>
+  rationale:                         # why this combination, not free-form notes
+    why_this_profile: "<one paragraph>"
+    why_this_preset: "<one paragraph>"
+    why_these_commands: "<one paragraph>"
+```
+
+### Field semantics
+
+| Field | Type | Required | Notes |
+|---|---|:-:|---|
+| `pack.id` | string | yes | Matches file stem. No collision with `profile.id` or `preset.id`. |
+| `composition.profile_id` | string | yes | Override applied to the chain documented in [`profile-system`](profile-system.md). Pack-supplied id wins over `.agent-settings.yml` only when the user explicitly opts in via `/onboard --pack <id>`. |
+| `composition.preset_id` | string | yes | Override applied to the chain documented in [`config-presets`](config-presets.md). Same opt-in semantics. |
+| `surface.commands_allowed` | list[string] | yes | Cap = **12**. Items must appear in [`command-clusters`](command-clusters.md). The pack does **not** disable other commands — the cap is for the wizard's first-screen rendering, not enforcement. |
+| `surface.skills_allowed` | list[string] | yes | Cap = **15**. Items must appear in `docs/skills-catalog.md`. Same render-only semantics. |
+| `surface.personas` | list[string] | yes | Cap = **4**. Items must appear in `.agent-src.uncompressed/personas/`. |
+| `rationale.*` | string | yes | Forces every pack to justify its composition in plain prose; reviewed at PR time, not at runtime. |
+
+## Resolution chain
+
+Packs are an **opt-in layer above the profile + preset chain**. The
+loader at `scripts/config/packs.py` (Phase 2 deliverable — not yet
+shipped) reads the pack iff:
+
+1. `--pack <id>` flag passed to `/onboard` or `agent-config init`, **or**
+2. `pack.id` set in `.agent-settings.yml` (written by `/onboard --pack`).
+
+When a pack is active:
+
+- `composition.profile_id` is passed to `profiles.load()` as
+  `pack_profile_id` (already wired — see `scripts/config/profiles.py`).
+- `composition.preset_id` is passed to `presets.load()` analogously.
+- `surface.*` lists override the rendered command / skill lists in
+  `/onboard` and in the README "Six entry paths" surface **for the
+  duration of the active pack only**.
+
+Removing a pack (`/onboard --pack none`) reverts to the underlying
+profile + preset defaults; **no data is lost**.
+
+## Validation
+
+`scripts/lint_packs.py` (Phase 2 deliverable — not yet shipped) fails
+CI on:
+
+- Missing required field.
+- `profile_id` / `preset_id` / `commands_allowed` / `skills_allowed`
+  / `personas` referencing an artefact that does not exist.
+- Cap violation (commands > 12, skills > 15, personas > 4).
+- `pack.id` collision with another pack, profile, or preset id.
+
+Until the linter lands, packs are reviewed by hand at PR time against
+this schema.
+
+## What packs do **not** do
+
+- **Do not** declare new commands. Use [`command-clusters`](command-clusters.md).
+- **Do not** modify rules. Use the kernel-rule edit process.
+- **Do not** override safety floors. Domain-safety rules
+  (`.agent-src.uncompressed/rules/domain-safety-*.md`) apply
+  unconditionally — packs cannot widen the deny-list.
+- **Do not** ship telemetry or usage hints. Packs are pure composition.
+
+## Seed packs
+
+Three packs ship at Phase 2 Item 7 close:
+
+| Pack id | Profile | Preset | One-liner |
+|---|---|---|---|
+| `founder-mvp` | `founder` | `fast` | Ship the MVP and the pitch deck in the same week. |
+| `content-engine` | `content_creator` | `balanced` | Editorial calendar, brand voice, and ghostwriter on one loop. |
+| `agency-delivery` | `agency` | `strict` | Multi-client refine → estimate → deliver with audit-grade trace. |
+
+Each pack lives at `.agent-src.uncompressed/packs/<id>.yml` and is
+covered by the validation rules above.
+
+## See also
+
+- [`profile-system`](profile-system.md) — profile axis (audience defaults)
+- [`config-presets`](config-presets.md) — preset axis (risk appetite)
+- [`command-clusters`](command-clusters.md) — verb axis (invocation)
+- [`command-taxonomy`](command-taxonomy.md) — discoverability axis
+- `step-15-product-refinement` § Phase 2 Item 7

package/docs/decisions/ADR-010-profile-pack-preset-boundary.md

@@ -0,0 +1,132 @@
+---
+adr: 010
+status: proposed
+date: 2026-05-16
+decision: profile-pack-preset-boundary
+supersedes: —
+superseded_by: —
+phase: v2.x · step-15 Phase 1 prerequisite
+---
+
+# ADR-010 — Profile / Pack / Preset Boundary
+
+## Status
+
+**Proposed** · 2026-05-16 · pending Phase 1 of
+[`agents/roadmaps/step-15-product-refinement.md`](../../agents/roadmaps/step-15-product-refinement.md).
+Council v3 action #2 (`agents/council-responses/2026-05-16-step-15-product-refinement-v3.json`): <!-- council-ref-allowed: ADR decision-trace to originating council response -->
+**"Profile / Pack / Preset boundary is undefined; Phase 2 will duplicate
+Phase 1 abstractions"**. Promoted from Phase 2 to Phase 1 prerequisite —
+the profile loader (Phase 1 item 1) cannot ship without the boundary.
+
+## Context
+
+Step-15 introduces three new configuration concepts:
+
+- **Profile** — Phase 1 item 1: `profile.id` ∈ {`founder`, `developer`,
+  `content_creator`, `agency`, `finance`, `ops`}.
+- **Preset** — Phase 1 item 4: `preset.id` ∈ {`fast`, `balanced`,
+  `strict`} bundling 12+ governance knobs (cost caps, confidence band,
+  block-on-risk, …).
+- **Pack** — Phase 2 item 7: workflow bundles (`founder-mvp`,
+  `content-engine`, `agency-delivery`) of `(profile + preset +
+  command-set + skill-allowlist)`.
+
+A pre-existing fourth concept is in play:
+
+- **`cost_profile`** — current setting in `.agent-settings.yml`, values
+  `minimal` / `balanced` / `full` / `custom`. Owns **rule-tier loading**
+  (kernel · kernel + tier-1 · kernel + tier-1 + tier-2). Contract:
+  [`docs/contracts/cost-profile-defaults.md`](../contracts/cost-profile-defaults.md).
+
+Without a written boundary, three failure modes are predictable:
+
+1. The preset loader re-implements rule-tier gating (overlap with
+   `cost_profile`).
+2. Packs ship duplicate `profile` + `preset` defaults that drift from
+   the canonical source.
+3. Three teams add knobs to three places, and a user picking
+   `developer + strict + founder-mvp` discovers contradicting values
+   at runtime.
+
+## Decision
+
+Four orthogonal axes, four owners, one resolution chain.
+
+| Axis | Answers | Owns | Identity key |
+|---|---|---|---|
+| **Profile** | *Who is the user?* (audience taxonomy) | Default skill/command surface; README entry-paragraph; persona pre-selection | `profile.id` |
+| **Preset** | *How cautious is this run?* (risk + cost + autonomy budget) | The 12+ governance knobs (per-call $ ceiling, confidence band, block-on-risk, autonomy default, council escalation, …) | `preset.id` |
+| **Pack** | *What bundle of skills + commands?* (workflow recipe) | A frozen `(profile, preset, allow_skills, allow_commands)` 4-tuple; nothing more | `pack.id` |
+| **Cost Profile** | *How many rules load?* (token budget) | Rule-tier loading at session start (kernel · +tier-1 · +tier-2) | `cost_profile` |
+
+### Resolution chain (read order, last writer wins)
+
+```
+pack  →  profile  →  preset  →  cost_profile  →  user/env/runtime overrides
+```
+
+- A **pack** declares defaults for `profile`, `preset`, and the
+  skill / command allowlists. It cannot set `cost_profile` (that
+  axis belongs to the rule-tier loader and is governed separately).
+- A **profile** declares defaults for `preset`, audience-specific
+  README pointer, persona pre-selection. It cannot set any preset
+  knob directly — only `preset.id`.
+- A **preset** owns the 12+ knobs. No other axis writes them.
+- A **cost_profile** owns rule-tier loading. No other axis writes it.
+- The user's `.agent-settings.yml`, environment variables, and
+  runtime CLI flags override every axis above them.
+
+### Non-overlap rules (Iron Law)
+
+```
+A KNOB BELONGS TO EXACTLY ONE AXIS.
+DUPLICATION ACROSS AXES IS A CONTRACT VIOLATION.
+```
+
+- A pack **may not** override a preset knob; it overrides `preset.id`.
+- A profile **may not** override a preset knob; it overrides `preset.id`.
+- A preset **may not** override `cost_profile`; the user does that.
+- The CI `task lint-config-schema` (added in Phase 1) hard-fails on a
+  pack/profile YAML that names any preset-owned knob.
+
+## Consequences
+
+### Positive
+
+- Phase 1 ships the profile loader against a fixed surface (`profile.id`
+  → audience + `preset.id` + persona). No 12-knob inheritance ambiguity.
+- Phase 1 item 4 (Config Presets) owns the knobs alone. The "Cost
+  Enforcement" section in [`config-presets.md`](../contracts/config-presets.md)
+  has a single home.
+- Phase 2 item 7 (Workflow Packs) is a 4-tuple, not a re-implementation
+  of profile + preset. Pack YAML stays under 30 lines.
+- `cost_profile` keeps its single-axis charter; this ADR explicitly
+  refuses to fold it into the preset layer.
+
+### Negative
+
+- One more concept on the install screen (`profile` + `preset` + `pack`
+  + `cost_profile` = four axes). Mitigated by: the wizard (Phase 1 item
+  2) only asks for **profile** + **stack** + **risk appetite** and
+  derives the rest. Packs are opt-in; `cost_profile` keeps its
+  `balanced` default.
+- A skill-allowlist conflict between a pack and a runtime CLI flag is
+  resolved by "runtime wins". Users on a pack who shadow-disable a
+  skill will not see it again until the override is removed.
+
+### Neutral
+
+- This ADR records the boundary; it does **not** specify the seed
+  values for any axis. Profile IDs live in
+  [`docs/contracts/profile-system.md`](../contracts/profile-system.md)
+  (Phase 1 item 1). Preset knobs live in
+  [`docs/contracts/config-presets.md`](../contracts/config-presets.md)
+  (Phase 1 item 4). Pack shape lives in `docs/contracts/workflow-packs.md`
+  (Phase 2 item 7).
+
+## See also
+
+- [`docs/contracts/cost-profile-defaults.md`](../contracts/cost-profile-defaults.md) — the existing `cost_profile` contract this ADR explicitly does **not** touch.
+- [`agents/roadmaps/step-15-product-refinement.md`](../../agents/roadmaps/step-15-product-refinement.md) — Phase 1 items 1, 4 and Phase 2 item 7.
+- [`agents/council-responses/2026-05-16-step-15-product-refinement-v3.json`](../../agents/council-responses/2026-05-16-step-15-product-refinement-v3.json) — Council v3 action #2 (origin). <!-- council-ref-allowed: ADR decision-trace to originating council response -->

package/docs/decisions/INDEX.md

@@ -13,6 +13,7 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-007](ADR-007-agent-discovery-scopes.md) | Global Default Install With Export Subcommand | accepted | 2026-05-12 | — |
 | [ADR-008](ADR-008-installed-tools-manifest.md) | Committed Installed Tools Manifest Separate From Settings | proposed | 2026-05-12 | — |
 | [ADR-009](ADR-009-event4u-namespace.md) | Event4U Namespace And Claude Desktop Zip Bundles | accepted | 2026-05-13 | — |
+| [ADR-010](ADR-010-profile-pack-preset-boundary.md) | Profile Pack Preset Boundary | proposed | 2026-05-16 | — |
 
 ## Unnumbered (legacy)