@event4u/agent-config 2.26.0 → 3.1.0

package/docs/contracts/agent-user-schema.md

@@ -23,10 +23,11 @@ explicit `accept` step.
 ---
 version: 1
 identity:
-  name: "Mathias"          # required — full name or how the user wants to be addressed
-  nickname: "Matze"        # optional — preferred shorthand (used by default in chat)
+  name: "Matze"            # required — how the user wants to be addressed (full name or shorthand)
 language: "de"             # required — BCP-47-ish primary language ("de", "en", "fr", ...)
-role: "founder/engineer"   # required — short free-form role label
+role:                      # required — unordered list of role labels; ≥ 1 entry
+  - founder
+  - engineer
 style:
   formality: "informal"    # informal | formal
   pace: "pragmatic"        # pragmatic | thorough | rapid
@@ -36,6 +37,13 @@ last_updated: "2026-05-15" # YYYY-MM-DD — bumped on every accepted change
 ---
 ```
 
+`role` is an **unordered** YAML block-style list. Order carries no meaning
+(no "primary" role). The seeded enum mirrors `SEED_PROFILE_IDS` in
+[`scripts/config/profiles.py`](../../scripts/config/profiles.py):
+`founder`, `developer`, `content_creator`, `agency`, `finance`, `ops`.
+Free-form additions are accepted (forward-compatibility) — closed
+validation lives in the wizard / settings GUI, not in the loader.
+
 After the frontmatter, the body is a single freeform **`# Notes`**
 section. Hard cap: **100 lines** total file size (including
 frontmatter, body, and the Notes section). The 100-line cap is
@@ -46,10 +54,9 @@ enforced by `/agents user accept` and `/agents user update`.
 | Field | Required | Purpose |
 |---|---|---|
 | `version` | yes | Schema version. v1 is the only valid value today. |
-| `identity.name` | yes | Default address form. |
-| `identity.nickname` | no | Preferred shorthand — agent uses this by default in chat replies when set. |
+| `identity.name` | yes | How the agent addresses the user (full name or shorthand — user's choice). |
 | `language` | yes | Primary language; the agent mirrors per [`language-and-tone`](../../.agent-src/rules/language-and-tone.md). |
-| `role` | yes | Short free-form label — drives reviewer voice selection and persona pairing. |
+| `role` | yes | Unordered list of role labels (≥ 1). Drives reviewer-voice selection and persona pairing. Seeded enum mirrors `SEED_PROFILE_IDS`; additional free-form entries accepted. |
 | `style.formality` | yes | `informal` (Du / first-name) or `formal` (Sie / full name). |
 | `style.pace` | yes | `pragmatic` (default), `thorough` (more verification), or `rapid` (shorter replies). |
 | `voice_sample` | yes | One representative paste — anchors mirror-back and tone calibration. |
@@ -77,11 +84,10 @@ Host agents read `.agent-user.md` at session start, in this priority
 order:
 
 1. `.agent-user.md` at project root (this contract).
-2. `personal.user_name` in `.agent-settings.yml` (legacy fallback).
-3. Nothing — agent uses generic address forms.
+2. Nothing — agent uses generic address forms.
 
-The host agent surfaces the user's `identity.nickname` (or `name` if
-unset) on first reply when the file is present.
+The host agent surfaces the user's `identity.name` on first reply
+when the file is present.
 
 ## Determinism floor
 
