@event4u/agent-config 2.25.0 → 3.0.0

package/docs/contracts/adr-implement-ticket-runtime.md

@@ -108,7 +108,7 @@ Python is 3 files with shared types.
   handlers onto the dispatcher shape spiked here.
 - `implement-ticket-flow.md` will have its `Runtime: TBD` line replaced
   with `Runtime: Python 3.10+` when Phase 1 lands.
-- Metrics contract (Q38, JSON lines under `agents/logs/implement-ticket/`)
+- Metrics contract (Q38, JSON lines under `agents/runtime/logs/implement-ticket/`)
   is already demonstrated by both prototypes.
 
 ## Follow-ups (not part of this ADR)

package/docs/contracts/adr-install-user-type-axis.md

@@ -83,7 +83,7 @@ Three options were considered:
   [`scripts/audit_user_type_axis.py`](../../scripts/audit_user_type_axis.py)).
   Initial sweep at Phase 4 close: 7 declared / 7 used / 0 orphans / 0
   unused — coverage is clean, no rename or backfill needed. Report:
-  [`agents/reports/user-type-axis-audit.md`](../../agents/reports/user-type-axis-audit.md).
+  [`agents/runtime/reports/user-type-axis-audit.md`](../../agents/runtime/reports/user-type-axis-audit.md).
 - Adding an 8th value is non-trivial by design — it requires a YAML, a
   schema-compatible frontmatter rollout, and a roadmap entry. The
   friction is the feature: a sprawling axis defeats the purpose of

package/docs/contracts/adr-mcp-runtime.md

@@ -68,7 +68,7 @@ hardcoded module-level tuple in
 | Tool | Mode | Source |
 |---|---|---|
 | `lint_skills` | read-only | wraps `scripts.skill_linter.lint_file` |
-| `chat_history_append` | path-scoped write | wraps `scripts.chat_history.append`; writes restricted to `agents/.agent-chat-history` or `.agent-chat-history` under the consumer root |
+| `chat_history_append` | path-scoped write | wraps `scripts.chat_history.append`; writes restricted to `agents/runtime/.agent-chat-history` (current default), `agents/.agent-chat-history`, or `.agent-chat-history` under the consumer root |
 
 No `push`, `merge`, `commit`, or prod-write surface is exposed. The
 unimplemented-tool envelope from
@@ -105,7 +105,7 @@ Writing the global Claude Desktop config from the npx dispatcher without
 an operator pasting JSON is **not** part of this contract — Claude Desktop
 restarts and config-merge semantics make silent rewrites a footgun. The
 copy-paste path stays the canonical install shape until non-dev recruit
-evidence under `agents/eval-findings/` demonstrates the manual step is the
+evidence under `agents/evidence/eval-findings/` demonstrates the manual step is the
 actual adoption blocker.
 
 ## Consequences

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

@@ -26,7 +26,9 @@ identity:
   name: "Mathias"          # required — full name or how the user wants to be addressed
   nickname: "Matze"        # optional — preferred shorthand (used by default in chat)
 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 +38,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
