@event4u/agent-config 6.0.0 → 7.0.0

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

@@ -33,7 +33,7 @@ column 1 of this table.
 | `feature` | 1 | `explore` · `plan` · `refactor` · `roadmap` · `dev` | `feature-explore` · `feature-plan` · `feature-refactor` · `feature-roadmap` · `feature-dev` |
 | `chat-history` | 2 | `show` · `import` · `learn` | `chat-history` (legacy status) — `resume` / `clear` / `checkpoint` removed in `road-to-chat-history-hook-only` (auto-adopt + structural hooks); `import` (verbatim cross-session render) and `learn` (project-improving learning extraction) added in the v4 stateless schema |
 | `agents` | 2 | `init` · `optimize` · `audit` · `user` | AGENTS.md file family (high-frequency) — repurposed 2026-05-09: `init` (was `/copilot-agents init`) · `optimize` (merger of `/optimize agents-md` + `/copilot-agents optimize`) · `audit` (was `/optimize agents`, collapses old `audit` + `check` verbs); legacy folder ops (`prepare` / `cleanup` / folder-`audit`) moved to `/optimize agents-dir`; `user` sub-cluster added 2026-05-15 — manages the project-root `.agent-user.md` persona file (sub-sub-commands: `init` · `show` · `review` · `accept` · `update`) per [`agent-user-schema`](agent-user-schema.md) |
-| `memory` | 2 | `add` · `load` · `promote` · `propose` · `mine-session` · `learn-low-impact` | `memory-add` · `memory-full` · `memory-promote` · `propose-memory`; `mine-session` added 2026-05-10 — manual transcript-mining sub-command from `road-to-dream-skill-adoption.md`, opt-in via `--confirm-transcript-access` per invocation; `learn-low-impact` added 2026-05-15 — upstreams `## Validated` entries from `agents/decisions/low-impact-decisions.md` to the package seed via a DRAFT PR (re-runs the privacy-floor redactor as a second gate per `low-impact-corpus-privacy-floor`) |
+| `memory` | 2 | `add` · `load` · `promote` · `propose` · `mine-session` · `learn-low-impact` | `memory-add` · `memory-full` · `memory-promote` · `propose-memory`; `mine-session` added 2026-05-10 — manual transcript-mining sub-command from an internal roadmap (local-only), opt-in via `--confirm-transcript-access` per invocation; `learn-low-impact` added 2026-05-15 — upstreams `## Validated` entries from `agents/decisions/low-impact-decisions.md` to the package seed via a DRAFT PR (re-runs the privacy-floor redactor as a second gate per `low-impact-corpus-privacy-floor`) |
 | `roadmap` | 2 | `create` · `ai-council` · `process-step` · `process-phase` · `process-full` | `roadmap-create` · `roadmap-execute` (replaced — autonomous, no per-step gate; `process-phase` is the default execution scope); `ai-council` added 2026-05-07 — wraps `/council default` with `--input-mode roadmap --depth deep` |
 | `module` | 2 | `create` · `explore` | `module-create` · `module-explore` |
 | `tests` | 2 | `create` · `execute` | `tests-create` · `tests-execute` |
@@ -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/cost-enforcement.md

@@ -128,7 +128,7 @@ suite is wired to `task test-cost-budget` per `step-11` Phase 2 Step 5.
 
 ## See also
 
-- `step-11-ruflo-parity` — Measurement & Governance Parity roadmap.
+- an internal parity roadmap (local-only) — Measurement & Governance Parity roadmap.
 - `docs/contracts/cost-dashboard.md` — companion dashboard contract.
 - `scripts/cost/budget.mjs` — evaluator implementation.
 - `internal/bench/pricing.yaml` — per-model USD pricing table.

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

@@ -9,7 +9,7 @@ Stable JSON contract for inter-tool consumption of cost-tracking data
 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
+Design reference: the external runtime `scripts/summary.mjs` (upstream cite). Our shape
 diverges to align with the local `agents/cost-tracking/sessions.jsonl`
 fields and the telegraph-suspended-multiplier contract.
 

package/docs/contracts/daily-workspace.md

@@ -139,6 +139,7 @@ counters only. No prompt bodies, no response bodies.
 
 ## Cross-references
 
