@event4u/agent-config 9.8.0 → 9.9.0

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

@@ -1,139 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-09-04
----
-
-# Branch Protection Policy
-
-> **Status:** active · **Owner:** maintainer (GitHub UI ruleset) ·
-> **Opened:** 2026-05-26
->
-> Codifies the per-PR-shape required-status-check floor. Companion to
-> [`release-pr-gating.md`](release-pr-gating.md) (Phase A) and
-> [`ci-cost-budget.md`](ci-cost-budget.md) (Phase C). Branch protection
-> itself is applied by the maintainer in the GitHub Settings → Rules UI;
-> this doc is the source of truth the UI mirrors.
-
-## The floor
-
-Every PR proves a floor of CI checks before it can merge. The floor differs
-by **PR shape** — a feature PR proves more (it carries runtime / install
-risk) than a release PR (whose diff is structurally limited to version
-bumps). Shape is detected by the same predicates documented in
-`release-pr-gating.md`; the workflows enforce the cut.
-
-The optimisation is **never** subtractive: a PR whose shape can't be proved
-falls back to the full feature-PR floor. The cut is opt-in per push, not
-per branch name.
-
-## Per-PR-shape required-check matrix
-
-| Required check | Feature PR | Release PR | Docs-only PR |
-|---|:---:|:---:|:---:|
-| `Consistency` | ✅ | ✅ | ✅ |
-| `Smoke Contracts` (smoke.yml) | ✅ | ✅ | ✅ |
-| `Skill Lint` | ✅ | — | — |
-| `Tests / install-tests (ubuntu)` | ✅ | — | — |
-| `Tests / install-tests (macos)` | ✅ | — | — |
-| `Tests / install-aux-tests (ubuntu)` | ✅ | — | — |
-| `Tests / install-aux-tests (macos)` | ✅ | — | — |
-| `Tests / python-tests (ubuntu × 3.10–3.13)` | ✅ | — | — |
-| `Tests / python-tests (macos × 3.12)` | ✅ | — | — |
-| `Tests / node-tests (ubuntu)` | ✅ | — | — |
-| `Tests / node-tests (macos)` | ✅ | — | — |
-| `Tests / windows-lockfile-export` | path-filter only | — | — |
-| `Public Install Smoke / smoke (matrix)` | ✅ | — | — |
-| `Release Validation / release-shape` | — | ✅ | — |
-| `Release Validation / changelog-entry` | — | ✅ | — |
-| `Release Validation / version-consistency` | — | ✅ | — |
-| `Migration Dry-Run` | path-filter only | path-filter only | — |
-| `Release Guard` (tag-trigger) | — | (post-merge tag) | — |
-
-**Definitions:**
-
-- **Feature PR** — head branch does not match `release/X.Y.Z` (the default).
-- **Release PR** — head branch matches `^release/\d+\.\d+\.\d+$` AND the
-  diff stays within the version-bump allowlist (see `release-pr-gating.md`).
-  Either condition failing falls the PR back to feature-PR mode. Author is
-  either a maintainer (`task release`) or `github-actions[bot]` (the
-  `release`-labeled-PR CI path, `.github/workflows/release.yml`) — the
-  shape checks are author-agnostic. Verified live: this repo's branch
-  protection requires zero approving reviews and exactly one status check
-  (`Sync + Generate Tools Consistency`); the bot path's real friction is
-  GitHub's separate bot-created-PR approval gate, not a review requirement
-  — see [`ADR-113`](../decisions/ADR-113-ci-native-release-label-trigger.md).
-- **Docs-only PR** — diff is entirely inside `docs/**` or matches only
-  top-level Markdown (`README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`,
-  `AGENTS.md`). No code, tests, workflows, or scripts. This shape is
-  detected by an opt-in linter (`task ci:required-checks`); branch
-  protection still defaults to the feature-PR floor unless the linter
-  asserts the docs-only shape.
-
-## Failure mode — the cut never silently lifts
-
-If a release-PR's diff exits the allowlist mid-stream (e.g. a last-minute
-CHANGELOG fixup that also touches `src/scripts/release.ts`):
-
-1. `Release Validation / release-shape` exits non-zero.
-2. The required-check set for the PR effectively flips back to the
-   feature-PR floor because:
-   - `tests.yml` / `smoke-public-install.yml` jobs carry
-     `if: !startsWith(github.head_ref, 'release/')`, so they still skip on
-     the branch name — but
-   - the maintainer is expected to either narrow the diff (move the
-     out-of-shape edit to a separate PR) or close-and-reopen the release
-     PR off a freshly-bumped branch so the heavy matrix runs.
-3. Branch protection still blocks the merge because `release-shape` is red.
-
-The branch name alone never bypasses the heavy matrix — the diff has to
-prove it can't regress runtime / install paths.
-
-## Why path-filter only for some checks
-
-`Tests / windows-lockfile-export` and `Migration Dry-Run` are path-filtered
-at the workflow level (not branch-protection level). They run on every PR
-whose diff hits their declared paths and skip on every other PR. Branch
-protection lists them as "must pass if they run" — the GitHub Rules UI
-under "Required status checks" honours this when "Require branches to be
-up to date before merging" is enabled and the check's most recent run
-on the head SHA is green.
-
-## Addendum — `python2ts` integration branch (py2ts migration)
-
-> Added 2026-06-11 for the Python → TypeScript migration (roadmap
-> `road-to-typescript-only-scripts.md`, Phase 1). Lives until the
-> migration completes; applied by the maintainer in the same Rules UI.
-
-The `python2ts` branch is the working trunk of the migration and carries
-its own protection rules:
-
-- **PRs only, no force-push, no deletion** — direct commits are blocked;
-  the scheduled `py2ts-main-sync.yml` workflow is the single sanctioned
-  direct-push writer (clean `main → python2ts` merges only; conflicts go
-  through the `sync/main-into-python2ts` PR instead).
-- **Required checks** — the full feature-PR floor (matrix above) plus
-  `py2ts Base Guard / py2ts-base-guard`.
-- **Migration PRs never target `main`** — a head branch matching
-  `^(feat|fix|chore)/py2ts-` or `^py2ts` must base on `python2ts`; the
-  base guard fails the PR otherwise. The inverse direction (non-py2ts
-  head targeting `python2ts`) only warns — sync PRs and hotfixes are
-  legitimate.
-- **Drift surfacing** — `py2ts-drift.yml` comments nightly on open
-  migration PRs whose touched `.py` files changed on `python2ts` since
-  the merge-base; such PRs rebase before merge.
-- **Final `python2ts → main` merge is user-owned** — Hard Floor
-  (production-trunk merge, explicit per-turn confirmation); never a
-  workflow, bot, or roadmap step.
-
-## See also
-
-- [`release-pr-gating.md`](release-pr-gating.md) — shape predicates, cut
-  surface, kept surface, fail-closed contract.
-- [`ci-cost-budget.md`](ci-cost-budget.md) — measured baseline durations
-  per job + quarterly review cadence (Phase C).
-- `.github/workflows/release-validation.yml` — the three release-PR jobs.
-- `src/scripts/check_release_pr_shape.ts` — the shape detector.
-- `src/scripts/release.ts` — emits release PRs (both entry points); release
-  cadence stays driven by Conventional Commits, not CI cost.
-- [`ADR-113`](../decisions/ADR-113-ci-native-release-label-trigger.md) — the
-  CI-native (`release`-label) entry point and the bot-PR-approval finding.

