@event4u/agent-config 5.10.0 → 6.0.0

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.

package/docs/contracts/command-clusters.md

@@ -40,8 +40,8 @@ column 1 of this table.
 | `context` | 2 | `create` · `refactor` | `context-create` · `context-refactor` |
 | `override` | 2 | `create` · `manage` | `override-create` · `override-manage` |
 | `judge` | 2 | `solo` · `on-diff` · `steps` | `judge` (legacy standalone) · `do-and-judge` · `do-in-steps` |
-| `commit` | 2 | `in-chunks` | `commit-in-chunks` |
-| `create-pr` | 2 | `description-only` | `create-pr-description` |
+| `git-commit` | 2 | `in-chunks` | `commit-in-chunks` · former cluster name `commit` — renamed 2026-06-09 to the path-derived pack-prefixed slug (`src/domains/git/commit/`, ADR-044 amendment; issue #380) |
+| `git-pr-create` | 2 | `description-only` | `create-pr-description` · former cluster `create-pr` — physically merged into the `pr` verb family at `src/domains/git/pr/create/` and renamed 2026-06-09 to the path-derived pack-prefixed slug (ADR-044 amendment; issue #380) |
 | `council` | 3 | `default` · `pr` · `design` · `optimize` · `analysis` | `council` (legacy default lens) · `council-pr` · `council-design` · `council-optimize`; `analysis` added 2026-05-14 — wrapper for local analysis outputs with a Top-N consensus tail block consumed by `/roadmap create` |
 | `challenge-me` | — | `vision` · `with-docs` | new — Pocock-inspired one-question-at-a-time interview; `vision` is the standard 95%-confidence variant, `with-docs` adds doc/glossary awareness with a session-scoped glossary and load-bearing claim-vs-code verification |
 | `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. |
@@ -55,7 +55,7 @@ column 1 of this table.
 | `skill` | — | `preview` | new cluster 2026-05-30 (`road-to-leaner-core-and-discovery` Phase 5) — non-destructive skill/command preview: surfaces the declared steps + files/commands a skill would touch before it runs, per [`skill-dry-run`](skill-dry-run.md). Singular `skill` (one target) vs plural `skills` (the catalog) by design. |
 | `image` | — | `analyse` · `create` · `verify` | new cluster 2026-05-31 (`road-to-character-image-fidelity` Phase 4) — character-image fidelity surface mirroring `/video:*`. `:analyse` extracts a per-feature spec from an image and diffs it against a Canon Spec down to the smallest mole (OCR for lettered tattoos, per-section severity scores, canon-breaking hard gate); `:create` assembles a max-fidelity anchors-first generation prompt from the Canon Spec, governance- + provider-gated, `AIV_DRYRUN=true` default; `:verify` runs the analyser in loop mode against a candidate and reports the gate verdict + remaining diff with plateau/oscillation/budget stop conditions. Skills: [`image-analyser`](../../skills/image-analyser/SKILL.md) + [`image-creator`](../../skills/image-creator/SKILL.md); schema/rubric/loop in [`canon-spec.md`](../../skills/image-analyser/canon-spec.md). |
 
-| `profile` | — | `activate` · `deactivate` · `show` | new cluster 2026-06-02 (`road-to-session-profile-activation`) — session-profile activation: an ephemeral `runtime.active_packs` overlay that biases the surfaced command/skill set to the active pack closure, with no persistence and no execution-gating (recommendation-bias MVP). `:activate <name…>` resolves an alias (`config/discovery/session-profiles.yml`) or a raw pack id, fails fast on a not-installed pack, expands the `requires_hint` closure, and writes the overlay atomically to `agents/settings/.agent-settings.local.yml`; `:deactivate [name…]` clears it (or drops named packs, keeping deps a still-active pack needs); `:show` is the observability surface (active packs + surfaced/hidden counts). Overlay = runtime modulation of the existing `pack` axis, not a fifth axis (ADR-010 addendum). Library: `scripts/config/session_profiles.py`; schema in [`session-profile-overlay`](session-profile-overlay.md). |
+| `profile` | — | `activate` · `deactivate` · `show` | new cluster 2026-06-02 (`road-to-session-profile-activation`) — session-profile activation: an ephemeral `runtime.active_packs` overlay that biases the surfaced command/skill set to the active pack closure, with no persistence and no execution-gating (recommendation-bias MVP). `:activate <name…>` resolves an alias (`src/config/discovery/session-profiles.yml`) or a raw pack id, fails fast on a not-installed pack, expands the `requires_hint` closure, and writes the overlay atomically to `agents/settings/.agent-settings.local.yml`; `:deactivate [name…]` clears it (or drops named packs, keeping deps a still-active pack needs); `:show` is the observability surface (active packs + surfaced/hidden counts). Overlay = runtime modulation of the existing `pack` axis, not a fifth axis (ADR-010 addendum). Library: `scripts/config/session_profiles.py`; schema in [`session-profile-overlay`](session-profile-overlay.md). |
 
 **Net change:** Phase 1 collapsed 15 atomics → 3 clusters; Phase 2
 collapses 26 atomics → 11 sub-command clusters. Sub-commands use
@@ -107,6 +107,44 @@ every new sub-command added to an existing cluster.
    semantics: [`slash-command-routing-policy-mechanics.md`](../../.agent-src.uncondensed/contexts/communication/rules-auto/slash-command-routing-policy-mechanics.md)
    § Routing semantics.
 
+## Command justification — a command must earn a top-level slot
+
+```
+A NEW COMMAND ONLY EARNS A TOP-LEVEL SLOT IN THREE CASES.
+EVERYTHING ELSE IS A SKILL — THE AGENT TRIGGERS IT BY TASK.
+```
+
+Before adding a command, answer: which of these is it?
+
+1. **Flow-entry** — a daily starting point of a flow the user TYPES to begin
+   work (`work`, `git-commit`, `git-pr-create`, `ticket-implement`,
+   `feature-plan`, `review-changes`, `fix-ci`, `test-run`).
+2. **State-query** — a read-only check typed many times a day (`agent-status`,
+   `project-health`, `profile-show`).
+3. **Product-surface** — a FEATURE the user starts deliberately (not daily, but
+   consciously): `council`, `challenge-me`, `research`, `roadmap`,
+   `video-storyboard`. These are products, not implementation helpers — burying
+   them as skills destroys discoverability.
+
+If none of the three, it is a **skill**. Skills already trigger automatically by
+task, so a sub-action, a one-off/setup-once op, a pipeline stage, a destructive
+op (skill + mandatory confirmation gate — destructive ≠ command), or a system /
+admin op (the `agent-admin` platform surface, NOT a flow) does NOT need a
+top-level command. Sibling variants become a flag, never a second command
+(`commit`, not `commit-in-chunks`; `roadmap --step`, not a separate
+`roadmap-process-step` — and `roadmap` with no scope defaults to processing the
+WHOLE roadmap, because that is why you write one). A new verb still needs an ADR
+per [`ADR-041`](../decisions/ADR-041-controlled-command-verbs.md). A genuine
+skill is `code-review` / `git-workflow` / `testing` — never `council` /
+`challenge-me` / `research`.
+
+> The rule that ends "should X be a command?" — a proposed `jira-comment`: not
+> flow-entry, not state-query, not a product-surface feature → skill. Done. The
+> sweet spot is ~40–50 visible commands (workflow + status + product features),
+> not 125 (overwhelms) and not ~29 (buries features). Converged across the
+> 6.0.0-D council passes + feedback (2026-06-03); the dedicated ADR is authored
+> during the 6.0.0-D structural rollout.
+
 ## Frontmatter contract
 
 A new command file under `.agent-src.uncondensed/commands/` MUST
@@ -149,7 +187,7 @@ here so future lens additions follow the same shape.
   to the master (e.g. "cost gate from `/council default` Step 3",
   "render via Step 5/5a/5b of `/council default`"), not the wrapper.
 - **Single source of lens addendums:** lens-specific neutrality
-  addendums live in [`scripts/ai_council/prompts.py:_MODE_TABLE`](../../scripts/ai_council/prompts.py)
+  addendums live in [`scripts/ai_council/prompts.py:_MODE_TABLE`](../../src/scripts/ai_council/prompts.py)
   and are selected by `mode_override`. A new lens = a new `_MODE_TABLE`
   entry **plus** a new wrapper file mirroring the `pr.md` / `design.md` /
   `optimize.md` shape (~100–130 lines). No new master.

package/docs/contracts/config-presets.md

@@ -107,7 +107,7 @@ turn a session unrecoverably hostile mid-task.
   shell commands, MCP-static-resource fetches). The per-call ceiling
   targets paid token spend.
 - It does **not** override the Hard Floor in
-  [`non-destructive-by-default`](../../.agent-src/rules/non-destructive-by-default.md)
+  [`non-destructive-by-default`](../../dist/agent-src/rules/non-destructive-by-default.md)
   — a preset cannot lift the universal safety floor.
 
 ## Resolution chain

package/docs/contracts/cost-dashboard.md

@@ -32,7 +32,7 @@ agent-config cost reset --confirm       # truncate sessions.jsonl + budget.json
 All subcommands are **read-only by default**. `ingest` writes only to
 `agents/cost-tracking/sessions.jsonl`. `reset` is destructive and
 gated by `--confirm` (Hard-Floor per
-[`non-destructive-by-default`](../../.agent-src/rules/non-destructive-by-default.md)).
+[`non-destructive-by-default`](../../dist/agent-src/rules/non-destructive-by-default.md)).
 
 ## `cost status` — output contract
 

package/docs/contracts/cost-profile-defaults.md

@@ -39,7 +39,7 @@ correct default while tier-1 was experimental, but four signals now point
 at `balanced`:
 
 1. **Documented intent already says so.** Both
-   `config/agent-settings.template.yml` (the source the installer projects
+   `src/config/agent-settings.template.yml` (the source the installer projects
    from) and `docs/customization.md` describe `balanced` as
    "default — current behaviour superset". The code default of `minimal`
    was a drift artifact, not a deliberate stance.
@@ -76,7 +76,7 @@ state-machine impact because the kernel carries the Iron-Law floor.
 CI must keep three surfaces in sync:
 
 - `scripts/install.py` — `DEFAULT_PROFILE` constant.
-- `config/agent-settings.template.yml` — comment block on the
+- `src/config/agent-settings.template.yml` — comment block on the
   `rule_loading_tier:` key.
 - `docs/customization.md` — cost-profile table default column.
 

package/docs/contracts/cost-summary-schema.md

@@ -6,7 +6,7 @@ keep-beta-until: 2026-08-15
 # cost-summary schema (`cost-summary/v1`)
 
 Stable JSON contract for inter-tool consumption of cost-tracking data
-emitted by [`scripts/cost_summary.py`](../../scripts/cost_summary.py).
+emitted by [`scripts/cost_summary.py`](../../src/scripts/cost_summary.py).
 Schema-versioned so downstream consumers can pin and migrate explicitly.
 
 Design reference: Ruflo `scripts/summary.mjs` (upstream cite). Our shape
@@ -102,6 +102,6 @@ model-scoped.
 
 - [`telegraph-telemetry.md`](telegraph-telemetry.md) — defines the
   `telegraph_*` fields and the suspended-multiplier contract.
-- [`scripts/cost_summary.py`](../../scripts/cost_summary.py) — implementation.
-- [`scripts/cost_by_conversation.py`](../../scripts/cost_by_conversation.py) — narrower per-conversation lens with the same JSONL source.
-- [`scripts/telegraph_stats.py`](../../scripts/telegraph_stats.py) — telegraph-only delta lens with the same JSONL source.
+- [`scripts/cost_summary.py`](../../src/scripts/cost_summary.py) — implementation.
+- [`scripts/cost_by_conversation.py`](../../src/scripts/cost_by_conversation.py) — narrower per-conversation lens with the same JSONL source.
+- [`scripts/telegraph_stats.py`](../../src/scripts/telegraph_stats.py) — telegraph-only delta lens with the same JSONL source.