@event4u/agent-config 5.10.1 → 6.1.0

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

@@ -3,16 +3,16 @@ stability: beta
 keep-beta-until: 2026-08-12
 ---
 
-# AI-Council Config (`agents/settings/.ai-council.yml`)
+# AI-Council Config (`.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/settings/.ai-council.yml` file itself.
+orchestrator, and the `.ai-council.yml` file itself.
 
 **Audience.** Authors of `scripts/ai_council/config.py`, `council_cli.py`,
-`scripts/ai_council/orchestrator.py`, and the `agents/settings/.ai-council.yml`
+`scripts/ai_council/orchestrator.py`, and the `.ai-council.yml`
 starter. Also reviewers checking that new providers / advisors / debate
 features keep the schema intact.
 
@@ -21,10 +21,45 @@ a revision entry in the consuming roadmap.
 
 ## File location
 
-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.
+The council is configured **once per user**, not per project. The config
+lives in the user-global namespace:
+
+```
+~/.event4u/agent-config/settings/.ai-council.yml
+```
+
+(with the legacy `~/.config/agent-config/settings/.ai-council.yml` read as a
+fallback during the v2.4 namespace transition). This is where a single
+developer enables members, pins models, and sets caps once — and the
+council then works in **every** project they open, with no per-project
+file to check in or accidentally commit. See
+[ADR-093](../decisions/ADR-093-ai-council-config-user-global.md).
+
+`scripts/ai_council/config.py:resolve_config_path` resolves the active
+file with this precedence (first match wins):
+
+1. **`$AI_COUNCIL_CONFIG`** — an explicit absolute path. Honoured even
+   when the target is absent (so a typo surfaces as "create it here"
+   rather than silently falling back). Primarily for tests / power users.
+2. **Project-local** `<project_root>/agents/settings/.ai-council.yml` —
+   only when a consumer project deliberately checks in its own council
+   config. This **overrides** the user-global file for that project.
+3. **User-global** `~/.event4u/agent-config/settings/.ai-council.yml` — the
+   canonical default described above.
+
+When none exists, the loader reports the user-global path as the place to
+create it. `agents/templates/.ai-council.yml.example` ships the documented
+shape to copy from. The legacy `ai_council.*` block under
+`.agent-settings.yml` remains removed (Phase 0 Step 5); a one-line
+breadcrumb there points at this contract.
+
+> **Why user-global, not project-tracked.** A council config checked into
+> the project tree (the pre-ADR-093 layout) (a) re-applied per-project
+> instead of per-developer, (b) risked being committed to a public repo,
+> and (c) was silently *not found* on cloud / headless / fresh-checkout
+> surfaces with no project copy — the council then refused with
+> "ai_council.enabled is false" even though the user had set it up. The
+> user-global location fixes all three.
 
 ## Top-level schema
 
@@ -197,7 +232,7 @@ A heuristic pre-flight that decides whether the request actually
 warrants a full council deliberation. Three verdicts (`necessary`,
 `borderline`, `unnecessary`) drive three exit paths in the dispatcher
 (skip silently, educate + block, or proceed). Implemented in
-[`scripts/ai_council/necessity.py`](../../scripts/ai_council/necessity.py);
+[`scripts/ai_council/necessity.py`](../../src/scripts/ai_council/necessity.py);
 wired into `council_cli.cmd_run` and `cmd_debate` before any member
 is invoked.
 
@@ -259,7 +294,7 @@ Decision table:
 | `== 0` | `== 0` | no | `borderline` |
 
 Trigger word lists live in
-[`scripts/ai_council/necessity.py`](../../scripts/ai_council/necessity.py)
+[`scripts/ai_council/necessity.py`](../../src/scripts/ai_council/necessity.py)
 as `NECESSARY_TRIGGERS` and `UNNECESSARY_TRIGGERS` — extend there with
 a unit test; never edit downstream copies.
 
@@ -271,7 +306,7 @@ final-round per-member texts — no extra model calls. The artefact
 surfaces, per top finding, the verdict band (Strong/Moderate/Weak), the
 evidence-quality bucket (H/M/L), the agree/dissent member split, and one
 key argument per member. Implementation:
-[`scripts/ai_council/replay.py`](../../scripts/ai_council/replay.py).
+[`scripts/ai_council/replay.py`](../../src/scripts/ai_council/replay.py).
 
 **Configuration.**
 