package/docs/contracts/brand-token-consumption.md

@@ -1,74 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-17
----
-
-# Brand-Token Consumption Contract (greenfield interface stub)
-
-> **Status:** interface stub. This contract is the **only** greenfield surface
-> shipped by `road-to-image-brand-typography` (Phase B.3, decision 2). The
-> Lovable-style `scaffold` work-engine directive that *consumes* it ships in the
-> sibling `road-to-greenfield-scaffold.md` — **no `scaffold.py` lives here.**
-> This doc exists so brand→token output is not dead output: it publishes the
-> shape a scaffold step reads, and the `mixed`-set routing hook, against a frozen
-> interface a later roadmap can build to.
-
-## 1 — What a scaffold step reads
-
-A greenfield scaffold step consumes a brand profile through two artifacts that
-pack-brand already produces — it does **not** call any pack-brand skill at
-build time:
-
-| Artifact | Producer | Shape |
-|---|---|---|
-| `.tokens.json` | [`brand-to-tokens`](../../src/skills/brand-to-tokens/SKILL.md) | DTCG (`$value` / `$type`) token tree — colour, type, spacing, radius. The same file `design-tokens/scripts/tokens.py` emits CSS vars + Tailwind from. |
-| voice profile | [`brand-strategy`](../../src/skills/brand-strategy/SKILL.md) / [`brand-identity`](../../src/skills/brand-identity/SKILL.md) | the confirmed voice traits + do/don't (3-5 traits) used to seed microcopy register. |
-
-**Read contract (frozen v1):**
-
-- The scaffold step reads `.tokens.json` as a DTCG document — never a
-  pack-brand-internal format. Style Dictionary / Tokens Studio round-trip is the
-  sanctioned external transform.
-- It reads the voice profile as a list of `{trait, do, don't}` records.
-- Absence of either artifact is **not an error** — it means greenfield with no
-  brand layer. The scaffold step then proceeds on the brief and SHOULD invoke
-  `brand-strategy` / `brand-identity` to define the tokens first (graceful, like
-  the brand-asset generation fallback). The scaffold never invents tokens
-  silently.
-
-## 2 — The `mixed`-set routing hook
-
-A greenfield request can arrive as one of three set-shapes; the routing hook
-names which path the scaffold takes:
-
-| Set | Meaning | Brand-token behaviour |
-|---|---|---|
-| `branded` | a brand profile (`.tokens.json` + voice) exists | consume tokens; `brand-consistency` gates emitted artifacts. |
-| `bare` | no brand layer, none requested | scaffold on neutral defaults; no brand gate. |
-| `mixed` | partial brand (some tokens, no voice; or voice, no tokens) | consume what exists; **route the gaps** to `brand-identity` to define the missing slice before emitting, then re-read `.tokens.json`. |
-
-The `mixed` path is the load-bearing one: it prevents a scaffold from either
-ignoring a partial brand or hard-failing on an incomplete one. The sibling
-scaffold roadmap implements the directive; this contract fixes the hook's
-inputs/outputs so that implementation has a stable target.
-
-## 3 — Direction of dependency (do not invert)
-
-```
-pack-brand  EXPORTS  .tokens.json + voice profile
-                 │
-                 ▼  (read-only, build time)
-greenfield scaffold step  (sibling roadmap)  and  pack-ai-image generation
-```
-
-The scaffold and pack-ai-image generation **consume** brand tokens; they never
-write back into pack-brand. Generation does not live in pack-brand (that would
-be a God-object — decision 1). This contract is read-only from the consumer
-side.
-
-## See also
-
-- [`brand-to-tokens`](../../src/skills/brand-to-tokens/SKILL.md) — emits the `.tokens.json` source of truth.
-- [`brand-consistency`](../../src/rules/brand-consistency.md) — the gate that runs on the `branded` / `mixed` paths.
-- [`design-tokens`](../../src/skills/design-tokens/SKILL.md) — DTCG token authoring + CSS/Tailwind emission.
-- `road-to-greenfield-scaffold.md` (sibling roadmap) — the scaffold directive that consumes this contract.

