@event4u/agent-config 6.1.0 → 7.0.1

package/docs/command-naming-audit.md

@@ -0,0 +1,60 @@
+# Command-naming audit (road-to-contract-integrity F5)
+
+External review flagged inconsistent command naming across the docs
+(`/pr:create` vs `/create-pr`, `/feature/plan` vs `/feature:plan`). Two
+names for one command is two sources of truth — a discoverability failure,
+not cosmetic polish. This audit fixes the user-facing inconsistencies and
+records the canonical rule + the alias registry that already exists.
+
+## The canonical form
+
+Per [ADR-003](decisions/ADR-003-flat-cluster-subs-and-colon-syntax.md) and
+[`command-clusters.md`](contracts/command-clusters.md) §"Colon-canonical
+invocation": **`/<cluster>:<sub>` is the canonical invocation form
+everywhere** — catalog, docs, cookbook. The frontmatter `name:` field is
+always the hyphen slug (`feature-plan`); the slash form (`/feature/plan`)
+is never an invocation syntax.
+
+## The alias registry already exists — do not add a parallel field
+
+The roadmap step proposed adding an `aliases:` field to the command
+schema. That would **duplicate** the mechanism that already ships:
+
+- **`replaces:`** (on the new/canonical command) — the prior name(s) or
+  alias(es) it absorbs. Colon forms are allowed here on purpose (historical
+  aliases like `commit:in-chunks`). Enforced by `lint_command_routing.py`.
+- **`superseded_by:`** (on the old shim) — points forward to the successor.
+
+Adding a second `aliases:` field would re-create the exact two-sources-of-
+truth problem this audit fixes. **Decision: `replaces:` is the canonical
+alias registry; no new field is introduced.** (This deviates from the
+literal Phase-1 roadmap text by intent — see the roadmap step note.)
+
+## Clashes resolved in this change
+
+Everything resolves **toward** the colon-canonical form. The PR command
+only ships as `dist/agent-src/commands/pr/create.md` (invoked `/pr:create`);
+there is no `commands/create-pr.md` projection, so `/create-pr` is a legacy
+*alias name* recorded in `replaces:`, not a directly-invocable command.
+
+| Surface | Was | Now | Basis |
+|---|---|---|---|
+| `README.md` Delivery flow + 2 prose refs | `/pr:create` (1) + `/create-pr` (2) | `/pr:create` (all) | Colon-canonical (ADR-003); `/pr:create` is the only projected command. |
+| `docs/featured-commands.md` | `/create-pr` (→ stale `commands/create-pr.md` link) | `/pr:create` (→ `commands/pr/create.md`) | The legacy link target no longer exists; point at the real projection. |
+| `docs/cookbook.md` (generated) | `/feature/explore`, `/feature/plan`, … (slash) | `/feature:explore`, `/feature:plan`, … (colon) | Fixed at the **generator** (`_invocation()` renders `cluster/sub` → `/cluster:sub`); all clustered refs now colon. The file is generated — the slash form was a generator bug, not a hand-edit. |
+
+## Known debt — deferred (own change)
+
+The PR command's frontmatter still carries `cluster: git-pr-create` and its
+body prose still self-documents the `/create-pr` family (and
+`/create-pr:description-only`). The user-facing invocation and all docs are
+now `/pr:create`; retiring the `/create-pr` alias name entirely — frontmatter
+`cluster`, the body prose, and the `:description-only` sub-family wording —
+is a command-body refactor out of scope for this audit and is tracked as
+command-surface debt.
+
+## See also
+
+- [`contracts/command-clusters.md`](contracts/command-clusters.md) — cluster + colon-syntax rules.
+- [`decisions/ADR-003-flat-cluster-subs-and-colon-syntax.md`](decisions/ADR-003-flat-cluster-subs-and-colon-syntax.md).
+- [`contracts/STABILITY.md`](contracts/STABILITY.md) — command stability policy.

package/docs/contracts/STABILITY.md

@@ -150,6 +150,38 @@ for the contract and the transitional allowlist.
   shipped `dist/agent-src/` (condensed) directory; the uncondensed
   source size is informational only.
 
