@event4u/agent-config 2.16.0 → 2.17.0

package/docs/contracts/ghostwriter-schema.md

@@ -0,0 +1,337 @@
+---
+stability: beta
+keep-beta-until: 2026-08-13
+---
+
+# `ghostwriter/<slug>.md` schema (v1)
+
+> **Status:** beta — locked for the `/ghostwriter` cluster roadmap.
+> Re-evaluate fields after the cluster has shipped + been in use
+> for ≥ 1 week.
+
+A **ghostwriter profile** is a single Markdown file that captures the
+public writing voice of a documented public figure so the `/ghostwriter:write`
+and `/post-as:ghostwriter` commands can emit copyable drafts in that
+voice. Ghostwriter is the third voice primitive in the package, peer
+to `personas/*.md` (review-lens, internal) and `.agent-user.md` (the
+maintainer themselves).
+
+The file is owned by the user. The agent never edits it without an
+explicit `accept` step on `/ghostwriter:fetch` re-runs.
+
+## Storage model (dual)
+
+- **Consumer projects** — `agents/ghostwriter/<slug>.md`. Real-person
+  profiles live here. **Gitignored by default** via the package-managed
+  `.gitignore` block. A `--shared` opt-in to commit profiles is
+  deferred to v2; only the doc note lands in v1.
+- **Package source** — `.agent-src.uncompressed/ghostwriter/` ships
+  the README, this schema doc, and `fictional: true` fixtures only.
+  **Zero real-person profiles ever ship with the OSS package.** A CI
+  lint (`task lint-ghostwriter-source`) enforces this rule by failing
+  on any non-allowlisted file or any file lacking the `fictional: true`
+  frontmatter key.
+
+Slug = full-name kebab-case (`alice-walker`). Optional `-<discriminator>`
+suffix for disambiguation (`alice-walker-novelist` vs `alice-walker-cyclist`).
+Namespace conflict resolution is consumer-owned — the package does not
+deduplicate across consumers.
+
+## Locked frontmatter (v1)
+
+```yaml
+---
+version: 1
+fictional: false             # required — true for package-side fixtures, false for real-person consumer profiles
+identity:
+  name: "Alice Walker"       # required — public name
+  role_or_title: "novelist"  # required — short role label
+  era: "1944–"               # optional — birth–death range; "1944–" if living
+  public_figure_category: "public_artist"  # required — enum below
+  source_urls:               # required — public sources only, ≥ 3 distinct items
+    - "https://example.org/walker/interview-1"
+    - "https://example.org/walker/essay-collection"
+    - "https://example.org/walker/lecture-2018"
+  fetched_at: "2026-05-15"   # required — ISO date of last fetch
+  confidence: "med"          # required — low | med | high (see § Confidence)
+  attestation_recorded_at: "2026-05-15T10:00:00Z"  # required — when the user attested (NOT consent, see § Ethics floor)
+aliases:                     # optional, consumer-only — alternative names that resolve to this slug
+  - "Hawking"                # case-insensitive match, case-preserving storage
+  - "Prof. Hawking"          # min 2 chars, no homoglyphs (see § Aliases)
+style:
+  fingerprint:
+    sentence_length_avg: 18  # avg words per sentence across samples
+    vocab_register: "literary"  # casual | conversational | professional | literary | academic
+    opener_patterns: ["personal anecdote", "rhetorical question"]
+    closer_patterns: ["call to reflection", "quoted aphorism"]
+    hashtag_rules: "never"   # always | sometimes | never
+    emoji_rules: "never"     # always | sometimes | never
+    paragraph_cadence: "long-form, 4–6 sentence paragraphs"
+  free_form_notes: |
+    Tends to weave personal narrative with broader social observation.
+    Rarely uses imperatives; prefers invitations.
+voice_samples:               # required — max 3 items, each ≤ 200 words, source-attributed
+  - source_url: "https://example.org/walker/interview-1"
+    length_words: 142
+    text: |
+      [actual public excerpt, max 200 words]
+taboos:                      # required — what the target never does in public writing
+  - "political endorsements"
+  - "profanity"
+  - "hashtag-driven posts"
+source_provenance:           # required
+  count: 3                   # number of distinct source URLs
+  last_fetched_at: "2026-05-15"
+  types: ["interview", "essay", "lecture"]  # platforms/formats represented
+  verification: "fetched"    # required — fetched | user-asserted (see § Verification)
+last_updated: "2026-05-15"   # YYYY-MM-DD — bumped on every accepted change
+---
+```
+
+After the frontmatter, the body is a single freeform **`# Notes`**
+section for the user's own observations on the profile. Hard cap:
+**200 lines** total file size (frontmatter + body + Notes).
+
+## Field reference
+
+| Field | Required | Purpose |
+|---|---|---|
+| `version` | yes | Schema version. v1 is the only valid value today. |
+| `fictional` | yes | `true` for package fixtures, `false` for real-person consumer profiles. Drives `task lint-ghostwriter-source`. |
+| `identity.name` | yes | Public name of the figure. |
+| `identity.role_or_title` | yes | Short role label (novelist, executive, …). |
+| `identity.era` | no | Birth–death range. Trailing `–` for living figures. |
+| `identity.public_figure_category` | yes | Enum: `author` \| `executive` \| `academic` \| `politician` \| `journalist` \| `public_speaker` \| `public_artist` \| `deceased_historical`. |
+| `identity.source_urls` | yes | ≥ 3 public source URLs. Drives `confidence`. |
+| `identity.fetched_at` | yes | ISO date of the most recent fetch. |
+| `identity.confidence` | yes | `low` \| `med` \| `high` — derived from source count/diversity. |
+| `identity.attestation_recorded_at` | yes | ISO timestamp the user attested the public-figure gate. |
+| `aliases` | no | Consumer-only list of alternative names that resolve to this profile's slug. See [§ Aliases](#aliases). Banned on `fictional: true` fixtures. |
+| `style.fingerprint.*` | yes | Structured shape of the voice. All sub-fields required. |
+| `style.free_form_notes` | yes | Free-form supplement to the structured fingerprint. |
+| `voice_samples` | yes | Max 3 items; each `≤ 200 words`; each source-attributed. |
+| `taboos` | yes | What the target never does — feeds the write engine's negative-constraint pass. |
+| `source_provenance.count` | yes | Distinct source URLs. |
+| `source_provenance.last_fetched_at` | yes | ISO date — drives the 90-day stale warning. |
+| `source_provenance.types` | yes | Platforms/formats (interview, essay, post, book, …). |
+| `source_provenance.verification` | yes | `fetched` (host agent retrieved) \| `user-asserted` (user pasted; not verifiable). |
+| `last_updated` | yes | ISO date, bumped on every accept. |
+
+## Confidence
+
+Derived deterministically from `source_provenance.count` and `types`:
+
+| Sources × types | Confidence |
+|---|---|
+| 3 sources, same platform | `low` |
+| 3+ sources, 2+ platforms | `med` |
+| 5+ sources, 3+ platforms, ≥ 1 canonical (Wikipedia / official site / published book) | `high` |
+
+`/ghostwriter:fetch` refuses to write a profile with fewer than 3 distinct
+authoritative sources.
+
+
+## Aliases
+
+`aliases` is an **optional, consumer-only** field listing alternative
+names that resolve to this profile's slug. It is a portability win
+over per-user shell aliases — team-shared profiles become immediately
+usable without per-developer config.
+
+The list is read by `/ghostwriter:write --as=<value>` (and the
+`/post-as:ghostwriter` thin alias) when resolving the style source:
+
+1. Exact slug match (case-insensitive on filename stem).
+2. **If no slug match**, scan every consumer profile's `aliases` list
+   for a case-insensitive equality match against `<value>`.
+3. If neither matches, fall through to the interactive numbered menu.
+
+### Storage rules
+
+- **Case-insensitive match, case-preserving storage** — the resolver
+  treats `--as=hawking` and `--as=Hawking` as identical, but the YAML
+  preserves the author's chosen casing.
+- **Minimum length: 2 characters** — single-character aliases are
+  collision magnets and are rejected by the consumer-side lint.
+- **No homoglyphs** — aliases must use Latin script (ASCII letters,
+  digits, common punctuation, common Latin diacritics). Cyrillic,
+  Greek, or other confusable scripts are rejected. Prevents spoofing
+  like `Stephеn` (Cyrillic `е`) shadowing `Stephen`.
+- **Case-insensitive uniqueness within a profile** — a single profile
+  cannot list both `"Hawking"` and `"hawking"`.
+- **Case-insensitive uniqueness across consumer profiles** — two
+  different profiles in the same consumer tree cannot share an alias
+  (including alias-vs-slug collisions). Conflicts fail the consumer-side
+  lint (Option B — lint-time rejection, never a runtime disambiguation
+  menu). Determinism contract trumps UX convenience.
+
+### Footer integrity (canonical name only)
+
+The mandatory [disclosure footer](#mandatory-disclosure-footer-deterministic)
+**always** uses `identity.name`, never the alias that triggered the
+command. A user invoking `/ghostwriter:write --as=Hawking` against a
+profile with `identity.name: "Stephen Hawking"` produces a footer
+reading *"Written in the style of Stephen Hawking, not by them."* —
+not *"…of Hawking, not by them."* This makes aliases UX-only; identity
+attribution stays deterministic.
+
+### Package-source ban
+
+`aliases:` is **forbidden** on any file with `fictional: true`. Package
+fixtures are schema examples for a single canonical name; aliases are a
+consumer-only deployment feature. The package-source lint
+(`task lint-ghostwriter-source`) fails on `aliases:` in
+`.agent-src.uncompressed/ghostwriter/`.
+
+### Settings toggle (consumer-only)
+
+The consumer enables alias resolution via `.agent-project-settings.yml`:
+
+```yaml
+ghostwriter:
+  aliases: true   # default: true — set to false to disable resolver
+```
+
+Toggling `aliases: false` makes `/ghostwriter:write --as=<value>` resolve
+against slug names only; any `aliases:` entries in profiles are ignored
+at resolve time (but the lint still validates them on commit).
+
+## Verification
+
+`source_provenance.verification` distinguishes two acquisition paths:
+
+- `fetched` — the host agent retrieved the source URLs via its built-in
+  web-fetch / web-search capability. Default for `/ghostwriter:fetch`.
+- `user-asserted` — the host agent could not fetch and the user pasted
+  the material manually. The package cannot independently verify these
+  sources. `/ghostwriter:show` surfaces user-asserted profiles with a
+  visible `⚠️ user-asserted sources — not independently verified` line.
+
+This split exists because the package contains zero network code (see
+[§ Determinism floor](#determinism-floor)); the agent cannot otherwise
+distinguish first-party fetch from paste-and-trust.
+
+## Ethics floor
+
+### Public-figure-only gate (advisory)
+
+Before `/ghostwriter:fetch` writes any file, the user must explicitly
+attest that:
+
+1. The target is a documented public figure with a public-facing role
+   matching `public_figure_category`.
+2. The source URLs are public, not paywalled, not login-walled, not
+   leaked, not retracted.
+3. The user accepts the right-of-publicity and defamation surface — the
+   user owns the legal call, not the package.
+4. The user understands the disclosure footer on every `/ghostwriter:write`
+   output is non-removable.
+
+The attestation timestamp is recorded in `identity.attestation_recorded_at`.
+
+**The gate is advisory by design.** The package has no network code and
+cannot verify the target's public-figure status against Wikidata or any
+external source. The user's attestation is a documented user-asserted
+checkpoint, not legal consent on the figure's behalf — for living
+figures, no consent path exists short of direct opt-in (deferred to v2).
+
+### Mandatory disclosure footer (deterministic)
+
+Every `/ghostwriter:write` and `/post-as:ghostwriter` output ends with
+this literal footer:
+
+```
+Written in the style of <identity.name>, not by them.
+```
+
+The footer is appended by the command's procedural output template as
+a literal string — **not** generated by the model. There is no
+`--no-disclosure` flag. The acceptance criteria grep-verify the absence
+of any opt-out flag in the command source.
+
+### Banned content (always)
+
+Even for documented public figures, `/ghostwriter:fetch` refuses:
+
+- Leaked drafts or material marked private / draft / internal.
+- Paywalled or login-walled content.
+- Private DMs, private email leaks, retracted posts.
+- Medical, financial, or legal data attributed to the figure.
+- Opinions the figure has not publicly stated.
+
+### Excluded targets
+
+Private individuals (a random LinkedIn user who is not a public figure)
+remain out of scope. This carve-out only widens the persona-roadmap's
+"no third-party PII" floor for documented public figures, never for
+anyone else.
+
+## Determinism floor (inherited)
+
+The `agent-config` package contains **zero network code**. `/ghostwriter:fetch`
+is a procedural document that delegates the fetch or search to the host
+agent's built-in capability. The package only reads the returned data
+and proposes a diff for user acceptance.
+
+## Staleness
+
+When `source_provenance.last_fetched_at` is older than 90 days, any
+`/ghostwriter:*` command surfaces a one-line warning (non-blocking):
+
+```
+⚠️  ghostwriter/<slug>.md was last fetched YYYY-MM-DD (>90 days ago). Run /ghostwriter:fetch <slug> --force-refresh.
+```
+
+## Re-fetch flow
+
+`/ghostwriter:fetch` on an existing slug routes through a diff-and-accept
+flow mirroring `/agents user accept` — the user reviews the proposed
+diff before any write. `--force-refresh` rebuilds the profile from scratch
+instead of merging.
+
+## Lint enforcement (`task lint-ghostwriter-source`)
+
+The lint runs in `task ci` and fails on:
+
+1. Any file under `.agent-src.uncompressed/ghostwriter/` whose stem is
+   **not** on the fixture allowlist (`scripts/ghostwriter_fixture_allowlist.txt`).
+2. Any allowlisted file missing `fictional: true` in frontmatter.
+3. Any package-source file (`fictional: true`) carrying an `aliases:`
+   field (aliases are a consumer-only feature; see [§ Aliases](#aliases)).
+4. Any consumer-side file under `agents/ghostwriter/` with `fictional: true`
+   (fictional profiles belong in the package source, not consumer trees).
+5. Any consumer-side `aliases:` entry that violates the storage rules:
+   shorter than 2 characters, non-Latin scripts (homoglyph protection),
+   duplicate within a profile (case-insensitive), or colliding across
+   profiles (case-insensitive — alias-vs-alias or alias-vs-slug).
+
+New package-side fixtures require updating the allowlist + reviewer
+sign-off.
+
+## Commands
+
+| Command | Role |
+|---|---|
+| `/ghostwriter:fetch` | Creates or refreshes a profile from URL or name input. Runs the public-figure gate. |
+| `/ghostwriter:write` | Generates a draft in the chosen voice. Appends the mandatory disclosure footer. |
+| `/ghostwriter:list` | Numbered listing of available profiles. |
+| `/ghostwriter:show` | Read-only render of one profile. |
+| `/ghostwriter:delete` | Two-step confirmation, hard-deletes the file. |
+| `/post-as:me` | Separate top-level command. Reads `.agent-user.md`; shares the write engine. |
+| `/post-as:ghostwriter` | Thin alias to `/ghostwriter:write`. |
+
+See [`command-clusters.md`](command-clusters.md) for the locked
+cluster registration.
+
+## Gitignore
+
+`agents/ghostwriter/*.md` (except `README.md`) is added to the
+package-managed `.gitignore` block ([`config/gitignore-block.txt`](../../config/gitignore-block.txt))
+and ignored by default. A `--shared` opt-in to commit profiles is
+deferred to v2.
+
+## See also
+
+- [`agent-user-schema`](agent-user-schema.md) — the maintainer-self primitive that `/post-as:me` consumes.
+- [`persona-schema`](persona-schema.md) — the review-lens primitive, distinct from ghostwriter.
+- [`command-clusters`](command-clusters.md) — the canonical cluster registry.

package/docs/contracts/init-telemetry.md

@@ -0,0 +1,133 @@
+---
+stability: beta
+keep-beta-until: 2026-08-15
+---
+
+# Init Telemetry v1
+
+> **Status:** beta · **Owner:** step-12 Phase 7 (`agents/roadmaps/step-12-universal-os-reframe.md`) · **Depends on:** [`step-9-user-types-axis`](../../agents/roadmaps/step-99-north-star-restructure.md) telemetry wire-up · **Stability:** additive only
+
+## Purpose
+
+Define the wire-shape, redaction floor, opt-in semantics, and producer/consumer split for anonymous telemetry emitted by `agent-config init --interactive`. Used to validate the **Universal-OS reframe hypothesis**: that real `init` runs distribute across non-developer `user_type` values, not only `developer`.
+
+This contract ships **ahead of execution**. The producer (`scripts/install.py`) and consumer (aggregation endpoint) are gated on `step-9` user-type filtering — until that ships, this document is the binding shape for the deferred implementation.
+
+## Scope
+
+Defines:
+
+- The single event emitted (`init.user_type.selected`).
+- Field allowlist (no PII, no free-form text, no host fingerprints).
+- Opt-out default (no event without explicit `--telemetry=on` or `.agent-config.local.json` opt-in).
+- Endpoint contract (HTTPS POST, JSON, retention).
+
+Does **not** define:
+
+- Aggregation queries or dashboards (consumer concern).
+- Other agent-config events — this contract is `init`-scoped.
+
+## Iron Law — opt-out by default
+
+```
+NO TELEMETRY UNLESS THE USER OPTED IN THIS RUN OR IN .agent-config.local.json.
+NO IP, NO HOSTNAME, NO PATH, NO USERNAME, NO FREE-FORM TEXT.
+```
+
+The `--interactive` flag MUST surface the telemetry choice on first run with a clear default (`off`). The choice is persisted to `.agent-config.local.json` under `telemetry.init: true|false`. Re-runs read the persisted value; `--telemetry=on|off` overrides for that run only.
+
+## Event shape
+
+One JSON object per emitted event. UTF-8, no trailing newline:
+
+```json
+{
+  "event": "init.user_type.selected",
+  "schema_version": 1,
+  "ts": "2026-05-15T00:00:00Z",
+  "user_type": "creator",
+  "stack": "none",
+  "verbosity": "normal",
+  "interactive": true,
+  "agent_config_version": "1.4.2",
+  "install_id": "anon-7f3a2b1c"
+}
+```
+
+**Field rules:**
+
+| Field | Type | Required | Allowed values |
+|---|---|---|---|
+| `event` | string | yes | `init.user_type.selected` (only event in v1) |
+| `schema_version` | int | yes | `1` |
+| `ts` | string | yes | ISO-8601 UTC, second precision |
+| `user_type` | string | yes | `creator` · `founder` · `consultant` · `gtm` · `finance` · `ops` · `developer` |
+| `stack` | string | yes | `none` · `laravel` · `nextjs` · `python` · `symfony` · `generic` |
+| `verbosity` | string | yes | `quiet` · `normal` · `verbose` |
+| `interactive` | bool | yes | `true` if `--interactive`, `false` if env-var path |
+| `agent_config_version` | string | yes | semver from `package.json` |
+| `install_id` | string | yes | random 8-char hex, generated on first opt-in, persisted to `.agent-config.local.json` under `telemetry.install_id` |
+
+**Forbidden fields:** IP, hostname, OS user, working-directory path, project name, git remote, env vars beyond the version stamp, any free-form text.
+
+## Install-id semantics
+
+- Generated **only** when the user opts in.
+- Random 8 hex chars (`secrets.token_hex(4)`) — collision space is sufficient for "is this the same install retrying?" without identifying the install.
+- Persisted to `.agent-config.local.json` under `telemetry.install_id`.
+- Deleting the file regenerates the id on next opt-in — by design.
+- Never sent if opt-out is active.
+
+## Endpoint contract
+
+- **URL:** `https://telemetry.event4u.app/v1/agent-config/init` (placeholder; final URL pinned when consumer ships).
+- **Method:** POST, `Content-Type: application/json`, body is one event object.
+- **Auth:** none — anonymous by design.
+- **Timeout:** 2 s connect, 3 s total. Failure is silent — `init` MUST NOT block or error on telemetry failure.
+- **Retention:** events aggregated to user-type counts per day; raw events purged after 30 d. Aggregate retention 24 months.
+- **Region:** EU-hosted (GDPR Art. 3 footprint; no Standard Contractual Clauses needed for EU installs).
+
+## Opt-out mechanics
+
+`.agent-config.local.json`:
+
+```json
+{
+  "telemetry": {
+    "init": false
+  }
+}
+```
+
+When `telemetry.init: false`, the producer:
+
+1. Skips event construction entirely.
+2. Does NOT generate or persist `install_id`.
+3. Logs nothing to stderr.
+4. `--telemetry=on` for the run overrides only that invocation (does not persist).
+
+## GDPR fit
+
+- **Lawful basis:** consent (Art. 6(1)(a)). The `--interactive` prompt is the consent surface.
+- **Data minimization:** Art. 5(1)(c) — only the seven fields above; the field allowlist is the redaction floor.
+- **Storage limitation:** Art. 5(1)(e) — 30 d raw, 24 mo aggregate.
+- **Right to withdraw:** Art. 7(3) — `telemetry.init: false` revokes consent; no further events emitted. Already-collected events remain in the aggregate counts (anonymous, no link to person).
+- **Right of access / erasure:** Arts. 15 / 17 — `install_id` is the only handle; the user can rotate it by deleting `.agent-config.local.json`, breaking the link from current to future events.
+
+## Producer / consumer split
+
+| Side | Responsibility | Where |
+|---|---|---|
+| **Producer** | Construct + POST the event when opt-in is active. Silent failure. | `scripts/install.py::_emit_init_telemetry()` (deferred to `step-9` wire-up). |
+| **Consumer** | Receive + validate against this schema; aggregate per UTC day; purge raw after 30 d. | Telemetry endpoint (not in this repo; pinned URL ships with `step-9`). |
+
+## Cross-references
+
+- [`step-12-universal-os-reframe.md`](../../agents/roadmaps/step-12-universal-os-reframe.md) Phase 7 L127 — the box this contract pre-authors.
+- [`universal-skills.md`](universal-skills.md) — sibling contract for the allowlist this telemetry validates against.
+- [`router-blending.md`](router-blending.md) — the user-type → skill blend that telemetry confirms is being used.
+- [`STABILITY.md`](STABILITY.md) — schema_version bump rules.
+
+## Versioning
+
+`schema_version=1` is additive-only. Field additions require an `init-telemetry.md` patch and producer support. Field removals or type changes require a new `schema_version` and a producer that emits both shapes for ≥ 1 minor release.

package/docs/contracts/router-blending.md

@@ -0,0 +1,71 @@
+---
+stability: beta
+keep-beta-until: 2026-08-13
+---
+
+
+# Router Blending — Cross-Domain Skill Mix Contract
+
+> **Status:** beta · **Owner:** router governance · **Depends on:** [`universal-skills.md`](universal-skills.md), the user-types axis (axis seeds — schema field defined under [`skill.schema.json`](../../scripts/schemas/skill.schema.json) → `recommended_for_user_types`).
+
+## Purpose
+
+A founder doing technical due diligence needs both `runway-cognition` and `data-flow-mapper`. A consultant pitching ghost-written thought leadership needs both `ghostwriter` and `competitive-positioning`. Pure prefix-filtering — "load consulting/* for consultants" — silos these workflows and forces the operator to re-enable skills manually.
+
+Router blending defines the mix-ratio per user-type so the resolved skill set covers the **dominant** domain plus the **bridge** skills that real workflows demand.
+
+## The blend formula
+
+```
+loaded_skills(user_type) =
+    universal_allowlist            (always — see universal-skills.md)
+  ∪ dominant_pool(user_type)       (primary domain, ≈70%)
+  ∪ bridge_pool(user_type)         (cross-domain, ≈20%)
+  ∪ context_pool(user_type)        (content / writing / safety, ≈10%)
+```
+
+Percentages are **soft caps** measured against the post-filter skill count, not hard quotas. Drift > ±10% on any pool triggers a re-tag pass and a finding in `agents/eval-findings/`.
+
+## Per user-type blends
+
+| user_type | Dominant (~70%) | Bridge (~20%) | Context (~10%) |
+|---|---|---|---|
+| **creator** | `voice-and-tone-design`, `editorial-calendar`, `content-funnel-design`, `messaging-architecture`, `release-comms` | `customer-research`, `competitive-positioning`, `voc-extract` | `privacy-review`, `accessibility-auditor` |
+| **founder** | `runway-cognition`, `unit-economics-modeling`, `fundraising-narrative`, `scenario-modeling`, `okr-tree-modeling` | `data-flow-mapper`, `threat-modeling`, `api-design` | `voice-and-tone-design`, `release-comms` |
+| **consultant** | `discovery-interview`, `competitive-moat-analysis`, `competitive-positioning`, `stakeholder-tradeoff`, `customer-research` | `messaging-architecture`, `voice-and-tone-design`, `release-comms` | `privacy-review`, `data-handling-judgment` |
+| **gtm** | `pipeline-strategy`, `forecast-accuracy`, `deal-qualification-meddic`, `gtm-launch`, `release-comms` | `voice-and-tone-design`, `messaging-architecture`, `voc-extract` | `privacy-review`, `unit-economics-modeling` |
+| **finance** | `runway-cognition`, `unit-economics-modeling`, `scenario-modeling`, `forecasting`, `dcf-modeling` | `data-handling-judgment`, `privacy-review`, `contracts-cognition` | `voice-and-tone-design`, `stakeholder-tradeoff` |
+| **ops** | `incident-commander`, `data-handling-judgment`, `privacy-review`, `dashboard-design`, `launch-readiness` | `threat-modeling`, `secrets-management`, `api-design` | `voice-and-tone-design`, `release-comms` |
+| **developer** | language-/framework-keyed pool (laravel · nextjs-patterns · php-coder · …) | `api-design`, `authz-review`, `playwright-architect`, `threat-modeling` | `voice-and-tone-design`, `release-comms` |
+
+Each pool entry is a `recommended_for_user_types:` frontmatter tag on the skill. A skill with no tag is **universal** (see [`universal-skills.md`](universal-skills.md)).
+
+## How the loader resolves a profile
+
+1. **Read** `.agent-config.local.json` → `user_type`.
+2. **Filter** all 210 skills: keep the skill iff `user_type ∈ recommended_for_user_types` **or** `recommended_for_user_types` is absent (universal).
+3. **Stack overlay.** If `stack` is set (laravel / nextjs / python / …), also keep skills whose body cites that stack — language-keyed bridge. Implementation: pattern match on the skill `description:` frontmatter; details land with the schema-rigor contract once the schema bridge for stack-keyed bridge tagging is finalised.
+4. **Cap.** No filter is applied if the result drops below 50 skills (safety floor — under-filtering is recoverable, over-filtering hides essentials).
+5. **Surface** `loaded_skills_count` + per-pool counts in the agent debug output.
+
+## Drift detection
+
+`scripts/check_router_blend.py` (to ship with Phase 5) walks each user-type and reports:
+
+- Dominant-pool fraction (must be ≥ 0.55).
+- Bridge-pool fraction (≥ 0.15).
+- Empty-pool sentinel: any user-type with zero bridge tags fails the check.
+
+Wired into `task ci` as a non-blocking warning until the user-types axis stabilizes; promoted to blocking once `step-9` ships its three seed user-types.
+
+## Open questions (tracked for Phase 5 → Phase 6 transition)
+
+- Stack overlay precedence: framework tag vs. user-type tag — currently union, may want intersection for the `developer + laravel` combo. Empirical question, tested by corpus.
+- Cross-domain explicit opt-in: `agent-config skills enable <name>` to override the filter on demand. Not in scope for Phase 5 — opens once the filter ships.
+- Persona ↔ user-type mapping: a `consultant` user_type may default to `discovery-lead` persona, but personas are role-axis, not user-axis. Final mapping resolved with [`docs/contracts/persona-schema.md`](persona-schema.md).
+
+## Related
+
+- [`universal-skills.md`](universal-skills.md) — the always-loaded floor under the blend.
+- [`skill.schema.json`](../../scripts/schemas/skill.schema.json) — `recommended_for_user_types` field that carries the tags.
+- [`tests/eval/corpus-non-dev.yaml`](../../tests/eval/corpus-non-dev.yaml) — empirical validation of the blends.

package/docs/contracts/universal-skills.md

@@ -0,0 +1,92 @@
+---
+stability: beta
+keep-beta-until: 2026-08-13
+---
+
+
+# Universal Skills — Allowlist Contract
+
+> **Status:** beta · **Owner:** step-12 Phase 3 · **Stability:** additive only (no removals without a migration note in `STABILITY.md`)
+
+## Purpose
+
+When `agent-config init --interactive` writes a `.agent-config.local.json` with a `user_type` (e.g., `creator`, `founder`, `consultant`), the host agent filters its loaded skill set to that user-type's recommended skills + this allowlist. **Skills on this allowlist are loaded for every user-type regardless of profile.**
+
+The allowlist solves the over-siloing risk identified by the AI Council 2026-05-15 review: a `consultant` user still needs `decision-record` and `risk-officer`; a `creator` still needs `refine-prompt` and `verify-completion-evidence`. These are not domain skills — they are agent-OS primitives.
+
+## The 15
+
+| Skill | Why universal |
+|---|---|
+| [`refine-prompt`](../../.agent-src/skills/refine-prompt/SKILL.md) | Every free-form request needs AC + assumption + confidence band before the engine runs. |
+| [`refine-ticket`](../../.agent-src/skills/refine-ticket/SKILL.md) | Every ticket (Jira / Linear / GH issue) needs scoped AC before plan. |
+| [`estimate-ticket`](../../.agent-src/skills/estimate-ticket/SKILL.md) | Sizing + split + risk — applies to any work item, technical or not. |
+| [`verify-completion-evidence`](../../.agent-src/skills/verify-completion-evidence/SKILL.md) | Iron-Law gate: fresh evidence before any "done" claim. Survives every mode. |
+| [`threat-modeling`](../../.agent-src/skills/threat-modeling/SKILL.md) | Pre-implementation abuse-case enumeration — same lens applies to a marketing form and a payment endpoint. |
+| [`systematic-debugging`](../../.agent-src/skills/systematic-debugging/SKILL.md) | Reproduce → isolate → hypothesize → verify — works on broken pipelines, broken docs, broken funnels. |
+| [`doc-coauthoring`](../../.agent-src/skills/doc-coauthoring/SKILL.md) | 3-stage write loop (context → section → reader-test) for any long-form doc. |
+| [`deep-reading-analyst`](../../.agent-src/skills/deep-reading-analyst/SKILL.md) | Article / long-form analysis via SCQA + mental models — used by every role that reads. |
+| [`decision-record`](../../.agent-src/skills/decision-record/SKILL.md) | Trade-off framing before any commit. ADR-shape works for tech, hiring, and pricing. |
+| [`adr-create`](../../.agent-src/skills/adr-create/SKILL.md) | Naming + numbering + index regen — the file mechanics of `decision-record`. |
+| [`risk-officer`](../../.agent-src/skills/risk-officer/SKILL.md) | Blast-radius framing + residual-risk verdict before any commit. |
+| [`adversarial-review`](../../.agent-src/skills/adversarial-review/SKILL.md) | Devil's advocate stress-test — opt-in but always available. |
+| [`customer-research`](../../.agent-src/skills/customer-research/SKILL.md) | Discovery-slice shaping (JTBD, switch-event) — used by founder, GTM, consultant, creator. |
+| [`stakeholder-tradeoff`](../../.agent-src/skills/stakeholder-tradeoff/SKILL.md) | Per-lens framing when stakeholders disagree — applies in every org. |
+| [`md-language-check`](../../.agent-src/skills/md-language-check/SKILL.md) | Hard gate: `.md` files stay English; the agent translates at runtime. |
+
+## Inclusion criteria
+
+A skill earns the universal label when **all three** hold:
+
+1. **Cross-role payback.** ≥ 4 of the 6 seeded user-types (creator / founder / consultant / GTM / finance-ops / developer) reach for it in week-one workflows. The non-dev eval corpus ([`tests/eval/corpus-non-dev.yaml`](../../tests/eval/corpus-non-dev.yaml)) is the empirical test.
+2. **No stack assumption.** The skill body does not rely on a specific language, framework, or repo shape. `laravel`, `nextjs-patterns`, `pest-testing` are domain skills, not universal.
+3. **Agent-OS primitive.** The skill encodes a meta-pattern of agent behavior (refine, verify, decide, debug, document, threat-model) rather than a domain deliverable (write a launch email, draft an ADR for the auth module).
+
+## Exclusion criteria
+
+- **Domain anchor.** `voice-and-tone-design` (creator), `runway-cognition` (founder), `quality-tools` (developer), `pipeline-strategy` (GTM) — strong-fit for one user-type, weak for the other five. These tag via the `recommended_for_user_types:` frontmatter field defined in [`skill.schema.json`](../../scripts/schemas/skill.schema.json).
+- **Tool-specific.** `laravel-horizon`, `nextjs-patterns`, `mcp-builder`, `terraform` — load only when the matching stack flag is set.
+- **Council / role review.** `judge-bug-hunter`, `judge-security-auditor`, `architecture-review-lens` — load via subagent orchestration, not via universal allowlist.
+
+## How loading works (forward-compatible)
+
+```json
+// .agent-config.local.json — written by `agent-config init --interactive`
+{
+  "user_type": "consultant",
+  "stack": "none",
+  "verbosity": "normal",
+  "enabled_skill_prefixes": ["consulting/*", "writing/*"],
+  "default_persona": "discovery-lead"
+}
+```
+
+The host agent's skill loader is expected to:
+
+1. Resolve `enabled_skill_prefixes` against the per-user-type recommendation list (Phase 5 `recommended_for_user_types:` tags).
+2. Union with this universal allowlist (always, no opt-out).
+3. Surface a `loaded_skills_count` in the agent's debug / status output so the operator can verify filtering ran.
+
+**Runtime filter status:** the prefix-filter pass is gated on the user-types axis shipping the `user-types/` directory and `--user-type` flag. Until then, every skill loads (current v2.x behavior); this contract is the forward declaration of the eventual filter, not its implementation.
+
+## Change procedure
+
+Adding a skill to this allowlist:
+
+1. Open a PR that edits this file + the relevant skill's `recommended_for_user_types:` (omitted = universal).
+2. Cite ≥ 4 user-type prompts from `tests/eval/corpus-non-dev.yaml` that select the skill.
+3. Require approval from one Tier-1 reviewer (architecture-review-lens or skill-writing).
+4. Document the inclusion in `agents/eval-findings/` with the supporting eval prompts.
+
+Removing a skill is breaking. It must be announced in `STABILITY.md` with a deprecation window ≥ one minor release.
+
+## Versioning
+
+- This contract is **beta**. Once non-dev selection-accuracy ≥ 0.60 sustains across two consecutive `task bench --corpus non-dev` runs, status promotes to **stable** and entries become semver-protected.
+
+## Related
+
+- [`STABILITY.md`](STABILITY.md) — public-identifier stability surface.
+- [`agent-memory-contract.md`](agent-memory-contract.md) — companion contract for the cross-cutting memory layer.
+- [`docs/getting-started-by-role.md`](../getting-started-by-role.md) — consumer-facing role docs that reference these skills.
+- [`tests/eval/corpus-non-dev.yaml`](../../tests/eval/corpus-non-dev.yaml) — empirical test corpus.