@event4u/agent-config 5.10.1 → 6.1.0

package/dist/agent-src/rules/no-roadmap-references.md

@@ -0,0 +1,141 @@
+---
+type: "auto"
+tier: "mechanical-already"
+description: "Linking transient files (agents/roadmaps/, agents/runtime/council/*/) from a stable artifact — both layers expire; promote findings"
+alwaysApply: false
+triggers:
+  - path_prefix: "agents/roadmaps/"
+  - path_prefix: "agents/runtime/council/questions/"
+  - path_prefix: "agents/runtime/council/responses/"
+  - path_prefix: "agents/runtime/council/sessions/"
+  - intent: "link from stable artifact"
+  - intent: "link to council artefact"
+routes_to:
+  - "skill:ai-council"
+validator_ignore:
+  - type: "substring"
+    pattern: ".agent-src.uncondensed/"
+    reason: "Rule contrasts the authoring tree with transient layers."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# No Transient References from Stable Artifacts
+
+Two transient layers under `agents/` outlive nothing: roadmaps in
+`agents/roadmaps/` are archived, skipped, or deleted as work
+completes; council artefacts in `agents/runtime/council/{questions,responses,
+sessions}/` are **gitignored, local-only, and auto-pruned** after
+`ai_council.session_retention_days` (default 7). Stable artifacts
+(rules, skills, commands, contexts, guidelines, AGENTS.md, README,
+copilot-instructions) outlive both. A stable artifact citing a
+specific transient file becomes a broken reference the moment that
+file is deleted or pruned.
+
+Council links rot three ways: gitignored (not in cloned repo),
+pruned after retention window (gone even locally), and the installed
+`.augment/` projection cannot follow a path that does not exist in
+the consumer.
+
+## The Iron Law
+
+```
+NEVER LINK TO A SPECIFIC FILE IN agents/roadmaps/
+OR IN agents/runtime/council/{questions,responses,sessions}/
+FROM A STABLE ARTIFACT.
+PROMOTE DURABLE CONCLUSIONS TO agents/settings/contexts/ AND CITE THAT INSTEAD.
+INLINE COUNCIL CONVERGENCE WITH DATE + MEMBERS, NEVER THE PATH.
+```
+
+Stable artifact = anything that is **not** a roadmap, council
+session, chat-history archive, commit message, or PR description.
+
+## Forbidden patterns
+
+These paths must not appear inside a stable artifact:
+
+- `agents/roadmaps/<file>.md`, `agents/roadmaps/archive/<file>.md`,
+  `agents/roadmaps/skipped/<file>.md`
+- `agents/runtime/council/questions/<file>.md`,
+  `agents/runtime/council/responses/<file>.json`,
+  `agents/runtime/council/sessions/<file>.json` or `<timestamp>/...`
+
+Stable artifact = any file under `.agent-src.uncondensed/{rules,
+skills,commands,contexts,templates,personas}/`, `agents/settings/contexts/`,
+`docs/guidelines/`, `docs/contracts/`, `docs/architecture.md`,
+`docs/customization.md`, `docs/getting-started.md`, `docs/catalog.md`,
+`AGENTS.md`, `README.md`, `copilot-instructions.md`.
+
+CI enforcement: `scripts/check_no_roadmap_refs.py` (roadmap layer)
+and `scripts/check_council_references.py` (council layer) — both
+fail the build on any new violation.
+
+## Allowed patterns
+
+- `agents/roadmaps/` and `agents/runtime/council/*/` as **directory** mentions
+  (talking about the layer, not a specific file)
+- Roadmap → roadmap references (siblings within the transient layer)
+- The `ai-council` skill and `/council:*` commands documenting the
+  output path schema
+- Inline council convergence summary — e.g. *"Council
+  (claude-sonnet-4-5 + gpt-4o, 2026-05-06) converged on …"* with
+  date + members, no filepath
+- Council sessions, `agents/runtime/.agent-chat-history`, commit messages, PR
+  descriptions — transient by construction, not part of the package
+  surface
+
+## Structural carve-outs (immutable inputs / decision provenance)
+
+Two source/target shapes are exempt from the council-link ban
+because the target is **immutable input** or **decision provenance**,
+not transient drafting state. The linter implements these directly
+(`STRUCTURAL_CARVEOUTS` in `scripts/check_council_references.py`);
+they do **not** need an inline `<!-- council-ref-allowed: ... -->`
+pragma.
+
+| Source                                         | Target                                           | Why                                                                                  |
+| ---------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------ |
+| `agents/settings/contexts/evaluation-*.md`              | `agents/runtime/council/questions/*.md`                  | Question file is a frozen function-parameter / spend-gate input, not documentation. |
+| `docs/contracts/*.md`                          | `agents/runtime/council/sessions/*/synthesis.md`         | Synthesis is the audit-trail receipt; contract inlines the decision body itself.    |
+
+Driven by the 2026-05-14 P3.4 council round (claude-sonnet-4-5 +
+gpt-4o, converged on rule refactor over escape-hatch overuse). Any
+other source/target combination still needs an inline pragma or
+inline-summary rewrite.
+
+## What to do instead
+
+When a stable artifact needs to cite a transient finding:
+
+1. Identify the durable conclusion — decision, contract, lesson,
+   mechanic.
+2. Promote it to a context file under `agents/settings/contexts/` (ADR,
+   mechanics doc, locked decision). The roadmap or council session
+   can then point at the context, not the other way around.
+3. Reference the context from the stable artifact.
+4. For council convergences specifically: inline a convergence-summary
+   block (members, date, cost if relevant — see `ai-council`
+   § Output format) instead of linking the session JSON.
+
+Failure modes:
+
+- *"I'll just link to the roadmap, it's evidence."* The roadmap
+  gets archived, then deleted, then the link rots. **Promote first,
+  link second.**
+- *"I'll just link to the session JSON, it's evidence."* The session
+  is gone in 7 days. **Inline first, link never.**
+
+## See also
+
+- [`augment-edit-discipline`](augment-edit-discipline.md) — portability
+  + cross-reference sync after rename / delete
+- [`skill:agent-docs-writing`](../skills/agent-docs-writing/SKILL.md) —
+  roadmap layer conventions
+- [`roadmap-progress-sync`](roadmap-progress-sync.md) — sync dashboard
+  on roadmap touch
+- [`source-of-truth`](source-of-truth.md) — edit
+  `.agent-src.uncondensed/`
+- [`ai-council`](../skills/ai-council/SKILL.md) — output path
+  convention and convergence-summary format