+## Schema versioning and structural breaking changes
+
+The breaking-change gate is **two-layered** so it does not depend on
+author discipline alone:
+
+1. **Commit-annotation layer (`release.py`).** `infer_bump` reads the
+   Conventional-Commits annotation (`<type>!:` bang or a
+   `BREAKING CHANGE` line) and returns a major bump when present.
+2. **Structural layer (`check_structural_breaking.py`, run in
+   `task ci-fast`).** Independently of the commit message, the detector
+   inspects the diff against the trunk and FAILS when a structural break
+   is present *without* an annotation — forcing the annotation to exist.
+
+A change is **structurally breaking** when either:
+
+- a tracked artifact *source* file is **deleted or renamed** — a skill
+  `SKILL.md`, a rule, a command `command.md`, a pack manifest, or a
+  contract schema; or
+- a contract schema under `src/scripts/schemas/` is **modified without
+  bumping its `x-schemaVersion`**. The four contract schemas (`pack`,
+  `skill`, `rule`, `command`) carry an `x-schemaVersion`. Bump it when an
+  enum value is added or removed, a field type changes, or a validation
+  rule tightens — these are breaking-for-consumers yet invisible to a
+  name-status diff. Purely *additive* schema changes (a new optional
+  field) do not require a bump.
+
+Escape for an intentional break (e.g. a deprecation cycle completing):
+add `ci-override: structural-breaking-ok` to a commit body. The detector
+accepts ~20% false-negatives on purely *semantic* breaks (behaviour
+change with no artifact/schema delta); the structural + schema + commit
+cross-check reaches ~95% coverage (2026-06-16 council).
+
 ## See also
 
 - [`docs/architecture.md`](../architecture.md) — package architecture overview

package/docs/contracts/agents-md-tech-stack.md

@@ -30,7 +30,7 @@ package). The skill ships the four-layer security defense:
 Calibrated token claim: 3-5× comprehension on text-heavy formats
 (PDF, DOCX), 10-50× on image-heavy formats (scanned PDF, PPTX with
 diagrams). Measure locally with
-`python3 scripts/measure_markitdown_lift.py` against
+`./scripts-run src/scripts/measure_markitdown_lift` against
 `tests/fixtures/markitdown-corpus/`.
 
 ## Cognition-only floor for Wings 2–4

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

@@ -262,7 +262,7 @@ is invoked.
   tier. The two-tier split reconciles "Council always active when
   enabled" with "skip trivial agent-side requests": user-typed
   `/council` calls proceed by default, agent-initiated dispatches keep
-  `educate` behaviour. Override via `.agent-settings.yml`.
+  `educate` behaviour. Override via the resolved `.ai-council.yml`.
 - `lens_overrides.necessity_classifier_mode.<lens>` — per-lens override.
   Wins over the global `mode` for the matching invocation tier (agent
   vs user_explicit follow the same lens map). Typical use: leave the
