@event4u/agent-config 6.0.0 → 7.0.0

package/docs/contracts/skill-domains.md

@@ -100,7 +100,7 @@ artifact**, not its auxiliary side-effects.
 
 ## § 4 — Skill assignment by domain
 
-Snapshot from B3 back-fill (regenerate via `python3 scripts/_emit_domain_table.py`).
+Snapshot from B3 back-fill (regenerate via `./scripts-run src/scripts/_emit_domain_table`).
 Source-of-truth for the assignment is each skill's `domain:` frontmatter —
 this table is a derived view, kept readable for reviewers.
 

package/docs/contracts/smoke-contracts.md

@@ -3,7 +3,7 @@ stability: beta
 keep-beta-until: 2026-08-14
 ---
 
-# Smoke Contracts — Phase 3 of step-11-ruflo-parity
+# Smoke Contracts — Phase 3 of an internal parity roadmap (local-only)
 
 > **Status:** active · **Owner:** step-11 Phase 3 · **Sibling:**
 > [`measurement-baseline.md`](measurement-baseline.md) (snapshot semantics)
@@ -59,7 +59,7 @@ constant in the script body and the row below.
   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
+- **≤ 2 budget breaches** — `./scripts-run src/scripts/measure_rule_budget
   --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`

package/docs/contracts/surface-tiers.md

@@ -0,0 +1,81 @@
+---
+stability: beta
+keep-beta-until: 2026-09-15
+---
+
+# Surface tiers — core vs lab
+
+Every shipped artefact carries a **surface tier** so lab churn cannot
+destabilise the lean engine users install (road-to-install-contract-stability
+Phase 2).
+
+- **`core`** — the lean stable multi-host engine: rules + skills + install +
+  condensation, plus the engineering/authoring packs and the script tooling
+  that build and ship them. This is the adoptable surface.
+- **`lab`** — experimental / pilot meta-tooling that must not ride the same
+  release train as the core: AI media pipelines, the multi-model council, the
+  MCP server, prediction-pool, cost analytics, chat-history, benchmarking.
+
+The split is council-locked (2026-06-17, claude-sonnet-4-5 + gpt-4o, design
+mode, full convergence). Where it lives:
+
+- **Packs/domains** carry `surface_tier: core | lab` in their `pack.yaml`
+  manifest (default `core`; sourced from `src/config/discovery/packs.yml`).
+- **`src/scripts/` clusters** are mapped in
+  [`src/scripts/surface-tiers.yml`](../../src/scripts/surface-tiers.yml)
+  (exhaustive over cluster directories).
+- A **boundary guard** (`scripts/check_surface_tiers.py`) asserts the registry
+  is exhaustive and that no `core` module hard-imports a `lab` module.
+
+## Pack / domain tiers
+
+| Pack / domain | Tier | Reason |
+|---|---|---|
+| engineering-base, git, php, laravel, symfony | core | framework-neutral engineering hygiene + language patterns |
+| javascript, typescript, react, nextjs, python | core | language / framework pattern packs |
+| frontend-design, brand | core | design-intelligence + brand-consistency corpus |
+| product-basic, product-discovery | core | PO/PM + discovery surface |
+| finance-basic, finance-advanced | core | cash/runway + valuation cognition |
+| gtm-sales, gtm-marketing | core | pipeline + positioning surface |
+| ops-people, founder-strategy, small-business, construction | core | stable role/vertical packs |
+| analysis-workbench | core | RCA / post-mortem learning loop, no lab deps |
+| meta, memory, analytics, product-reasoning | core | always-on maintainer engine |
+| **ai-video** | **lab** | AI video pipeline, `trust_level_default: experimental` |
+| **ai-image** | **lab** | AI image generation, `trust_level_default: experimental` |
+| **fun** | **lab** | prediction-pool tips, non-essential, experimental |
+
+## Script-cluster tiers
+
+Authoritative map: [`src/scripts/surface-tiers.yml`](../../src/scripts/surface-tiers.yml).
+
+| Cluster | Tier | Reason |
+|---|---|---|
+| `_cli`, `_lib` | core | install / condense / CLI engine |
+| `adr`, `config`, `hooks`, `schemas`, `skill_tools`, `tools`, `smoke`, `repro` | core | engine tooling: ADR, discovery vocab, hooks, schemas, linters, fixtures |
+| `ai_council` | lab | multi-model council orchestration, external API deps |
+| `mcp_server` | lab | MCP stdio server, separate runtime, pilot distribution |
+| `media`, `ai-video`, `ai-image` | lab | AI media adapters + shared substrate (experimental consumers only) |
+| `command_suggester` | lab | context-aware suggestion engine, pilot; no core caller |
+| `prediction-pool` | lab | prediction-pool optimizer (fun pack) |
+| `cost` | lab | cost tracking / budget gate, observability (not a core/CI dep) |
+| `_archive` | lab | archived / deprecated scripts |
+
+Top-level lab scripts (`council_cli`, `chat_history`, `mine_session`,
+`mcp_render`, `bench_ab_*`, `cost_*`, `build_cloud_bundle`,
+`build_linear_digest`, `build_mcp_registry_manifest`, `memory_report`,
+`memory_signal`, …) are listed under `lab_modules` in the registry; every other
+top-level script defaults to `core`.
+
+## Core → lab coupling
+
+The boundary guard forbids a `core` module from **hard**-importing a `lab`
+module. A `try/except ModuleNotFoundError` *optional* import is allowed —
+core degrades gracefully when lab is absent. The only existing core→lab edges
+are three such guarded optional imports (`_lib/knowledge_global_redaction.py`
+and `_cli/cmd_doctor.py` → `ai_council`); they are tolerated by design.
+
+## See also
+
+- [`install-layout.md`](install-layout.md) — the install-ABI freeze this split builds on.
+- [`src/scripts/surface-tiers.yml`](../../src/scripts/surface-tiers.yml) — the cluster registry.
+- [`docs/architecture.md`](../architecture.md) — core vs full install (the consumer-facing framing).