package/dist/agent-src/rules/non-destructive-by-default.md

@@ -0,0 +1,58 @@
+---
+type: "always"
+tier: "safety-floor"
+description: "Hard Floor: agent asks before prod-trunk commits/merges, deploys, pushes, prod data/infra, bulk deletions/infra commits; verify branch before each commit; no autonomy or roadmap bypass"
+alwaysApply: true
+load_context:
+  - ../contexts/authority/destructive-mechanics.md
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# Non-Destructive by Default
+
+Universal safety floor — every mode, every conversation, every turn. Autonomy, "just keep going", roadmap authorizations, standing permissions narrow other rules — **none lift this one**.
+
+## The Iron Law
+
+```
+HARD FLOOR OVERRIDES EVERYTHING.
+NO AUTONOMY SETTING, NO ROADMAP STEP, NO STANDING INSTRUCTION,
+NO "JUST KEEP GOING" CAN BYPASS IT.
+```
+
+Triggers below require explicit user confirmation **on this turn** — not from a previous turn, not from a roadmap, not from a standing autonomy directive (anchor list: [`autonomous-execution`](autonomous-execution.md)):
+
+| Trigger | Examples |
+|---|---|
+| **Production-branch merge** | `main`, `master`, `prod`, `production`, `release/*`, or any project-marked deployment trunk |
+| **Commit on a production branch** | any `git commit` while `HEAD` is on a prod trunk (set above). **Verify branch before every commit** — `main` is opt-in only, never inferred from a prior turn or a merged PR that left the repo on `main` |
+| **Deploy / release** | prod `terraform apply` / `kubectl apply`, deploy scripts, release commands, CI-deploying tag pushes |
+| **Push to remote** | any `git push` (also covered by [`scope-control`](scope-control.md), restated so the floor never weakens) |
+| **Production data / infra** | prod DB writes / migrations, prod config, secrets rotation, IAM / role / policy, DNS, anything in a `prod`-scoped path or pipeline |
+| **Whimsical / unscoped bulk deletion** | `rm -rf <dir>`, `git rm -r`, glob deletions, `DROP TABLE`, `TRUNCATE`, `git reset --hard` past unpushed work — when **not required** by the current task. Task-aligned WIP deletions are allowed (below) |
+| **Commit containing bulk deletions or infra changes** | diff removes a directory, deletes ≥5 unrelated files, or touches Terraform / Pulumi / k8s / Ansible / cloud-config — surface the diff and confirm even when [`commit-policy`](commit-policy.md) authorizes |
+
+Standing "just keep going" + next step crosses the floor → STOP, surface what's about to happen (one numbered-options block per [`user-interaction`](user-interaction.md)), wait. Other rules still apply to every other step.
+
+## Not in scope — deterministic regeneration
+
+Output regenerated from a tracked source (condensation, code-gen, formatter passes, lock-file rebuilds) is reversible from source — **not destructive**. Lives in [`autonomous-execution`](autonomous-execution.md). Per-file diff approval is theater.
+
+## Bulk deletions during WIP — allowed if task-connected
+
+Deletions inside an **active, user-stated task** are allowed in the working tree, even multiple files / folders — the Hard Floor moves to the **commit** (row 6), not the in-progress edit. Whimsical / drive-by / unnamed-scope deletions still trip the floor on the edit. Allowed / forbidden lists: [`destructive-mechanics`](../contexts/authority/destructive-mechanics.md).
+
+## Failure modes
+
+Full catalog (autonomy-as-cover, roadmap-as-authorization, refusing-named-deletions, commit-without-diff-surface, roadmap-step ≠ commit-authorization): [`destructive-mechanics`](../contexts/authority/destructive-mechanics.md).
+
+## Cloud Behavior
+
+Floor applies on every surface — Claude.ai Web, Skills API, any cloud agent. No "cloud override".
+
+## See also
+
+[`autonomous-execution`](autonomous-execution.md) · [`commit-policy`](commit-policy.md) · [`scope-control`](scope-control.md) · [`user-interaction`](user-interaction.md).

