@event4u/agent-config 2.18.0 → 2.20.0

package/.agent-src/user-types/truck-driver.md

@@ -0,0 +1,113 @@
+---
+id: truck-driver
+kind: user-type
+description: "Commercial truck driver — voice-first, hours-of-service gated, dead-zone tolerant, photo+GPS proof-of-delivery."
+version: "1.0"
+source: project
+---
+
+# Truck Driver
+
+## Focus
+
+Commercial truck driver doing regional or long-haul delivery —
+typically single driver, phone or in-cab tablet on a mount, gloves
+optional but hands often busy with the wheel, paperwork, or a
+pallet jack. Day is gated by **hours-of-service (HOS)** — legally
+bounded driving and rest windows that cannot be ignored without
+losing the licence. Cargo moves through warehouses, loading docks,
+customer yards; signal drops in tunnels, basements, rural
+stretches. Proof-of-delivery (photo + signature + GPS + timestamp)
+is the moment the invoice becomes collectable.
+
+Review lens only, never operational instruction source. No driving
+advice, no HOS legal interpretation, no vehicle-maintenance
+guidance, no hazmat procedure. Trade execution stays with the
+dispatcher, the safety officer, and the certified driver-trainer.
+
+## Daily Workflow
+
+- 05:00 — pre-trip inspection, vehicle check captured on tablet;
+  driver swipes into HOS clock at start of duty.
+- 06:00 — first loading-dock arrival; wait time on the dock can be
+  15 minutes or 3 hours; status (waiting / loading / loaded)
+  matters for billing and HOS attribution.
+- 07:30 — driving: device must not require typing or precise taps
+  while in motion; voice input or large single-tap actions only.
+- Multiple stops — route may reorder mid-day (cancelled stop, new
+  rush stop); ETA must recalc and propagate to the customer
+  without driver intervention beyond confirming.
+- Per delivery — photo of the pallet, customer signature
+  on-screen, GPS pin, timestamp; the four-tuple is the invoice
+  trigger.
+- End of duty — HOS clock closes; if next break-window starts
+  mid-route, system warns **before** the driver commits.
+
+## Vocabulary
+
+- **HOS (hours-of-service)** — legally enforced driving / rest
+  windows; not "shift hours" or "working time".
+- **POD (proof-of-delivery)** — the photo + signature + GPS +
+  timestamp four-tuple; missing one element = unbilled delivery.
+- **Dock dwell / detention** — wait time at a dock, often billable
+  to the shipper; capturing the timestamps is the negotiation
+  evidence.
+- **Bill of lading (BOL)** — paper or electronic; the legal cargo
+  manifest, not a "shipment summary".
+
+## Operational Constraints
+
+- **Driving-while-using is prohibited.** No typing flow on the
+  critical path while in motion; voice or large single-tap only.
+  Anything else risks the licence and the company.
+- **HOS is hard law.** A UI that lets the driver accept a stop
+  that would breach the remaining break-window is rejected — the
+  system warns first, dispatcher reroutes.
+- **Dead zones are routine.** Tunnels, basements, rural roads;
+  every write queues, every read works from cache, and POD
+  uploads sync with photo intact when signal returns.
+- **One-handed operation.** Other hand on the wheel, paperwork,
+  or pallet jack; bottom-thumb-reachable primary actions, no
+  precision drag.
+- **Cold / wet / glare.** Outdoor docks in winter; gloves on,
+  screen wet, sun directly on the display — same outdoor-default
+  high-contrast as the field-crew lens.
+
+## Unique Questions
+
+- Does the primary flow work hands-busy at a loading dock, with
+  voice or one large tap, and not collapse if the connection
+  drops mid-step?
+- Does the POD step capture photo + signature + GPS + timestamp
+  in a single offline-resilient action, or are they four separate
+  forms that can each drop?
+- Does the system block or warn before the driver accepts a stop
+  that would breach the remaining HOS break-window?
+- Is dock-dwell time captured automatically from arrival to
+  loaded, or does it rely on the driver remembering to tap?
+
+## Ticket Red Flags
+
+- "Driver enters …" with text input on the in-motion path.
+- POD described as a single field rather than a four-element
+  bundle (photo + signature + GPS + timestamp).
+- HOS treated as informational ("show remaining hours") rather
+  than a constraint on what stops can be accepted.
+- Sync described as online-only; no queue + retry sketched for
+  dead-zone delivery.
+- Dock-dwell capture left to manual tap with no arrival-trigger
+  fallback.
+
+## Anti-Patterns
+
+- **Review-only, never operational.** No driving advice, no HOS
+  legal interpretation, no vehicle-maintenance procedure, no
+  hazmat-handling guidance. Those need certified humans.
+- **No generic prose.** "Consider mobile usability" fails the
+  Anti-Generic Quality Bar — every observation cites HOS, POD,
+  dock-dwell, dead-zone, or hands-busy.
+- **No in-motion typing on the critical path.** A flow needing
+  the driver to type while driving is rejected outright.
+- **No partial POD acceptance.** Missing any element of the
+  four-tuple = unbilled; the flow must hold the action open
+  until all four are captured or explicitly waived by dispatch.

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Shared agent configuration \u2014 skills for AI coding tools (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI).",
-    "version": "2.18.0",
+    "version": "2.20.0",
     "keywords": [
       "agent-config",
       "skills",

package/CHANGELOG.md

@@ -695,13 +695,94 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
-# Era: 2.15.x — current
+# Era: 2.16.x — current
 
-> Started at `2.15.0` (2026-05-15). Full entries live inline below.
+> Started at `2.16.0` (2026-05-15). Full entries live inline below.
 > The drift test caps this era at 200 lines of entry body; growth past
-> that forces a new era split (`# Era: 2.16.x`, etc.) — see
+> that forces a new era split (`# Era: 2.17.x`, etc.) — see
 > [`docs/contracts/CHANGELOG-conventions.md § Era splits`](docs/contracts/CHANGELOG-conventions.md).
 
+## [2.20.0](https://github.com/event4u-app/agent-config/compare/2.19.0...2.20.0) (2026-05-16)
+
+### Features
+
+* **product:** step-15 product refinement — profiles + packs + presets + explain CLI ([59e7d6f](https://github.com/event4u-app/agent-config/commit/59e7d6f3ddce025e558da08c1da1b4c8155e68eb))
+* **parity:** step-11 ruflo parity — smoke + ADR + cost + namespace + MCP ([521b4c6](https://github.com/event4u-app/agent-config/commit/521b4c62f5fe266f5c18dfcca2abf4e06d97c217))
+* **caveman:** step-10 default-kill criterion + parity roadmap ([dd7ec3c](https://github.com/event4u-app/agent-config/commit/dd7ec3cae4f8839b28b4d3ff9dbdbb316ec5d035))
+* **bench:** step-4 measurement + benchmark infrastructure ([981d0cd](https://github.com/event4u-app/agent-config/commit/981d0cd1c48e2d23eede29bd86e833cd826ddfd9))
+* **skills:** step-2 skill inventory rationalization ([3fa651d](https://github.com/event4u-app/agent-config/commit/3fa651d2496e4fc483cd7ed452bb39f41dd39365))
+
+### Bug Fixes
+
+* **adr-create:** restore Inspect keyword in step-1 heading ([46c40ad](https://github.com/event4u-app/agent-config/commit/46c40adf4741f1e13d8d275f9363f98047d4b733))
+* **audit_mcp_tools:** drop roadmap link from generated inventory ([d35459e](https://github.com/event4u-app/agent-config/commit/d35459e94d9be473bbb567f7c348be5bff4b5e9d))
+* **audit_mcp_tools:** emit stability frontmatter in generated inventory ([ba7af12](https://github.com/event4u-app/agent-config/commit/ba7af12cf26509f2ea0ddb867303f3b225fea866))
+* **no-cheap-questions:** trim to clear concentration cap ([3516283](https://github.com/event4u-app/agent-config/commit/351628301aa168c31130b62ee306858944ecf9f2))
+* **onboard:** move recommendation off inline (recommended) tag ([6a77a06](https://github.com/event4u-app/agent-config/commit/6a77a06c014d8820662906ca6ab0ee55ac847e05))
+* **refs:** suppress legitimate council-response audit links ([d764329](https://github.com/event4u-app/agent-config/commit/d764329d8718124d150deafcce52bdd206ada740))
+* **contracts:** drop roadmap-file links from stable artefacts ([96ea60f](https://github.com/event4u-app/agent-config/commit/96ea60f8f6e85c6ce04e8042d9d2535938f75d9f))
+* **contracts:** bring beta-review markers into the 90-day window ([4be4a47](https://github.com/event4u-app/agent-config/commit/4be4a47cc30532fa20d1ea7c3311d7eaa154d7e6))
+* **contracts:** add stability frontmatter to 6 new contracts ([8b27577](https://github.com/event4u-app/agent-config/commit/8b27577bc6b4b28c36ccfbea48b4e92e35372fbd))
+* **portability:** replace task cost:* with direct script invocations ([0225f60](https://github.com/event4u-app/agent-config/commit/0225f60d0157edf4b4f74fe8fc1266295d5b90f2))
+* **rules:** restore no-cheap-questions Iron Law block ([e95315f](https://github.com/event4u-app/agent-config/commit/e95315f96323d1ef32328b1c8a630b5aacafee84))
+
+### Documentation
+
+* **readme:** restore three-audience headings, tighten user-types blurb ([fdb03bf](https://github.com/event4u-app/agent-config/commit/fdb03bf314acb1a7a570400c1ba3cadb8098b943))
+* **readme:** restore browse-all-commands canonical line ([d91f6e0](https://github.com/event4u-app/agent-config/commit/d91f6e0d99230792f570b02fab6a1b30a744187c))
+* **readme:** extract profile detail + featured commands to /docs ([e8745f3](https://github.com/event4u-app/agent-config/commit/e8745f33f1da089aefd763cc659be4568177dd07))
+* **roadmap:** regenerate dashboard + cross-roadmap link refresh ([f6b7085](https://github.com/event4u-app/agent-config/commit/f6b7085d3419f1a8b57daf9b949bd55312c17b9b))
+* **roadmap:** step-5 schema rigor + test cleanup ([b043230](https://github.com/event4u-app/agent-config/commit/b043230291222f6d6287d73e0807ea772e227e98))
+
+### Chores
+
+* **changelog:** split era 2.15.x → pre-2.16.0 ([88b81ba](https://github.com/event4u-app/agent-config/commit/88b81bac54ae5f9558a1087c81d453c47d3039bb))
+* **mcp:** regenerate MCP tool inventory ([bce3169](https://github.com/event4u-app/agent-config/commit/bce3169b353c2d240df610e4bf01c91c96d23e0d))
+* **ownership:** regenerate ownership matrix after no-cheap-questions trim ([dbe58a9](https://github.com/event4u-app/agent-config/commit/dbe58a9dfafbca487f11b2501b1f1dabb1053a8d))
+* **template:** bump agent_config_version pin to 2.19.0 ([cfc4c59](https://github.com/event4u-app/agent-config/commit/cfc4c59e288862eccf4e7b9d215adf30e527f5a0))
+* **build:** wire step-2/4/11/15 tooling into Taskfile + gitignore ([0acc9e7](https://github.com/event4u-app/agent-config/commit/0acc9e77515e611eb685c58aeba91f3d5af9423f))
+
+Tests: 4535 (+42 since 2.19.0)
+
+## [2.19.0](https://github.com/event4u-app/agent-config/compare/2.18.0...2.19.0) (2026-05-16)
+
+### Features
+
+* **user-types:** land three seed user-types (galabau, metalworking, truck) ([361745e](https://github.com/event4u-app/agent-config/commit/361745ec88d32c7f6faa8f50ac4d350f95f6b6d1))
+* **refine-ticket:** add --user-type lens, orthogonal to --personas ([7d70138](https://github.com/event4u-app/agent-config/commit/7d7013840d92d53ead0b8dba15bf6613398dcd5b))
+* **linter:** add user-type artifact-type support ([bce874c](https://github.com/event4u-app/agent-config/commit/bce874cdb7e925585b74b478b0f4f0e4a7f40380))
+* **user-types:** wire compile pipeline + author scaffolding ([8637dae](https://github.com/event4u-app/agent-config/commit/8637dae4463796726b0d7e737d37169334a0283b))
+* **user-types:** lock schema + ADR for runtime user-type axis ([0ce1549](https://github.com/event4u-app/agent-config/commit/0ce1549a1e5037521cb06e9d1c467fa4ebf87d06))
+* **eval-findings:** add schema template for step-13 closure evidence ([2b2daa4](https://github.com/event4u-app/agent-config/commit/2b2daa46fbf348f5a2901b185c91901de06a1025))
+* **recruits:** add intake template for step-13 P1 recruit walkthroughs ([a569071](https://github.com/event4u-app/agent-config/commit/a569071853d665ca57813fc4c4676bba38716fac))
+
+### Bug Fixes
+
+* **adr:** drop transient roadmap links from user-types axis ADR ([e8d30fe](https://github.com/event4u-app/agent-config/commit/e8d30fe80c2d0b87406571b2c3dbbdd031312998))
+* **contracts:** clamp user-type beta-review markers to 90-day window ([25af8cc](https://github.com/event4u-app/agent-config/commit/25af8ccd650d6ea304f5060ebb55c2d034d746a2))
+* **refine-ticket:** sync compressed SKILL.md with --user-type persona-voice bullet ([14b9dcd](https://github.com/event4u-app/agent-config/commit/14b9dcdab69f063e1dcfc8d9070892b4d56305b1))
+* **refs:** inline AI Council Phase 4 convergence summary ([0e6a578](https://github.com/event4u-app/agent-config/commit/0e6a5780773fbabba6f98a01bd4b25726c996903))
+* **adr:** drop transient roadmap links from MCP runtime ADR ([8f2691e](https://github.com/event4u-app/agent-config/commit/8f2691e90130a9333bd9e01d0863ecb0c9f7ec97))
+* **template:** bump agent_config_version pin to 2.18.0 ([dd7441d](https://github.com/event4u-app/agent-config/commit/dd7441d2fc0fd785a70272b6520eb0eb29a61a66))
+
+### Documentation
+
+* **user-types:** cross-link personas↔user-types and surface metalworking-shop example ([ac0b0ce](https://github.com/event4u-app/agent-config/commit/ac0b0ce2e356654352d3c4caf1528b3d5772047c))
+* **step-13:** link new recruit + eval-finding templates from prerequisites ([57b729a](https://github.com/event4u-app/agent-config/commit/57b729a236bf1b442df140fb2efbdecd9e73ffd9))
+* **adr:** record MCP server runtime as Anthropic Python SDK ([5f5d689](https://github.com/event4u-app/agent-config/commit/5f5d6895d4369b313e1a5058eca21807e5566cfd))
+
+### Tests
+
+* **user-types:** add coverage audit script + tests ([ca403bb](https://github.com/event4u-app/agent-config/commit/ca403bb714fd505f539715fe25b7948714d0ee66))
+* **user-types:** lock schema, lint, and composition contracts ([cfeb48a](https://github.com/event4u-app/agent-config/commit/cfeb48a9d04956ff9d6744383b44bcabeaa57702))
+
+### Chores
+
+* **roadmap:** close step-6 user-types axis and refresh progress dashboard ([2f50a96](https://github.com/event4u-app/agent-config/commit/2f50a96eeec1ea1bf832ed560553d4e940a94812))
+* **roadmap:** close step-14 phases 1+2 against shipped MCP server ([2dcf04b](https://github.com/event4u-app/agent-config/commit/2dcf04bdf5f71bd546b7ec9cf27bbbb7fc6d0ec4))
+
+Tests: 4493 (+17 since 2.18.0)
+
 ## [2.18.0](https://github.com/event4u-app/agent-config/compare/2.17.0...2.18.0) (2026-05-16)
 
 ### Features
@@ -842,34 +923,14 @@ Tests: 4459 (+54 since 2.16.0)
 
 Tests: 4405 (+53 since 2.15.0)
 
-## [2.15.0](https://github.com/event4u-app/agent-config/compare/2.14.0...2.15.0) (2026-05-15)
-
-### Features
-
-* **agent-user:** add /agents user command cluster (init, show, review, accept, update) ([15d53d8](https://github.com/event4u-app/agent-config/commit/15d53d8d9a2365b044831cd42127e247a70d7e20))
-* **agent-user:** add v1 schema contract for .agent-user.md persona file ([64f4eab](https://github.com/event4u-app/agent-config/commit/64f4eab62ccf6a2606fbca0c56d398372c05a7a0))
-
-### Bug Fixes
-
-* **agent-user:** inline council-reference summary per no-roadmap-references ([ee4d3ce](https://github.com/event4u-app/agent-config/commit/ee4d3cedf9f4429450d21ca5badc2ae5c2ecaaed))
-* **agent-user:** drop roadmap references per no-roadmap-references rule ([c8ade8d](https://github.com/event4u-app/agent-config/commit/c8ade8d7c5b495e0e4295aa0cb801e59076ee0b0))
-* **agent-user:** adjust keep-beta-until to fit 90-day window ([801b365](https://github.com/event4u-app/agent-config/commit/801b365117a2d1efb4505e504bdd730e4cbbc217))
-
-### Documentation
+# Era: pre-2.16.0 — archived
 
-* **persona:** README section + agent-settings legacy-fallback note ([4da7629](https://github.com/event4u-app/agent-config/commit/4da7629f1f0b5a35a64d0a861040ad8639a66ebe))
-* **roadmap:** mark step-3-agent-user-persona phases as in-progress ([f29d3bc](https://github.com/event4u-app/agent-config/commit/f29d3bce2380c0ea9c67e6094540b88d920ed9ff))
-
-### Chores
-
-* **roadmap:** close out + archive step-3-agent-user-persona ([09c0229](https://github.com/event4u-app/agent-config/commit/09c0229efd67af9cad7b2ca8202f4caa351d028d))
-* **ownership:** regenerate file-ownership-matrix for /agents user ([128890d](https://github.com/event4u-app/agent-config/commit/128890d880584704b4842a398555dd979ae54462))
-* **docs:** bump command count from 109 to 115 ([f8c61b1](https://github.com/event4u-app/agent-config/commit/f8c61b1d0ec48034e0d66e8d32534056ca4aa1f0))
-* **template:** bump agent_config_version pin to 2.14.0 ([fcb885f](https://github.com/event4u-app/agent-config/commit/fcb885fd19bdbca46ef91ec4d5e723cc6c186c6d))
-* **index:** regenerate agents/index.md + docs/catalog.md for /agents user ([56b281d](https://github.com/event4u-app/agent-config/commit/56b281d69960d3e57adbd24b9ec6fd24fc1a5aff))
-* **agent-user:** regenerate compressed sources + claude tool stubs ([f79b6d1](https://github.com/event4u-app/agent-config/commit/f79b6d1cfcf1caccde4a723ad779c65d9ed87198))
-
-Tests: 4352 (+12 since 2.14.0)
+> All `2.15.0` entries live in
+> [`docs/archive/CHANGELOG-pre-2.16.0.md`](docs/archive/CHANGELOG-pre-2.16.0.md).
+> The archive is read-only; git tag `2.15.0` remains the canonical
+> source for what shipped. Splitting these out of the main file keeps
+> the active era under the 200-line drift cap enforced by
+> `tests/test_changelog_eras.py`.
 
 # Era: pre-2.15.0 — archived
 

package/README.md

@@ -4,47 +4,67 @@
 
 Give your AI agents an audit-disciplined execution layer: **210 skills**, **79 governance rules**, **124 commands**, and a replayable state machine that turns any host agent (Claude Code, Augment, Cursor, Copilot, Windsurf) into a reliable team member.
 
-| 👩‍💻 Developers | 🚀 Founders & Operators | ✍️ Creators & Consultants |
-|---|---|---|
-| Implement tickets, fix CI, write tests, run PR reviews — `/implement-ticket`, `/work`, `/commit`, `/fix ci`, `/create-pr` — with stack-aware skills for Laravel · Symfony · Next.js · React · Node. | Pitch decks, runway math, OKR trees, GTM launches, pricing reviews — `runway-cognition`, `unit-economics-modeling`, `fundraising-narrative`, `gtm-launch`, `okr-tree-modeling`. | Editorial calendars, brand voice, ghostwriting, content funnels, discovery interviews — `voice-and-tone-design`, `editorial-calendar`, `ghostwriter`, `content-funnel-design`, `discovery-interview`. |
+### Pick your profile — six entry paths
+
+`/onboard` writes `profile.id` to `.agent-settings.yml`; each anchor
+below is the first-screen the wizard sends you to. One README, six
+entries, no role-detection guesswork.
+
+| Profile (`profile.id`) | Audience | First commands | First skills |
+|---|---|---|---|
+| 👩‍💻 [`developer`](docs/profiles.md#profile-developer) | IC engineer | `/implement-ticket` · `/work` · `/review-changes` · `/fix` · `/commit` | `developer-like-execution` · `verify-completion-evidence` · `minimal-safe-diff` · `systematic-debugging` · `test-driven-development` |
+| ✍️ [`content_creator`](docs/profiles.md#profile-content_creator) | Writers, ghostwriters, marketers | `/work` · `/post-as` · `/ghostwriter` · `/optimize-prompt` | `voice-and-tone-design` · `messaging-architecture` · `editorial-calendar` · `release-comms` · `prompt-engineering-patterns` |
+| 🚀 [`founder`](docs/profiles.md#profile-founder) | Solo / early-stage founder | `/work` · `/feature` · `/challenge-me` · `/council` | `refine-prompt` · `rice-prioritization` · `vision-articulation` · `fundraising-narrative` · `runway-cognition` |
+| 🏛 [`agency`](docs/profiles.md#profile-agency) | Multi-client delivery shop | `/work` · `/implement-ticket` · `/refine-ticket` · `/feature` · `/roadmap` | `doc-coauthoring` · `decision-record` · `refine-ticket` · `estimate-ticket` · `perf-feedback-craft` |
+| 💼 [`finance`](docs/profiles.md#profile-finance) | CFO / fractional finance / FP&A | `/work` · `/council` · `/challenge-me` | `dcf-modeling` · `forecasting` · `scenario-modeling` · `unit-economics-modeling` · `runway-cognition` |
+| 🛡 [`ops`](docs/profiles.md#profile-ops) | RevOps, support, SRE-adjacent | `/work` · `/threat-model` · `/review-changes` · `/fix` | `incident-commander` · `dashboard-design` · `logging-monitoring` · `threat-modeling` · `launch-readiness` |
+
+**Not sure which one?** Run `npx @event4u/agent-config init` and open
+your AI agent — `/onboard` asks a single 8-option role question and
+maps to the closest profile. Source-of-truth:
+[`.agent-src.uncompressed/profiles/`](.agent-src.uncompressed/profiles/) ·
+schema: [`docs/contracts/profile-system.md`](docs/contracts/profile-system.md).
+Beyond software: [`user-types/`](.agent-src.uncompressed/user-types/)
+(galabau · metalworking · truck — see [Who this is for](#who-this-is-for)).
 
 <p align="center">
   <strong>210 Skills</strong> · <strong>79 Rules</strong> · <strong>124 Commands</strong> · <strong>72 Guidelines</strong> · <strong>22 Personas</strong> · <strong>5 Advisors</strong> · <strong>8 AI Tools</strong>
 </p>
 
+<p align="center">
+  <a href="CHANGELOG.md">CHANGELOG</a> ·
+  <a href="https://github.com/event4u-app/agent-config/releases/latest">Latest release</a> ·
+  <a href="https://github.com/event4u-app/agent-config/discussions">Discussions</a>
+</p>
+
 ---
 
 ## Use it in your project
 
-You run the package from a consumer repo — bootstrap via `npx`, let the
-agent pick up your stack, and ship work end-to-end. New install? Start
-with the [Quickstart](#quickstart) to write `.agent-settings.yml`,
-`.augment/`, `.claude/`, …. Already installed? [Supported Tools](#supported-tools)
-shows which AIs the package wires up, and [Featured Commands](#featured-commands)
-lists the end-to-end workflows (`/implement-ticket`, `/work`, `/commit`,
-`/create-pr`). For a deeper tour, see the
-[2-minute demo: `/implement-ticket`](#2-minute-demo-implement-ticket).
+Run from a consumer repo — bootstrap via `npx`, the agent picks up
+your stack, and you ship work end-to-end. New install? Start with the
+[Quickstart](#quickstart). Already installed? [Supported Tools](#supported-tools)
+shows the wired AIs; [`docs/featured-commands.md`](docs/featured-commands.md)
+lists the end-to-end workflows (`/implement-ticket`, `/work`,
+`/commit`, `/create-pr`). Deeper tour: [2-minute demo](#2-minute-demo-implement-ticket).
 
 ## Prove it
 
-The package is audit-disciplined by construction — every memory consult,
-decision key, and hook concern lands in `agents/state/` so you can
-replay it. [Core Principles](#core-principles) names the four invariants.
+Audit-disciplined by construction — every memory consult, decision
+key, and hook concern lands in `agents/state/` so you can replay it.
+[Core Principles](#core-principles) names the four invariants;
 [What this package is — and what it isn't](#what-this-package-is--and-what-it-isnt)
-draws the scope boundary. [Documentation](#documentation) lists the
-contracts the package ships against, including
-[`memory-visibility-v1`](docs/contracts/memory-visibility-v1.md) (beta) and
-[`decision-trace-v1`](docs/contracts/decision-trace-v1.md) (beta).
+draws the scope boundary. Beta contracts:
+[`memory-visibility-v1`](docs/contracts/memory-visibility-v1.md) ·
+[`decision-trace-v1`](docs/contracts/decision-trace-v1.md).
 
 ## Contribute
 
-Working on the package itself rather than with it?
-[Development](#development) covers the `task ci` pipeline,
-[Requirements](#requirements) the toolchain, and
+Working on the package itself? [Development](#development) covers the
+`task ci` pipeline, [Requirements](#requirements) the toolchain,
 [Maintainer telemetry](#maintainer-telemetry-opt-in-default-off) the
-opt-in measurement loop. The source-of-truth tree is
-`.agent-src.uncompressed/`; never hand-edit the generated `.augment/`
-or `.agent-src/`.
+opt-in measurement loop. Source-of-truth tree is
+`.agent-src.uncompressed/`; never hand-edit `.augment/` or `.agent-src/`.
 
 ## Quickstart
 
@@ -464,18 +484,20 @@ session is explicitly not.
 
 ## You don't need everything
 
-`cost_profile` is the master switch for **rule-tier loading**. The kernel
-(always-loaded Iron-Law floor, ≤ 26k chars across 9 rules) ships in every
-profile; tier-1 and tier-2 rules are gated by profile and resolved at
-session start from `router.json`.
+Pick how much governance your agent loads up front. The safety floor
+(non-destructive defaults, ask-before-guessing, mirror-the-user's-language)
+ships in **every** profile — what changes is how much extra coaching gets
+pulled in alongside it.
 
-| Profile | Rule tiers loaded | Token footprint | Best for |
-|---|---|---|---|
-| **`minimal`** | kernel only (no router, no auto-rules) | lowest | Cost-sensitive sessions; trivial Q&A; CI runs |
-| **`balanced`** (default) | kernel + tier-1 auto-rules | medium | Day-to-day work — current behaviour superset |
-| **`full`** | kernel + tier-1 + tier-2 (everything) | highest | Agent-config development; full rule fidelity |
+| Profile | What you get | When to pick it |
+|---|---|---|
+| **`minimal`** | The non-negotiable safety floor and nothing else. Cheapest, fastest. | Quick questions · throw-away scripts · running in CI · tight token budgets |
+| **`balanced`** (default) | Safety floor plus the everyday coaching most teams want — sensible defaults, code-review nudges, common pitfalls flagged. | Day-to-day work · the right answer if you're not sure |
+| **`full`** | Everything, including the long-tail rules normally only the package maintainers need. | Working on `agent-config` itself · audits · maximum fidelity demos |
 
-Architecture: [`docs/contracts/rule-router.md`](docs/contracts/rule-router.md) (beta) ·
+Under the hood, this is the rule-tier switch: kernel-only · kernel + tier-1
+auto-rules · kernel + tier-1 + tier-2. Architecture details:
+[`docs/contracts/rule-router.md`](docs/contracts/rule-router.md) (beta) ·
 kernel set: [`docs/contracts/kernel-membership.md`](docs/contracts/kernel-membership.md) (beta) ·
 [Configure profiles →](docs/customization.md)
 
@@ -503,53 +525,27 @@ kernel set: [`docs/contracts/kernel-membership.md`](docs/contracts/kernel-member
 
 **Deepest reference stack today: Laravel** — Pest, PHPStan, Rector, Eloquent, Livewire/Flux, Horizon, Pulse, Reverb, Pennant. **Workflow-grade second tier: Symfony** (`symfony-workflow` — DI, Doctrine, Messenger, voters, Twig) and **Next.js App Router** (`nextjs-patterns` — RSC boundaries, Server Actions, caching, route handlers). Other stacks ship in the order they are battle-tested, not second-class. Adopting on a thin stack? Open an issue so we can prioritize the right skills for extraction.
 
----
-
-## Data governance & domain safety
+### …and beyond software (`user-types/`)
 
-12 domain-safety rules (`.agent-src.uncompressed/rules/domain-safety-*.md`) act as a per-domain output floor — PII redaction for support / finance / recruiting / marketing, advice disclaimers for legal / financial / medical / consulting drafts, retention guidance for finance / support, and ops floors for logging / export. Full surface → rule(s) → floor matrix: [`docs/safety.md`](docs/safety.md).
+The same orchestration core drives non-software trades. Worked-example user types ship as the actual prompt-pack the agent loads: [`galabau-field-crew`](.agent-src.uncompressed/user-types/galabau-field-crew.md) (landscaping) · [`metalworking-shop`](.agent-src.uncompressed/user-types/metalworking-shop.md) · [`truck-driver`](.agent-src.uncompressed/user-types/truck-driver.md). Contributing your own? [5-minute scaffold](.agent-src.uncompressed/user-types/_template/) + [conventions](.agent-src.uncompressed/user-types/README.md). Same governance, command suite, and safety rules apply.
 
 ---
 
-## Featured Skills
+## Data governance & domain safety
 
-| Skill | What your agent learns |
-|---|---|
-| [`laravel`](.agent-src/skills/laravel/SKILL.md) | Write Laravel code following framework conventions and project architecture |
-| [`pest-testing`](.agent-src/skills/pest-testing/SKILL.md) | Write Pest tests with clear intent, good coverage, and project conventions |
-| [`eloquent`](.agent-src/skills/eloquent/SKILL.md) | Eloquent models, relationships, scopes, eager loading, type safety |
-| [`create-pr`](.agent-src/commands/create-pr.md) | Create GitHub PRs with structured descriptions from Jira tickets |
-| [`commit`](.agent-src/commands/commit.md) | Stage and commit changes following Conventional Commits |
-| [`/fix ci`](.agent-src/commands/fix.md) | Fetch CI errors from GitHub Actions and fix them |
-| [`/fix pr-comments`](.agent-src/commands/fix.md) | Fix and reply to all open review comments on a PR |
-| [`quality-fix`](.agent-src/commands/quality-fix.md) | Run PHPStan/Rector/ECS and fix all errors |
-| [`bug-analyzer`](.agent-src/skills/bug-analyzer/SKILL.md) | Root cause analysis from Sentry errors or Jira tickets |
-| [`improve-before-implement`](.agent-src/rules/improve-before-implement.md) | Challenge weak requirements before coding |
-| [`docker`](.agent-src/skills/docker/SKILL.md) | Dockerfile, docker-compose, container management |
-| [`security`](.agent-src/skills/security/SKILL.md) | Auth, policies, CSRF, rate limiting, secure coding |
-| [`api-design`](.agent-src/skills/api-design/SKILL.md) | REST conventions, versioning, deprecation |
-| [`database`](.agent-src/skills/database/SKILL.md) | MariaDB optimization, indexing, query performance |
-
-→ [Public catalog](docs/catalog.md) (all rules, skills, commands, guidelines) · [Skills only](docs/skills-catalog.md) · [llms.txt](llms.txt)
+12 domain-safety rules (`.agent-src.uncompressed/rules/domain-safety-*.md`) act as a per-domain output floor — PII redaction for support / finance / recruiting / marketing, advice disclaimers for legal / financial / medical / consulting drafts, retention guidance for finance / support, and ops floors for logging / export. Full surface → rule(s) → floor matrix: [`docs/safety.md`](docs/safety.md).
 
 ---
 
-## Featured Commands
+## Profile entry paths & featured commands
 
-| Command | What it does |
-|---|---|
-| [`/commit`](.agent-src/commands/commit.md) | Stage and commit with Conventional Commits |
-| [`/create-pr`](.agent-src/commands/create-pr.md) | Create PR with Jira-linked description |
-| [`/fix ci`](.agent-src/commands/fix.md) | Fetch and fix GitHub Actions failures |
-| [`/fix pr-comments`](.agent-src/commands/fix.md) | Fix and reply to review comments |
-| [`/optimize skills`](.agent-src/commands/optimize.md) | Audit skills, find duplicates, run linter |
-| [`/feature plan`](.agent-src/commands/feature.md) | Interactively plan a feature |
-| [`/quality-fix`](.agent-src/commands/quality-fix.md) | Run and fix all quality checks |
-| [`/review-changes`](.agent-src/commands/review-changes.md) | Self-review before creating a PR |
-| [`/jira-ticket`](.agent-src/commands/jira-ticket.md) | Read ticket from branch, implement feature |
-| [`/compress`](.agent-src/commands/compress.md) | Compress skills for token efficiency |
-
-→ [Browse all 124 active commands](.agent-src/commands/)
+Deep version of the profile table above (audience · first commands ·
+first skills · preset default per profile):
+[`docs/profiles.md`](docs/profiles.md). Curated featured-commands
+subset: [`docs/featured-commands.md`](docs/featured-commands.md).
+[Browse all 124 active commands](.agent-src/commands/) · full catalog:
+[`docs/catalog.md`](docs/catalog.md) ·
+[skills only](docs/skills-catalog.md) · [`llms.txt`](llms.txt).
 
 ---
 

package/config/agent-settings.template.yml

@@ -30,6 +30,28 @@ agent_config_version: ""
 # custom   = ignore profile — every matrix value must be set explicitly.
 cost_profile: __COST_PROFILE__
 
+# --- Cost tracking + budget enforcement ---
+#
+# USD budgets evaluated against `agents/cost-tracking/sessions.jsonl` by
+# `scripts/cost/budget.mjs`. Empty / 0 = unbudgeted (no enforcement,
+# `cost:check` reports spend only). See docs/contracts/cost-enforcement.md
+# for the full contract (tier ladder, hook surface, bypass mechanism).
+cost:
+  budgets:
+    # Daily USD ceiling (rolling 24h). 0 / null = no daily budget.
+    daily: 0
+    # Weekly USD ceiling (rolling 7d). 0 / null = no weekly budget.
+    weekly: 0
+    # Monthly USD ceiling (rolling 30d). 0 / null = no monthly budget.
+    monthly: 0
+  # Enforcement mode at the HARD_STOP tier (100% utilization):
+  #   advisory  = dashboards and `cost:check` show the breach; agent
+  #               keeps working. Default. Safe for greenfield projects.
+  #   hard-stop = preflight hook (scripts/cost/preflight.mjs) exits
+  #               non-zero on HARD_STOP; CI / shell wrappers refuse to
+  #               start the turn until the budget is raised or reset.
+  enforcement: advisory
+
 # --- Personal preferences ---
 personal:
   # IDE to use for opening files (code, phpstorm, cursor, …)

package/docs/adrs/caveman/0001-default-off-until-bench.md

@@ -0,0 +1,93 @@
+# ADR 0001 — Caveman compression default stays OFF until `task bench`
+
+> Area: `caveman` · Status: accepted · Date: 2026-05-16 · Type: retrospective
+> Roadmap: `agents/roadmaps/step-11-ruflo-parity.md` Phase 4 Step 3
+> Supersedes: —
+
+## Context
+
+Caveman-speak is a turn-time compression dialect that trades English
+grammar for tokens. The dialect is documented in
+[`caveman-speak`](../../../.agent-src.uncompressed/rules/caveman-speak.md);
+the question this ADR records is **whether the dialect should default
+ON for all consumers**.
+
+The North-Star council ([`council-synthesis.md` § 7](../../../agents/audit-2026-05-14-north-star/council-synthesis.md))
+landed split: two voices (token-efficiency, ops) argued default-ON
+saves 40 %+ tokens on long sessions; two voices (UX, governance)
+argued default-ON degrades novice readability and locks in a dialect
+nobody has measured against the real benchmark corpus.
+
+## Decision
+
+**`caveman.speak_scope` defaults `off`**. Carve-outs (security ·
+destructive · multi-step · code blocks · paths · numbered options ·
+Iron-Law markers) stay in the rule body so the dialect is **defined**
+even when **inactive**. The default flips only when `task bench`
+produces measured win/loss numbers against the locked 25-prompt corpus.
+
+Authoritative kill-criterion:
+[`docs/contracts/compression-default-kill-criterion.md`](../../contracts/compression-default-kill-criterion.md)
+§ Rule lines 8–11.
+
+### Decision owner
+
+`step-4-measurement-and-benchmark.md` closeout phase. Not this doc.
+Not `step-99`. Not the North-Star council. The closeout reads
+`docs/parity/bench.json` and applies exactly one of three branches
+defined in the kill-criterion.
+
+### Default-ON gates (all required)
+
+1. ≥ 30 % token reduction averaged across the 25-prompt corpus.
+2. ≤ 5 % regression on the readability score from the same run.
+3. Reversibility check passes (caveman → English round-trip ≥ 95 %
+   semantic preservation per the bench scorer).
+
+Any gate fails → default stays OFF. Re-bench after the next dialect
+edit.
+
+## Considered alternatives
+
+### Alt 1 — Default ON now (rejected)
+
+Flip the default immediately; let consumers opt out.
+
+**Why rejected:** no measured baseline exists. The two pro voices'
+40 % claim is from informal turn-snippet comparisons, not the locked
+corpus. Default-on without measurement is exactly the Ruflo-style
+"trust me it's faster" pattern the audit calls out.
+
+### Alt 2 — Default ON for cost-profile `lean`, OFF for `default` (rejected)
+
+Couple the default to the cost profile.
+
+**Why rejected:** cost profiles already carry profile-specific budget
+ladders and smoke contracts. Adding a dialect coupling makes the
+matrix `2 × N` instead of `1 × N`. The kill-criterion measurement is
+the same regardless of profile — make the decision once.
+
+### Alt 3 — Keep default OFF, measure first (accepted)
+
+The chosen path. Dialect ships, stays dormant, gets benched, then
+either ships default-on or gets deprecated. No middle state.
+
+## Consequences
+
+- **Positive:** new consumers get standard English by default; the
+  novice-onboarding path is unaffected; the dialect is auditable and
+  measurable before it becomes the default cost vector.
+- **Negative:** the 40 %+ token savings are leave-on-table for any
+  consumer who doesn't explicitly opt in. Mitigated by surfacing the
+  flag in `/onboard` once `task bench` lands.
+- **Reversal cost:** flip the default in
+  [`.agent-settings.yml`](../../../.agent-settings.yml.example)
+  template; existing user settings unaffected by template change.
+
+## References
+
+- [`docs/contracts/compression-default-kill-criterion.md`](../../contracts/compression-default-kill-criterion.md) — kill-criterion contract.
+- [`.agent-src.uncompressed/rules/caveman-speak.md`](../../../.agent-src.uncompressed/rules/caveman-speak.md) — dialect definition.
+- [`agents/roadmaps/step-4-measurement-and-benchmark.md`](../../../agents/roadmaps/step-4-measurement-and-benchmark.md) — bench owner.
+- [`agents/audit-2026-05-14-north-star/council-synthesis.md`](../../../agents/audit-2026-05-14-north-star/council-synthesis.md) § 7 — council split.
+- [`agents/roadmaps/step-11-ruflo-parity.md`](../../../agents/roadmaps/step-11-ruflo-parity.md) Phase 4 Step 3 — origin.

package/docs/adrs/caveman/README.md

@@ -0,0 +1,9 @@
+# ADRs — `caveman`
+
+> Caveman-speak compression, decompression, reversibility guards.
+
+Contract: [`docs/contracts/compression-default-kill-criterion.md`](../../../docs/contracts/compression-default-kill-criterion.md).
+
+| # | Title | Status | Date | Supersedes |
+|---|---|---|---|---|
+| [0001](0001-default-off-until-bench.md) | Default Off Until Bench | — | — | — |