package/docs/contracts/ticket-bundle-format.md

@@ -0,0 +1,228 @@
+# Ticket-bundle format
+
+> The contract every downstream artifact reads from: the `emit-tickets` skill,
+> the buildability/manifest linters, and the `implement-ticket` bundle
+> input path. Authoritative for the frontmatter
+> schema, the body doctrine, the tracker mapping, and the self-containedness
+> floor. Locked by [ADR-101](../decisions/ADR-101-ticket-bundle-emission.md).
+
+## 1. Why this exists
+
+A roadmap step is a one-line checkbox; the full build spec is spread across the
+roadmap (what), ADRs (why), and the code (how). A `high`-tier agent holds that
+together; a `lite`-tier agent (Haiku) cannot. A **ticket bundle** is the closed,
+durable, importable artifact that lets an expensive planning agent hand a cheap
+building agent a complete unit of work. Markdown is the source of truth; a
+tracker issue (Linear/Jira) is a copy you make by paste or via MCP — not a
+generated export (§8).
+
+## 2. Layout
+
+A bundle is a directory, one per roadmap, under `agents/tickets/`:
+
+```
+agents/tickets/{roadmap-slug}/
+  manifest.yml                 # machine index: dependency graph
+  T-001-{slug}.md              # one ticket = one Markdown build contract
+  T-001-{slug}.assets/         # durable design context for that ticket
+    before.png  wireframe.png  example-io.md
+  T-002-{slug}.md
+  ...
+agents/tickets/_registry.yml   # machine-generated index of all bundles
+```
+
+- **Separate tree, not co-located** under the roadmap — the flat-file dashboard
+  and archival machinery (`update_roadmap_progress.py`,
+  `archive_completed_roadmaps.py`) assume `agents/roadmaps/*.md` are flat files;
+  a separate tree keeps that untouched (ADR-101 R1).
+- **Discovery** is via the generated `agents/tickets/_registry.yml` — one scan,
+  no recursive glob, no roadmap↔manifest circular dependency.
+- **Lifecycle**: a bundle is durable (unlike transient `agents/roadmap-assets/`);
+  when its roadmap archives, the bundle moves with it to
+  `agents/tickets/archive/{slug}/`.
+
+## 3. Ticket frontmatter (schema: `src/scripts/schemas/ticket.schema.json`)
+
+```yaml
+---
+id: T-001                      # bundle-local id; stable handle for the ticket
+roadmap: road-to-xyz           # back-link (traceability spine)
+phase: 2                       # roadmap phase number
+title: "…"                     # → Linear Title
+status: ready                  # ready | draft | done
+model_tier: lite               # lite | medium | high — WHO may build it (ADR-035)
+estimate: 3                    # story points (from estimate-ticket)
+priority: 2                    # 0–4, Linear-compatible
+labels: [backend, mcp]
+parent: T-000                  # → Linear "Parent issue"; null at phase root
+blocked_by: [T-000]            # dependency edges (must be acyclic)
+adr_refs:                      # the "why", SHA-pinned (drift here HARD-blocks)
+  - { path: docs/decisions/ADR-101-ticket-bundle-emission.md, sha: <git-blob-sha> }
+source_refs:                   # files the build reads/changes, SHA-pinned (drift WARNS)
+  - { path: src/scripts/build_linear_digest.py, sha: <git-blob-sha> }
+assets: [T-001.assets/wireframe.png]   # relative to the bundle dir
+acceptance:                    # runnable AND isolation-testable; no prose-only
+  - "python3 src/scripts/lint_ticket_buildable.py exits 0"
+boundaries:                    # ENFORCED by the work_engine boundary guard
+  must_touch:    [src/scripts/lint_ticket_buildable.py]
+  may_touch:     [Taskfile.yml]
+  must_not_touch: [src/scripts/work_engine/**, ".github/**"]
+---
+```
+
+`status` is `done` only after the work landed + verification passed.
+
+## 4. Ticket body doctrine (the build contract)
+
+A lite ticket is autonomous only with this fixed section order:
+
+| Section | Purpose |
+|---|---|
+| `## Why` | 1–3 lines; the outcome, not backstory |
+| `## Context spine` | exact paths (`file.py:142`), the sibling-to-mirror, the producer of any shape it consumes — so the builder never searches |
+| `## Do` | ordered, mechanical steps |
+| `## Do NOT touch` | hard boundaries (mirrors frontmatter `boundaries`) |
+| `## Acceptance` | points at frontmatter `acceptance` (runnable, isolation-testable) |
+| `## Quality gates` | the concrete commands (not "run CI") |
+| `## Assets` | relative links into `T-NNN.assets/` (UI tickets) |
+
+**Self-containedness rule:** if the builder must read a file that is not in the
+context spine or `source_refs`, the ticket is incomplete.
+
+## 5. Self-containedness floor (per `model_tier`)
+
+Enforced by `lint_ticket_buildable.py`. A ticket FAILS the gate if its tier's
+row is not satisfied:
+
+| tier | acceptance | ≥1 concrete path | non-empty boundaries | resolvable assets | size floor |
+|---|---|---|---|---|---|
+| `lite` | required, runnable + isolation-testable | required | required | required (or `assets: none`) | ≤ 5 files AND ≤ 200 lines, else split or escalate to `medium` |
+| `medium` | required | required | recommended | recommended | — |
+| `high` | required | recommended | — | — | — |
+
+A failing `lite` ticket is rejected or auto-escalated to `medium`.
+
+## 6. Manifest (schema: `src/scripts/schemas/ticket-manifest.schema.json`)
+
+```yaml
+status: ready
+planner_tier: high
+builder_tier: lite
+import_targets: { linear: true, jira: false }
+dependency_graph:              # acyclic (no topological layering in v1)
+  T-001: { status: ready, blocks: [T-002] }
+  T-002: { status: ready, blocks: [] }
+```
+
+The manifest carries no tracker state — there is no API export to keep
+idempotent (§8). The bundle is the source of truth; a tracker issue is created
+by paste or by the agent via MCP, never synced back into the manifest.
+
+## 7. Registry (`agents/tickets/_registry.yml`, machine-generated)
+
+```yaml
+bundles:
+  road-to-ticket-bundles:
+    manifest_path: agents/tickets/road-to-ticket-bundles/manifest.yml
+    source_roadmap: agents/roadmaps/archive/road-to-ticket-bundles.md
+    status: in_progress        # derived from manifest
+```
+
+`update_roadmap_progress.py` reads this one file; never recursive-globs bundles.
+
+## 8. Tracker handoff — paste-ready, or via MCP (no API export)
+
+A ticket goes into Linear/Jira **by copy/paste** or, when programmatic, by the
+**agent using a tracker MCP server**. There is **no bundled API client and no
+automatic export** — the ticket Markdown *is* the handoff artifact.
+
+| Ticket field | Tracker issue |
+|---|---|
+| frontmatter `title` | issue title |
+| the Markdown **body** (everything after the frontmatter) | issue description — paste it; Markdown renders in Linear/Jira |
+| `priority` / `estimate` / `labels` | the matching issue fields (set during paste / by MCP) |
+| `parent` (phase root) | parent issue, when the tracker supports sub-issues |
+
+- **Copy/paste (default):** the ticket body is clean, render-ready Markdown.
+  Paste it into a new Linear/Jira issue; set title from `title`. Asset images
+  are relative repo paths — attach them in the tracker, or (public repo) paste a
+  `raw.githubusercontent.com` URL.
+- **MCP (programmatic):** to create issues without pasting, the agent calls the
+  Linear/Jira **MCP server** with the ticket as input. The package ships **no**
+  API wiring of its own — MCP is the integration surface.
+- **One direction only:** the bundle is the source of truth; a tracker issue is
+  a copy, never read back into the bundle (no sync, no `linear_state`).
+
+## 9. Traceability spine (bidirectional)
+
+`roadmap ↔ ticket ↔ ADR ↔ PR`. Each ticket frontmatter names its `roadmap` +
+`adr_refs`; each materialized roadmap step carries an inline
+`<!-- ticket: T-NNN -->` marker. The `work_engine` ticket envelope
+(`{id, title, body, acceptance_criteria}`) is a strict subset of this
+frontmatter, so `/implement-ticket` consumes a bundle with no schema fork.
+
+## 10. Staleness — split severity
+
+`lint_ticket_stale` recomputes the pinned SHAs:
+
+- **`adr_refs` drift → HARD block** (`not build-ready`); ADRs are semantic
+  decisions, rarely change → resolution = re-emit the bundle.
+- **`source_refs` drift → WARN only**; source files churn constantly, so a hard
+  block would keep most tickets perma-stale and multiply bundles. The builder
+  proceeds on a warning.
+
+## 11. Assets — durable, size-capped (LFS deferred)
+
+Git LFS is **not** configured in this repo today, and wiring it (install +
+remote LFS store) is heavier than v1 needs. v1 decision: assets are git-tracked
+binaries under a **size cap** — ≤ 500 KB per asset — and authors prefer vector /
+text context (Mermaid, ASCII, SVG, example-I/O Markdown) over raster where it
+carries the same information. `lint_ticket_buildable.py` warns on any asset over
+the cap. LFS is revisited only if `agents/tickets/**` binary weight is proven a
+real problem (same "defer until observed" discipline as the mutable-tickets
+mode). Non-binary design context lives as plain Markdown in the `.assets/` folder.
+
+## 12. Kill-switch & rollback
+
+Two reversal surfaces, since a bundle is git-tracked and the tracker is a
+projection:
+
+- **Per-ticket.** A ticket is reverted by `git`-restoring its `T-NNN-*.md`
+  (and `.assets/`) to a prior commit. A `lite` build gone wrong is bounded by
+  the ticket's `boundaries` (the work_engine boundary guard halts out-of-scope
+  edits before commit) — so the blast radius is the ticket's `must_touch` set.
+- **Per-bundle.** To abandon a bundle entirely, `git mv` it to
+  `agents/tickets/archive/{slug}/` (it moves with its roadmap on archival,
+  §2) — never delete in place, so the audit trail survives.
+
+A tracker issue created by paste/MCP from a ticket is a one-way copy (§8); the
+bundle is the source of truth, so reverting the bundle needs no tracker
+coordination — fix the issue in the tracker by hand if it was already created.
+
+## 13. Status projection — one direction only
+
+Three surfaces show a ticket's progress; exactly one is the truth and the other
+two are derived. The writeback is **single-directional** so they never become
+rival truths:
+
+```
+ticket `status` (MD)  ──►  roadmap checkbox  ──►  agents/roadmaps-progress.md (dashboard)
+```
+
+- The ticket file's `status` (`ready` / `draft` / `done`) is the **truth**.
+- When a ticket flips to `done`, its roadmap step's `<!-- ticket: T-NNN -->`
+  checkbox flips `[x]` in the **same edit**, and the dashboard regenerates
+  (`./agent-config roadmap:progress`) — the existing `roadmap-progress-sync`
+  cadence, unchanged.
+- A tracker issue (created by paste/MCP, §8) is a point-in-time copy; its state
+  is **not** read back into the ticket. If you keep a tracker issue in sync, do
+  it from the ticket outward (re-paste / MCP update), never the reverse.
+
+Never wire the reverse (tracker → ticket): that recreates the two-drifting-truths
+failure the whole format avoids.
+
+## See also
+
+- [ADR-101](../decisions/ADR-101-ticket-bundle-emission.md) — the format commitment + council convergence.
+- [`roadmaps.md`](../../src/agent-src/templates/roadmaps.md) — the sibling planning artifact.
+- [ADR-035](../decisions/ADR-035-model-capability-tiers.md) — the `model_tier` bands.

