@event4u/agent-config 2.18.0 → 2.20.0

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

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/user-type-schema.md

@@ -0,0 +1,146 @@
+---
+stability: beta
+keep-beta-until: 2026-08-14
+---
+
+# User-type Schema — runtime review-lens axis
+
+> **Status:** active · **Stability:** beta · **Owner:** step-6-user-types-axis
+> · **Linter:** `scripts/skill_linter.py § lint_usertype`
+> · **Source-of-truth dir:** `.agent-src.uncompressed/user-types/`
+> · **Sibling axis (distinct):** install-time `user-types/` (package root) — see [`adr-install-user-type-axis`](adr-install-user-type-axis.md)
+> · **ADR:** [`adr-user-types-axis`](adr-user-types-axis.md)
+
+Locks the canonical user-type shape. A user-type is a **runtime review
+lens** simulating a real end-user of the software under review (a
+galabau field crew, a metalworking shop, a truck driver). It is the
+twin of `personas/` along a different axis: persona = *how* we review
+(methodology — qa, senior-engineer); user-type = *who* we simulate
+(end-user — domain workflow + operational reality).
+
+## § 1 — Frontmatter
+
+| Key | Type | Required | Notes |
+|---|---|---|---|
+| `id` | string | yes | lowercase-hyphenated, must match filename stem |
+| `kind` | const `user-type` | yes | discriminator — locks this file as a review-lens user-type, separates it from the install-time user-type-axis YAMLs |
+| `description` | string | yes | one sentence, ≤ 160 chars (linter cap matches persona) |
+| `version` | string | yes | semver; bump on breaking changes |
+| `source` | enum | yes | `package` \| `project` — project-specific is the typical case (consumer-domain end-users) |
+
+`user-types:` is NOT a skill-frontmatter key in v1. The axis is
+CLI-only (`/refine-ticket --user-type=<id>`). Skill-level defaults are
+deferred to v2 — see [`adr-user-types-axis`](adr-user-types-axis.md).
+
+## § 2 — Required section spine (locked)
+
+User-types share the spine across the axis — no Core/Specialist split,
+no tier enum. Every user-type carries all seven sections:
+
+1. **Focus** — one paragraph. Who this lens is, the operational
+   context they work in, and what no other lens catches. End with one
+   sentence pinning the boundary: review-lens only, never operational
+   instruction source.
+2. **Daily Workflow** — concrete day-shape, not generic prose. What
+   they do at 06:00, 10:00, 15:00; what they look at, what they touch,
+   what they wait for.
+3. **Vocabulary** — domain terms the software must use (or must NOT
+   substitute). Bilingual where the trade is bilingual. Plain-language
+   over engineer-language where the user is non-technical.
+4. **Operational Constraints** — mobile / offline / gloves / noise /
+   PPE / time pressure / connectivity / lighting / dead-zones /
+   hours-of-service / break-windows / shop-floor vs office split.
+   Each constraint is a UI / flow signal, not generic empathy.
+5. **Unique Questions** — ≥ 3 questions no persona asks verbatim.
+   Each must be falsifiable against the ticket under review. (Linter
+   warns < 3, matches persona heuristic.)
+6. **Ticket Red Flags** — what this lens would flag as missing or
+   unrealistic when reviewing a ticket. Bullet list, each item names a
+   concrete signal a generic reviewer would miss.
+7. **Anti-Patterns** — what this lens must refuse to do. Guardrails
+   are non-negotiable here: **review-only, never operational
+   instruction**. No trade execution (welding procedure, electrical
+   work, structural advice). No dangerous how-to. No medical / legal
+   / engineering advice. Generic prose ("consider usability") is
+   itself an anti-pattern.
+
+`Composes well with` is permitted as an optional eighth section
+(advisory pairings with personas), not budget-counted.
+
+## § 3 — Size budget
+
+| Section count | Line cap | Rationale |
+|---|---|---|
+| 7 | ≤ 120 | Matches the persona core budget. Spine is wider than a
+core persona (7 vs 5 sections) but narrower than a wing-3/4 specialist
+(no Critical Rules + Workflows blocks). 120 is the larger of the two
+candidate caps and the persona core uses it for a 5-section spine —
+the extra two sections need the headroom. |
+
+Enforced by `lint-skills` against the full file including frontmatter
+and trailing blank line.
+
+## § 4 — Anti-Generic Quality Bar (merge gate)
+
+Every user-type must encode **≥ 5 concrete, domain-specific review
+points** across `Daily Workflow`, `Vocabulary`, `Operational
+Constraints`, and `Ticket Red Flags`. Generic prose is REJECTED at
+lint or review time:
+
+- ❌ "consider mobile usability"  →  ✅ "capacitive touch fails with
+  wet leather gloves at 4 °C; tap targets ≥ 60 px or voice command"
+- ❌ "think about offline"  →  ✅ "no signal in cellar yards; queue
+  changes locally, conflict-resolve on the morning brief"
+- ❌ "users want reports"  →  ✅ "end-of-day proof = timestamped photo
+  + customer signature + GPS fix; anything less is a billing dispute"
+
+The Reviewer test: a generic reviewer persona could not have produced
+the `Unique Questions` or `Ticket Red Flags` of this file. If they
+could, the file is generic.
+
+## § 5 — Guardrails (encoded in every Anti-Patterns block)
+
+User-types are review lenses, not operational manuals. Every file's
+`## Anti-Patterns` section MUST explicitly forbid:
+
+- Trade-execution instructions (welding procedure, electrical work,
+  structural advice, anything that could harm if followed)
+- Dangerous how-to (chemical handling, equipment operation, work-at-
+  height procedures)
+- Medical / legal / engineering advice that requires a licensed
+  practitioner
+
+Allowed and encouraged: workflow realism, ticket gap analysis,
+terminology correction, mobile / offline / safety / approval signals
+as ticket-requirement signals.
+
+## § 6 — Schema enforcement
+
+The linter (`scripts/skill_linter.py § lint_usertype`) enforces:
+
+- frontmatter shape (table in § 1)
+- `kind` const value
+- required sections per § 2
+- size budget per § 3
+- ≥ 3 bullets in `Unique Questions`
+- `id` matches filename stem
+- description ≤ 160 chars
+
+Authors must use the template at
+`.agent-src.uncompressed/user-types/_template/user-type.md`.
+
+## § 7 — Versioning
+
+Section rename / add / remove → ADR + linter update + user-type
+migrations in the same PR. Size-cap tightening is breaking when it
+forces existing user-types to lose content; size-cap loosening is
+non-breaking. The `kind` const is locked — renaming requires a major
+version bump and a separate ADR.
+
+## See also
+
+- [`persona-schema`](persona-schema.md) — sister axis (methodology vs end-user)
+- [`adr-user-types-axis`](adr-user-types-axis.md) — why the axis split exists
+- [`adr-install-user-type-axis`](adr-install-user-type-axis.md) — the install-time `user_type` axis (distinct layer, same vocabulary)
+- `.agent-src.uncompressed/user-types/README.md` — authoring entry point
+- `.agent-src.uncompressed/user-types/_template/user-type.md` — template starter