package/docs/contracts/capability-boundary.md

@@ -1,69 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-17
----
-
-# Capability Boundary Matrix
-
-The per-pack safety posture at a glance: is a pack on by default, does it need
-consent, a council pass, a disclaimer, an eval — and how risky is it. The matrix
-makes the invisible visible; the **enforcement** lives in the per-pack safety
-floors + gates (this doc is the map, not the engine).
-
-> Source of truth: `src/config/discovery/packs.yml` (`surface_tier`,
-> `trust_level_default`, `domain`, and the legal-review-prep gate fields) + the
-> domain safety-floor rules. Built in `road-to-capability-governance` Phase 1;
-> `risk_class` becomes a real pack field in Phase 2.
-
-## Policy by risk class
-
-| `risk_class` | default install | consent | council / deep-research | disclaimer | eval expectation | surface_tier |
-|---|---|---|---|---|---|---|
-| **low** | per profile | no | no | no | optional | `core` |
-| **medium** (advisory) | per profile | no | no | **yes** (domain safety floor) | recommended | `core` |
-| **high** | **no** (opt-in) | **yes** | **yes** (fail-closed) | **yes** | **yes** | `lab` |
-
-- **low** — engineering, product, meta, and tooling packs. Normal capability; no domain liability surface.
-- **medium (advisory)** — packs that emit advisory-shaped output (finance, strategy). They carry a **domain safety floor** that mandates a not-X-advice disclaimer + structural elements (assumptions / counter-case / confidence). Not off-by-default, but never a final call.
-- **high** — regulated-advice-adjacent. Off by default, consent-gated, council-gated (fail-closed), disclaimer-bound, eval-backed, lab-tier, and promotion-gated behind a professional review.
-
-## Per-pack assignment (non-low)
-
-| Pack | `risk_class` | Floor | Gates |
-|---|---|---|---|
-| `legal-review-prep` | **high** | `legal-safety-floor` | consent (`legal_review_prep.acknowledged`) · council (`require_council`, fail-closed) · hard individual-case STOP · attorney-review line + `Jurisdiction:` tag · attorney-framing-review promotion tripwire · `default_install: false` · `surface_tier: lab` |
-| `finance-basic` | medium | `finance-safety-floor` | not-financial-advice disclaimer · assumptions + sensitivity + confidence + counter-case · no final invest/raise call |
-| `finance-advanced` | medium | `finance-safety-floor` | as finance-basic (DCF / scenario depth) |
-| `founder-strategy` | medium | `strategy-safety-floor` | not-a-strategic-decision footer · bet + counter-case + residual risk + decision owner |
-
-Every other pack in `packs.yml` is **low** by default. A pack moves to medium the
-moment it ships advisory-shaped output behind a domain safety floor, and to high
-only through the high-risk checklist (consent + council + disclaimer + eval +
-lab + promotion gate) — see `road-to-legal-review-prep` for the worked example.
-
-## Capability lifecycle (a view, not a new axis)
-
-Reviewers wanted one lifecycle vocabulary for promoting / retiring capabilities.
-This is a **derived view** over the metadata that already exists
-(`trust_level_default` + `surface_tier` + eval presence) — **not** a new field.
-Nothing to set; it is read off what is already there.
-
-| Lifecycle | Derived from | Promotion criterion (to reach it) |
-|---|---|---|
-| **experimental** | `surface_tier: lab` **or** `trust_level_default: experimental` | default for any new pack/skill |
-| **validated** | `surface_tier: core` **and** has an `evals/` (or regression harness) | a real eval exists + the pack left lab |
-| **recommended** | validated **and** in a default profile / ≥1 real consumer | adoption evidence, not just existence |
-| **deprecated** | a `deprecated`/`superseded_by` marker in frontmatter | a successor named (per the persona/skill deprecation discipline) |
-
-Read the lifecycle column off the matrix above: a `lab` + `experimental` pack
-(e.g. `legal-review-prep`, `ai-video`) is **experimental**; a `core` pack with an
-eval is **validated**; a `core` pack a profile ships is **recommended**.
-Promotion stays a human/maintainer decision (criteria-documented, never
-automated — see `road-to-capability-governance` Phase 6).
-
-## See also
-
-- [`legal-safety-floor`](../../src/rules/legal-safety-floor.md) — the high-risk exemplar.
-- `finance-safety-floor` · `strategy-safety-floor` — the medium-risk advisory floors.
-- [`domain-pack-architecture`](../guidelines/agent-infra/domain-pack-architecture.md) — the pack build sequence.
-- `road-to-capability-governance` Phase 2 — `risk_class` as a validated pack field.