package/docs/contracts/universal-skills.md

@@ -87,6 +87,5 @@ Removing a skill is breaking. It must be announced in `STABILITY.md` with a depr
 ## 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.

package/docs/contracts/workspace-boundary.md

@@ -0,0 +1,84 @@
+---
+stability: stable
+---
+
+# Workspace Boundary Contract
+
+> **Status** · stable · 2026-06-14. Governed by
+> [`ADR-095`](../decisions/ADR-095-workspace-boundary-contract.md). Exists to
+> stop "workspace" from becoming the new "meta" — a catch-all that absorbs
+> every nearby concern until it owns everything and means nothing.
+
+The **workspace** is the task-orchestration layer behind `/work`,
+`/implement-ticket`, and the host-drive loop — 13 modules under
+`src/cli/python/workspace_*.py`. This contract draws the line around it.
+
+## Owns
+
+The workspace owns the **orchestration and lifecycle** of work:
+
+- **Task orchestration** — picking up, sequencing, and driving a task to done.
+- **Host-session lifecycle** — host detection, tier selection, fallback, the
+  drive loop, the kill-switch.
+- **Continuation** — multi-turn resume: a long task survives across turns
+  instead of restarting cold.
+- **Drive health** — task completion / abandonment / retry telemetry, drive
+  kill-switch signals, local workspace analytics **as drive-health data**.
+
+## Does NOT own
+
+The workspace orchestrates these domains but does **not** own their
+*design, semantics, or policy*. It may **consume** their artefacts (read a
+skill body to hand it off; read a profile to launch under it) — it must not
+**define** them:
+
+| Not owned | Owner lives at | The line |
+|---|---|---|
+| **Skill design** | `src/skills/`, `condense.py`, `skill_linter.py` | Workspace may *resolve* a skill body for hand-off; it must not define what a skill is or how it is authored. |
+| **Profile semantics** | `src/profiles/`, `build_discovery_manifest.py` | Workspace may *launch under* a profile; it must not decide what a profile means. |
+| **Video-provider logic** | `src/scripts/ai-video/` | Workspace never reaches into provider adapters or lifecycle. |
+| **MCP-registry policy** | the MCP builder / registry surface | Workspace never encodes which MCP servers exist or how they install. |
+| **Analytics product strategy** | the telemetry / product-analytics surface | Workspace records *drive-health* metrics locally; it does not decide analytics product strategy. |
+
+## Drift detection — import-edge check + doc-governance
+
+Two layers, with an explicit division of labour:
+
+1. **Import-edge linter** (`scripts/lint_workspace_boundary.py`, AST-static,
+   wired into CI). Fails if any `src/cli/python/workspace_*.py` module imports
+   an owner-module of a not-owned domain. This is the cheap, precise lock — it
+   catches the most common concrete drift (a workspace module reaching into
+   video / MCP / skill-design internals).
+
+2. **Doc-governance (review).** The import check enforces **import edges
+   only**. It does **not** catch *semantic* drift — a workspace module that
+   encodes profile-semantics or analytics-*product-strategy* judgement without
+   importing anything forbidden. That stays a **review responsibility** against
+   this contract. **A green import check is not proof the boundary holds** — it
+   is one supplement to boundary thinking, not a substitute for it.
+
+### Escape hatch
+
+A genuinely justified import may carry an inline pragma:
+
+```python
+import some_owner_module  # boundary-exception: <reason>
+```
+
+The linter then allows that line. A `boundary-exception` is reviewed like any
+boundary change — it is a documented, deliberate exception, not a silent
+bypass. Persistent exceptions are a signal to revisit this contract or the
+module's placement.
+
+## Day-one state
+
+Survey of all 13 `workspace_*.py` modules (2026-06-14, recorded in ADR-095):
+**zero violations**. The only cross-module import is intra-workspace
+(`workspace_inbox → workspace_skills`). The import check therefore locks a
+boundary that currently holds.
+
+## See also
+
+- [`ADR-095`](../decisions/ADR-095-workspace-boundary-contract.md) — the decision.
+- [`ADR-050`](../decisions/ADR-050-workspace-vs-package-root-boundary.md) — the workspace-vs-package-root trust boundary (this refines it at module level).
+- [`daily-workspace.md`](daily-workspace.md) — the daily-workspace surface contract.