package/dist/agent-src/rules/notes-first-reasoning.md

@@ -0,0 +1,71 @@
+---
+type: "auto"
+tier: "2b"
+description: "Reasoning-heavy work (debugging, multi-hypothesis, weighing alternatives) — keep hypotheses/predictions/decisions in session notes, response carries conclusions + evidence only"
+triggers:
+  - keyword: "debug"
+  - keyword: "investigate"
+  - keyword: "hypothesis"
+  - keyword: "root cause"
+  - phrase: "figure out why"
+  - phrase: "should we use"
+load_context:
+  - ../contexts/execution/rdp-gate.md
+routes_to:
+  - "skill:memory-consolidation"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# Notes-First Reasoning
+
+Part of the Reasoning Discipline Protocol. Engage per
+[`rdp-gate`](../contexts/execution/rdp-gate.md) (settings + task-signal + host
+self-assessment) — skip on trivial tasks; apply lightly on a strong-reasoning
+host. The notes file is grounded in the documented cross-run lessons memory
+(consolidated via [`memory-consolidation`](../skills/memory-consolidation/SKILL.md));
+the in-task sections below are a local derivation for within-task scope.
+
+## The Iron Law
+
+```
+MULTI-HYPOTHESIS REASONING, PREDICTIONS, AND DECISIONS LIVE IN THE SESSION
+NOTES FILE — NEVER ECHOED INTO THE RESPONSE.
+THE RESPONSE CARRIES CONCLUSIONS + EVIDENCE ONLY.
+```
+
+Reasoning dumped into the user-facing answer is both noise and a
+`reasoning_extraction` refusal risk (see `rdp-gate`). Keep it in the notes file.
+This is not "show your work in the reply" — it is the opposite.
+
+## Notes file structure (the file, not the response)
+
+Use the sections that apply; the structure carries the enumeration, so there is
+no "write N hypotheses" instruction — record what the work actually surfaced.
+
+- `## In-Task Hypothesis Log` — competing explanations under consideration.
+- `## Killed beliefs` — each discarded hypothesis + the evidence that killed it.
+- `## Predictions` — prediction · confidence · result · lesson (the calibration
+  loop: hypothesis → prediction → reality → calibration).
+- `## Decisions` — decision · alternatives · reason · revisit-if. Tactical,
+  in-task decisions stay here; **escalate to
+  [`decision-record`](../skills/decision-record/SKILL.md)/ADR** when the decision
+  is cross-task or architectural (litmus: would a dev on a different component
+  next month need this context?).
+- `## Uncertainty` — per-dimension score (e.g. architecture/implementation/
+  requirements: high/medium/low); feeds the adaptive-effort decision.
+
+## What stays out of notes
+
+User-attribute facts, transient TODOs, and durable cross-run lessons — those go
+to the memory system (`memory-consolidation`), not the in-task notes.
+
+## See also
+
+- [`rdp-gate`](../contexts/execution/rdp-gate.md) — the table-free engagement gate.
+- [`memory-consolidation`](../skills/memory-consolidation/SKILL.md) — promotes
+  durable lessons across runs.
+- [`verify-before-complete`](verify-before-complete.md) — the evidence the
+  response carries comes from real tool results.