+- **Boundary:** [`workspace-boundary`](workspace-boundary.md) — what the workspace owns vs. does **not** own ([`ADR-095`](../decisions/ADR-095-workspace-boundary-contract.md)), enforced by the import-edge linter.
 - ADRs: [`022`](../decisions/ADR-022-daily-workspace-decomposition.md) · [`023`](../decisions/ADR-023-host-agent-protocol.md) · [`024`](../decisions/ADR-024-workspace-v0-feature-floor.md) · [`025`](../decisions/ADR-025-workspace-chrome.md).
 - Host-agent protocol: [`host-agent-protocol`](host-agent-protocol.md).
 - GUI substrate: [`gui-wizard`](gui-wizard.md).

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,7 +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"
+        "ops-people", "founder-strategy", "small-business", "construction", "ai-video", "ai-image", "fun", "meta", "git", "frontend-design", "brand",
+        "memory", "analytics", "product-reasoning", "analysis-workbench"
       ]
     },
     "lifecycle": {
@@ -134,7 +154,8 @@
         "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." },
+        "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)." },
         "replaces": { "type": "array", "items": { "type": "string" }, "description": "6.0.0-C — command routing metadata (prior names/aliases this command absorbs; may be empty)." },

package/docs/contracts/explain-modes.md

@@ -182,6 +182,6 @@ profile-explain (`ask-when-uncertain`).
 ## Cross-references
 
 - ADR: [`ADR-026`](../decisions/ADR-026-explain-mode-translation.md).
-- Envelope contract: [`agent-memory-contract`](agent-memory-contract.md) (`explain-v1`).
+- Envelope contract: [`retrieval-v1.schema.json`](../../internal/schemas/retrieval-v1.schema.json) (`explain-v1`).
 - Workspace integration: [`daily-workspace`](daily-workspace.md) (right rail).
 - Roles: [`role-experience`](role-experience.md) (`explain_default` field).

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

@@ -34,7 +34,7 @@ in Phase 0 and recorded in a short ADR once decided.
 - A runtime implementation spec.
 - A DSL for user-authored flows (explicitly out of scope).
 - A memory retrieval spec — that lives in
-  [`agent-memory-contract.md`](agent-memory-contract.md).
+  [`../guidelines/agent-infra/memory-access.md`](../guidelines/agent-infra/memory-access.md).
 
 ## The linear flow
 
@@ -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.
@@ -262,17 +262,16 @@ boundary writes. Full reference: [`work-engine-hooks.md`](work-engine-hooks.md).
 Bounded per the top-level roadmap rule:
 
 - **Max 12 hits total.**
-- **Four allowed types:** `domain-invariants`,
-  `architecture-decisions`, `incident-learnings`,
-  `historical-patterns`. All four exist in the
-  [templates directory](../../.agent-src.uncondensed/templates/agents/memory/).
+- **Three allowed types:** `domain-invariants`, `incident-learnings`,
+  `historical-patterns`. (Architectural rationale lives in ADRs —
+  `docs/decisions/` — not in curated memory.)
 - **Keys:** files touched by the plan, symbols referenced by the
   ticket.
 - **Decision-change rule:** a memory hit that did not change an
   outcome is dropped from the report. If none changed an outcome,
   the `memory` section of the report is omitted — not padded.
 - Follows the retrieval shape in
-  [`agent-memory-contract.md`](agent-memory-contract.md).
+  [`../guidelines/agent-infra/memory-access.md`](../guidelines/agent-infra/memory-access.md).
 
 ## Persona policies
 
@@ -429,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 \
@@ -444,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
@@ -493,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
 ```
 
@@ -567,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
 ```
 
@@ -588,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
 
@@ -619,7 +618,7 @@ are blocked by `freeze-guard.yml::manifest-integrity` at PR time.
 - `tests/golden/` — capture sandbox, recipes, and Capture Packs
 - [`../../tests/golden/harness.py`](../../tests/golden/harness.py) — Strict-Verb replay harness
 - [`../../.github/workflows/freeze-guard.yml`](../../.github/workflows/freeze-guard.yml) — manifest-integrity + live-replay gates
-- [`agent-memory-contract.md`](agent-memory-contract.md)
+- [`../guidelines/agent-infra/memory-access.md`](../guidelines/agent-infra/memory-access.md)
 - [`../../docs/guidelines/agent-infra/role-contracts.md`](../../docs/guidelines/agent-infra/role-contracts.md)
 - [`../../.agent-src.uncondensed/rules/user-interaction.md`](../../.agent-src.uncondensed/rules/user-interaction.md)
 - [`../../.agent-src.uncondensed/rules/scope-control.md`](../../.agent-src.uncondensed/rules/scope-control.md)