package/docs/cookbook.md

@@ -0,0 +1,152 @@
+# Cookbook — things you can do in a minute
+
+> **Generated** by `scripts/generate_cookbook.py` from `src/flows/cookbook.yaml` + `src/flows/<flow>.yaml` — do NOT hand-edit.
+> Every command and skill below is validated to exist at generation time; a recipe naming a missing command fails the build.
+
+Each recipe is a short command sequence. Run the commands in order; the listed skills are the capabilities they compose.
+
+## Named recipes
+
+### Review a change before it ships
+
+*You have a diff and want a real review, not a rubber-stamp.*
+
+- **Commands:** `/review-changes` → `/judge` → `/quality-fix`
+- **Skills:** `code-review`, `adversarial-review`
+
+### Fix a red CI run
+
+*CI is failing and you want the failure pinpointed and fixed.*
+
+- **Commands:** `/fix:ci`
+- **Skills:** `systematic-debugging`
+
+### Build a feature from a ticket
+
+*You have a ticket and want it refined, estimated, and implemented.*
+
+- **Commands:** `/refine-ticket` → `/estimate-ticket` → `/implement-ticket`
+- **Skills:** `feature-planning`, `test-driven-development`
+
+### Plan a feature before writing code
+
+*The ask is fuzzy and you want a bounded plan first.*
+
+- **Commands:** `/feature:explore` → `/feature:plan`
+- **Skills:** `feature-planning`, `complexity-first-planning`
+
+### Security-audit a surface
+
+*You touched auth / billing / tenancy and want abuse cases first.*
+
+- **Commands:** `/threat-model` → `/judge:solo`
+- **Skills:** `threat-modeling`, `security-audit`
+
+### Open a pull request
+
+*The work is done and you want a clean PR ready for review.*
+
+- **Commands:** `/prepare-for-review` → `/pr:create`
+- **Skills:** `requesting-code-review`, `conventional-commits-writing`
+
+### Research a topic deeply
+
+*You need a multi-source, fact-checked report, not a guess.*
+
+- **Commands:** `/research:deep` → `/research:report`
+- **Skills:** `deep-reading-analyst`
+
+### Investigate and fix a bug
+
+*Something is broken and you want root cause before the patch.*
+
+- **Commands:** `/bug-investigate` → `/bug-fix`
+- **Skills:** `systematic-debugging`, `bug-analyzer`
+
+### Get a second opinion from the AI council
+
+*A design call is genuinely contested and you want independent models.*
+
+- **Commands:** `/council:design` → `/council:debate`
+- **Skills:** `ai-council`
+
+### Process a roadmap autonomously
+
+*You have a roadmap and want it worked end-to-end.*
+
+- **Commands:** `/roadmap:create` → `/roadmap:process-full`
+- **Skills:** `roadmap-management`
+
+### Refactor with a safety net
+
+*You want to restructure code without changing behaviour.*
+
+- **Commands:** `/feature:refactor` → `/review-changes` → `/judge`
+- **Skills:** `code-refactoring`, `test-driven-development`
+
+### Commit in logical chunks
+
+*You have a messy working tree and want clean, scoped commits.*
+
+- **Commands:** `/commit:in-chunks`
+- **Skills:** `conventional-commits-writing`
+
+### Analyze an unfamiliar project
+
+*You just opened a repo and want a fast structural read.*
+
+- **Commands:** `/project-analyze` → `/project-health`
+- **Skills:** `project-analyzer`
+
+### Estimate a ticket
+
+*You need a defensible estimate with the reasoning shown.*
+
+- **Commands:** `/estimate-ticket`
+- **Skills:** `estimate-ticket`
+
+### Run a blame-free post-mortem that teaches the next change
+
+*An incident, near-miss, or risky plan needs analysis that closes the learning loop.*
+
+- **Commands:** `/analyze`
+- **Skills:** `blameless-post-mortem`, `root-cause-frameworks`
+
+### Upgrade a Laravel app one major version
+
+*You want a gated, catalog-driven Laravel major-version upgrade (10→11) on a provisional branch — never auto-PR.*
+
+- **Commands:** `/mission:upgrade`
+- **Skills:** `dependency-upgrade`
+
+## The four work flows
+
+Broader than a single recipe — the end-to-end shapes most work follows.
+
+### Discovery flow
+
+Explore, plan, estimate, refine, and investigate before building. The "what should we build and how" front of the developer journey.
+
+- **Path:** `/feature:explore` → `/feature:plan` → `/estimate-ticket` → `/refine-ticket`
+- **Skills:** `feature-planning`, `estimate-ticket`, `refine-ticket`, `project-analysis-core`, `validate-feature-fit`
+
+### Implementation flow
+
+Build it. The core "make the change" front — drive a prompt, ticket, or feature end-to-end through plan → implement → verify.
+
+- **Path:** `/work` → `/review-changes` → `/quality-fix` → `/commit`
+- **Skills:** `test-driven-development`, `code-review`, `systematic-debugging`, `git-workflow`
+
+### Review flow
+
+Check it. Self-review, judge, quality-fix, and threat-model a change before it ships.
+
+- **Path:** `/review-changes` → `/judge` → `/quality-fix` → `/threat-model`
+- **Skills:** `code-review`, `adversarial-review`, `quality-tools`, `threat-modeling`, `receiving-code-review`
+
+### Delivery flow
+
+Ship it. Commit in logical chunks, open the PR, answer review comments, and prepare the branch for review.
+
+- **Path:** `/commit` → `/pr:create` → `/fix:pr-comments`
+- **Skills:** `conventional-commits-writing`, `git-workflow`, `requesting-code-review`