package/dist/agent-src/rules/persona-governance.md

@@ -0,0 +1,93 @@
+---
+type: "auto"
+tier: "2a"
+description: "Creating/editing/proposing personas — enforce per-domain cap (≤ 2 specialists), ≥ 1 skill citation, deprecation path"
+triggers:
+  - path_prefix: ".agent-src.uncondensed/personas/"
+  - path_prefix: "dist/agent-src/personas/"
+  - keyword: "persona"
+  - keyword: "personas"
+  - phrase: "new persona"
+  - phrase: "add a persona"
+  - phrase: "specialist persona"
+  - phrase: "review lens"
+routes_to:
+  - "contract:persona-schema"
+applies_to_user_types:
+  - "maintainer"
+  - "developer"
+validator_ignore:
+  - type: "substring"
+    pattern: "../../docs/"
+    reason: "Rule routes to docs/contracts/persona-schema.md and docs/personas.md — the canonical persona catalog and schema live there by design."
+  - type: "substring"
+    pattern: ".agent-src.uncondensed/"
+    reason: "Rule documents the persona authoring tree (.agent-src.uncondensed/personas/) as the deprecation-path operand."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# Persona Governance
+
+## Iron Law
+
+```
+ONE PERSONA, ONE OWNER, ONE SKILL CITATION, ONE DOMAIN SLOT.
+NO NEW SPECIALIST WITHOUT A DEPRECATION CANDIDATE WHEN THE DOMAIN IS FULL.
+```
+
+Personas are review lenses, not free real estate. Every specialist persona has a maintenance cost: it must stay aligned with the schema, the cited skills must still want it, and the per-domain reasoning surface must not bloat to the point that no single persona is load-bearing. This rule routes the agent to [`docs/contracts/persona-schema.md`](../docs/contracts/persona-schema.md) and [`docs/personas.md`](../../docs/personas.md) and enforces the four discipline checks below.
+
+## The four checks
+
+### 1. Per-domain cap — ≤ 2 specialised personas per content domain
+
+A **content domain** is a self-contained creative or technical surface that one or two specialist personas can fully cover. Current domains:
+
+| Domain | Specialists allowed | Examples |
+|---|---|---|
+| ai-video / ai-image / ai-audio | ≤ 2 | one director-shaped lens + one technical-tuning lens |
+| backend engineering | ≤ 2 | architect + ORM-tamer |
+| frontend engineering | ≤ 2 | component / lifecycle + design / a11y |
+| security | ≤ 2 | abuse-case + secrets-and-trust |
+| gtm / growth | ≤ 2 | CMO + RevOps |
+| money / strategy | ≤ 2 | finance-partner + strategist |
+| people / org | ≤ 2 | engineering-manager + people-strategist |
+| customer / discovery | ≤ 2 | discovery-lead + customer-success-lead |
+
+**Core personas** (`developer`, `senior-engineer`, `product-owner`, `stakeholder`, `critical-challenger`, `ai-agent`) are exempt — they are always-loaded cross-cutting lenses, not domain specialists.
+
+A new specialist into a full domain MUST come with a deprecation candidate from the same domain. The agent surfaces both, then runs an ai-council debate (per [`ai-council`](../skills/ai-council/SKILL.md)) before any rename / merge / delete.
+
+### 2. Skill citation floor — ≥ 1 cite before merge
+
+A specialist persona without a `personas: [<id>]` citation in at least one skill's frontmatter is dead weight. The PR adding the persona MUST also add the citation, OR the PR is rejected. Citation map lives in [`docs/personas.md § Skill citations`](../../docs/personas.md#skill-citations).
+
+### 3. Deprecation path — delete immediately, record in commit
+
+A persona being removed is **deleted in the same commit** that lands its replacement. The commit message names the successor (or "merged into X") and cites the council decision (or maintainer rationale) that authorised it. No soak window — internal personas have no external consumers; a persona file kept around as a tombstone is dead weight the linter still loads. No silent deletes either: the audit trail is the commit, not a docs table.
+
+### 4. Schema conformance — the skill linter is the gate
+
+Every persona file is linted against [`docs/contracts/persona-schema.md`](../docs/contracts/persona-schema.md) by the skill linter: frontmatter shape, tier enum, wing enum, required sections per tier, line budget per tier (with wing override), `Unique Questions` ≥ 3, filename / id match, description ≤ 160 chars. The agent runs `python3 scripts/skill_linter.py` before any persona PR is marked ready.
+
+## Failure modes — what counts as a violation
+
+- Adding a third specialist to a full domain without naming the deprecation candidate.
+- Landing a specialist with no `personas: [<id>]` cite in any skill.
+- Renaming or deleting a persona file without naming the successor (or sunset reason) in the commit message.
+- Editing core-tier personas in-place with breaking changes (rename, section removal) without bumping to a new id.
+- Skipping the skill linter (`python3 scripts/skill_linter.py`) on a persona PR.
+
+## Day-one state
+
+Resolved 2026-05-17 via two-round ai-council debate (members: anthropic/claude-sonnet-4-5, openai/gpt-4o — converged delete-and-fold): `pixar-storyboard-artist` deleted; acting / beat-decomposition lens folded into [`pixar-storyteller`](../skills/pixar-storyteller/SKILL.md) skill body. Active per-domain count for `ai-video` now 2 (`ai-video-technical-director`, `hollywood-director`), within cap. Total active personas in root cluster: 24 (plus 5 advisors in `personas/advisors/`). Full inventory + ownership in [`docs/personas.md`](../../docs/personas.md).
+
+## See also
+
+- [`docs/contracts/persona-schema.md`](../docs/contracts/persona-schema.md) — schema lock, tiers, sections, size budgets, linter enforcement surface.
+- [`docs/personas.md`](../../docs/personas.md) — active persona catalog, citation map, ownership column.
+- [`ai-council`](../skills/ai-council/SKILL.md) — neutral second-opinion mechanism used for merge / deprecation decisions.
+- [`skill-quality`](skill-quality.md) — sibling discipline rule for skill files.