@@ -134,7 +140,7 @@ Each line is a single JSON object:
 {"ts":"2026-05-15T10:23:00Z","field":"style.pace","suggest":"rapid","source":"chat","evidence":"user said 'mach kürzer' 3× this session"}
 ```
 
-Allowed `field` values mirror the schema (`identity.nickname`,
+Allowed `field` values mirror the schema (`identity.name`,
 `language`, `role`, `style.formality`, `style.pace`, `voice_sample`,
 `notes`). Anything outside that set is dropped on read.
 

package/docs/contracts/ai-council-config.md

@@ -3,16 +3,16 @@ stability: beta
 keep-beta-until: 2026-08-12
 ---
 
-# AI-Council Config (`agents/.ai-council.yml`)
+# AI-Council Config (`agents/settings/.ai-council.yml`)
 
 **Purpose.** Lock the schema, validation, and precedence rules for the
 centralized council config file. Every phase of the AI-Council
 consolidation work reads from this file; the contract here is the
 boundary that prevents drift across the loader, the CLI, the
-orchestrator, and the `agents/.ai-council.yml` file itself.
+orchestrator, and the `agents/settings/.ai-council.yml` file itself.
 
 **Audience.** Authors of `scripts/ai_council/config.py`, `council_cli.py`,
-`scripts/ai_council/orchestrator.py`, and the `agents/.ai-council.yml`
+`scripts/ai_council/orchestrator.py`, and the `agents/settings/.ai-council.yml`
 starter. Also reviewers checking that new providers / advisors / debate
 features keep the schema intact.
 
@@ -21,7 +21,7 @@ a revision entry in the consuming roadmap.
 
 ## File location
 
-The single source of truth is **`agents/.ai-council.yml`** at the
+The single source of truth is **`agents/settings/.ai-council.yml`** at the
 project root. The legacy `ai_council.*` block under `.agent-settings.yml`
 is removed by Phase 0 Step 5 and replaced by a one-line breadcrumb
 pointing at this contract.
@@ -131,7 +131,7 @@ Implications:
 
 ### Persistent events log (step-8 D3)
 
-The orchestrator appends one JSON line to `agents/council-events.log`
+The orchestrator appends one JSON line to `agents/runtime/council/events.log`
 on every necessity-gate decision (`proceed` / `skip_necessity`) and on
 every `cli_call_budget` block (`block_quota`). The log is gitignored
 by default — it is a local-only audit trail, never part of the
@@ -155,7 +155,7 @@ Schema v1:
 - `action` ∈ `proceed | skip_necessity | block_quota`.
 - `original_ask_hash` is `sha256(original_ask)[:12]`. The raw prompt
   is **never** written — privacy floor per
-  [`agents/low-impact-decisions.md`](../../agents/low-impact-decisions.md).
+  [`agents/decisions/low-impact-decisions.md`](../../agents/decisions/low-impact-decisions.md).
 - Diagnostic fields outside the reserved set (`category`, `mode`,
   `cli_calls_used`, …) pass through verbatim. Consumers MUST treat
   unknown keys as forward-compatible.
@@ -514,20 +514,20 @@ when the gate flags the response.
 
 ### Low-impact corpus build pipeline (step-10)
 
-[`agents/low-impact-decisions.md`](../../agents/low-impact-decisions.md)
+[`agents/decisions/low-impact-decisions.md`](../../agents/decisions/low-impact-decisions.md)
 remains the **human-editable source of truth** — Validated, Probation,
 and Anti-Example phrases stay in Markdown so PR-reviewers diff prose,
 not YAML. A build step compiles it into a generated YAML lockfile
-[`agents/low-impact-decisions.lock.yaml`](../../agents/low-impact-decisions.lock.yaml)
+[`agents/decisions/low-impact-decisions.lock.yaml`](../../agents/decisions/low-impact-decisions.lock.yaml)
 that is the **runtime source of truth**: the necessity classifier and
 the solo-dispatch fuzzy matcher load phrases from the lockfile, with
 Markdown parsing reserved as fallback.
 
 | Component | File | Role |
 |---|---|---|
-| Source | `agents/low-impact-decisions.md` | Hand-edited Markdown. Strict parser (step-9 P4) catches drift. |
+| Source | `agents/decisions/low-impact-decisions.md` | Hand-edited Markdown. Strict parser (step-9 P4) catches drift. |
 | Build tool | `scripts/ai_council/compile_corpus.py` | `parse_corpus_strict()` → schema-v1 YAML. Deterministic output. |
-| Lockfile | `agents/low-impact-decisions.lock.yaml` | Generated, **committed**. Schema `{schema_version: 1, provenance: {…}, validated, probation, anti_examples}`. |
+| Lockfile | `agents/decisions/low-impact-decisions.lock.yaml` | Generated, **committed**. Schema `{schema_version: 1, provenance: {…}, validated, probation, anti_examples}`. |
 | Runtime loader | `low_impact_corpus.load_corpus_lock()` + lenient `load_*` shims | YAML preferred; Markdown fallback when the lockfile is missing or schema-mismatched. |
 | CI gate | `task check-corpus` (used by `task consistency`) | Fails on drift between source and lockfile. |
 
@@ -599,13 +599,13 @@ as comments and the loader enforces them.
   `min_rounds` has no effect. Standard tasks keep `min_rounds`; cost
   rises only when an artefact opts in via `council_depth: deep` in
   frontmatter or `--depth deep` on the CLI.
-- **Session retention.** `agents/council-sessions/` audit folders older
+- **Session retention.** `agents/runtime/council/sessions/` audit folders older
   than `defaults.session_retention_days` are pruned automatically on the
   next `save()`. `0` disables pruning — disk grows unbounded.
 - **`cost_budget` semantics.** The orchestrator pauses before any member
   whose projected spend would breach a cap and asks the user to continue.
   Each `0` value disables that single cap; other caps still apply.
-  Prices come from [`agents/.agent-prices.md`](../../agents/.agent-prices.md)
+  Prices come from [`agents/runtime/.agent-prices.md`](../../agents/runtime/.agent-prices.md)
   (gitignored, refreshed weekly by `python3 scripts/update_prices.py`;
   bootstrapped from `scripts/ai_council/_default_prices.py` on first run).
 
@@ -652,7 +652,7 @@ error) when any of these hold:
   after a one-line breadcrumb comment is in place pointing at this
   contract.
 - `.agent-settings.template.yml` → same removal.
-- New file `agents/.ai-council.yml` checked in with two enabled
+- New file `agents/settings/.ai-council.yml` checked in with two enabled
   providers (anthropic + openai) and three disabled
   (gemini + xai + perplexity). Models pre-filled from the Phase 0
   default set; comments mirror this contract.

package/docs/contracts/audit-log-v1.md

@@ -28,7 +28,7 @@ Last refreshed: 2026-05-11.
 ## File location
 
 ```