@@ -532,7 +567,7 @@ Markdown parsing reserved as fallback.
 | CI gate | `task check-corpus` (used by `task consistency`) | Fails on drift between source and lockfile. |
 
 The committed lockfile is the contract: a stale lockfile fails CI the
-same way `.agent-src/` drift does. The Markdown parser stays in the
+same way `dist/agent-src/` drift does. The Markdown parser stays in the
 repo as a build-time dependency, not a runtime dependency — a parser
 regression breaks `task consistency`, never the live council.
 

package/docs/contracts/at-rest-encryption.md

@@ -9,6 +9,18 @@ stability: experimental
 > Single-user, single-machine encryption for the three workspace
 > stores added in Phases 4 / 5 / 7. Does **not** touch the existing
 > `agents/memory/` store — that gets a separate decision.
+>
+> **Architecture locked 2026-06-08 → [`ADR-062`](../decisions/ADR-062-encrypt-at-rest-store-architecture.md).**
+> Two decisions the store-wiring PR implements: (A) the shipped
+> `workspace_crypto.py` currently uses **Fernet**, not the AES-256-GCM
+> `AC1\0` envelope this contract specifies — the code is re-ciphered to
+> match the contract (safe: flag default-OFF, no field data to migrate);
+> (B) store access is **Python-authoritative end-to-end** — the Node GUI
+> server stops touching the encrypted files directly and routes through
+> the Python CLI (no `keytar`, no dual-runtime crypto). The wiring is a
+> deliberate dedicated PR with a must-have checklist (CI-exercised
+> cipher, concurrency-safe migration, key rotation, kill-switch, envelope
+> versioning, cross-runtime test) — see ADR-062.
 
 ## Threat model
 
@@ -53,15 +65,20 @@ never logged.
 
 ## Scope
 
-Encrypts (Phase 8 v0):
+**Shipped — encrypted at rest:**
 
-| Path | Phase | Sensitivity |
+| Path | Form | ADR | Sensitivity |
+|---|---|---|---|
+| `workspace/documents/**/*.md` | whole-file `.md.enc`, Python-authoritative read | 062 | offer / mail / memo / brief bodies |
+| `workspace/documents/**/*.history.jsonl` | per-record (one base64 `AC1\0` line per revision) | 064 | edit metadata + SHAs |
+| `workspace/analytics/events.jsonl` | per-record (one base64 `AC1\0` line per event) | 064 | event counters; lower sensitivity |
+| `workspace/sessions/**/*.jsonl` | per-record (Python-authoritative; Node routes all 5 session endpoints through the CLI) | 064 | host replies may contain customer data |
+
+**Intentionally plaintext (encryption declined — [`ADR-065`](../decisions/ADR-065-tier3-inbox-handoff-v0.md)):**
+
+| Path | Form | Why not encrypted |
 |---|---|---|
-| `workspace/sessions/**/*.jsonl` | 4 | host replies may contain customer data |
-| `workspace/documents/**/*.md` | 5 | offer / mail / memo / brief bodies |
-| `workspace/documents/**/*.history.jsonl` | 5 | edit metadata + SHAs |
-| `workspace/inbox/**/*.md` | 4 | rendered prompts for Tier-3 hand-off may contain customer names |
-| `workspace/analytics/events.jsonl` | 7 | event counters; lower sensitivity but uniform treatment |
+| `workspace/inbox/**/*.md` | plaintext, ephemeral (24h prune), Python-authoritative, ships dark behind `AGENT_CONFIG_TIER3_INBOX` | the Tier-3 hand-off holds a rendered prompt the user **reads to copy-paste**; that same content already lives in the **encrypted sessions store**, so encrypting it defends against no incremental threat (security theater). **Trigger to revisit:** if the inbox ever carries content NOT mirrored in sessions, encrypt it via the documents whole-file `.md.enc` pattern. |
 
 Does **not** encrypt (v0):
 
@@ -93,6 +110,30 @@ accepted trade-off — slugs are kebab-case derived from titles and
 may contain customer names; mitigation: title slug allowlist
 documented in `workspace-documents.md`).
 