@@ -433,26 +433,26 @@ Worked example — opt the Anthropic and OpenAI members in, leave the
 others off, and switch the `low_impact` class to `council`:
 
 ```yaml
-ai_council:
-  members:
-    anthropic:
-      enabled: true
-      model: claude-sonnet-4-5
-      api_key_ref: file:anthropic.key
-      participate_low_impact: true   # eligible for fast-path
-    openai:
-      enabled: true
-      model: gpt-4o
-      api_key_ref: file:openai.key
-      participate_low_impact: true   # eligible for fast-path
-    gemini:
-      enabled: false                  # disabled — opt-in ignored even if set
-
-  fast_path:
-    max_members: 2          # 1 or 2 only
-    max_rounds: 1           # LOCKED
-    max_tokens: 2500
-    max_cost_usd: 0.05
+# In the resolved .ai-council.yml — keys are top-level (no `ai_council:` wrapper).
+members:
+  anthropic:
+    enabled: true
+    model: claude-sonnet-4-5
+    api_key_ref: file:anthropic.key
+    participate_low_impact: true   # eligible for fast-path
+  openai:
+    enabled: true
+    model: gpt-4o
+    api_key_ref: file:openai.key
+    participate_low_impact: true   # eligible for fast-path
+  gemini:
+    enabled: false                  # disabled — opt-in ignored even if set
+
+fast_path:
+  max_members: 2          # 1 or 2 only
+  max_rounds: 1           # LOCKED
+  max_tokens: 2500
+  max_cost_usd: 0.05
 
 decision_resolution:
   classes:
@@ -641,7 +641,7 @@ as comments and the loader enforces them.
   whose projected spend would breach a cap and asks the user to continue.
   Each `0` value disables that single cap; other caps still apply.
   Prices come from [`agents/runtime/.agent-prices.md`](../../agents/runtime/.agent-prices.md)
-  (gitignored, refreshed weekly by `python3 scripts/update_prices.py`;
+  (gitignored, refreshed weekly by `./scripts-run src/scripts/update_prices`;
   bootstrapped from `scripts/ai_council/_default_prices.py` on first run).
 
 ## Validation rules

package/docs/contracts/analysis-memory-loop.md

@@ -0,0 +1,149 @@
+---
+stability: draft
+keep-draft-until: first-skill-ships
+owner: road-to-analysis-workbench
+---
+
+# Analysis Memory Loop — produce → propose → promote → retrieve
+
+> **Status:** draft · **Owner:** road-to-analysis-workbench
+> · **Governed by:** `src/rules/non-destructive-by-default.md`,
+> `src/rules/domain-safety-disclaimer.md`
+
+Contract for the closed learning loop in the `analysis-workbench` pack.
+Binds all analysis skills: `blameless-post-mortem`, `root-cause-frameworks`,
+`premortem`, `decision-review`.
+
+---
+
+## § 1 — Produce: what analysis flows draft
+
+Post-mortem, RCA, decision-review, and near-miss flows MUST draft
+`incident-learnings` and `historical-patterns` **candidates** into the
+`/memory propose` provisional JSONL intake stream.
+
+Candidates are produced; they are **never auto-promoted** to curated memory.
+The human drives promotion. An analysis skill that skips the draft step or
+claims self-promotion violates this contract.
+
+### Candidate schema (minimum)
+
+```jsonc
+{
+  "type":               "incident-learnings" | "historical-patterns",
+  "summary":            "one-line human-readable pattern",
+  "evidence_paths":     ["path/to/file", "path/to/other"],
+  "decision_surface":   ["area1", "area2"],
+  "last_validated":     "YYYY-MM-DD",
+  "review_after_days":  90,
+  "applicable_scope":   "project" | "domain" | "global"
+}
+```
+
+`last_validated` defaults to today. `review_after_days` defaults to 90.
+`applicable_scope` defaults to `"project"`.
+
+---
+
+## § 2 — Propose: intake and dedup pre-check
+
+Before drafting a **new** candidate, each skill calls `retrieve()` over the
+same key-space (incident type, affected paths, decision area).
+
+- **Match found** — propose a `frequency`/`supersedes` **update** to the
+  existing entry, not a new entry. The proposal notes which existing entry is
+  being reinforced or superseded.
+- **No match** — draft a new candidate as described in § 1.
+
+This dedup check is not optional. A skill that skips it and produces a
+duplicate candidate fails the loop contract.
+
+---
+
+## § 3 — Promote: the admission gate
+
+`/memory promote` runs `scripts/check_memory_proposal.py`.
+
+**Admission criteria** (unchanged from the existing gate):
+
+- `≥ 2 distinct file paths` referenced in `evidence_paths`, OR
+- `≥ 3 future decisions` the pattern would change (listed in
+  `decision_surface`).
+
+Failing either criterion → proposal stays provisional; skill surfaces the
+gap to the user and suggests either deferring or strengthening evidence.
+
+The agent NEVER overrides or bypasses this gate. Redaction is enforced by
+`check_memory.py` (no customer names, secrets, internal IPs, project-rooted
+paths) before any entry is promoted.
+
+---
+
+## § 4 — Retrieve: staleness is explicit
+
+`retrieve()` returns:
+
+```jsonc
+{
+  "results": [...],
+  "skipped": [
+    {
+      "id":      "...",
+      "reason":  "stale",
+      "details": "last_validated=YYYY-MM-DD, review_after_days=90"
+    }
+  ]
+}
+```
+
+Stale entries (age > `review_after_days`) appear in `skipped`, NOT in
+`results`. A skill that silently uses stale entries (ignores `skipped`)
+violates this contract. Stale matches MUST be surfaced to the user.
+
+---
+
+## § 5 — Handoff: incident-commander → blameless-post-mortem
+
+`incident-commander` produces a handoff skeleton. That skeleton **may carry
+an empty or TBD root cause** — incomplete evidence at incident close is
+normal.
+
+`blameless-post-mortem`:
+
+1. **Accepts** any incoming skeleton, complete or not.
+2. Invokes `root-cause-frameworks` to fill gaps; `root-cause-frameworks`
+   returns ranked candidates with confidence levels, not a forced verdict.
+3. Marks the post-mortem `status: draft` if root cause remains unresolved
+   after the analysis pass.
+4. NEVER rejects or stalls on an incomplete skeleton.
+
+A post-mortem marked `draft` can still produce `incident-learnings`
+candidates (`summary` must note the open question).
+
+---
+
+## § 6 — Framework-neutrality scope
+
+The `framework-neutrality-in-generic-skills` rule governs **tech-stack names**
+(Laravel, React, Django). It does **not** govern analysis method names.
+
+5-whys, fishbone, fault-tree, STAMP/STPA, and similar are method names used
+generically across analysis skills. Using them in a skill named
+`root-cause-frameworks` is not a framework-neutrality violation.
+
+---
+
+## § 7 — What this contract does NOT cover
+
+- The schema of curated memory entries (governed by `low-impact-corpus-format.md`).
+- The internal mechanics of `check_memory_proposal.py` (lives in `src/scripts/`).
+- AI-specific RCA (deferred; gated on `road-to-security-hardening`).
+
+---
+
+## See also
+
+- [`low-impact-corpus-format.md`](low-impact-corpus-format.md) — curated memory schema.
+- [`ADR-096`](../decisions/ADR-096-analysis-workbench.md) — council decisions behind this contract.
+- `src/skills/blameless-post-mortem/SKILL.md` — primary consumer (Phase 2).
+- `src/skills/root-cause-frameworks/SKILL.md` — RCA engine (Phase 2).

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

@@ -32,7 +32,7 @@ This contract covers the **variant axis** (`with` vs. `without` agent-config) th
 
 1. `task bench:ab` runs (the full pipeline ends with `bench:ab:diff` which calls the renderer).
 2. `task bench:ab:diff` runs alone (no fresh bench, just re-render).
-3. The renderer is invoked directly: `python3 scripts/render_benchmark_md.py`.
+3. The renderer is invoked directly: `./scripts-run src/scripts/render_benchmark_md`.
 
 The renderer is deterministic: same reports → same output. It never runs a bench. If no reports exist, it writes a placeholder document — never errors out.
 
@@ -86,10 +86,10 @@ The integrity check `bench_ab_tracka_run.py::integrity_check` fails the run if `
 
 A bench run counts as a real measurement (rather than a plumbing health check) when:
 