-agents/state/audit/<YYYY-MM>.jsonl
+agents/runtime/state/audit/<YYYY-MM>.jsonl
 ```
 
 One file per UTC month. Files are append-only — `merge=union` via
@@ -95,7 +95,7 @@ Lines MUST NOT contain:
 - Memory entry bodies, ids, or content. Only **counts** travel here —
   ids stay in `decision-trace-*.json` per [`memory-visibility-v1.md`](memory-visibility-v1.md).
 - Secrets, tokens, environment values, file contents.
-- Paths outside the package's `agents/state/` and `tests/` allowlist.
+- Paths outside the package's `agents/runtime/state/` and `tests/` allowlist.
 
 The floor is enforced by
 `tests/contracts/test_audit_log_redaction.py` — any new producer-side

package/docs/contracts/command-clusters.md

@@ -33,7 +33,7 @@ column 1 of this table.
 | `feature` | 1 | `explore` · `plan` · `refactor` · `roadmap` · `dev` | `feature-explore` · `feature-plan` · `feature-refactor` · `feature-roadmap` · `feature-dev` |
 | `chat-history` | 2 | `show` · `import` · `learn` | `chat-history` (legacy status) — `resume` / `clear` / `checkpoint` removed in `road-to-chat-history-hook-only` (auto-adopt + structural hooks); `import` (verbatim cross-session render) and `learn` (project-improving learning extraction) added in the v4 stateless schema |
 | `agents` | 2 | `init` · `optimize` · `audit` · `user` | AGENTS.md file family (high-frequency) — repurposed 2026-05-09: `init` (was `/copilot-agents init`) · `optimize` (merger of `/optimize agents-md` + `/copilot-agents optimize`) · `audit` (was `/optimize agents`, collapses old `audit` + `check` verbs); legacy folder ops (`prepare` / `cleanup` / folder-`audit`) moved to `/optimize agents-dir`; `user` sub-cluster added 2026-05-15 — manages the project-root `.agent-user.md` persona file (sub-sub-commands: `init` · `show` · `review` · `accept` · `update`) per [`agent-user-schema`](agent-user-schema.md) |
-| `memory` | 2 | `add` · `load` · `promote` · `propose` · `mine-session` · `learn-low-impact` | `memory-add` · `memory-full` · `memory-promote` · `propose-memory`; `mine-session` added 2026-05-10 — manual transcript-mining sub-command from `road-to-dream-skill-adoption.md`, opt-in via `--confirm-transcript-access` per invocation; `learn-low-impact` added 2026-05-15 — upstreams `## Validated` entries from `agents/low-impact-decisions.md` to the package seed via a DRAFT PR (re-runs the privacy-floor redactor as a second gate per `low-impact-corpus-privacy-floor`) |
+| `memory` | 2 | `add` · `load` · `promote` · `propose` · `mine-session` · `learn-low-impact` | `memory-add` · `memory-full` · `memory-promote` · `propose-memory`; `mine-session` added 2026-05-10 — manual transcript-mining sub-command from `road-to-dream-skill-adoption.md`, opt-in via `--confirm-transcript-access` per invocation; `learn-low-impact` added 2026-05-15 — upstreams `## Validated` entries from `agents/decisions/low-impact-decisions.md` to the package seed via a DRAFT PR (re-runs the privacy-floor redactor as a second gate per `low-impact-corpus-privacy-floor`) |
 | `roadmap` | 2 | `create` · `ai-council` · `process-step` · `process-phase` · `process-full` | `roadmap-create` · `roadmap-execute` (replaced — autonomous, no per-step gate; `process-phase` is the default execution scope); `ai-council` added 2026-05-07 — wraps `/council default` with `--input-mode roadmap --depth deep` |
 | `module` | 2 | `create` · `explore` | `module-create` · `module-explore` |
 | `tests` | 2 | `create` · `execute` | `tests-create` · `tests-execute` |