package/dist/agent-src/rules/preservation-guard.md

@@ -0,0 +1,97 @@
+---
+type: "auto"
+tier: "2b"
+alwaysApply: false
+description: "Merging/refactoring/condensing skills, rules, commands, or guidelines — prevent quality loss"
+triggers:
+  - intent: "merge skill"
+  - intent: "condense rule"
+  - intent: "refactor artifact"
+  - keyword: "Iron Law"
+validator_ignore:
+  - type: "substring"
+    pattern: ".agent-src.uncondensed/"
+    reason: "Rule references the authoring tree as the operand of condensation/preservation."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# Preservation Guard
+
+When transforming any agent artifact (merge, refactor, condense, split, restructure),
+the result must be **at least as strong** as the original.
+
+## Iron Laws — every passage stays, telegraph is fine
+
+Sections marked **Iron Law** (any heading matching `# Iron Law`, `# Iron Laws`,
+`# The Iron Law`, at any heading level, including numbered variants like
+`Iron Law 1`, `Iron Law 2`) are **non-negotiable** and require the strictest
+preservation:
+
+- [ ] **Heading preserved verbatim** — exact text and exact heading level. Drop the
+  heading → the law is gone, even if the code block underneath survives.
+- [ ] **Fenced code blocks preserved byte-for-byte** — the law itself.
+- [ ] **Negation clauses preserved** — `NO X`, `NEVER Y`, `NOT Z` stay in. These
+  are the load-bearing exception denials, not filler.
+- [ ] **Every passage stays** — every paragraph, every list item, and every
+  fenced code block from the source survives in the condensed output, in
+  order. One paragraph → one paragraph; one bullet → one bullet. Dropping
+  whole sentences, merging two paragraphs into one, or skipping a list item
+  is forbidden, even if the surviving prose still "makes the point".
+- [ ] **No Iron Law downgrades** — `## Iron Law` MUST NOT become `### Iron Law`,
+  `**Iron Law:**`, or inline prose. Heading level is part of the prominence.
+
+**Telegraph style is encouraged for Iron Law bodies** — drop articles ("the",
+"a"), shorten phrasing, primitive grammar, terse cave-speak. Word count is
+not a budget; the structural unit count is. As long as every paragraph,
+bullet, and code block from the source is present, condense as hard as you
+want. What's forbidden is **deletion**: the rationale paragraph stays, the
+canonical-failure example stays, every "NEVER X" bullet stays.
+
+`scripts/check_condensation.py` enforces these mechanically — any violation is
+an `error`, not a warning.
+
+## Mandatory preservation checklist
+
+Before completing any transformation, verify:
+
+- [ ] **Iron Law sections** preserved per the rules above — heading, body, fenced blocks, rationale
+- [ ] **Strongest validation step** preserved — concrete verify/confirm actions survive
+- [ ] **Strongest example** preserved — the most illustrative code block or scenario stays
+- [ ] **Strongest anti-pattern** preserved — the most important "Do NOT" or failure mode stays
+- [ ] **Essential decision hints** preserved — if/when/unless logic that prevents mistakes
+- [ ] **Required sections** preserved — When to use, Procedure, Output, Gotchas, Do NOT
+- [ ] **Single clear responsibility** preserved — no scope creep from merging unrelated concerns
+- [ ] **Strong language** preserved — "MUST", "NEVER", "Do NOT" not weakened to "should", "avoid"
+
+## Reject criteria
+
+**REJECT** the transformation if it:
+
+- Removes or downgrades an Iron Law heading
+- Drops a paragraph, list item, or fenced code block from an Iron Law section
+- Strips negation clauses or canonical-failure prose from an Iron Law
+- Removes a concrete validation step without equivalent replacement
+- Removes the strongest example without equivalent replacement
+- Removes the strongest anti-pattern without equivalent replacement
+- Weakens routing or decision logic
+- Broadens scope by merging unrelated workflows
+- Weakens strong enforcement language
+
+## Applies to
+
+- Skill merges (combining two skills into one)
+- Skill splits (extracting part of a skill)
+- Refactoring (restructuring without behavior change)
+- Condensation (`.agent-src.uncondensed/` → `dist/agent-src/`)
+- Rule consolidation
+- Guideline restructuring
+
+## References
+
+- Skill: `skill-management` — condensation/refactoring modes
+- Skill: `skill-reviewer` — condensation safety checks
+- Command: `/condense` — condensation quality checklist
+- Linter: `scripts/skill_linter.py` — `check_condensation_quality()`