+## Part B operations (documents) — shipped
+
+`workspace_documents.py` owns document encryption (Python-authoritative,
+ADR-062 Option 4):
+
+- **Write** (`create` / `save`): when the flag is on, the `.md` body is
+  written as `<slug>.md.enc` via atomic temp+fsync+rename; the opposite form
+  is removed so a slug never has both.
+- **Read** (`read` / `list` / `export`): auto-detects `.md` vs `.md.enc` on
+  disk and decrypts the `.enc` — **independent of the flag** (decryption needs
+  only the key), so a read is correct after the flag flips either way.
+- **Node read path**: the GUI server's recent-documents rail calls
+  `workspace_documents.py list --json --root <writeRoot>/workspace/documents`
+  rather than reading files directly — so it never has to decrypt `.enc` in
+  Node. The script is resolved from the server source tree.
+- **`migrate`**: non-destructive plaintext → `.enc` (encrypt, verify-decrypt,
+  then delete plaintext; idempotent; rolls back a file on verify failure).
+- **`decrypt-all`**: kill-switch — every `.md.enc` back to plaintext `.md`
+  (works after the flag is off; `AGENT_CONFIG_NO_ENCRYPTION` also forces
+  plaintext writes).
+- **`rekey`**: rotate the master key and re-encrypt every document under the
+  new key (coherent only when the key lives in keyring/keyfile, not pinned via
+  `AGENT_CONFIG_WORKSPACE_KEY`).
+
 ## Feature flag + migration
 
 Single setting in `.agent-settings.yml`:

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

@@ -7,7 +7,7 @@ keep-beta-until: 2026-08-12
 
 **Purpose.** Pin the append-only schema that the audit-as-memory
 pipeline writes per `/work` and `/implement-ticket` run, so the
-pattern-extraction script ([`extract_audit_patterns.py`](../../scripts/extract_audit_patterns.py))
+pattern-extraction script ([`extract_audit_patterns.py`](../../src/scripts/extract_audit_patterns.py))
 and the `learning-to-rule-or-skill` skill can mine repeated successful
 patterns without re-reading conversation bodies.
 
@@ -23,7 +23,7 @@ Last refreshed: 2026-05-11.
 | Side | Responsibility | Where |
 |---|---|---|
 | **Producer** | One JSONL line per phase end, derived from the phase's [`decision-trace-v1.md`](decision-trace-v1.md) JSON and the [`memory-visibility-v1.md`](memory-visibility-v1.md) counts. | `work_engine` hook on phase boundary. |
-| **Consumer** | Pattern mining + human review gate. Never edits a written line; corrections are new lines with `type=supersede`. | [`extract_audit_patterns.py`](../../scripts/extract_audit_patterns.py). |
+| **Consumer** | Pattern mining + human review gate. Never edits a written line; corrections are new lines with `type=supersede`. | [`extract_audit_patterns.py`](../../src/scripts/extract_audit_patterns.py). |
 
 ## File location
 
@@ -136,7 +136,7 @@ majors.
 
 - Input feed (counts + ids): [`memory-visibility-v1.md`](memory-visibility-v1.md).
 - Per-phase JSON the producer reads: [`decision-trace-v1.md`](decision-trace-v1.md).
-- Pattern-extraction consumer: [`extract_audit_patterns.py`](../../scripts/extract_audit_patterns.py).
+- Pattern-extraction consumer: [`extract_audit_patterns.py`](../../src/scripts/extract_audit_patterns.py).
 - Skill that consumes promoted patterns:
   [`learning-to-rule-or-skill`](../../.agent-src.uncondensed/skills/learning-to-rule-or-skill/SKILL.md).
 - Append-only JSONL precedent:

package/docs/contracts/benchmark-ab-contract.md

@@ -1,3 +1,8 @@
+---
+stability: beta
+keep-beta-until: 2026-09-04
+---
+
 # Package-Impact A/B Benchmark — Contract
 
 > Lifecycle, cache invalidation, and reader-side semantics for `docs/benchmark.md` and the underlying A/B bench reports. Companion to `docs/contracts/benchmark-report-schema.md` (which owns the per-report JSON shape this contract layers an axis onto).
@@ -96,6 +101,6 @@ A bench run counts as a real measurement (rather than a plumbing health check) w
 
 ## See also
 
-- `agents/roadmaps/road-to-package-impact-benchmark.md` — the roadmap that built this surface.
+- the `road-to-package-impact-benchmark` roadmap (archived) — built this surface.
 - `internal/bench/ab/README.md` — the Shape A vs. Shape B decision and the layout.
 - `docs/contracts/benchmark-report-schema.md` — per-report JSON shape (sibling contract).