package/docs/customization.md

@@ -190,6 +190,9 @@ is recovered on the next server boot.
 | `ai_council.cost_budget.max_total_usd` | `0.0` | Per-invocation USD ceiling. `0` disables (token caps still apply). |
 | `ai_council.cost_budget.daily_limit_usd` | `0.0` | Rolling 24h USD ceiling across all `/council` calls. `0` disables. Ledger lives at `~/.event4u/agent-config/council-spend.jsonl` (mode 0600). |
 | `ai_council.session_retention_days` | `14` | Auto-prune for `agents/runtime/council/sessions/` audit folders. Older session directories are removed on the next `save()`. `0` disables (keep forever). |
+| `reasoning.enabled` | `true` | Master switch for the Reasoning Discipline Protocol (RDP). `false` = the whole layer is inert (zero overhead). See [`docs/contracts/reasoning-discipline-protocol.md`](contracts/reasoning-discipline-protocol.md). |
+| `reasoning.auto_gate` | `true` | Benefit-gates RDP on table-free signals (task signal + host self-assessment) so it engages only where it pays. `false` = gate on task-signal + toggles only (skip the host self-assessment). |
+| `reasoning.components.<name>` | `true` | Per-component switches — `orchestrator`, `notes_first`, `grounding`, `intent`, `complexity_first`, `verifier_default`, `prediction_tracking`, `decision_ledger`, `uncertainty_budget`. Each fires only when `reasoning.enabled` **and** the `auto_gate` test passes. |
 
 > **Experimental.** AI Council is not yet validated by external users. API costs apply per consultation.
 
