@event4u/agent-config 6.1.0 → 7.0.1

package/docs/contracts/install-layout.md

@@ -0,0 +1,249 @@
+---
+stability: beta
+keep-beta-until: 2026-09-15
+---
+
+# Install Layout — the on-disk ABI
+
+The **install layout** is the on-disk shape `agent-config` writes into a host:
+the file paths it creates, the JSON-pointer keys it claims in shared/foreign
+config files, the surgical-uninstall pointer schema, and the lockfile shapes.
+For a tool whose promise is "install into your shared host config," this layout
+is part of the public contract — a consumer's working tree, their other tools'
+configs, and any automation that reads the lockfile all depend on it staying
+stable.
+
+This document is the **frozen source** the install-ABI conformance test
+(`tests/test_install_layout_contract.py`) guards against. Any change to the
+shape below must (a) bump `install_layout_version` and (b) carry a
+`### Breaking` / deprecation note per the install-ABI deprecation-window rule in
+[`BREAKING_CHANGES.md`](../../BREAKING_CHANGES.md).
+
+- **Authoritative writer:** [`src/scripts/install.py`](../../src/scripts/install.py)
+  (the wizard plans via `src/install/`, then `install.py --apply-payload`
+  performs the real writes).
+- **Lockfile writers:** [`src/scripts/_lib/installed_tools.py`](../../src/scripts/_lib/installed_tools.py)
+  (project manifest), [`src/scripts/_lib/installed_lock.py`](../../src/scripts/_lib/installed_lock.py)
+  (global lockfile).
+- **Companion contracts:** [`install-scopes.md`](install-scopes.md) (user-global
+  vs project-local), [`installed-tools-lockfile.md`](installed-tools-lockfile.md)
+  (project manifest wire format).
+
+## `install_layout_version`
+
+The on-disk layout carries a single integer version, defined in
+[`src/scripts/_lib/install_layout.py`](../../src/scripts/_lib/install_layout.py)
+as `INSTALL_LAYOUT_VERSION`. The installer stamps it into the global lockfile
+(`~/.event4u/agent-config/installed.lock`) so an installed tree self-declares
+which ABI it was written under.
+
+| Value | Meaning |
+|---|---|
+| absent | **v0 / pre-freeze** — an installed tree written before this contract existed. Treated as the current shape; the installer migrates it in place on the next run. |
+| `1` | **frozen baseline** — the shape documented below. |
+
+A bump to `INSTALL_LAYOUT_VERSION` is a declared layout change: it ships under
+the deprecation-window rule (old + new shape side-by-side for one minor cycle),
+and the installer migrates an older installed tree in place before the old shape
+is dropped.
+
+## Supported tools
+
+The canonical install targets are `_VALID_TOOLS` in
+[`install.py`](../../src/scripts/install.py):
+
+```
+claude-code  claude-desktop  cursor  windsurf  cline  gemini-cli  copilot
+augment  aider  codex  roocode  continue  kilocode  zed  jetbrains  kiro
+qoder  opencode  trae  antigravity  codebuddy  droid  warp
+```
+
+`all` is an expansion sentinel accepted by `--tools`, not a tool.
+
+## Written paths
+
+Two install scopes (see [`install-scopes.md`](install-scopes.md)): **project-local**
+(`<root>/…`) and **user-global** (`~/…`). The layout below is the union; a given
+run writes only the subset for the selected scope + tools.
+
+### Always-written project files (both scopes)
+
+| Path | Kind | Notes |
+|---|---|---|
+| `<root>/agents/settings/.agent-settings.yml` | deployed | canonical YAML settings (ADR-038) |
+| `<root>/.agent-settings.yml` | deployed | legacy fallback; migrated then removed on first run |
+| `<root>/agents/.event4u-bridge.yml` | bridge | project → `~/.event4u/agent-config/` pointer; schema `event4u-bridge/v1` |
+| `<root>/agents/.agent-state/install-mode.txt` | marker | `minimal\n` or `full\n` |
+
+Minimal-install scaffold (override layer): `agents/overrides/{rules,skills,commands}/.gitkeep`,
+`agents/overrides/README.md`.
+
+VSCode substrate bridge: `<root>/.vscode/settings.json` key
+`/chat/pluginLocations/<plugin_path>` is written unconditionally and is
+**intentionally not tracked** in the manifest (see § Untracked surfaces).
+
+### Per-tool project-scope bridge markers
+
+`PROJECT_BRIDGE_MARKERS` in [`install.py`](../../src/scripts/install.py). The
+manifest records the marker path as the tool's `bridge_marker`.
+
+| Tool | Path (project-relative) | Kind |
+|---|---|---|
+| claude-code | `.claude/settings.json` | bridge (JSON merge) |
+| claude-desktop | `.claude-desktop/agent-config.md` | marker |
+| cursor | `.cursor/hooks.json` | bridge (JSON merge) |
+| windsurf | `.windsurf/hooks.json` | bridge (JSON merge) |
+| cline | `.clinerules/hooks/<HookName>` (6 hook scripts) | bridge (executable) |
+| gemini-cli | `.gemini/settings.json` | bridge (JSON merge) |
+| copilot | `.github/plugin/marketplace.json` | bridge (whole-file write) |
+| augment | `.augment/settings.json` | bridge (JSON merge) |
+| aider | `.aider/agent-config.md` | marker |
+| codex | `.codex/agent-config.md` | marker |
+| roocode | `.roo/rules/agent-config.md` | marker |
+| continue | `.continue/rules/agent-config.md` | marker |
+| kilocode | `.kilocode/rules/agent-config.md` | marker |
+| zed | `.zed/agent-config.md` | marker |
+| jetbrains | `.jetbrains/agent-config.md` | marker |
+| kiro | `.kiro/steering/agent-config.md` | marker |
+
+Anchor-pointer bridges (subset, project scope): `.windsurf/agent-config.bridge.yml`,
+`.clinerules/agent-config.bridge.yml`, `.gemini/agent-config.bridge.yml`.
+
+> **Known gap (frozen as-is):** `qoder`, `opencode`, `trae`, `antigravity`,
+> `codebuddy`, `droid`, `warp` are valid tools with global deploy sources but no
+> project-scope bridge marker — a project-scope install of these writes no marker
+> and records no `bridge_marker`. The contract freezes the current behaviour; a
+> future addition of markers for these tools is an additive (non-breaking) change.
+
+### User-global content deployment (`--global` / `--scope=global`)
+
+User-scope anchor roots are `USER_SCOPE_PATHS`; deployed subtrees are
+`GLOBAL_DEPLOY_SOURCES` (both in [`install.py`](../../src/scripts/install.py)).
+
+| Tool | User-scope anchor | Deployed subtrees |
+|---|---|---|
+| claude-code | `~/.claude/` | `rules/`, `skills/`, `commands/`, `personas/` |
+| augment | `~/.augment/` | `rules/`, `skills/`, `commands/`, `contexts/`, `personas/`, `templates/` |
+| cursor | `~/.cursor/` | `rules/`, `commands/`, `personas/` |
+| windsurf | `~/.codeium/windsurf/` | `rules/` |
+| cline | `~/Documents/Cline/Rules/` | flat `rules/` (no sub-prefix) |
+| gemini-cli | `~/.gemini/` | `rules/`, `skills/`, `commands/`, `personas/` |
+| codex | `~/.codex/` | `rules/`, `skills/`, `commands/`, `personas/` |
+| continue / roocode / kilocode / qoder / opencode / trae / codebuddy | `~/.continue/`, `~/.roo/`, `~/.kilocode/`, `~/.qoder/`, `~/.opencode/`, `~/.trae/`, `~/.codebuddy/` | claude-code bundle |
+| antigravity | `~/.agents/` | claude-code bundle |
+| droid | `~/.factory/` | claude-code bundle |
+| warp | `~/.warp/` | claude-code bundle |
+| kiro | `~/.kiro/` | `rules/`, `steering/`, `personas/` |
+| claude-desktop | `~/Library/Application Support/Claude/agent-config.md` (marker) | `~/.event4u/agent-config/claude-desktop/bundles/*.zip` |
+
+Tools `copilot`, `aider`, `zed`, `jetbrains` write no global content (hint
+printed only).
+
+### Global runtime root (`~/.event4u/agent-config/`)
+
+| Path | Writer | Notes |
+|---|---|---|
+| `installed.lock` | `installed_lock.py` | global lockfile (carries `install_layout_version`) |
+| `.agent-settings.yml` | `install.py` | global layer of the three-layer settings merge |
+| `.agent-user.yml` | `install.py` | user personal settings |
+| `install-log.jsonl` | `src/install/` (TS) | transaction log (TS engine only) |
+
+### User-scope hook trampolines (explicit-flag only)
+
+Written only with `--{augment,cursor,cline,windsurf,gemini}-user-hooks`:
+a per-tool `*-dispatcher.sh` under the tool's hook dir, plus a JSON merge into
+that tool's user-scope settings/hooks file (cline also writes 6 hook wrappers).
+
+## Claimed JSON-pointer keys
+
+All JSON merges use `deep_merge()` — recurse into nested dicts, replace at
+leaves; sibling keys owned by other tools survive. The exceptions are noted.
+
+| File | Pointer(s) | Merge / overwrite |
+|---|---|---|
+| `.augment/settings.json` | `/enabledPlugins/agent-config@event4u` | deep_merge |
+| `~/.augment/settings.json` | `/hooks/{SessionStart,SessionEnd,Stop,PreToolUse,PostToolUse}/0` | deep_merge (array-replace) |
+| `.claude/settings.json` | `/enabledPlugins/agent-config@event4u-agent-config` | deep_merge |
+| `.cursor/hooks.json`, `~/.cursor/hooks.json` | `/hooks/{sessionStart,sessionEnd,stop,beforeSubmitPrompt,postToolUse}` | deep_merge |
+| `.windsurf/hooks.json`, `~/.codeium/windsurf/hooks.json` | `/hooks/{post_setup_worktree,pre_user_prompt,post_cascade_response}` | deep_merge |
+| `.gemini/settings.json`, `~/.gemini/settings.json` | `/hooks/{SessionStart,SessionEnd,AfterAgent,BeforeAgent,AfterTool}` | deep_merge |
+| `.github/plugin/marketplace.json` | `/marketplace/name`, `/marketplace/plugins/0` | **whole-file write** |
+| `.vscode/settings.json` | `/chat/pluginLocations/<path>` | deep_merge (**untracked**) |
+
+Per the manifest contract, RFC-6901 pointers target object keys, never array
+indices — except the documented hook-array replacements above, which the
+installer owns wholesale.
+
+## Surgical-uninstall pointer schema
+
+An uninstall/prune flow removes exactly what the installer wrote, leaving
+foreign keys and files intact. The pointers it follows:
+
+1. **`bridge_marker`** (per tool) — single canonical path proving the tool is
+   installed. Existence-tracked; removal signals complete uninstall for that tool.
+2. **`files[]`** (per tool) — objects with `path`, `kind` ∈ `{deployed, bridge, marker}`,
+   and `sha256` (or `null` for markers). `deployed` = owned content (delete);
+   `bridge` = shared config (remove only our keys); `marker` = sentinel (delete).
+3. **`merged_keys[]`** (per tool) — objects with `file` + `json_pointer` (+ optional
+   `value_hash`). Uninstall removes only these keys.
+4. **`status`** — `installed` (default) or `uninstalling`; the two-phase uninstall
+   resume target (`agent-config prune --resume-uninstall` sweeps only `uninstalling`
+   entries' `files[]`).
+
+Full wire format: [`installed-tools-lockfile.md`](installed-tools-lockfile.md).
+
+## Lockfile shapes
+
+### Project manifest — `agents/installed-tools.lock`
+
+`schema_version: 2`, reader tolerates v1 + v2. Wire format is the canonical
+contract in [`installed-tools-lockfile.md`](installed-tools-lockfile.md); this
+layout contract freezes that the file exists at that path and carries that shape.
+
+### Global lockfile — `~/.event4u/agent-config/installed.lock`
+
+Written by `installed_lock.py`. Frozen shape:
+
+```yaml
+schema_version: 1
+install_layout_version: 1
+agent_config_version: "<semver>"
+installed_at: "<ISO-8601 UTC>"
+tools:
+  - claude-code
+  - cursor
+```
+
+`install_layout_version` is the field this contract adds (§ `install_layout_version`).
+Absent on a pre-freeze tree → treated as v0, migrated in place. The legacy
+`~/.config/agent-config/installed.lock` is read as a fallback, never written.
+
+## Untracked surfaces (frozen as known gaps)
+
+These are written but **not** recorded in any lockfile; uninstall cannot
+currently undo them. They are frozen as documented behaviour, not contract
+promises — fixing them is an additive change (recording a previously-untracked
+write), never a breaking one.
+
+- `.vscode/settings.json` `chat.pluginLocations` (substrate bridge, written
+  unconditionally).
+- User-scope `merged_keys` (the global install path passes `files_by_tool` but
+  not `merged_keys_by_tool`, so JSON merges into `~/.augment/settings.json`,
+  `~/.cursor/hooks.json`, etc. are unrecorded).
+- Best-effort legacy-trampoline removal (`OSError` swallowed; failed removals
+  leave stale files with no manifest entry).
+
+## `--apply-payload` entry point
+
+The real-apply path consumes a JSON payload (`wizard-v2` or legacy `installer-v1`
+schema) and writes the layout above, emitting NDJSON progress frames
+(`{"type":"file",…}`, `{"type":"done"}`, `{"type":"error",…}`). `dry_run: true`
+previews without writing. The payload schema is a separate wire contract from the
+on-disk layout this document freezes.
+
+## See also
+
+- [`STABILITY.md`](STABILITY.md) — beta/stable contract policy.
+- [`BREAKING_CHANGES.md`](../../BREAKING_CHANGES.md) — install-ABI deprecation-window rule.
+- [`install-scopes.md`](install-scopes.md) · [`installed-tools-lockfile.md`](installed-tools-lockfile.md).
+- [`tests/test_install_layout_contract.py`](../../tests/test_install_layout_contract.py) — the conformance test that locks this shape.

package/docs/contracts/kernel-membership.md

@@ -259,7 +259,7 @@ with the trigger-relaxed parameter, lock new value, re-attempt.
 
 | check | command | acceptance |
 |---|---|---|
-| Pilot reproducibility | `python3 scripts/_pilot_measure.py` | r-values, sum, SHAs identical across runs |
+| Pilot reproducibility | `./scripts-run src/scripts/_pilot_measure` | r-values, sum, SHAs identical across runs |
 | Iron-Law preservation | SHA-256 of fence-block content (whitespace-norm, case-fold) | all 3 pilots match originals |
 | Bucket projection | `r_median × sum(always)` | ≤ 25 000 chars |
 | Per-rule cap (P2.1) | `measure_rule_budget.py --kernel-budget-check` (P2 deliverable) | each ≤ 2 500 chars OR ADR |

package/docs/contracts/linear-ai-rules-inclusion.md

@@ -11,7 +11,7 @@ keep-beta-until: 2026-08-12
 > agent (Codegen, Charlie, Cursor's Linear app, …) reads it verbatim —
 > no skill triggering, no script execution, no `.augment/` access.
 >
-> Source of tier data: `python3 scripts/audit_cloud_compatibility.py
+> Source of tier data: `./scripts-run src/scripts/audit_cloud_compatibility
 > --details` (47 rules: T1=20, T2=19, T3-S=8).
 >
 > Last refreshed: 2026-04-29.
@@ -135,7 +135,7 @@ persistence on cloud platforms; the rule is a no-op.
 ## Source of tier data
 
 ```
-python3 scripts/audit_cloud_compatibility.py --details --format json
+./scripts-run src/scripts/audit_cloud_compatibility --details --format json
 ```
 
 47 rules: T1=20, T2=19, T3-S=8. Counts in this document derive from the

package/docs/contracts/linter-structural-model.md

@@ -66,7 +66,7 @@ imperatives (`NEVER COMMIT.`).
 Sweep covered all 310 lintable artifacts via
 [`scripts/measure_density.py`](../../src/scripts/measure_density.py); raw
 data lives at `agents/runtime/density/snapshot.jsonl` (local-only — re-run
-`python3 scripts/measure_density.py --root dist/agent-src --jsonl
+`./scripts-run src/scripts/measure_density --root dist/agent-src --jsonl
 agents/runtime/density/snapshot.jsonl` to regenerate).
 
 | Type | Count | Avg density | Median | Bucket [0.4-0.6] | Bucket [0.6-1.0] |

package/docs/contracts/mcp-discovery-phase-notice.md

@@ -35,7 +35,7 @@ raw identifiers (J4 in the roadmap). Three outcomes are logged:
 On any host running the stdio server:
 
 ```bash
-python3 scripts/mcp_telemetry_health.py
+./scripts-run src/scripts/mcp_telemetry_health
 ```
 
 Healthy → exit 0 with the 24 h count. Silent → exit 1; treat as an alert.

package/docs/contracts/multi-tool-projection-fidelity.md

@@ -105,7 +105,7 @@ native `model:`. See ADR-035 and `road-to-model-capability-tiers.md`.
 | `skill:laravel` | skill | Augment + Claude only; rationale for absence on others |
 | `command:commit` | command | per-tool command surface divergence |
 
-Run: `python3 scripts/probe_projection_fidelity.py` — exits non-zero on any divergence. Report at `agents/runtime/reports/projection-fidelity.json`.
+Run: `./scripts-run src/scripts/probe_projection_fidelity` — exits non-zero on any divergence. Report at `agents/runtime/reports/projection-fidelity.json`.
 
 ## Known divergences (do not file as bugs)
 

package/docs/contracts/namespace.md

@@ -91,9 +91,9 @@ Diagnostic format: one issue per line — `<path>: <rule> — <detail>`.
 Pick the name; verify locally:
 
 ```bash
-python3 scripts/lint_namespace.py --name <candidate>
+./scripts-run src/scripts/lint_namespace --name <candidate>
 # or full run:
-python3 scripts/lint_namespace.py
+./scripts-run src/scripts/lint_namespace
 ```
 
 If the candidate fails, the linter prints the rule it violated.

package/docs/contracts/no-runtime-boundary.md

@@ -0,0 +1,56 @@
+# No-Runtime Boundary Contract
+
+> **Audience:** Every Mission-Mode decision, skill author, and recipe reviewer.
+> Read this before asking "is X allowed in a mission step?"
+
+AC is a **file-first, no-runtime suite** — skills and missions emit text and
+files; they do not spawn processes, own state stores, or poll the environment.
+This contract makes that boundary explicit for the Mission-Mode layer.
+
+See also: `lethal-trifecta-guard` (no private-data + untrusted-content +
+external-comms in one autonomous path), and the internal agent-memory sunset
+decision (cross-session persistent stores rejected as architecturally unsound
+and violating the no-runtime principle).
+
+---
+
+## Allowed
+
+| Category | Examples | Notes |
+|---|---|---|
+| **Codegen / file emit** | Write a migration file, emit a `UPGRADE.md` plan, produce a diff patch | The canonical mission output |
+| **File I/O** | Read `composer.json`, write `.work-state.json`, append to a report | Single-invocation scope only |
+| **Multi-turn prompting** | Agent asks user to run `php artisan migrate`, user pastes result back | Human stays in the loop; agent interprets the pasted output |
+| **git-as-state** | `git commit -m "mission:upgrade step=11 status=ok"`, `git revert HEAD`, `git reset --soft HEAD~1` | AC shells out to git constantly — structured commit messages are logging, not a daemon; rollback is `git revert` / branch reset on a provisional `mission/…` branch |
+| **Shell invocation (single-shot)** | `composer install`, `php artisan test --filter=…` run once per step and their output piped back | One-shot, result returned immediately; never a background job |
+| **Report / plan files** | Write `agents/evidence/mission-upgrade-decision.md`, emit a breaking-change checklist | Authoring-time output, not a runtime artifact |
+
+---
+
+## Prohibited
+
+| Category | Why |
+|---|---|
+| **Background processes / daemons** | No spawned subprocesses that outlive the current agent turn |
+| **Cross-session persistent state stores** | No SQLite, pgvector, MCP memory servers, Redis, or any store that persists beyond the git working tree — agent-memory layer sunset applies here |
+| **Event loops / polling** | No `while true; do …; done`, no `inotifywait`, no cron-inside-mission |
+| **Auto-PR / auto-push** | Hard-Floor (`non-destructive-by-default`): missions never push to remote or open PRs autonomously; those gates require explicit user confirmation every turn |
+| **Network egress from mission scripts** | Mission scripts may not initiate outbound HTTP calls; skills that need network access declare `allowed_tools` explicitly and go through the normal lethal-trifecta gate |
+
+---
+
+## Gray — requires council review before adopting
+
+| Pattern | Risk | Gate |
+|---|---|---|
+| **Conditional branching on prior step outputs** | Missions could become implicit state machines, defeating the no-runtime constraint | Must be expressed as a skill decision tree with explicit LLM judgment — not a script `if`/`else`; council sign-off required per mission |
+| **File-based state within a single invocation** | `.work-state.json` already exists and may gain a `mission_history` key — that is allowed; adding new control-flow primitives (loops, conditional keys that drive execution) is **not** | Extension of `.work-state.json` for logging is OK; adding execution-control semantics requires a new ADR |
+| **Nested sub-missions** | Could create unbounded depth; Phase 1 PoC must first prove a flat sequence is sufficient | Defer until Phase 1 evidence shows a real need |
+
+---
+
+## Decision authority
+
+A mission step that is unclear against this contract goes to the AI Council
+(`python3 src/scripts/council_cli.py`) before any build work starts.
+The council verdict becomes an ADR if it changes this table.

package/docs/contracts/package-self-orientation.md

@@ -22,6 +22,30 @@ as `event4u/agent-config` / `@event4u/agent-config`. No application
 runtime. Installed via `scripts/install.sh` (Bash) and
 `scripts/install.py` (Python bridge).
 
+## Authoring-time vs. runtime — the scope line
+
+The package is an **authoring-time orchestration toolkit, not an agent
+runtime.** This single distinction decides what belongs in the package
+and what is out of charter — cite it instead of re-deriving the boundary
+per proposal.
+
+- **Authoring-time (in scope).** Code that runs during prompt
+  construction or in response to an explicit user command, assembling
+  context / skills for the agent to *review* — e.g. `compile_router.py`
+  (deploy-time routing table) and `work_engine` (assembles directives
+  when the user types `/work`; the **agent**, not the engine, decides
+  whether to execute the next step — there is no `while not
+  task_complete:` LLM loop in `dispatcher.py`).
+- **Runtime (out of scope).** Code that executes autonomously *during
+  agent operation*, making decisions or LLM calls without per-step human
+  approval — auto-retry loops, autonomous tool-calling, self-modifying
+  skill selection.
+
+When a proposal (a competitor surface, an external-LLM suggestion, a new
+skill idea) would require the package to *run* an agent loop, it crosses
+this line and is rejected on scope, not on merit. Durable application:
+`road-to-capability-discoverability.md` (disposition of "fable-feedback-3").
+
 ## The four wings
 
 Four wings compose via [`cross-wing-handoff.md`](cross-wing-handoff.md)

package/docs/contracts/provider-lifecycle.md

@@ -36,11 +36,11 @@ the human noticing.
    `agents/reference/ai-video/smoke-traces/<provider>.md` with timestamp,
    model id, and **redacted** response shape.
 2. **Secret-redaction confirmation** — the captured trace, re-read
-   through `scripts/ai-video/lib/redact.sh`, shows zero residual
+   through `scripts/media/lib/redact.sh`, shows zero residual
    key fragments.
 3. **Contract conformance** — the adapter's four-method shell
    surface (`submit / poll / fetch / dry-run` *or* `run / dry-run`)
-   matches `scripts/ai-video/lib/adapter-contract.md` verbatim.
+   matches `scripts/media/lib/adapter-contract.md` verbatim.
 
 A maintainer flipping the tier in `agents/templates/.ai-video.xml.example`
 **and** the adapter header comment is the promotion event. There is
@@ -117,6 +117,6 @@ snapshot — older snapshots live in git history, not in this file.
 ## See also
 
 - [`provider-lifecycle-discipline`](../../dist/agent-src/rules/provider-lifecycle-discipline.md) — the tier-2 routing rule that surfaces this contract when a provider is touched.
-- [`scripts/ai-video/lib/adapter-contract.md`](../../src/scripts/ai-video/lib/adapter-contract.md) — the four-method shell contract every adapter implements.
+- [`scripts/media/lib/adapter-contract.md`](../../src/scripts/media/lib/adapter-contract.md) — the four-method shell contract every adapter implements.
 - [`agents/templates/.ai-video.xml.example`](../../agents/templates/.ai-video.xml.example) — operator-facing provider configuration template (carries the tier tag inline).
 - [`agents/settings/policies/media/README.md`](../../agents/settings/policies/media/README.md) — the agent-in-the-loop enforcement model this contract participates in.

package/docs/contracts/reasoning-discipline-protocol.md

@@ -0,0 +1,83 @@
+---
+stability: beta
+keep-beta-until: 2026-09-14
+---
+
+# Reasoning Discipline Protocol (RDP) — User Contract
+
+> **Status:** beta · **Owner:** package maintainer · **Last reviewed:** 2026-06-16
+>
+> The one-screen, user-facing contract for the `reasoning.*` settings. It says
+> what RDP does, when it engages, and how to switch it off. The sourced design
+> rationale lives in the dossier
+> [`docs/guidelines/agent-infra/frontier-reasoning-operating-profile.md`](../guidelines/agent-infra/frontier-reasoning-operating-profile.md);
+> the runtime cost-gate mechanic lives in
+> [`contexts/execution/rdp-gate.md`](../../src/agent-src/contexts/execution/rdp-gate.md). <!-- ref-ignore -->
+> This file is the entry point; depth stays there.
+
+## What RDP does
+
+RDP transplants the **operating discipline** of a frontier reasoning model onto
+whatever host model you run — the steps a strong model takes on its own that a
+weaker one skips unless prompted. When engaged, it nudges the agent toward:
+
+- **notes-first** — keeping multi-hypothesis reasoning, predictions, and
+  decisions in the session notes rather than the response;
+- **complexity-first** — resolving the load-bearing unknown before writing code;
+- **verifier** — a fresh-context check on structurally risky work
+  (branching · multiple constraints · stateful · irreversible);
+- **orchestrator** — a single coordination point that sequences the chain.
+
+These are disciplines the agent *applies*, not guarantees it *enforces*: how much
+of each applies is decided by the gate below, and a strong-reasoning host may
+apply them lightly or skip them where they would not pay.
+
+```
+CAPABILITY DOES NOT TRANSFER. DISCIPLINE DOES.
+```
+
+RDP makes the agent **work** more like a frontier model on under-specified and
+long-horizon tasks. It does **not** make a weaker model as *capable* as one — no
+prompt closes the weights gap.
+
+## When it engages
+
+RDP never runs on every turn. It engages only where it pays, decided by three
+**table-free** signals (there is no runtime model→band lookup — ADR-035):
+
+1. **Settings** — your `reasoning:` block (below). `enabled: false` stops here.
+2. **Task signal** — skips trivial / short / fully-specified tasks (rename, typo,
+   one-line edit, list files); engages on complex / ambiguous / multi-component /
+   long-horizon / stateful / irreversible work.
+3. **Host self-assessment** — a strong-reasoning host applies the discipline
+   **lightly / as a suggestion**; a standard host applies it **fully**. The agent
+   introspects; no maintained model list exists.
+
+The verifier carries its own stricter gate — it fires only on genuinely risky,
+non-trivial work, so the most expensive component stays rare. The exact
+condition lives in the gate context (it may evolve; this contract does not pin
+it).
+
+## How to turn it off
+
+All switches live in the `reasoning:` block of `.agent-settings.yml` (repo root;
+full schema in [`docs/customization.md`](../customization.md) § Available
+settings):
+
+| Goal | Setting |
+|---|---|
+| Disable the whole layer (zero overhead) | `reasoning.enabled: false` |
+| Keep the layer, drop the host self-assessment | `reasoning.auto_gate: false` (gate on task-signal + toggles only) |
+| Disable one behaviour | `reasoning.components.<name>: false` (e.g. `verifier_default`) |
+
+A component fires only when `reasoning.enabled` is `true` **and** the `auto_gate`
+test passes.
+
+## Why it is not a Fable / Mythos copy
+
+A frontier model's edge lives in its weights, which no prompt copies — so RDP
+copies the *discipline*, never the model. It ships **one** constraint-light
+scaffold with no "heavy" variant (two variants would be a hidden model→band
+table, forbidden by ADR-035); a host that wants more asks at turn time. The
+sourced evidence — including why over-prescription degrades a strong host — is in
+the dossier.

package/docs/contracts/rule-classification.md

@@ -29,7 +29,7 @@ document is the disposition map P2 / P4 will execute against.
 | auto | 47 | 142 297 | ≤ 60 000 |
 | **total** | **56** | **174 700** | **≤ 85 000** |
 
-Source: `python3 scripts/measure_rule_budget.py`.
+Source: `./scripts-run src/scripts/measure_rule_budget`.
 
 ## § 3 — Disposition table
 
@@ -142,8 +142,8 @@ Reference / examples / mechanics. Body migrates into
 
 | check | command | acceptance |
 |---|---|---|
-| Coverage | `python3 scripts/measure_rule_budget.py` | 56 rules total → 9 kernel + 22 condense + 18 skill + 7 guideline |
-| Determinism | `python3 scripts/measure_rule_budget.py --json` × 2 | byte-identical output |
+| Coverage | `./scripts-run src/scripts/measure_rule_budget` | 56 rules total → 9 kernel + 22 condense + 18 skill + 7 guideline |
+| Determinism | `./scripts-run src/scripts/measure_rule_budget --json` × 2 | byte-identical output |
 | No-edits | `git diff --stat .agent-src.uncondensed/rules/` | clean (this is plan-only) |
 
 ## § 5 — Open questions

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

@@ -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).