package/docs/contracts/benchmark-corpus-spec.md

@@ -6,7 +6,7 @@ keep-beta-until: 2026-08-14
 # Benchmark Corpus Spec — step-4 Phase 1
 
 Parser-visible contract for the golden corpus consumed by
-[`scripts/bench_runner.py`](../../scripts/bench_runner.py) and the
+[`scripts/bench_runner.py`](../../src/scripts/bench_runner.py) and the
 upcoming `scripts/lint_bench_corpus.py`. Defines composition, schema,
 and validation invariants.
 
@@ -118,7 +118,7 @@ without tripping CI.
 
 ## Cross-references
 
-- Runner — [`scripts/bench_runner.py`](../../scripts/bench_runner.py)
+- Runner — [`scripts/bench_runner.py`](../../src/scripts/bench_runner.py)
 - Linter — `scripts/lint_bench_corpus.py` (Phase 1 Step 3)
 - Existing non-dev corpus — [`tests/eval/corpus-non-dev.yaml`](../../tests/eval/corpus-non-dev.yaml)
 - Language gate — [`language-and-tone`](../../.agent-src.uncondensed/rules/language-and-tone.md)

package/docs/contracts/benchmark-report-schema.md

@@ -6,7 +6,7 @@ keep-beta-until: 2026-08-14
 # Benchmark Report Schema — step-4 Phase 2
 
 Parser-visible contract for the JSON + Markdown reports emitted by
-[`scripts/bench_run.py`](../../scripts/bench_run.py). Every `task bench`
+[`scripts/bench_run.py`](../../src/scripts/bench_run.py). Every `task bench`
 run writes one `internal/bench/reports/<ts>-<corpus_id>.json` + matching `.md`.
 
 ## File layout
@@ -106,8 +106,8 @@ Headers in order:
 
 ## Cross-references
 
-- Runner — [`scripts/bench_run.py`](../../scripts/bench_run.py)
-- Baseline collector — [`scripts/bench_runner.py`](../../scripts/bench_runner.py)
+- Runner — [`scripts/bench_run.py`](../../src/scripts/bench_run.py)
+- Baseline collector — [`scripts/bench_runner.py`](../../src/scripts/bench_runner.py)
 - Corpus contract — [`benchmark-corpus-spec.md`](benchmark-corpus-spec.md)
 - Pricing source — [`internal/bench/pricing.yaml`](../../bench/pricing.yaml)
-- Cost session reader (live sessions) — [`scripts/cost/track.mjs`](../../scripts/cost/track.mjs)
+- Cost session reader (live sessions) — [`scripts/cost/track.mjs`](../../src/scripts/cost/track.mjs)

package/docs/contracts/branch-protection-policy.md

@@ -1,3 +1,8 @@
+---
+stability: beta
+keep-beta-until: 2026-09-04
+---
+
 # Branch Protection Policy
 
 > **Status:** active · **Owner:** maintainer (GitHub UI ruleset) ·

package/docs/contracts/capability-packs.md