@@ -200,6 +203,14 @@ vars. Pre-2.4 installs at `~/.config/agent-config/<provider>.key` are still
 honoured by the loaders as a fallback. The `/council` command refuses to run
 if the key file's permissions drift.
 
+The `reasoning.*` group controls the **Reasoning Discipline Protocol (RDP)** —
+a cost-gated layer that transplants the *operating discipline* of a frontier
+reasoning model onto any host model (it transfers discipline, never capability).
+For what it does, when it engages, and how to switch it off, see the user-facing
+contract [`docs/contracts/reasoning-discipline-protocol.md`](contracts/reasoning-discipline-protocol.md);
+the sourced rationale lives in the design dossier
+[`docs/guidelines/agent-infra/frontier-reasoning-operating-profile.md`](guidelines/agent-infra/frontier-reasoning-operating-profile.md).
+
 ### Cost profiles
 
 > **Four "cost" concepts — don't confuse them.** Several settings sound like
@@ -242,7 +253,7 @@ to `false` in `.agent-settings.yml` to silence post-task analysis without
 changing the profile.
 
 The authoritative matrix of all matrix-controlled settings lives in
-[`.agent-src.uncondensed/templates/agent-settings.md`](../.agent-src.uncondensed/templates/agent-settings.md).
+[`src/agent-src/templates/agent-settings.md`](../src/agent-src/templates/agent-settings.md).
 
 ### Chat-history defaults per profile
 