@@ -47,7 +47,7 @@ column 1 of this table.
 | `research` | 2 | `deep` · `report` | preliminary-research scaffolder ported from `Weizhena/Deep-Research-skills` (cluster head emits `outline.yaml` + `fields.yaml` against the `research-schema` contract). `:deep` populates per-item JSON in batches with native web-search + JSON-Schema self-validation (no Python runtime); `:report` renders `report.md` directly + optionally emits a `jq` template for deterministic regeneration. `add-items` / `add-fields` intentionally **not** ported — re-run `/research <topic>` to extend the field framework. |
 | `orchestrate` | — | _(none yet — cluster head only)_ | new — runtime executor for YAML pipelines under `.agent-config/orchestrations/` per the [`orchestration-dsl-v1`](orchestration-dsl-v1.md) contract; chains personas / skills / commands / sub-agents deterministically. Single cluster head; sub-commands deferred until a second verb is needed. |
 | `sync-gitignore` | — | `fix` | new sub-command 2026-05-11 — cluster head retains the existing append-only sync as its default flow; `:fix` adds `--cleanup-legacy` semantics, scrubbing pre-`/agents/` runtime patterns wherever they appear in the consumer's `.gitignore` (inside or outside the managed block) and re-syncing the canonical entries. |
-| `ghostwriter` | — | `fetch` · `write` · `list` · `show` · `delete` | new cluster 2026-05-15 — third voice primitive for AI-assisted writing in the public voice of a public figure. Hybrid storage: real-person profiles live consumer-side under `agents/ghostwriter/<slug>.md` (gitignored by default); package source ships only `fictional: true` fixtures. Zero network code in the package — `:fetch` delegates web-fetch / web-search to the host agent. Mandatory disclosure footer on every `:write` output (no opt-out). Schema: [`ghostwriter-schema`](ghostwriter-schema.md). |
+| `ghostwriter` | — | `fetch` · `write` · `list` · `show` · `delete` | new cluster 2026-05-15 — third voice primitive for AI-assisted writing in the public voice of a public figure. Hybrid storage: real-person profiles live consumer-side under `agents/reference/ghostwriter/<slug>.md` (gitignored by default); package source ships only `fictional: true` fixtures. Zero network code in the package — `:fetch` delegates web-fetch / web-search to the host agent. Mandatory disclosure footer on every `:write` output (no opt-out). Schema: [`ghostwriter-schema`](ghostwriter-schema.md). |
 | `post-as` | — | `me` · `ghostwriter` | new cluster 2026-05-15 — consumer-facing write entry points. `:me` reads `.agent-user.md.voice_sample` and drafts in the maintainer's own voice (no disclosure footer — the user is the author); `:ghostwriter` is a thin alias for `/ghostwriter:write` with the mandatory disclosure footer. Both share the procedural [`write-engine`](write-engine.md) contract — style source and footer are the only axes of variation. |
 | `video` | — | `from-script` · `scene` · `storyboard` · `stitch` | new cluster 2026-05-17 — AI video generation pipeline. Cluster head orchestrates the full flow; `:scene` runs a single scene end-to-end (script → blueprint → still → motion → clip); `:storyboard` expands a script into per-scene blueprints + reference stills with character-lock JSON; `:from-script` walks a multi-scene script through storyboard + per-scene generation; `:stitch` concatenates scene clips with `ffmpeg` against a scene manifest. Provider-agnostic via the adapter contract under `scripts/ai-video/lib/adapter-contract.md`; cost-gated with mandatory `AIV_DRYRUN=true` default and explicit confirmation before live provider calls. |
 