package/dist/agent-src/rules/provider-lifecycle-discipline.md

@@ -0,0 +1,78 @@
+---
+type: "auto"
+tier: "2a"
+description: "Editing an AI video/image/audio adapter — declare lifecycle tier (experimental | stable | deprecated | community); never default to non-stable"
+triggers:
+  - keyword: "/video:"
+  - keyword: "/image:"
+  - keyword: "/audio:"
+  - keyword: "ai-video"
+  - keyword: "ai-image"
+  - keyword: "ai-audio"
+  - keyword: "adapter"
+  - keyword: "provider"
+  - path_prefix: "scripts/ai-video/adapters/"
+  - path_prefix: "agents/.ai-video.xml"
+  - phrase: "lifecycle"
+  - phrase: "default provider"
+routes_to:
+  - "contract:provider-lifecycle"
+applies_to_user_types:
+  - "creator"
+  - "developer"
+  - "maintainer"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# Provider Lifecycle Discipline
+
+## Iron Law
+
+```
+NEVER DEFAULT TO A NON-STABLE PROVIDER SILENTLY.
+SURFACE THE LIFECYCLE TIER. ASK BEFORE RUNNING.
+```
+
+This rule routes the agent to [`docs/contracts/provider-lifecycle.md`](../docs/contracts/provider-lifecycle.md) whenever a `/video:* / /image:* / /audio:*` surface fires, an adapter under `scripts/ai-video/adapters/` is read or edited, or `agents/templates/.ai-video.xml.example` (or the operator's `agents/.ai-video.xml`) is in play. The contract defines four tiers — `experimental | stable | deprecated | community` — and the agent's obligations per tier.
+
+## What this rule enforces
+
+1. **Read the tier before picking.** When the agent resolves a provider (from `--provider <id>`, from `<default-video-provider>` / `<default-image-provider>`, or from a skill's default), it MUST read both:
+   - the `<lifecycle>` element under `<provider id="…">` in `agents/templates/.ai-video.xml.example` (or the operator's `.ai-video.xml`), and
+   - the `Lifecycle:` header comment in `scripts/ai-video/adapters/<id>.sh`.
+   Mismatch between the two is a contract violation and MUST be surfaced before running.
+
+2. **Refuse-and-surface on non-stable.** If the resolved default is `experimental`, `deprecated`, or `community`, the agent surfaces the tier and the path to the contract, then emits **one** clarifying question (per [`ask-when-uncertain`](ask-when-uncertain.md)): either confirm the non-stable run, or pick a `stable` provider. No silent default. No "I'll just try it".
+
+3. **Refuse `deprecated` without naming the successor.** A `deprecated` adapter's header comment records the successor; the agent surfaces "X is deprecated; successor: Y" before any run, even with confirmation.
+
+4. **Record the tier in the run summary.** The summary line emitted after every `/video:* / /image:* / /audio:*` run names the chosen provider AND its tier. This is the audit-log entry the agent-in-the-loop enforcement model rests on.
+
+5. **Promotion is the maintainer's call.** The agent never auto-promotes `experimental → stable`. It MAY draft a promotion checklist (see [`docs/contracts/provider-lifecycle.md § 2`](../docs/contracts/provider-lifecycle.md#-2--promotion-path)) for maintainer review, but the tier-flip commit is human-authored.
+
+## Failure modes — what counts as a violation
+
+- Running `/video:scene` against the `<default-video-provider>` without reading the lifecycle tag first → violation.
+- Picking a `community` provider because it was named in the prompt, without surfacing the tier → violation.
+- Editing an adapter and leaving its header `Lifecycle:` comment out of sync with `agents/templates/.ai-video.xml.example` → violation (CI does not catch this; the agent must).
+- Auto-promoting an adapter from `experimental` to `stable` because "dry-run worked" → violation. Promotion requires a maintainer-captured real-API smoke trace under `agents/reference/ai-video/smoke-traces/`.
+
+## Day-one state
+
+All five shipped adapters (`openai-images`, `gemini-veo`, `kling`, `higgsfield`, `sora`) ship as `experimental`. This means **every** default `/video:* / /image:*` run today triggers the refuse-and-surface path. That is intentional — it is the conservative-by-construction posture the contract argues for. As maintainers capture smoke traces and flip individual adapters to `stable`, the friction reduces per-adapter.
+
+## Why agent-in-the-loop, not Python gate
+
+A Python pre-run gate enumerating tier-by-command rules would either be too coarse (`experimental → block`, breaking day-to-day dev iteration) or too detailed (per-command tier matrix, drifting from reality on every new provider). The agent reading the tag at run time, surfacing the tier, and asking is the correct enforcement surface: the model that picked the provider is the model that surfaces the obligation, and the human is the policy decision point.
+
+The CI guarantee is structural reachability — the linter would fail if a provider was declared in `agents/templates/.ai-video.xml.example` without a lifecycle tag (extension planned). It does not enforce the runtime obligation; the agent does.
+
+## See also
+
+- [`docs/contracts/provider-lifecycle.md`](../docs/contracts/provider-lifecycle.md) — the full tier definitions, promotion / demotion criteria, and day-one assignment matrix.
+- [`src/scripts/ai-video/lib/adapter-contract.md`](../../src/scripts/ai-video/lib/adapter-contract.md) — the four-method shell surface every adapter implements; the tier tag is read alongside this contract.
+- [`media-governance-routing`](media-governance-routing.md) — sibling tier-2a rule that surfaces the prompt-side policy layer; this rule covers the provider-side discipline.
+- [`ask-when-uncertain`](ask-when-uncertain.md) — the one-question-per-turn discipline the refuse-and-surface path uses.