package/docs/contracts/capability-packs.md

@@ -1,217 +0,0 @@
----
-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,111 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-09-04
----
-
-# CI Cost Budget
-
-> **Status:** active · **Owner:** maintainer · **Opened:** 2026-05-26 ·
-> **Review cadence:** quarterly (next: 2026-08-26)
->
-> Measured durations + trigger surfaces for every PR-blocking CI job in
-> `.github/workflows/`. Sets a per-job wall-clock budget (5 min average)
-> beyond which the job either earns its cost in writing or gets a
-> follow-up optimisation step. Companion to
-> [`release-pr-gating.md`](release-pr-gating.md) and
-> [`branch-protection-policy.md`](branch-protection-policy.md).
-
-## Baseline (pre-optimisation, 2026-05-26)
-
-Captured via `gh run list --branch main --limit 50 --json
-name,createdAt,updatedAt`. Wall-clock figures are the average of the most
-recent 50 main-branch runs.
-
-| Workflow | Job | OS × variant | Avg duration | Trigger surface |
-|---|---|---|--:|---|
-| `tests.yml` | `install-tests` | 4 shards × 2 OS | 218 s | `scripts/**`, `tests/**`, `src/**`, manifest pins |
-| `tests.yml` | `install-aux-tests` | 2 OS | 90 s | same as above |
-| `tests.yml` | `python-tests` | 4 versions × ubuntu + 3.12 × macOS | ~210 s | same as above |
-| `tests.yml` | `node-tests` | 2 OS | 180 s | same as above |
-| `tests.yml` | `windows-lockfile-export` | windows-latest | 60–90 s | same as above (over-broad — see Phase C Step 1) |
-| `smoke-public-install.yml` | `smoke` | 3 OS × 2 Node | 413 s | install paths + setup.sh + templates |
-| `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 | `dist/agent-src*/**`, schemas |
-| `release-guard.yml` | (single) | ubuntu | < 10 s | tag-trigger only |
-
-**Critical path observations:**
-
-- `smoke-public-install.yml` and `tests.yml` dominate non-release-PR
-  wall-clock. Both trigger on `package.json` — a release PR (which only
-  touches `package.json` + CHANGELOG + marketplace + pack manifests)
-  pulled the full matrix on every bump pre-Phase A.
-- `tests.yml` `python-tests` ran four Python versions on Linux + 3.12 on
-  macOS on every PR touching `scripts/**`. The 3.10 / 3.11 / 3.13 legs
-  are extras: they prove the supported range but rarely surface a
-  Python-version-only regression. Moved to a path-filtered sibling
-  workflow in Phase C Step 2.
-- `tests.yml` `windows-lockfile-export` fired on every PR touching
-  `scripts/**` even when the PR never went near `install_global` /
-  `cmd_export`. Moved to its own path-filtered workflow in Phase C
-  Step 1.
-
-## Expected savings (post-optimisation)
-
-The Phase A guards on `tests.yml` + `smoke-public-install.yml` cut
-release-PR critical-path from `218 s + 413 s` (serial worst case ≈ 11
-min) to `~30 s` (`Consistency` + `Smoke Contracts` + new `Release
-Validation`). Phase C cuts feature-PR critical-path by removing the
-Windows leg (60–90 s) and the 3-version Python sweep from PRs that
-don't touch Python paths.
-
-| Scenario | Pre | Post | Reduction |
-|---|--:|--:|--:|
-| Release PR (release/X.Y.Z) | ~660 s | ~60 s | –91 % |
-| Feature PR touching scripts/** but no install_global / cmd_export | ~700 s | ~600 s | –14 % |
-| Feature PR touching only docs/** | ~30 s (consistency) | ~30 s | unchanged |
-| Feature PR touching Python paths only on 3.12 | ~700 s | ~700 s | unchanged (baseline still runs) |
-
-## Per-job cost ceiling — 5-min average
-
-Any job averaging **> 5 min wall-clock** across the most-recent 50
-main-branch runs requires one of:
-
-1. A documented justification in this file ("This job protects
-   property X; shrinking it would mean losing the regression Y").
-2. A follow-up optimisation step opened in the next quarterly review.
-3. An ADR superseding the ceiling for this specific job (e.g. integration
-   smoke that proves a real consumer-visible promise).
-
-Current jobs above the ceiling: `smoke-public-install.yml` (413 s) —
-ceiling violation is acknowledged. The Phase A skip on release PRs
-mitigates it; an ADR will follow if it re-exceeds 5 min on feature PRs
-post-Phase C.
-
-## Quarterly review checklist
-
-Run the first Monday of every quarter:
-
-1. Re-capture the baseline table via `gh run list --branch main --limit
-   50 --json name,createdAt,updatedAt` + arithmetic.
-2. Compare each row against the previous quarter; flag any > 25 %
-   regression.
-3. For every row over the 5-min ceiling, file a follow-up step in the
-   open CI-roadmap (or in this file's history if no roadmap is
-   currently active).
-4. Update the "Expected savings" table once optimisations land so the
-   delta is provable, not asserted.
-5. Audit the path-filter surfaces — when a workflow keeps firing on
-   PRs that don't touch its real scope, tighten the filter.
-
-## See also
-
-- [`release-pr-gating.md`](release-pr-gating.md) — release-PR shape
-  predicates, cut surface, kept surface.
-- [`branch-protection-policy.md`](branch-protection-policy.md) — required
-  status check floor per PR shape.
-- `.github/workflows/python-version-sweep.yml` — extras Python versions
-  (3.10 · 3.11 · 3.13) on Python-path PRs.
-- `.github/workflows/windows-lockfile-export.yml` — Windows leg gated by
-  `install_global` / `cmd_export` paths.