-- `python3 scripts/bench_ab_integrity.py` exits 0 (the variant axis is clean).
+- `./scripts-run src/scripts/bench_ab_integrity` exits 0 (the variant axis is clean).
 - Track A runs in BOTH variants and produces `integrity_ok: true` (with scoring close to 100%, without scoring 0%).
 - Track B runs in BOTH variants in `--mode live` (not dry-run).
-- `python3 scripts/lint_bench_ab.py` passes.
+- `./scripts-run src/scripts/lint_bench_ab` passes.
 - The rendered `docs/benchmark.md` carries the Headline + Track A + Track B + Methodology + History sections.
 
 ## Out of scope for this contract

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

@@ -91,6 +91,33 @@ 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

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

@@ -0,0 +1,69 @@
+# 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/command-clusters.md

@@ -49,11 +49,12 @@ column 1 of this table.
 | `sync-gitignore` | — | `fix` | new sub-command 2026-05-11 — cluster head retains the existing append-only sync as its default flow; `:fix` adds `--cleanup-legacy` semantics, scrubbing pre-`/agents/` runtime patterns wherever they appear in the consumer's `.gitignore` (inside or outside the managed block) and re-syncing the canonical entries. |
 | `ghostwriter` | — | `fetch` · `write` · `list` · `show` · `delete` | new cluster 2026-05-15 — third voice primitive for AI-assisted writing in the public voice of a public figure. Hybrid storage: real-person profiles live consumer-side under `agents/reference/ghostwriter/<slug>.md` (gitignored by default); package source ships only `fictional: true` fixtures. Zero network code in the package — `:fetch` delegates web-fetch / web-search to the host agent. Mandatory disclosure footer on every `:write` output (no opt-out). Schema: [`ghostwriter-schema`](ghostwriter-schema.md). |
 | `post-as` | — | `me` · `ghostwriter` | new cluster 2026-05-15 — consumer-facing write entry points. `:me` reads `.agent-user.md.voice_sample` and drafts in the maintainer's own voice (no disclosure footer — the user is the author); `:ghostwriter` is a thin alias for `/ghostwriter:write` with the mandatory disclosure footer. Both share the procedural [`write-engine`](write-engine.md) contract — style source and footer are the only axes of variation. |