@@ -49,7 +58,7 @@ enforced by `/agents user accept` and `/agents user update`.
 | `identity.name` | yes | Default address form. |
 | `identity.nickname` | no | Preferred shorthand — agent uses this by default in chat replies when set. |
 | `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. |

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/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.schema.json

@@ -0,0 +1,146 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://event4u.app/agent-config/schemas/discovery-manifest.schema.json",
+  "title": "Discovery Manifest",
+  "description": "Release-time scan output for @event4u/agent-config. See ADR-013 and agents/roadmaps/archive/automated-pack-workspace-and-skill-discovery.md (archived, status: completed).",
+  "type": "object",
+  "required": ["version", "generated_at", "scanner_version", "checksum", "workspaces", "packs", "artefacts", "unassigned"],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "const": 1,
+      "description": "Manifest schema version. Bump on breaking change."
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "UTC ISO-8601 timestamp; the only field allowed to differ between determinism runs."
+    },
+    "scanner_version": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{12}$",
+      "description": "First 12 hex chars of sha256(scripts/build_discovery_manifest.py)."
+    },
+    "checksum": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$",
+      "description": "sha256 of the JSON file with the checksum field zeroed out."
+    },
+    "workspaces": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/workspace" },
+      "minItems": 1
+    },
+    "packs": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/pack" },
+      "minItems": 1
+    },
+    "artefacts": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/artefact" }
+    },
+    "unassigned": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/unassigned" },
+      "description": "Artefacts that failed assignment. Each entry MUST carry a reason."
+    },
+    "documented_unassigned": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/unassigned" },
+      "description": "Artefacts explicitly skipped via config/discovery/unassigned-artefacts.yml. Each entry MUST carry a reason."
+    }
+  },
+  "$defs": {
+    "workspace_id": {
+      "type": "string",
+      "enum": ["engineering", "product", "finance", "founder", "gtm", "ops", "small-business", "construction", "agent-config-maintainer"]
+    },
+    "pack_id": {
+      "type": "string",
+      "enum": [
+        "engineering-base", "php", "laravel", "symfony", "javascript", "typescript", "react", "nextjs", "python",
+        "product-basic", "product-discovery",
+        "finance-basic", "finance-advanced",
+        "gtm-sales", "gtm-marketing",
+        "ops-people", "founder-strategy", "small-business", "construction", "ai-video", "meta"
+      ]
+    },
+    "lifecycle": {
+      "type": "string",
+      "enum": ["active", "deprecated", "experimental", "archived"]
+    },
+    "trust_level": {
+      "type": "string",
+      "enum": ["core", "professional", "experimental", "advisory", "restricted"]
+    },
+    "workspace": {
+      "type": "object",
+      "required": ["id", "label", "description", "default_packs"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "$ref": "#/$defs/workspace_id" },
+        "label": { "type": "string", "minLength": 1 },
+        "description": { "type": "string", "minLength": 1 },
+        "default_packs": { "type": "array", "items": { "$ref": "#/$defs/pack_id" } },
+        "optional_packs": { "type": "array", "items": { "$ref": "#/$defs/pack_id" } }
+      }
+    },
+    "pack": {
+      "type": "object",
+      "required": ["id", "label", "description", "workspaces", "trust_level_default", "artefact_count"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "$ref": "#/$defs/pack_id" },
+        "label": { "type": "string", "minLength": 1 },
+        "description": { "type": "string", "minLength": 1 },
+        "workspaces": { "type": "array", "items": { "$ref": "#/$defs/workspace_id" }, "minItems": 1 },
+        "requires_hint": { "type": "array", "items": { "$ref": "#/$defs/pack_id" } },
+        "trust_level_default": { "$ref": "#/$defs/trust_level" },
+        "artefact_count": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "artefact": {
+      "type": "object",
+      "required": ["path", "category", "workspaces", "packs", "lifecycle", "trust", "install"],
+      "additionalProperties": false,
+      "properties": {
+        "path": { "type": "string", "minLength": 1, "description": "POSIX path relative to repo root." },
+        "category": { "type": "string", "enum": ["skill", "rule", "command", "template"] },
+        "name": { "type": "string" },
+        "workspaces": { "type": "array", "items": { "$ref": "#/$defs/workspace_id" }, "minItems": 1 },
+        "packs": { "type": "array", "items": { "$ref": "#/$defs/pack_id" }, "minItems": 1 },
+        "lifecycle": { "$ref": "#/$defs/lifecycle" },
+        "trust": {
+          "type": "object",
+          "required": ["level", "confidence", "human_review_required"],
+          "additionalProperties": false,
+          "properties": {
+            "level": { "$ref": "#/$defs/trust_level" },
+            "confidence": { "type": "string", "enum": ["high", "medium", "low"] },
+            "human_review_required": { "type": "boolean" }
+          }
+        },
+        "install": {
+          "type": "object",
+          "required": ["default", "removable"],
+          "additionalProperties": false,
+          "properties": {
+            "default": { "type": "boolean" },
+            "removable": { "type": "boolean" }
+          }
+        }
+      }
+    },
+    "unassigned": {
+      "type": "object",
+      "required": ["path", "category", "reason"],
+      "additionalProperties": false,
+      "properties": {
+        "path": { "type": "string", "minLength": 1 },
+        "category": { "type": "string", "enum": ["skill", "rule", "command", "template", "unknown"] },
+        "reason": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/docs/contracts/explain-trace.schema.json

@@ -0,0 +1,144 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://event4u.app/agent-config/schemas/explain-trace.schema.json",
+  "title": "ExplainTrace v1",
+  "description": "Execution-trace contract emitted by `agent-config explain last`. The CLI's --json output is the wire format; the Markdown renderer is a deterministic projection of this same object. See agents/roadmaps/explainability-v2-explain-last.md and the in-tree builder at scripts/_cli/explain_last/.",
+  "type": "object",
+  "required": [
+    "version",
+    "generated_at",
+    "run_id",
+    "subject",
+    "inputs",
+    "route",
+    "council",
+    "memory",
+    "pack",
+    "assumptions",
+    "halt",
+    "provider"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "integer",
+      "const": 1,
+      "description": "Schema version. Bumps require a sibling roadmap; readers MUST refuse unknown versions."
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 UTC timestamp at which the trace was built (renderer-deterministic only when fixed by the test harness)."
+    },
+    "run_id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Identifier of the originating /work run. Pulled from state.input.data.id, with fallback to the state file mtime serialised as ISO-8601."
+    },
+    "subject": {
+      "type": "string",
+      "enum": ["work", "implement-ticket", "council", "video", "unknown"],
+      "description": "Originating directive set. `unknown` fires when state.directive_set is absent or unrecognised."
+    },
+    "inputs": {
+      "type": ["object", "null"],
+      "description": "Profile / preset / cost_profile resolution chain. Null when the loader could not resolve any of them (broken settings).",
+      "required": ["profile", "preset", "cost_profile", "source_per_knob"],
+      "additionalProperties": false,
+      "properties": {
+        "profile": {"type": ["string", "null"]},
+        "preset": {"type": ["string", "null"]},
+        "cost_profile": {"type": ["string", "null"]},
+        "source_per_knob": {
+          "type": "object",
+          "description": "Map<knob, source>; source ∈ pack | profile | preset | user | env | runtime | default.",
+          "additionalProperties": {"type": "string"}
+        }
+      }
+    },
+    "route": {
+      "type": ["object", "null"],
+      "description": "Rule-router activation snapshot. Null when router.json is absent.",
+      "required": ["matched_rules", "kernel_rules", "persona"],
+      "additionalProperties": false,
+      "properties": {
+        "matched_rules": {"type": "array", "items": {"type": "string"}},
+        "kernel_rules": {"type": "array", "items": {"type": "string"}},
+        "persona": {"type": ["string", "null"]}
+      }
+    },
+    "council": {
+      "type": ["array", "null"],
+      "description": "List of council member responses attached to this run. Null when no session file matched the run window.",
+      "items": {
+        "type": "object",
+        "required": ["member_id", "verdict", "citations"],
+        "additionalProperties": false,
+        "properties": {
+          "member_id": {"type": "string"},
+          "verdict": {"type": "string"},
+          "citations": {"type": "array", "items": {"type": "string"}}
+        }
+      }
+    },
+    "memory": {
+      "type": ["array", "null"],
+      "description": "Memory-MCP hits that influenced this run. Null when no memory layer was consulted.",
+      "items": {
+        "type": "object",
+        "required": ["entry_id", "hit_score", "used_in"],
+        "additionalProperties": false,
+        "properties": {
+          "entry_id": {"type": "string"},
+          "hit_score": {"type": "number"},
+          "used_in": {"type": "string"}
+        }
+      }
+    },
+    "pack": {
+      "type": ["object", "null"],
+      "description": "Active workspace pack selection. Null when no pack was active.",
+      "required": ["id", "reason"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {"type": "string"},
+        "reason": {"type": "string"}
+      }
+    },
+    "assumptions": {
+      "type": "array",
+      "description": "Assumptions the engine recorded; empty list when none were captured.",
+      "items": {
+        "type": "object",
+        "required": ["id", "accepted", "source"],
+        "additionalProperties": false,
+        "properties": {
+          "id": {"type": "string"},
+          "accepted": {"type": "boolean"},
+          "source": {"type": "string"}
+        }
+      }
+    },
+    "halt": {
+      "type": ["object", "null"],
+      "description": "Most recent halt persisted by the engine. Null on clean runs.",
+      "required": ["reason", "step", "surface"],
+      "additionalProperties": false,
+      "properties": {
+        "reason": {"type": "string"},
+        "step": {"type": "string"},
+        "surface": {"type": "array", "items": {"type": "string"}}
+      }
+    },
+    "provider": {
+      "type": ["object", "null"],
+      "description": "Video provider selection record. Non-null only when state.directive_set == 'video' AND state.video_provider was written.",
+      "required": ["id", "selection_reason"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {"type": "string"},
+        "selection_reason": {"type": "string"}
+      }
+    }
+  }
+}