@event4u/agent-config 2.24.0 → 2.25.0

package/CHANGELOG.md

@@ -702,6 +702,49 @@ our recommendation order, not its support status.
 > that forces a new era split (`# Era: 2.21.x`, etc.) — see
 > [`docs/contracts/CHANGELOG-conventions.md § Era splits`](docs/contracts/CHANGELOG-conventions.md).
 
+## [2.25.0](https://github.com/event4u-app/agent-config/compare/2.24.0...2.25.0) (2026-05-18)
+
+### Features
+
+* **rules:** add post-push-rewrite-discipline tier-2a guard ([1af51e1](https://github.com/event4u-app/agent-config/commit/1af51e1809de3522bd344453cc7e6206032f5d4a))
+* enforce roadmap CI-steps policy as Hard Gate ([a2ec868](https://github.com/event4u-app/agent-config/commit/a2ec868e81a9d9a4644d04704ff964b67754b2b2))
+* **provider-lifecycle:** tier adapters and enforce safety gates ([e9771e6](https://github.com/event4u-app/agent-config/commit/e9771e672e07804ff80b4f182c7b095acec6995d))
+* **policy:** add media governance policy layer ([4adc2ac](https://github.com/event4u-app/agent-config/commit/4adc2ac19fa31a6b0393ba4f662d91e85e6c63d0))
+
+### Bug Fixes
+
+* **ci:** extend portability skip-list with roadmap-ci-steps-policy files ([c68893d](https://github.com/event4u-app/agent-config/commit/c68893dfcb6189a951deb0ebab9802683e705d7a))
+* **ci:** repair archived-roadmap refs + bump smoke warn baseline ([11e181b](https://github.com/event4u-app/agent-config/commit/11e181b78a8303fc54cc4aa79138753b1c0c4148))
+
+### Performance
+
+* **roadmap:** batchable dashboard regen + parallel step reads in autonomous runs ([c1aa3a5](https://github.com/event4u-app/agent-config/commit/c1aa3a51cf1d99e71151f1d7116ab970d36cd85b))
+* **create-pr:** mandate single github-api call and parallel context fetch ([cbade08](https://github.com/event4u-app/agent-config/commit/cbade08df40b0d501791eeb6847e6452b2971d1d))
+
+### Documentation
+
+* **skills:** expand git-workflow with safe-squash and divergent-state recovery ([745859f](https://github.com/event4u-app/agent-config/commit/745859f100c1ffd6d607de81f701dacefb1feff0))
+* **roadmap:** add framework-neutrality-audit roadmap + scan evidence ([6daf8b8](https://github.com/event4u-app/agent-config/commit/6daf8b8a0a16880f02a7afb1fb07cf7526be3c28))
+* **adr:** record ADR-011 domain-pack readiness (Phase 6) ([830cefa](https://github.com/event4u-app/agent-config/commit/830cefafdbec8474d1f6f71421457d1761f746ab))
+* **roadmap:** file Phase 5 advisory issues #178-#180 and sync dashboard ([3859d08](https://github.com/event4u-app/agent-config/commit/3859d085ebf7cf9bc091ae55d3e8ad1e15893dcb))
+* **roadmap:** add universal-platform-refinement roadmap ([0912bb5](https://github.com/event4u-app/agent-config/commit/0912bb505dac59ac5d4cc5e25b42b2f1d6efa694))
+
+### Tests
+
+* **ai-video:** add blueprint, prompt-optimizer, adapter-contract suites (Phase 4) ([7762df7](https://github.com/event4u-app/agent-config/commit/7762df720412049f6d3b12bd328cd7c9a78b215b))
+
+### Chores
+
+* add claude rules ([744328d](https://github.com/event4u-app/agent-config/commit/744328d57b4ba3c502ab3b41ded10e25ba3db8cf))
+* compress 4 .md files into .agent-src/ ([96ef2f9](https://github.com/event4u-app/agent-config/commit/96ef2f94504661f71b86a3fb16762069c39caaa7))
+* regenerate compiled trees for new rule (82 to 83) ([8b8af6a](https://github.com/event4u-app/agent-config/commit/8b8af6a4a918e927dbaafaeadc4402e3a7220981))
+
+### Other
+
+* Clarify skills, rules, and commands description ([b586a0c](https://github.com/event4u-app/agent-config/commit/b586a0c6895da701a2719aeb4758f14cbe3fc2db))
+
+Tests: 4664 (+95 since 2.24.0)
+
 ## [2.24.0](https://github.com/event4u-app/agent-config/compare/2.23.0...2.24.0) (2026-05-17)
 
 ### Features

package/README.md

@@ -2,11 +2,13 @@
 
 # Agent Config — Universal AI Agent OS
 
-[![Skills](https://img.shields.io/badge/Skills-216-1f6feb?style=flat-square)](.augment/skills/) [![Rules](https://img.shields.io/badge/Rules-79-d73a49?style=flat-square)](.augment/rules/) [![Commands](https://img.shields.io/badge/Commands-129-2da44e?style=flat-square)](.augment/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-73-8957e5?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-25-bf8700?style=flat-square)](docs/personas.md) [![Advisors](https://img.shields.io/badge/Advisors-5-fb8500?style=flat-square)](docs/profiles.md) [![AI Tools](https://img.shields.io/badge/AI%20Tools-8-1abc9c?style=flat-square)](docs/architecture.md) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
+[![Skills](https://img.shields.io/badge/Skills-216-1f6feb?style=flat-square)](.augment/skills/) [![Rules](https://img.shields.io/badge/Rules-84-d73a49?style=flat-square)](.augment/rules/) [![Commands](https://img.shields.io/badge/Commands-129-2da44e?style=flat-square)](.augment/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-73-8957e5?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-24-bf8700?style=flat-square)](docs/personas.md) [![Advisors](https://img.shields.io/badge/Advisors-5-fb8500?style=flat-square)](docs/profiles.md) [![AI Tools](https://img.shields.io/badge/AI%20Tools-8-1abc9c?style=flat-square)](docs/architecture.md) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
 
 > **A deterministic orchestration contract for AI agents — audited skills, governance rules, replayable state — usable by developers, founders, and creators alike.**
 
-Give your AI agents an audit-disciplined execution layer: **210 skills**, **79 governance rules**, **129 commands**, and a replayable state machine that turns any host agent (Claude Code, Augment, Cursor, Copilot, Windsurf) into a reliable team member.
+Give your AI agents an audit-disciplined execution layer: multiple **skills**, **governance rules**, **commands**, and a replayable state machine that turns any host agent (Claude Code, Augment, Cursor, Copilot, Windsurf) into a reliable team member.
+
+> **Cinematic AI video** — script → character-locked image → motion+audio prompt → provider render → stitched clip, with `AIV_DRYRUN=true` as the cost-safety default. See [`/video:from-script`](.augment/commands/video/from-script.md).
 
 ### Pick your profile — six entry paths
 
@@ -17,7 +19,7 @@ entries, no role-detection guesswork.
 | Profile (`profile.id`) | Audience | First commands | First skills |
 |---|---|---|---|
 | 👩‍💻 [`developer`](docs/profiles.md#profile-developer) | IC engineer | `/implement-ticket` · `/work` · `/review-changes` · `/fix` · `/commit` | `developer-like-execution` · `verify-completion-evidence` · `minimal-safe-diff` · `systematic-debugging` · `test-driven-development` |
-| ✍️ [`content_creator`](docs/profiles.md#profile-content_creator) | Writers, ghostwriters, marketers | `/work` · `/post-as` · `/ghostwriter` · `/optimize-prompt` | `voice-and-tone-design` · `messaging-architecture` · `editorial-calendar` · `release-comms` · `prompt-engineering-patterns` |
+| ✍️ [`content_creator`](docs/profiles.md#profile-content_creator) | Writers, ghostwriters, marketers | `/work` · `/post-as` · `/ghostwriter` · `/optimize-prompt` · `/video:from-script` · `/video:storyboard` | `voice-and-tone-design` · `messaging-architecture` · `editorial-calendar` · `release-comms` · `character-consistency` |
 | 🚀 [`founder`](docs/profiles.md#profile-founder) | Solo / early-stage founder | `/work` · `/feature` · `/challenge-me` · `/council` | `refine-prompt` · `rice-prioritization` · `vision-articulation` · `fundraising-narrative` · `runway-cognition` |
 | 🏛 [`agency`](docs/profiles.md#profile-agency) | Multi-client delivery shop | `/work` · `/implement-ticket` · `/refine-ticket` · `/feature` · `/roadmap` | `doc-coauthoring` · `decision-record` · `refine-ticket` · `estimate-ticket` · `perf-feedback-craft` |
 | 💼 [`finance`](docs/profiles.md#profile-finance) | CFO / fractional finance / FP&A | `/work` · `/council` · `/challenge-me` | `dcf-modeling` · `forecasting` · `scenario-modeling` · `unit-economics-modeling` · `runway-cognition` |

package/config/agent-settings.template.yml

@@ -209,6 +209,32 @@ roadmap:
   # is mandatory before any "roadmap complete" claim regardless of cadence.
   quality_cadence: end_of_roadmap
 
+  # Dashboard regen cadence inside autonomous runs (process-step /
+  # process-phase / process-full). Controls how often
+  # `./agent-config roadmap:progress` runs **between** steps in a
+  # single session. The dashboard is always regenerated at the start
+  # of the run, at every phase boundary, and at run end — this knob
+  # only affects the inter-step beat.
+  #
+  #   per_step         = legacy default: regen after every checkbox flip.
+  #                      Safest for crash recovery; highest subprocess
+  #                      overhead. Use when a session may be killed
+  #                      mid-roadmap and a fresh dashboard must always
+  #                      reflect the last-saved step.
+  #   every_5_steps    = batch flips, regen every 5 closed steps + at
+  #                      every phase boundary. Balanced cost/freshness
+  #                      for runs of 20–100 steps.
+  #   phase_boundary   = regen only at phase boundaries + run end.
+  #                      Cheapest for long roadmaps (100+ steps).
+  #                      The checkbox flip itself is still inline per
+  #                      Iron Law 2 — only the subprocess regen batches.
+  #
+  # `process-step` ignores this knob (single-step runs always regen
+  # at the end of the step). The Iron Law 1 mandate to regen on any
+  # file-shape touch (rename / phase add / archive) still fires
+  # immediately regardless of this setting.
+  dashboard_regen_cadence: per_step
+
   # Visible-horizon framing in roadmap authoring (integer weeks, default 0).
   # 0  = off (default). Time-boxed plate / horizon framing is forbidden:
   #      no `## Horizon (N-week visible plate)` sections, no

package/docs/architecture.md

@@ -142,7 +142,7 @@ note, package-internal path-swap, description budget, and the
 | Layer | Count | Purpose |
 |---|---|---|
 | **Skills** | 216 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
-| **Rules** | 79 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
+| **Rules** | 84 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
 | **Commands** | 129 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
 | **Guidelines** | 73 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
 | **Templates** | 7 | Scaffolds for features, roadmaps, contexts, skills, overrides |

package/docs/catalog.md

@@ -1,6 +1,6 @@
 # agent-config — Public Catalog
 
-Consumer-facing catalog of all **494 public artefacts** shipped by
+Consumer-facing catalog of all **497 public artefacts** shipped by
 this package. Internal package-maintenance rules and deprecation shims
 are excluded.
 
@@ -228,7 +228,7 @@ are excluded.
 | skill | [`voice-and-tone-design`](../.agent-src/skills/voice-and-tone-design/SKILL.md) |  | Use when shaping brand voice — voice attributes, tone-by-context matrix, consistency review. Triggers on 'define our voice', 'why does our copy sound different on every surface'. |
 | skill | [`websocket`](../.agent-src/skills/websocket/SKILL.md) |  | Use when building real-time features — WebSocket broadcasting, live updates, presence channels, connection state — even when the user just says 'push this to the client live'. |
 
-## Rules (76)
+## Rules (79)
 
 | kind | name | type | description |
 |---|---|---|---|
@@ -276,6 +276,7 @@ are excluded.
 | rule | [`laravel-translations`](../.agent-src/rules/laravel-translations.md) | auto | Laravel language files, translations, i18n, lang/de, lang/en, __() helper, localization, multilingual text |
 | rule | [`low-impact-corpus-privacy-floor`](../.agent-src/rules/low-impact-corpus-privacy-floor.md) | auto | Writing, editing, or upstreaming entries in `agents/low-impact-decisions.md` — non-bypassable privacy floor for the learning corpus. |
 | rule | [`markdown-safe-codeblocks`](../.agent-src/rules/markdown-safe-codeblocks.md) | auto | Generating markdown output that contains code blocks — prevent broken nesting |
+| rule | [`media-governance-routing`](../.agent-src/rules/media-governance-routing.md) | auto | When generating AI video/image/voice — surface project-local media policies (likeness, style, public-figures, voice-cloning, disclosure) |
 | rule | [`minimal-safe-diff`](../.agent-src/rules/minimal-safe-diff.md) | auto | When writing or reviewing a diff — the smallest change that solves the stated problem; no drive-by edits, opportunistic refactors, or reformatting |
 | rule | [`missing-tool-handling`](../.agent-src/rules/missing-tool-handling.md) | auto | When a CLI tool needed for the task is not installed — ask before working around it; do NOT install silently |
 | rule | [`model-recommendation`](../.agent-src/rules/model-recommendation.md) | auto | Starting a new task, switching task type, or invoking a command — detect complexity and recommend optimal model (Opus/Sonnet/GPT) before work |
@@ -286,8 +287,10 @@ are excluded.
 | rule | [`non-destructive-by-default`](../.agent-src/rules/non-destructive-by-default.md) | always | Agent is never destructive — Hard Floor always asks for prod-trunk merges, deploys, pushes, prod data/infra, bulk deletions, and bulk-deletion/infra commits; no autonomy or roadmap bypass |
 | rule | [`onboarding-gate`](../.agent-src/rules/onboarding-gate.md) | auto | First turn of a conversation on a project — check onboarding.onboarded in .agent-settings.yml; when false, prompt to run /onboard before any request |
 | rule | [`package-ci-checks`](../.agent-src/rules/package-ci-checks.md) | manual | Before pushing to remote or creating a PR in the agent-config package — run all CI checks locally first |
+| rule | [`persona-governance`](../.agent-src/rules/persona-governance.md) | auto | When creating, editing, or proposing personas — enforce per-domain cap (≤ 2 specialists), ≥ 1 skill citation, and the deprecation path |
 | rule | [`php-coding`](../.agent-src/rules/php-coding.md) | auto | Writing or reviewing PHP code — strict types, naming, comparisons, early returns, Eloquent conventions |
 | rule | [`preservation-guard`](../.agent-src/rules/preservation-guard.md) | auto | When merging, refactoring, compressing, or restructuring skills, rules, commands, or guidelines — prevent quality loss |
+| rule | [`provider-lifecycle-discipline`](../.agent-src/rules/provider-lifecycle-discipline.md) | auto | When editing an AI video/image/audio adapter — declare lifecycle tier (experimental \| stable \| deprecated \| community); never default to non-stable |
 | rule | [`reviewer-awareness`](../.agent-src/rules/reviewer-awareness.md) | auto | When suggesting reviewers or flagging risk hotspots — anchor in paths/risk + ownership-map + bug-patterns; medium/high needs primary + secondary |
 | rule | [`roadmap-progress-sync`](../.agent-src/rules/roadmap-progress-sync.md) | auto | Any roadmap touch (file move, checkbox flip, phase change) regens dashboard same response; archive at 0 open. Autonomous runs flip checkboxes inline |
 | rule | [`role-mode-adherence`](../.agent-src/rules/role-mode-adherence.md) | auto | When roles.active_role is set in .agent-settings.yml — closing outputs must match the mode's contract and emit the structured mode marker |

package/docs/contracts/file-ownership-matrix.json

@@ -1095,12 +1095,6 @@
       "load_context": [],
       "load_context_eager": []
     },
-    ".agent-src.uncompressed/personas/pixar-storyboard-artist.md": {
-      "kind": "persona",
-      "rule_type": null,
-      "load_context": [],
-      "load_context_eager": []
-    },
     ".agent-src.uncompressed/personas/product-owner.md": {
       "kind": "persona",
       "rule_type": null,
@@ -1451,6 +1445,12 @@
       "load_context": [],
       "load_context_eager": []
     },
+    ".agent-src.uncompressed/rules/media-governance-routing.md": {
+      "kind": "rule",
+      "rule_type": "auto",
+      "load_context": [],
+      "load_context_eager": []
+    },
     ".agent-src.uncompressed/rules/minimal-safe-diff.md": {
       "kind": "rule",
       "rule_type": "auto",
@@ -1513,6 +1513,12 @@
       "load_context": [],
       "load_context_eager": []
     },
+    ".agent-src.uncompressed/rules/persona-governance.md": {
+      "kind": "rule",
+      "rule_type": "auto",
+      "load_context": [],
+      "load_context_eager": []
+    },
     ".agent-src.uncompressed/rules/php-coding.md": {
       "kind": "rule",
       "rule_type": "auto",
@@ -1525,6 +1531,12 @@
       "load_context": [],
       "load_context_eager": []
     },
+    ".agent-src.uncompressed/rules/provider-lifecycle-discipline.md": {
+      "kind": "rule",
+      "rule_type": "auto",
+      "load_context": [],
+      "load_context_eager": []
+    },
     ".agent-src.uncompressed/rules/reviewer-awareness.md": {
       "kind": "rule",
       "rule_type": "auto",
@@ -6116,6 +6128,13 @@
       "via": "body_link",
       "depth": 1
     },
+    {
+      "source": ".agent-src.uncompressed/personas/README.md",
+      "target": ".agent-src.uncompressed/rules/persona-governance.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
     {
       "source": ".agent-src.uncompressed/personas/_template-specialist/persona.md",
       "target": ".agent-src.uncompressed/personas/_template-specialist/persona.md",
@@ -6263,13 +6282,6 @@
       "via": "self",
       "depth": 0
     },
-    {
-      "source": ".agent-src.uncompressed/personas/pixar-storyboard-artist.md",
-      "target": ".agent-src.uncompressed/personas/pixar-storyboard-artist.md",
-      "type": "WRITE",
-      "via": "self",
-      "depth": 0
-    },
     {
       "source": ".agent-src.uncompressed/personas/product-owner.md",
       "target": ".agent-src.uncompressed/personas/product-owner.md",
@@ -7117,6 +7129,13 @@
       "via": "self",
       "depth": 0
     },
+    {
+      "source": ".agent-src.uncompressed/rules/media-governance-routing.md",
+      "target": ".agent-src.uncompressed/rules/media-governance-routing.md",
+      "type": "WRITE",
+      "via": "self",
+      "depth": 0
+    },
     {
       "source": ".agent-src.uncompressed/rules/minimal-safe-diff.md",
       "target": ".agent-src.uncompressed/rules/minimal-safe-diff.md",
@@ -7327,6 +7346,27 @@
       "via": "self",
       "depth": 0
     },
+    {
+      "source": ".agent-src.uncompressed/rules/persona-governance.md",
+      "target": ".agent-src.uncompressed/rules/persona-governance.md",
+      "type": "WRITE",
+      "via": "self",
+      "depth": 0
+    },
+    {
+      "source": ".agent-src.uncompressed/rules/persona-governance.md",
+      "target": ".agent-src.uncompressed/rules/skill-quality.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/rules/persona-governance.md",
+      "target": ".agent-src.uncompressed/skills/pixar-storyteller/SKILL.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
     {
       "source": ".agent-src.uncompressed/rules/php-coding.md",
       "target": ".agent-src.uncompressed/rules/php-coding.md",
@@ -7341,6 +7381,27 @@
       "via": "self",
       "depth": 0
     },
+    {
+      "source": ".agent-src.uncompressed/rules/provider-lifecycle-discipline.md",
+      "target": ".agent-src.uncompressed/rules/ask-when-uncertain.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/rules/provider-lifecycle-discipline.md",
+      "target": ".agent-src.uncompressed/rules/media-governance-routing.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/rules/provider-lifecycle-discipline.md",
+      "target": ".agent-src.uncompressed/rules/provider-lifecycle-discipline.md",
+      "type": "WRITE",
+      "via": "self",
+      "depth": 0
+    },
     {
       "source": ".agent-src.uncompressed/rules/reviewer-awareness.md",
       "target": ".agent-src.uncompressed/rules/reviewer-awareness.md",
@@ -11338,6 +11399,13 @@
       "via": "body_link",
       "depth": 1
     },
+    {
+      "source": ".agent-src.uncompressed/skills/scene-expander/SKILL.md",
+      "target": ".agent-src.uncompressed/skills/pixar-storyteller/SKILL.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
     {
       "source": ".agent-src.uncompressed/skills/scene-expander/SKILL.md",
       "target": ".agent-src.uncompressed/skills/scene-expander/SKILL.md",

package/docs/contracts/provider-lifecycle.md

@@ -0,0 +1,122 @@
+---
+stability: beta
+keep-beta-until: 2026-08-15
+---
+
+# Provider Lifecycle — AI Video / Image / Audio Adapter Tiers
+
+> **Status:** active · **Stability:** beta · **Owner:** universal-platform-refinement Phase 3
+> · **Linter:** none (declarative contract; enforced agent-in-the-loop via [`provider-lifecycle-discipline`](../../.agent-src/rules/provider-lifecycle-discipline.md))
+> · **Source-of-truth template:** [`agents/.ai-video.xml.example`](../../agents/.ai-video.xml.example)
+
+Locks the lifecycle tagging used on every adapter under
+`scripts/ai-video/adapters/` (and future `scripts/ai-image/`,
+`scripts/ai-audio/` peers). The tag is declarative — it tells the
+agent what the maintainer's confidence in the adapter is, so the
+agent can refuse to *default* to an under-validated provider without
+the human noticing.
+
+## § 1 — Tiers
+
+| Tier | Meaning | Default-eligibility |
+|---|---|---|
+| `stable` | Maintainer-validated against a real API run at least once; dry-run output matches the documented contract; secret-redaction confirmed on a live response | **Yes** — `/video:*` / `/image:*` / `/audio:*` commands may default to a `stable` adapter |
+| `experimental` | Adapter shipped; structural shape matches the contract; **no real-API smoke run by a maintainer yet** | **No** — must be invoked explicitly (`--provider <id>`), never silently the default |
+| `deprecated` | Replaced by a successor; kept for one release window so consumer scripts can migrate | **No** — refusal-and-surface: the agent names the successor before running |
+| `community` | Contributed externally; maintained on a best-effort basis; behaviour outside the maintainer's smoke-test matrix | **No** — explicit opt-in only; the agent surfaces "community-tier provider" in the run summary |
+
+## § 2 — Promotion path
+
+`experimental → stable` requires three checkmarks on the same commit
+(or on a tightly-scoped follow-up commit referencing the original):
+
+1. **Real-API smoke run** — at least one live `submit / poll / fetch`
+   cycle (or `run` for sync adapters) against the documented
+   `default-model`, captured under
+   `agents/ai-video/smoke-traces/<provider>.md` with timestamp,
+   model id, and **redacted** response shape.
+2. **Secret-redaction confirmation** — the captured trace, re-read
+   through `scripts/ai-video/lib/redact.sh`, shows zero residual
+   key fragments.
+3. **Contract conformance** — the adapter's four-method shell
+   surface (`submit / poll / fetch / dry-run` *or* `run / dry-run`)
+   matches `scripts/ai-video/lib/adapter-contract.md` verbatim.
+
+A maintainer flipping the tier in `agents/.ai-video.xml.example`
+**and** the adapter header comment is the promotion event. There is
+no separate registry — the example file is the registry.
+
+## § 3 — Demotion criteria
+
+`stable → experimental` (or `stable → deprecated`) on any of:
+
+- **Provider API contract drift** that breaks the adapter against
+  the documented `default-model` for ≥ 7 calendar days without a
+  maintainer fix.
+- **Auth-flow change** that invalidates the redaction matchers in
+  `lib/redact.sh` until the matchers are extended.
+- **Successor adapter declared** (use `deprecated`, not
+  `experimental`, and record the successor in the header comment).
+
+Demotion is the maintainer's call; the rule does not auto-demote.
+
+## § 4 — Agent obligations
+
+When the agent picks a provider for a `/video:*` / `/image:*` /
+`/audio:*` run, it MUST:
+
+1. **Read** the `provider_lifecycle` tag from the adapter's header
+   comment **and** the matching `<provider id="…">` block in
+   `agents/.ai-video.xml.example` (or the operator's
+   `agents/.ai-video.xml`).
+2. **Refuse-and-surface** if the operator's resolved default is a
+   non-`stable` tier — name the tier and the path to this contract
+   document, then emit one clarifying question (per
+   [`ask-when-uncertain`](../../.augment/rules/ask-when-uncertain.md)):
+   either pick a `stable` provider, or confirm the non-stable run.
+3. **Record** in the run summary which tier the chosen adapter
+   carries — this is the audit log entry the agent-in-the-loop
+   model rests on.
+
+The agent never picks `deprecated` silently. If a successor is
+declared, the agent surfaces "X is deprecated; successor: Y" before
+running.
+
+## § 5 — Day-one assignment
+
+The five shipped adapters carry the following tiers on the day
+this contract lands (PR `universal-platform-refinement`):
+
+| Adapter | Kind | Tier | Rationale |
+|---|---|---|---|
+| `openai-images` | image | `experimental` | Structural shape conformant; no maintainer real-API smoke captured yet |
+| `gemini-veo` | video | `experimental` | Default video provider; no real-API smoke captured yet |
+| `kling` | video | `experimental` | Async contract conformant; no maintainer real-API smoke captured yet |
+| `higgsfield` | image+video | `experimental` | Capability-discovery path conformant; no real-API smoke captured yet |
+| `sora` | video | `experimental` | Structural-prompt path conformant; no real-API smoke captured yet |
+
+**All five start as `experimental` on day one.** The promotion to
+`stable` happens per-adapter, on the commit that records the first
+real-API smoke trace. This is conservative by construction: a
+`/video:*` run today resolves to a default that is `experimental`,
+so the agent surfaces the tier and asks before proceeding — the
+human is the policy decision point.
+
+The `<default-image-provider>` and `<default-video-provider>`
+entries in `agents/.ai-video.xml.example` remain unchanged
+(`openai-images` and `gemini-veo`). The tier tag does not change
+defaults; it changes whether the agent silently honours them.
+
+## § 6 — Versioning
+
+Tier rename or new tier is breaking (linter and adapter headers
+both flip); promotion / demotion of an individual adapter is not
+breaking. The Day-One Assignment table above is the per-release
+snapshot — older snapshots live in git history, not in this file.
+
+## See also
+
+- [`provider-lifecycle-discipline`](../../.agent-src/rules/provider-lifecycle-discipline.md) — the tier-2 routing rule that surfaces this contract when a provider is touched.
+- [`scripts/ai-video/lib/adapter-contract.md`](../../scripts/ai-video/lib/adapter-contract.md) — the four-method shell contract every adapter implements.
+- [`agents/.ai-video.xml.example`](../../agents/.ai-video.xml.example) — operator-facing provider configuration template (carries the tier tag inline).
+- [`agents/policies/media/README.md`](../../agents/policies/media/README.md) — the agent-in-the-loop enforcement model this contract participates in.