-| `video` | — | `from-script` · `from-song` · `scene` · `storyboard` · `stitch` | new cluster 2026-05-17 — AI video generation pipeline. Cluster head orchestrates the full flow; `:scene` runs a single scene end-to-end (script → blueprint → still → motion → clip); `:storyboard` expands a script into per-scene blueprints + reference stills with character-lock JSON; `:from-script` walks a multi-scene script through storyboard + per-scene generation; `:from-song` builds a music-video from a song + reference images — derived/briefed timed script (via the `song-to-script` skill + `probe-audio.sh` hybrid segmentation), optional character-lock, then stitch with the song muxed as the master track and a mandatory AI-generation disclosure; `:stitch` concatenates scene clips with `ffmpeg` against a scene manifest. Provider-agnostic via the adapter contract under `scripts/ai-video/lib/adapter-contract.md`; cost-gated with mandatory `AIV_DRYRUN=true` default and explicit confirmation before live provider calls. |
+| `video` | — | `from-script` · `from-song` · `scene` · `storyboard` · `stitch` | new cluster 2026-05-17 — AI video generation pipeline. Cluster head orchestrates the full flow; `:scene` runs a single scene end-to-end (script → blueprint → still → motion → clip); `:storyboard` expands a script into per-scene blueprints + reference stills with character-lock JSON; `:from-script` walks a multi-scene script through storyboard + per-scene generation; `:from-song` builds a music-video from a song + reference images — derived/briefed timed script (via the `song-to-script` skill + `probe-audio.sh` hybrid segmentation), optional character-lock, then stitch with the song muxed as the master track and a mandatory AI-generation disclosure; `:stitch` concatenates scene clips with `ffmpeg` against a scene manifest. Provider-agnostic via the adapter contract under `scripts/media/lib/adapter-contract.md`; cost-gated with mandatory `AIV_DRYRUN=true` default and explicit confirmation before live provider calls. |
 | `knowledge` | — | `ingest` · `list` · `forget` · `cross-repo` | local-knowledge namespace (employee-product Phase 7); `:cross-repo` added 2026-05-30 (`road-to-leaner-core-and-discovery` Phase 4) — read-only targeted retrieval over opted-in `linked_projects` siblings (ADR-032 Option A), per [`cross-repo-retrieval`](cross-repo-retrieval.md). The pre-existing `ingest`/`list`/`forget` sub-commands are recorded in the registry here for the first time. |
 | `skills` | — | `discover` | new cluster 2026-05-30 (`road-to-leaner-core-and-discovery` Phase 3) — local, explained skill-recommendation surface over the catalog + role shortlists + optional local analytics, per [`skill-discovery`](skill-discovery.md). Every result carries a non-empty `why`; no network, honours the analytics opt-out. |
 | `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). |
+| `brand` | — | `strategy` · `identity` · `tokens` · `review` · `voice` | new cluster 2026-06-17 (`road-to-image-brand-followups` Phase 3) — brand-as-first-class-UX surface for `pack-brand`, consulted before `design-intelligence` so brand bounds style. `:strategy` (positioning/archetype/voice/messaging over the brand corpus), `:identity` (logo/colour/type/imagery direction — defines the tokens downstream generation consumes), `:tokens` (derive a DTCG `.tokens.json` source of truth → CSS/Tailwind, no Node), `:review` (audit emitted UI/copy/assets against active brand tokens + voice per the `brand-consistency` gate), `:voice` (voice-and-tone profile). Skills: [`brand-strategy`](../../skills/brand-strategy/SKILL.md) · [`brand-identity`](../../skills/brand-identity/SKILL.md) · [`brand-to-tokens`](../../skills/brand-to-tokens/SKILL.md) · [`brand-audit`](../../skills/brand-audit/SKILL.md) · [`voice-and-tone-design`](../../skills/voice-and-tone-design/SKILL.md). The companion `/imagegen:*` generation cluster (pack-ai-image) is deferred until its adapters' live submit/poll/fetch is wired. |
 
 | `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). |
 

package/docs/contracts/command-surface-tiers.md