package/docs/contracts/compression-default-kill-criterion.md

@@ -7,8 +7,8 @@ keep-beta-until: 2026-08-14
 
 > **Status:** v1-measured · criterion not met · default stays `off` · **Owner:** `step-16-caveman-substance.md`
 > Phase 1 closeout · **Sources:** [`bench/reports/caveman-v1.md`](../../bench/reports/caveman-v1.md) ·
-> [`council-synthesis.md` § 7](../../agents/council-sessions/audit-2026-05-14-north-star/council-synthesis.md) <!-- council-ref-allowed: ADR decision trace for v1 kill-criterion verdict --> ·
-> [`caveman-v1-kc-verdict.json`](../../agents/council-responses/caveman-v1-kc-verdict.json) <!-- council-ref-allowed: ADR decision trace for v1 kill-criterion verdict -->
+> [`council-synthesis.md` § 7](../../agents/evidence/audits/2026-05-14-north-star/council-synthesis.md) <!-- council-ref-allowed: ADR decision trace for v1 kill-criterion verdict --> ·
+> [`caveman-v1-kc-verdict.json`](../../agents/runtime/council/responses/caveman-v1-kc-verdict.json) <!-- council-ref-allowed: ADR decision trace for v1 kill-criterion verdict -->
 
 ## Rule
 
@@ -67,7 +67,7 @@ negative (caveman-04 path-list −108 %, caveman-06 mode-marker −123 %).
 
 ### Council split (recorded, not decisive)
 
-Council run [`caveman-v1-kc-verdict.json`](../../agents/council-responses/caveman-v1-kc-verdict.json) <!-- council-ref-allowed: ADR decision trace for v1 kill-criterion verdict -->
+Council run [`caveman-v1-kc-verdict.json`](../../agents/runtime/council/responses/caveman-v1-kc-verdict.json) <!-- council-ref-allowed: ADR decision trace for v1 kill-criterion verdict -->
 (2 members · 1 round · $0.0514 actual) split:
 
 - **`claude-sonnet-4-5`** → Decision A.1 (deprecate now) + Decision B.3

package/docs/contracts/consumer-bridge.md