@@ -280,7 +291,7 @@ output. Iron-Law gates (`commit-policy`, `scope-control` git-ops,
 | `telegraph.speak_scope` | `off`, `prose_only`, `aggressive` | `prose_only` | How widely telegraph-speak grammar applies in chat. `off` = no telegraph; `prose_only` = telegraph in body prose, numbered options + Iron-Law-literal blocks stay full prose; `aggressive` = telegraph everywhere except Iron-Law literals. |
 
 The cross-rule index for these defaults lives in
-[`.agent-src.uncondensed/contexts/contracts/frugality-charter.md`](../.agent-src.uncondensed/contexts/contracts/frugality-charter.md).
+[`src/agent-src/contexts/contracts/frugality-charter.md`](../src/agent-src/contexts/contracts/frugality-charter.md).
 Writer skills (`skill-writing`, `rule-writing`, `command-writing`,
 `guideline-writing`, `roadmap-writing`, `persona-writing`,
 `agent-docs-writing`, `context-authoring`, `conventional-commits-writing`,
@@ -410,7 +421,7 @@ tarball and is the source of truth consumed by:
 > When you read "the Laravel pack", picture a filter over the shared
 > artefact tree — not a separate npm package. The day ADR-011's
 > extraction trigger flips, the same scan output drives the split;
-> until then, every artefact lives under `.agent-src.uncondensed/`.
+> until then, every artefact lives under `src/`.
 
 Alongside the JSON manifest, the scanner writes
 `dist/discovery/discovery-manifest.json.sha256` — a sidecar hash that
@@ -554,7 +565,7 @@ Run the probe to confirm:
 
 ```bash
 task probe:skills
-# or directly: python3 scripts/probe_skill_registration.py
+# or directly: ./scripts-run src/scripts/probe_skill_registration
 ```
 
 The probe lists every registration across all six tools and flags

package/docs/decisions/ADR-009-event4u-namespace.md

@@ -36,7 +36,7 @@ points surfaced in production use:
    `~/.config/agent-config/claude-desktop/` and called it done. Claude
    Desktop does **not** auto-discover skills from any filesystem path
    — the user must upload each skill through **Settings → Customize →
-   Skills → Upload**. Research against `nextlevelbuilder/ui-ux-pro-max-skill`
+   Skills → Upload**. Research against an external reference suite
    and the Anthropic Skills API docs confirmed there is no public
    bulk-upload API for personal installs (the `/v1/skills` endpoint is
    workspace + code-execution gated).