@@ -0,0 +1,217 @@
+---
+stability: beta
+keep-beta-until: 2026-09-02
+---
+
+# Capability packs
+
+> **Status:** beta — first draft 2026-06-02 (Phase 0 of
+> [`road-to-6.0.0-b-pack-scoped-projection.md`](../../agents/roadmaps/road-to-6.0.0-b-pack-scoped-projection.md)).
+> Formalizes the capability-pack layer so the 6.0.0-B projection filtering
+> and the 6.0.0-C per-pack budget lint have a manifest with a size class to
+> read.
+
+A **capability pack** is the domain grouping a single artefact declares it
+belongs to — the value carried in a skill's or command's `packs:` frontmatter
+(e.g. `laravel`, `php`, `finance-basic`, `ai-video`). It answers *"which
+vertical does this artefact serve?"* It is the unit the projector filters on
+when a profile is active (6.0.0-B) and the unit the per-pack command budget is
+enforced against (6.0.0-C).
+
+## Capability pack vs. workflow pack — two distinct layers
+
+These are **different things** and must not be conflated:
+
+| | Capability pack | Workflow pack |
+|---|---|---|
+| **What** | A domain grouping (`packs:` tag on an artefact). | A curated bundle (`profile + preset + surface allowlist`). |
+| **Granularity** | Per-artefact ownership. | Per-audience composition. |
+| **Source of truth** | `src/config/discovery/packs.yml` (this contract). | `.agent-src.uncondensed/packs/<id>.yml` ([`workflow-packs`](workflow-packs.md)). |
+| **Cardinality** | ~19 in use today. | 3 seed bundles (`founder-mvp`, `content-engine`, `agency-delivery`). |
+| **Consumed by** | Projection filtering (6.0.0-B), per-pack budget lint (6.0.0-C), the pack-dependency graph. | The onboarding wizard's first-screen surface rendering. |
+
+A workflow pack *references* capability packs indirectly (through the profile
+it composes); a capability pack knows nothing about workflow packs. When this
+document says "pack" unqualified, it means **capability pack**.
+
+## Registry — extend the existing vocabulary, do not fork it
+
+Capability packs already exist as the closed discovery vocabulary at
+`src/config/discovery/packs.yml`, governed by
+[`ADR-013`](../decisions/ADR-013-discovery-frontmatter-contract.md) § packs.
+This contract **formalizes that file as the capability-pack registry** — it
+does not introduce a parallel catalog. Phase 0 extends each entry with the
+three new fields below; the existing fields keep their ADR-013 meaning.
+
+### Manifest shape
+
+```yaml
+# src/config/discovery/packs.yml — one entry per capability pack
+- id: laravel                        # kebab-case; matches the `packs:` tag
+  label: Laravel                     # human-readable (existing, ADR-013)
+  description: Laravel framework patterns; depends on PHP.
+  workspaces: [engineering]          # discovery axis (existing, ADR-013)
+  trust_level_default: professional  # existing, ADR-013
+  domain: engineering                # NEW — the single primary vertical
+  size_class: medium                 # NEW — budget input (see table)
+  requires: [php, engineering-base]  # NEW — hard dependency edges
+  suggests: [api, ui]                # NEW — soft companion edges
+```
+
+### Field semantics
+
+| Field | Type | Required | Notes |
+|---|---|:-:|---|
+| `id` | string | yes | kebab-case; matches the artefact `packs:` tag. No collision with a workflow-pack, profile, or preset id. |
+| `label` | string | yes | Existing ADR-013 field. |
+| `description` | string | yes | Existing ADR-013 field. |
+| `workspaces` | list[string] | yes | Existing ADR-013 discovery axis — the workspace tiles a pack surfaces under. A pack may serve several workspaces. |
+| `trust_level_default` | enum | yes | Existing ADR-013 field (`core` / `professional` / `experimental`). |
+| `domain` | string | in-use | **NEW.** The single primary vertical the pack belongs to (`engineering`, `product`, `finance`, `gtm`, `ops`, `founder`, `media`, `meta`, `fun`). Distinct from `workspaces` (a list of surfacing tiles): `domain` is the one canonical home used for the per-domain reasoning the persona/skill governance leans on; `workspaces` is where it *shows up*. **Co-required with `size_class`** — both present on an in-use pack, both absent on a reserved-unused vocab id. |
+| `size_class` | enum | in-use | **NEW.** `core` / `small` / `medium` / `large` / `platform`. The input the 6.0.0-C per-pack **visible-command** budget lint reads. Co-required with `domain`. Required for every in-use pack; absent on reserved vocab ids with zero artefacts (assigning it would fail the orphan-manifest determinism check). |
+| `always_on` | bool | no | **NEW.** When `true`, the pack loader (6.0.0-B Phase 3) includes this pack's artefacts in **every** projection, regardless of the selected profile / workspace / pack set. Default `false` (absent). See "Always-on packs" below. |
+| `requires` | list[id] | no | **NEW.** Hard dependency edges — packs whose artefacts must be present for this pack to function (e.g. `laravel.requires = [php, engineering-base]`). Formalizes the advisory `requires_hint` from ADR-013; once a manifest carries `requires`, `requires_hint` is the deprecated alias. Default `[]`. |
+| `suggests` | list[id] | no | **NEW.** Soft companion edges — packs commonly installed together but not mandatory (e.g. `laravel.suggests = [api, ui]`). Advisory; the resolver MAY surface them, never auto-installs. Default `[]`. |
+
+`cluster:` and `onboarding:` (ADR-013) remain valid optional fields and are
+out of scope for this contract.
+
+## Size class → visible-command budget
+
+`size_class` exists so the 6.0.0-C budget lint can cap how many **visible**
+(`visibility: visible` + `advanced`) commands a pack surfaces. `internal`
+commands are the composition layer and are **uncapped** — capping them kills
+composability (council, 2026-06-02).
+
+| `size_class` | Visible-command budget | Intended for |
+|---|:-:|---|
+| `core` | ≤ 8 | Always-relevant base packs (`engineering-base`, `meta`). |
+| `small` | ≤ 2 | Narrow single-purpose packs (`fun`, `python`). |
+| `medium` | ≤ 5 | Standard framework / domain packs (`laravel`, `gtm-sales`). |
+| `large` | ≤ 8 | Broad multi-surface packs (`ai-video`). |
+| `platform` | ≤ 10 | Cross-cutting platform packs spanning many surfaces. |
+
+> The **budget table is owned here** (size_class definition); the **enforcement
+> lint** is defined and wired into CI by 6.0.0-C Phase 1. This contract assigns
+> the class; the lint reads it. No pack is classified by guess — Phase 0 Step
+> 0.2 assigns each in-use pack a class, reviewed at PR time.
+
+## Budget exemption process
+
+The budget is a **hard cap with an explicit exemption path**, not a
+weighted/dynamic cap. The council (2026-06-02) was decisive: dynamic caps are
+"governance-by-algorithm and get gamed at the meta level". A pack that needs to
+exceed its `size_class` budget earns the exemption through a documented
+decision, never through a formula.
+
+A pack over budget MUST carry a **budget-exemption ADR** under `docs/adr/`
+(or legacy `docs/decisions/`) that records:
+
+1. **The user need** — the concrete workflow each over-budget visible command
+   serves, and why a user must reach it by name (not behind a `tier: 2`
+   internal surface or inside a sibling cluster).
+2. **The alternatives considered and rejected** — for each command over the
+   cap: why not **merge** into an existing cluster, why not **relocate** to a
+   pack with headroom, why not **internalize** (`tier: 2`). "All three were
+   considered and rejected because …" is mandatory; an exemption that does not
+   show its work is rejected at review.
+3. **Re-justification cadence** — the exemption is **re-justified at the next
+   major release**. An ADR that is not re-affirmed lapses; the lint then fails
+   the over-budget pack until commands are cut or the ADR is renewed.
+
+The `--check-new` gate (Phase 1) does not parse ADRs — it is forward-looking
+and fails any *newly visible* command that breaches the cap. The exemption ADR
+is the human record that authorises a maintainer to grandfather a pre-existing
+over-budget pack; the gate stays green for it only because no *new* visible
+command is added.
+
+### Gaming-detection — pack-split dodge
+
+The cheapest way to dodge a per-pack cap is to split a pack in two so each half
+stays under budget. To catch this at the meta level: **more than 3 new
+capability packs created in any rolling 6-month window without a user-facing
+launch (a profile, a wizard surface, or a documented consumer use case) triggers
+a governance review.** A burst of pack creation with no corresponding surfacing
+is the signal that the cap is being routed around rather than respected. The
+review asks the same exemption questions above, one level up: does each new pack
+serve a distinct user need, or is it a budget-laundering split?
+
+## Always-on packs
+
+A pack flagged `always_on: true` is a **default pack**: the resolver includes
+its artefacts in every projection unconditionally — it is never gated by the
+selected profile, workspace, or pack set, and it cannot be deselected. This is
+the mechanism for package-maintenance tooling that must be present wherever
+agent-config is installed.
+
+**Day-one always-on pack:** `meta`. Every install ships the agent-config layer
+(`.augment/`, `.claude/`, …), so the commands that maintain that layer
+(`condense`, `agents:audit`, `optimize:skills`, …) are relevant in every
+project regardless of the consumer's domain. The 6.0.0-B Phase 3 resolver
+seeds the active set with all `always_on` packs before expanding the selected
+profile's `requires` closure.
+
+`always_on` is independent of `size_class` (an always-on pack still has a
+visible-command budget) and of `requires` (always-on packs are seeded, not
+reached through a dependency edge).
+
+## Pack-dependency graph
+
+`requires` and `suggests` form a directed graph the pack loader
+(`scripts/config/packs.py`, 6.0.0-B Phase 3) expands when resolving the active
+artefact set: selecting `laravel` pulls in `php` and `engineering-base` via the
+transitive `requires` closure, so a Laravel install never lands without its
+PHP / testing base (closes the council / part1.5 § 6 "install Laravel but the
+base is missing" gap).
+
+**Graph invariants** (enforced by the Phase 0 Step 0.3 graph lint):
+
+1. Every `requires` / `suggests` target resolves to a declared capability pack
+   — no dangling edge.
+2. The `requires` graph is **acyclic** (`suggests` may form cycles; it is
+   advisory and never expanded transitively).
+3. `requires` is transitive (resolver expands the full closure); `suggests` is
+   non-transitive (one hop, surfaced not installed).
+
+## Determinism
+
+The capability-pack registry is release-time data, not runtime state. Two
+checks keep it honest (Phase 0 Step 0.2):
+
+- **No orphan tag** — every `packs:` value used by any artefact has a manifest
+  entry.
+- **No orphan manifest** — every manifest entry is referenced by at least one
+  artefact (a pack with zero artefacts is dead vocabulary; remove it or cite
+  the artefact).
+
+Both reproduce from the discovery manifest
+(`scripts/build_discovery_manifest.py` → `dist/discovery/`) with no manual
+list.
+
+## In-use packs (2026-06-02)
+
+19 capability packs carry at least one artefact today, enumerated from the
+built discovery manifest (not guessed):
+
+`engineering-base`, `meta`, `laravel`, `php`, `react`, `symfony`, `nextjs`,
+`typescript`, `python`, `ai-video`, `ops-people`, `gtm-marketing`,
+`gtm-sales`, `founder-strategy`, `product-basic`, `product-discovery`,
+`finance-basic`, `finance-advanced`, `fun`.
+
+Vocabulary ids with **zero** referencing artefacts today (`javascript`,
+`small-business`, `construction`) are not assigned a `size_class` until an
+artefact adopts them — an orphan manifest fails the determinism check.
+
+## See also
+
+- [`workflow-packs`](workflow-packs.md) — the bundle layer; do not conflate.
+- [`ADR-013`](../decisions/ADR-013-discovery-frontmatter-contract.md) — the
+  `packs:` vocabulary this contract formalizes; amendments require an ADR-013
+  amendment in the same PR.
+- [`discovery-manifest`](discovery-manifest.md) — the release-time scan that
+  feeds the determinism checks.
+- [`command-surface-tiers`](command-surface-tiers.md) — the orthogonal
+  visibility axis (tier 0/1/2); `size_class` budgets count `visible` +
+  `advanced`, tiers gate `--help` surfacing.
+- [`road-to-6.0.0-b-pack-scoped-projection.md`](../../agents/roadmaps/road-to-6.0.0-b-pack-scoped-projection.md)
+  Phase 0 — the steps that derive and lint the manifests defined here.

package/docs/contracts/ci-cost-budget.md

@@ -1,3 +1,8 @@
+---
+stability: beta
+keep-beta-until: 2026-09-04
+---
+
 # CI Cost Budget
 
 > **Status:** active · **Owner:** maintainer · **Opened:** 2026-05-26 ·
@@ -27,7 +32,7 @@ recent 50 main-branch runs.
 | `consistency.yml` | (single) | ubuntu | 27 s | always-on (PR / push) |
 | `smoke.yml` | smoke-contracts | ubuntu | 18 s | `scripts/schemas/**` |
 | `migration-dry-run.yml` | (single) | ubuntu | 20 s | migration-touching paths |
-| `skill-lint.yml` | (single) | ubuntu | 64 s | `.agent-src*/**`, schemas |
+| `skill-lint.yml` | (single) | ubuntu | 64 s | `dist/agent-src*/**`, schemas |
 | `release-guard.yml` | (single) | ubuntu | < 10 s | tag-trigger only |
 
 **Critical path observations:**

package/docs/contracts/ci-green-floor.md

@@ -7,7 +7,7 @@ roadmap_ref: road-to-adoption-proof-and-ci-green.md
 # CI Green Floor
 
 > **Status** · v0 / beta · 2026-05-26. Phase A Step 4 of
-> [`road-to-adoption-proof-and-ci-green.md`](../../agents/roadmaps/road-to-adoption-proof-and-ci-green.md).
+> the `road-to-adoption-proof-and-ci-green` roadmap (archived).
 > Defines what counts as a **blocking** CI failure (must be green
 > before merge) vs. an **advisory** signal (visible but not
 > merge-blocking), and the freeze rule that fires when main goes

package/docs/contracts/command-category-governance.md

@@ -0,0 +1,79 @@
+# Command-category governance
+
+> **Status (2026-06-09):** Phase-2b resolved as **Option 1 (light)** — an
+> AI-council tie-break (claude-sonnet-4-5 + gpt-4o) chose light over a
+> full/blocking lint, decisively: no consumer reads `category:` today, so
+> populating all 54 + blocking CI is "supply without demand" (YAGNI), and a
+> blocking gate on a 15%-ambiguous taxonomy enforces *presence, not correctness*
+> — mis-calls made under CI pressure surface later as a re-categorization pass
+> ("pays the cost twice"). What shipped, and the upgrade trigger, are below.
+
+## Shipped (Option 1 — light)
+
+- **`category:` defined** as an OPTIONAL enum in `command.schema.json`
+  (`flow-entry | state-query | product-surface`), **validate-when-present** —
+  a declared value must be a valid enum; absence is fine. (Note: the 150
+  `src/domains/**/command.md` files are not yet full-schema-validated — a
+  pre-existing gap, separate from this field; the enum bites wherever
+  command-schema validation runs / when a consumer reads it.)
+- **Creation-time checklist** in the [`command-writing`](../../src/skills/command-writing/SKILL.md)
+  skill: categorize a NEW top-level command at authoring; fits-none → it's a
+  skill; genuinely ambiguous → omit `category:` and note why (intentionally
+  deferred, not forgotten). Sub-commands inherit the parent cluster's category.
+
+## Deferred — until the upgrade trigger fires
+
+**Full categorization of all 54 top-level commands + a blocking lint + the
+demotion of fits-none commands** are deferred. **Upgrade trigger:** a **merged
+consumer PR** — runnable code that *reads* `category:` (routing, analytics, a
+catalog/discovery grouping, a "daily five" surface). A design doc is not the
+trigger; running code that breaks on miscategorization is. When it lands,
+population + enforcement land together in one focused PR, with the consumer's
+requirements defining the ambiguous categories unambiguously.
+
+## The schema (to introduce in Phase 2)
+
+Every **visible** command (`suggestion.eligible: true`) declares one
+`category:` in its frontmatter, per [`ADR-048`](../decisions/ADR-048-command-justification-rule.md):
+
+```yaml
+category: flow-entry | state-query | product-surface
+```
+
+- **flow-entry** — a daily starting point the user TYPES to begin work
+  (`work`, `git-commit`, `review-changes`, `fix-ci`, …).
+- **state-query** — a read-only check typed many times a day
+  (`agent-status`, `project-health`, `profile-show`, …).
+- **product-surface** — a feature the user starts deliberately
+  (`council`, `challenge-me`, `research`, `roadmap`, `video-storyboard`).
+
+A command that fits **none** is, per ADR-048, a **skill** — so the lint doubles
+as a demotion signal. That demotion is a product-surface change and is exactly
+why this belongs in Phase 2 (own → age → contract), not a Phase-0 guardrail.
+
+## Inventory at hand-off (2026-06-09)
+
+- **150** command files (`find src/domains -name command.md`).
+- **125** are visible (`suggestion.eligible: true`) → the categorization set.
+- **0** currently carry a `category:` field.
+
+So Phase 2 must: (1) add the `category:` schema to the frontmatter contract +
+validator; (2) categorize the 125 visible commands (a per-command judgment under
+ADR-048, ideally after the Phase-2 ownership map assigns owners); (3) decide the
+demotion path for any command that fits none; (4) ship the `category:` lint as a
+blocking gate once the field is populated (start non-blocking/warn to avoid a
+flag-day, then flip).
+
+## Phase-0 closure
+
+Phase 0 closes on **step 7a** (the dead-doc-path CI guardrail —
+`check_references.py` extended to `docs/` + `src/`, with tests) **plus this
+hand-off**. The two guardrails guard orthogonal properties (path integrity vs
+command-surface justification), so shipping 7a without 7b creates no false
+confidence about command categorization.
+
+## See also
+
+- [`ADR-048`](../decisions/ADR-048-command-justification-rule.md) — the three-category contract.
+- [`command-clusters.md`](command-clusters.md) — the command-justification section ADR-048 locks.
+- Positioning roadmap Phase 2 — where the `category:` lint now lands.