@@ -0,0 +1,79 @@
+---
+stability: beta
+keep-beta-until: 2026-08-21
+---
+
+# Consumer Bridge Marker
+
+**Status:** Proposed — road-to-global-only-install Phase 4.1.
+**Pairs with:** [`ADR-020 — global-only consumer scope`](../decisions/ADR-020-global-only-consumer-scope.md), [`ADR-007 § Amendment 2026-05-13`](../decisions/ADR-007-agent-discovery-scopes.md#amendment-2026-05-13--augment-global-only).
+
+## Purpose
+
+After Phase 3 of `road-to-global-only-install` lands, a consumer
+project carries **only** `agents/overrides/` plus this bridge marker.
+Every other agent artefact (rules, skills, commands, personas,
+settings, user identity) is read from `~/.event4u/agent-config/`. The
+bridge marker is the single, declarative pointer that lets per-tool
+adapters (Windsurf, Cline, Gemini-CLI, the Augment workspace
+projector) locate the global root from inside the repo.
+
+## File
+
+`agents/.event4u-bridge.yml` at the consumer project root. <!-- ref-ignore -->
+Written by `scripts/install.py` on every successful consumer install
+(global scope). Idempotent — same file, refreshed `installed_at`.
+
+## Schema
+
+```yaml
+schema: event4u-bridge/v1
+global_root: ~/.event4u/agent-config
+installed_at: 2026-05-23T14:00:00Z
+installer_version: 2.4.0
+```
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `schema` | string | yes | Must equal `event4u-bridge/v1`. Bumped on breaking field changes. |
+| `global_root` | string | yes | Absolute path or `~`-prefixed path to the global install. Readers MUST expand `~` against the current user's `$HOME`. |
+| `installed_at` | string (ISO-8601 UTC) | yes | Timestamp of the last successful install or refresh. |
+| `installer_version` | string (semver) | yes | Version of `@event4u/agent-config` that produced the marker. |
+
+Unknown fields are ignored by `v1` readers (forward-compat).
+
+## Reader contract
+
+Per-tool adapters MUST:
+
+1. Read `agents/.event4u-bridge.yml` from the project root. <!-- ref-ignore -->
+2. Reject `schema != event4u-bridge/v1` with a clear error pointing at this contract.
+3. Expand `~` in `global_root` against the **current process's** `$HOME` (not the writer's).
+4. Fail closed if `global_root` is missing on disk — never silently fall back to project-local lookup.
+5. Treat the marker as **read-only data**. Adapters MUST NOT write back through it.
+
+## Writer contract
+
+`scripts/install.py` MUST:
+
+1. Write the marker atomically (temp file + rename) so a crash never leaves a half-formed pointer.
+2. Refresh `installed_at` + `installer_version` on every consumer-scope install.
+3. Use `0644` permissions (world-readable, owner-writable). The marker contains no secrets.
+4. Skip the write under `AGENT_CONFIG_DEV_MODE=1` — maintainer dev installs never lay the bridge into the source repo (this repo's `agents/` directory is the project surface, not a consumer surface).
+
+## Per-tool anchor strategy
+
+Some AI tools only load rules when an anchor file is **inside** the workspace (Windsurf, Cline, Gemini-CLI). For those IDs, Phase 4.3 plants a thin pointer file under the tool's per-project directory whose body resolves to the bridge marker. Tools that load purely from user-scope (Claude Code, Cursor, Augment) read the marker once and need no per-tool file.
+
+## Out of scope
+
+- Cross-machine sync of `~/.event4u/agent-config/` (the marker is local-only).
+- Editing the marker by hand to swap installs (use `agent-config init --global-root=…` instead, once that flag ships in Phase 5).
+- Multi-tenant `global_root` (one marker = one global install per project).
+
+## References
+
+- [`ADR-020`](../decisions/ADR-020-global-only-consumer-scope.md) — global-only consumer scope; cites the in-flight roadmap for Phase 4 surface design + Phase 5 migration order.
+- [`ADR-007`](../decisions/ADR-007-agent-discovery-scopes.md) — scope precedence and the global-default amendment.

package/docs/contracts/decision-trace-v1.md

@@ -10,7 +10,7 @@ runs emit when the user opts into trace surfacing. The trace is the
 audit substrate for the rule-interaction matrix
 ([`rule-interactions.md`](rule-interactions.md)) and feeds the
 showcase-session capture pipeline
-([`outcome-baseline.md`](../../agents/contexts/outcome-baseline.md)).
+([`outcome-baseline.md`](../../agents/settings/contexts/outcome-baseline.md)).
 
 **Scope.** Defines the JSON envelope written next to a `WorkState`
 file when `decision_engine.surface_traces: true`. Does **not**
@@ -34,7 +34,7 @@ boundaries and emit one trace file per phase when set.
 ## File location
 
 ```
-agents/state/work/<work-id>/decision-trace-<phase>.json
+agents/runtime/state/work/<work-id>/decision-trace-<phase>.json
 ```
 
 `work-id` matches the `WorkState` directory; `phase` is one of
@@ -58,7 +58,7 @@ agents/state/work/<work-id>/decision-trace-<phase>.json
       "applied": true,
       "skipped": false,
       "conflicted_with": [],
-      "evidence_refs": ["agents/state/work/.../verify.log"]
+      "evidence_refs": ["agents/runtime/state/work/.../verify.log"]
     }
   ],
   "memory": {
@@ -89,7 +89,7 @@ compat extensions and MUST NOT raise on them.
 | `rules[].applied` | True if the rule's Iron Law fired and changed engine behaviour this phase. |
 | `rules[].skipped` | True if the rule was checked but produced no effect (no trigger match). |
 | `rules[].conflicted_with` | List of rule_ids that fired against this one. Reduction handled per `rule-interactions.md`. |
-| `rules[].evidence_refs` | Optional list of paths under `agents/state/` or `tests/` that back the `applied` claim. |
+| `rules[].evidence_refs` | Optional list of paths under `agents/runtime/state/` or `tests/` that back the `applied` claim. |
 | `memory.asks` | Count of `memory_retrieve` calls during the phase. |
 | `memory.hits` | Count of calls that returned ≥ 1 result. |
 | `memory.ids` | Stable memory entry ids returned. Bounded to ≤ 32 ids per phase; remainder dropped silently. |
@@ -174,4 +174,4 @@ majors.
   `work_engine/scoring/decision_trace.py` and exercised by
   `tests/work_engine/scoring/test_decision_trace_scoring.py`.
 - Outcome metrics consume `verify.first_try_passes`:
-  [`outcome-baseline.md`](../../agents/contexts/outcome-baseline.md).
+  [`outcome-baseline.md`](../../agents/settings/contexts/outcome-baseline.md).

package/docs/contracts/discovery-manifest.md

@@ -0,0 +1,209 @@
+---
+stability: beta
+keep-beta-until: 2026-08-19
+---
+
+# Discovery manifest — worked-example reference
+
+> Companion to [ADR-015](../decisions/ADR-015-discovery-manifest-contract.md)
+> and [`discovery-manifest.schema.json`](discovery-manifest.schema.json).
+> The ADR is the decision; the schema is the contract; this file is the
+> worked-example reference linters, the installer, and contributors
+> cite at runtime.
+
+## Source of truth
+
+The generator
+[`scripts/build_discovery_manifest.py`](../../scripts/build_discovery_manifest.py)
+walks `.agent-src.uncompressed/` and emits the manifest to
+`dist/discovery/discovery-manifest.json` plus a sidecar
+`discovery-manifest.json.sha256` for tamper detection.
+
+```bash
+task build-discovery                  # regenerate the manifest
+task validate-discovery-manifest      # re-build to tempdir + diff committed
+task discovery-stats                  # pretty-print the stats block
+```
+
+`task ci` runs `build-discovery`, `validate-discovery-manifest`,
+`check-discovery-determinism`, and `check-artefact-checksums` so a
+stale committed manifest, a non-deterministic build, or a
+per-artefact checksum drift all fail CI (Phase-6 invariants).
+
+## Top-level shape
+
+```jsonc
+{
+  "version": 1,
+  "generated_at": "2026-05-21T00:00:00Z",
+  "scanner_version": "a1b2c3d4e5f6",
+  "checksum": "sha256:<64 hex>",
+  "workspaces": [ /* one entry per workspace in config/discovery/workspaces.yml */ ],
+  "packs":      [ /* one entry per pack in config/discovery/packs.yml */ ],
+  "artefacts":  [ /* sorted by path, ADR-013 frontmatter projected here */ ],
+  "unassigned": [ /* artefacts that failed assignment; reason required */ ],
+  "documented_unassigned": [ /* explicit skips from config/discovery/unassigned-artefacts.yml */ ],
+  "stats": { /* see below */ }
+}
+```
+
+- `version` — stays `1` for additive changes (ADR-015). Breaking → bump.
+- `generated_at` — UTC ISO-8601. **Only field allowed to differ** between
+  two determinism runs.
+- `scanner_version` — first 12 hex of `sha256(build_discovery_manifest.py)`.
+- `checksum` — `sha256:<hex>` of the JSON with `checksum` zeroed and
+  `generated_at` normalized to `"<normalised>"`.
+
+## Worked artefact entry
+
+```jsonc
+{
+  "path": ".agent-src.uncompressed/skills/laravel/SKILL.md",
+  "category": "skill",
+  "name": "laravel",
+  "workspaces": ["engineering"],
+  "packs": ["laravel"],
+  "requires": ["php"],
+  "lifecycle": "active",
+  "trust": {
+    "level": "professional",
+    "confidence": "high",
+    "human_review_required": false
+  },
+  "install": { "default": false, "removable": true },
+  "checksum": "sha256:<64 hex of normalized file content>"
+}
+```
+
+- `path` is the canonical identity. There is no `id` field — the path
+  is short, unique, and survives renames via git history (ADR-015).
+- `requires` is optional. Empty/absent → no extra pack dependencies
+  beyond the artefact's own `packs[]`.
+- `checksum` covers the on-disk bytes with frontmatter normalized
+  (sorted keys, trailing newline, no trailing whitespace). Used by the
+  Phase-3 installer for drift detection.
+
+## Worked pack entry
+
+```jsonc
+{
+  "id": "laravel",
+  "label": "Laravel",
+  "description": "PHP framework — Eloquent, Artisan, queues, jobs.",
+  "workspaces": ["engineering"],
+  "requires_hint": ["php"],
+  "trust_level_default": "professional",
+  "artefact_count": 18
+}
+```
+
+`requires_hint` is a vocabulary-side hint (lives in
+`config/discovery/packs.yml`); the canonical dependency edges sit on
+the artefact-level `requires` field, which the installer aggregates.
+
+## Stats block
+
+```jsonc
+{
+  "total_artefacts": 419,
+  "by_category":      { "skill": 246, "rule": 91, "command": 76, "template": 6 },
+  "by_lifecycle":     { "active": 405, "experimental": 12, "deprecated": 2, "archived": 0 },
+  "by_trust_level":   { "core": 142, "professional": 220, "experimental": 41, "advisory": 12, "restricted": 4 },
+  "unassigned_count": 0,
+  "documented_unassigned_count": 3
+}
+```
+
+Counts derive from the `artefacts[]` list — no second walk, no desync
+risk. The optional `_count` fields mirror the lengths of the
+`unassigned` and `documented_unassigned` arrays for dashboard ease.
+
+## Published files
+
+`task build-discovery` writes:
+
+| File | Purpose |
+|---|---|
+| `dist/discovery/discovery-manifest.json` | The canonical manifest. |
+| `dist/discovery/discovery-manifest.json.sha256` | Sidecar checksum of the on-disk file bytes. |
+| `dist/discovery/discovery-manifest.summary.md` | Human-readable workspace/pack summary. |
+| `dist/discovery/deprecation-report.md` | Phase-4 lifecycle report — lists every `lifecycle: deprecated` artefact with workspace / pack context. |
+| `dist/discovery/trust-report.md` | Phase-4 trust report — per-workspace breakdown of trust levels and `human_review_required` artefacts. |
+| `dist/discovery/orphan-report.md` | Phase-4 orphan report — non-experimental artefacts whose declared pack has no other members (typo signal). |
+| `dist/discovery/workspaces.json` | Phase-5 flattened workspace sub-view — per workspace, the set of packs + artefact paths visible in it. Lightweight surface for browser wizard previews. |
+| `dist/discovery/packs.json` | Phase-5 flattened pack sub-view — per pack, the artefact paths, plus `by_lifecycle` and `by_trust_level` counts. Lightweight surface for pack-picker UIs. |
+
+### Sub-view shape
+
+`workspaces.json` and `packs.json` carry the parent manifest's
+`checksum`, `generated_at`, and `scanner_version` so consumers can
+pin against the same source-of-truth version. Artefacts are
+referenced by `path` (the stable identity from the main manifest);
+there is no `id` field.
+
+```jsonc
+// workspaces.json
+{
+  "generated_at": "…",
+  "scanner_version": "…",
+  "checksum": "sha256:…",
+  "workspaces": [
+    {
+      "id": "engineering",
+      "label": "Engineering",
+      "description": "…",
+      "default_packs": ["engineering-base", "php", "laravel"],
+      "optional_packs": ["symfony"],
+      "artefact_count": 124,
+      "packs": [
+        { "id": "engineering-base", "artefact_count": 83, "artefacts": [".agent-src.uncompressed/skills/…/SKILL.md", "…"] }
+      ]
+    }
+  ]
+}
+```
+
+```jsonc
+// packs.json
+{
+  "generated_at": "…",
+  "scanner_version": "…",
+  "checksum": "sha256:…",
+  "packs": [
+    {
+      "id": "engineering-base",
+      "label": "Engineering Base",
+      "description": "…",
+      "workspaces": ["engineering"],
+      "requires_hint": [],
+      "trust_level_default": "core",
+      "artefact_count": 83,
+      "artefacts": [".agent-src.uncompressed/skills/…/SKILL.md", "…"],
+      "by_lifecycle":   { "active": 82, "experimental": 1, "deprecated": 0, "archived": 0 },
+      "by_trust_level": { "core": 83, "professional": 0, "experimental": 0, "advisory": 0, "restricted": 0 }
+    }
+  ]
+}
+```
+
+Both sub-views are byte-identical between two consecutive
+`task build-discovery` runs (modulo `generated_at`), same determinism
+guarantee as the main manifest.
+
+## Consumer guide
+
+- **Phase-3 installer** — reads `artefacts[]`, resolves `requires`,
+  verifies each file against its `checksum` before write.
+- **Browser wizard / docs site** — reads `workspaces[]`, `packs[]`,
+  `stats` to render pickers and counts.
+- **Third-party tools** — treat the schema as the contract; pin the
+  schema by `version` and watch for breaking-change ADRs.
+
+## See also
+
+- [ADR-013](../decisions/ADR-013-discovery-frontmatter-contract.md) —
+  the frontmatter contract (input side).
+- [ADR-015](../decisions/ADR-015-discovery-manifest-contract.md) —
+  the manifest contract (output side, this file).
+- [`frontmatter-contract.md`](frontmatter-contract.md) — per-artefact
+  worked frontmatter examples.