@@ -156,6 +156,19 @@ the help text groups commands under `## Tier 0`, `## Tier 1`,
 
 Hooked into `task lint-skills` so it runs in CI.
 
+## `tier` deprecation signal (discovery manifest v2)
+
+Since ADR-090 the named `visibility:` field is the command classifier source
+of truth and the integer `tier:` (`0/1/2`) is a back-compat alias. The
+published discovery manifest (`dist/discovery/discovery-manifest.json`) is now
+**v2** and carries a machine-readable top-level `deprecations` block
+announcing the `tier` key (replacement: `visibility`). `tier` is **still
+emitted** on command artefacts (non-breaking) — the block only signals the
+deprecation so external manifest consumers can migrate during a soak window.
+Removal of `tier` (frontmatter + schema + manifest emit) is tracked in
+`road-to-tier-removal` (ADR-092, Phase 4) and is **not** done yet; restoring
+`tier` after removal would be a sub-1h manifest-schema patch.
+
 ## See also
 
 - The distribution-maturity roadmap — Phase 4 (under `agents/roadmaps/`).

package/docs/contracts/discovery-manifest.schema.json

@@ -8,8 +8,13 @@
   "additionalProperties": false,
   "properties": {
     "version": {
-      "const": 1,
-      "description": "Manifest schema version. Bump on breaking change."
+      "const": 2,
+      "description": "Manifest schema version. Bump on breaking change. v2 (road-to-tier-removal Phase 1 / ADR-092) adds the top-level `deprecations` block; the integer command `tier` field stays emitted (non-breaking)."
+    },
+    "deprecations": {
+      "type": "array",
+      "description": "road-to-tier-removal Phase 1 / ADR-092 — machine-readable deprecation signals for keys still emitted (non-breaking) but scheduled for removal. Lets external manifest consumers migrate during the soak window before any field is dropped.",
+      "items": { "$ref": "#/$defs/deprecation" }
     },
     "generated_at": {
       "type": "string",
@@ -53,6 +58,20 @@
     "stats": { "$ref": "#/$defs/stats" }
   },
   "$defs": {
+    "deprecation": {
+      "type": "object",
+      "required": ["key", "replacement", "since"],
+      "additionalProperties": false,
+      "description": "A single deprecated manifest key still emitted during its soak window.",
+      "properties": {
+        "key": { "type": "string", "minLength": 1, "description": "The deprecated key (e.g. `tier`)." },
+        "scope": { "type": "string", "minLength": 1, "description": "Where the key appears (e.g. `command` artefact entries)." },
+        "replacement": { "type": "string", "minLength": 1, "description": "The canonical key consumers should read instead (e.g. `visibility`)." },
+        "since": { "type": "string", "minLength": 1, "description": "The decision that deprecated it (e.g. an ADR id)." },
+        "sunset": { "type": ["string", "null"], "description": "Maintainer-owned removal date/marker; null until the soak window clears (scope-control: agents do not pin dates)." },
+        "note": { "type": "string", "description": "Human-readable migration guidance." }
+      }
+    },
     "workspace_id": {
       "type": "string",
       "enum": ["engineering", "product", "finance", "founder", "gtm", "ops", "small-business", "construction", "agent-config-maintainer"]
@@ -64,8 +83,8 @@
         "product-basic", "product-discovery",
         "finance-basic", "finance-advanced",
         "gtm-sales", "gtm-marketing",
-        "ops-people", "founder-strategy", "small-business", "construction", "ai-video", "fun", "meta", "git", "frontend-design",
-        "memory", "analytics", "product-reasoning"
+        "ops-people", "founder-strategy", "small-business", "construction", "ai-video", "ai-image", "fun", "meta", "git", "frontend-design", "brand",
+        "memory", "analytics", "product-reasoning", "analysis-workbench"
       ]
     },
     "lifecycle": {
@@ -135,7 +154,7 @@
         "category": { "type": "string", "enum": ["skill", "rule", "command", "template"] },
         "name": { "type": "string" },
         "pack": { "$ref": "#/$defs/pack_id", "description": "capability-packs.md — canonical OWNER pack (ownership/budget unit). Orthogonal to `packs` (discovery tags); the owner need not appear in `packs`." },
-        "tier": { "type": "integer", "enum": [0, 1, 2], "description": "6.0.0-C — command-surface tier surfaced on `category: command` artefacts so the CLI discovery surface reads the manifest, not a parallel catalog. Back-compat alias of `visibility` since ADR-090; dual-emitted during the deprecation window." },
+        "tier": { "type": "integer", "enum": [0, 1, 2], "description": "6.0.0-C — command-surface tier surfaced on `category: command` artefacts so the CLI discovery surface reads the manifest, not a parallel catalog. DEPRECATED back-compat alias of `visibility` since ADR-090; still dual-emitted (non-breaking) but announced for removal in the top-level `deprecations` block (road-to-tier-removal Phase 1 / ADR-092). Read `visibility`." },
         "visibility": { "type": "string", "enum": ["visible", "advanced", "internal"], "description": "ADR-090 — named command-surface visibility (visible↔tier 0, advanced↔tier 1, internal↔tier 2); the classifier source of truth. Dual-emitted alongside `tier` on `category: command` artefacts during the deprecation window." },
         "intent": { "type": "string", "description": "6.0.0-C — command routing metadata (one-line existence justification). Present on visible command artefacts." },
         "routes_to": { "type": "array", "items": { "type": "string" }, "description": "6.0.0-C — command routing metadata (skill/cluster-sub/command slugs the intent routes to)." },

package/docs/contracts/implement-ticket-flow.md

@@ -170,7 +170,7 @@ therefore requires:
 2. Re-run the per-dimension fixtures
    (`tests/work_engine/test_scoring_confidence.py`).
 3. Re-capture GT-P1..GT-P4 if a fixture's band assignment shifts
-   (`python3 -m tests.golden.capture`); review the diff before
+   (`node node_modules/.bin/tsx tests/golden/capture.ts`); review the diff before
    locking. If GT-P3 (low) or GT-P4 (UI rejection) flip bands the
    threshold change is rejected — those fixtures are pinned to
    their bands by design.
@@ -428,7 +428,7 @@ manual for producing and re-producing those packs.
 
 Each cycle is a fresh `./agent-config implement-ticket` subprocess
 seeded from the persisted state file. The runner
-(`tests/golden/sandbox/runner.py`) chains them:
+(`tests/golden/sandbox/runner.ts`) chains them:
 
 ```bash
 ./agent-config implement-ticket \
@@ -443,8 +443,8 @@ seeded from the persisted state file. The runner
 The runner is invoked via the capture driver:
 
 ```bash
-python3 -m tests.golden.capture                 # all five GTs
-python3 -m tests.golden.capture --scenarios GT-3
+node node_modules/.bin/tsx tests/golden/capture.ts                 # all five GTs
+node node_modules/.bin/tsx tests/golden/capture.ts --scenarios GT-3
 ```
 
 ### Kill points & resume
@@ -492,7 +492,7 @@ recipe and relock policy: [`tests/golden/CAPTURING.md`](../../tests/golden/CAPTU
 Only when the engine's observable behaviour intentionally changes:
 
 ```bash
-python3 -m tests.golden.capture
+node node_modules/.bin/tsx tests/golden/capture.ts
 git diff tests/golden/baseline tests/golden/CHECKSUMS.txt
 ```
 
@@ -566,7 +566,7 @@ Only when an engine change is **intentionally** behaviour-altering.
 The PR description must justify each new checksum. Procedure:
 
 ```bash
-python3 -m tests.golden.capture                  # regenerate Capture Packs + manifest
+node node_modules/.bin/tsx tests/golden/capture.ts                  # regenerate Capture Packs + manifest
 git diff tests/golden/baseline tests/golden/CHECKSUMS.txt
 ```
 
@@ -587,13 +587,13 @@ are blocked by `freeze-guard.yml::manifest-integrity` at PR time.
 
 - Loosening the harness comparator to "fix" a failing replay. The
   harness is the contract; the engine is the variable.
-- Re-running `python3 -m tests.golden.capture` to "make the diff go
+- Re-running `node node_modules/.bin/tsx tests/golden/capture.ts` to "make the diff go
   away" without justification. The diff *is* the question.
 - Treating the harness and freeze-guard as duplicate checks. They
   catch different drift classes — both must stay green.
 - Adding a sixth Capture Pack without adding a corresponding entry
-  to `RECIPE_MODULES` in `harness.py` and a parametrize row in
-  `test_replay.py`.
+  to `RECIPES` in `sandbox/recipes/index.ts` and a parametrize row in
+  `golden_replay.test.ts`.
 
 ## Non-goals