@event4u/agent-config 2.24.0 → 2.26.0

package/.agent-src/rules/framework-neutrality-in-generic-skills.md

@@ -0,0 +1,130 @@
+---
+type: "auto"
+tier: "2a"
+description: "When editing a generic skill/rule/command — block single-stack mandates; use language-agnostic procedures with carve-out pointers."
+source: package
+triggers:
+  - path_prefix: ".agent-src.uncompressed/skills/"
+  - path_prefix: ".agent-src.uncompressed/rules/"
+  - path_prefix: ".agent-src.uncompressed/commands/"
+  - keyword: "FormRequest"
+  - keyword: "PHPStan"
+  - keyword: "php artisan"
+  - keyword: "composer.json"
+  - keyword: "Eloquent"
+  - keyword: "Pest"
+  - keyword: "Blade"
+  - keyword: "vendor/bin"
+  - keyword: "Artisan"
+  - keyword: "Rector"
+  - phrase: "every controller"
+  - phrase: "all controllers"
+  - phrase: "generic skill"
+applies_to_user_types:
+  - "maintainer"
+validator_ignore:
+  - type: "substring"
+    pattern: ".agent-src.uncompressed/"
+    reason: "Rule's subject is generic artifacts under .agent-src.uncompressed/; every body link points there by design."
+  - type: "substring"
+    pattern: "scripts/lint_framework_leakage"
+    reason: "Rule cites the enforcing linter script by name in body and enforcement section."
+---
+
+# framework-neutrality-in-generic-skills
+
+## The Iron Law
+
+```
+NO GENERIC ARTIFACT MAY MANDATE A SPECIFIC FRAMEWORK.
+SPECIFICS BELONG IN CARVE-OUT ARTIFACTS (laravel-*, symfony-*,
+nextjs-*, pest-*, eloquent, quality-tools).
+```
+
+A generic skill, rule, or command names a *procedure* — what to do.
+A carve-out artifact names a *stack* — how that procedure looks in
+Laravel, Next.js, Pest, etc. Mixing the two leaks framework assumptions
+into surfaces the agent must trigger on regardless of project stack.
+
+## Scope
+
+This rule fires on edits under:
+
+- `.agent-src.uncompressed/skills/`
+- `.agent-src.uncompressed/rules/`
+- `.agent-src.uncompressed/commands/`
+
+**Exempt** (file or directory name matches — these are correctly
+framework-specific): `laravel*`, `symfony*`, `nextjs*`, `react-*`,
+`^php-*`, `^pest-*`, `^eloquent`, `^blade*`, `^livewire`, `^flux`,
+`^artisan-*`, `^composer-*`, `^docker*`, `^aws-*`, `^grafana`,
+`^openapi$`, `^quality-tools`, `^sql-writing`, `^tailwind*`,
+`^terraform*`, `^terragrunt*`, `^traefik`, `^mobile-e2e`,
+`-routing$`, `project-analysis-(laravel|symfony|nextjs|react|node-express|zend-laminas)`.
+
+## Forbidden patterns in generic artifacts
+
+| Pattern | Why it leaks | Fix |
+|---|---|---|
+| `FormRequest` as a mandate | Laravel-only validation class | Say "request-validation primitive (FormRequest in Laravel, zod in Next.js, pydantic in FastAPI)" or move to `laravel-validation` carve-out |
+| `php artisan …` as a canonical command | Laravel CLI | Generalize to "the framework's CLI" or move to `artisan-commands` carve-out |
+| `PHPStan` as the only example | PHP-only static analyser | List peers (`mypy` for Python, `tsc` for TypeScript) or move to `quality-tools` carve-out |
+| `composer.json` mentioned alone | PHP package manifest | Add `package.json` / `pyproject.toml` peers, or move to a PHP-scoped carve-out |
+| `Eloquent` / `Model::…` | Laravel ORM | Generalize to "the project's ORM/data layer" or move to `eloquent` carve-out |
+| `Pest` as the only test runner | PHP/Laravel test framework | List peers (`pytest`, `vitest`, `jest`) or move to `pest-testing` carve-out |
+| `Blade` / `Livewire` / `Flux` as default UI | Laravel view stack | Generalize to "the project's UI layer" or move to `blade-ui` / `livewire` / `flux` carve-outs |
+| `vendor/bin/<tool>` as a canonical path | PHP/Composer-specific binary path | Say "the project's quality CLI" or carve-out it |
+| `Rector` as the only refactor tool | PHP-only refactorer | List peers (`ts-morph`, `libcst`) or carve-out it |
+| "every controller" / "all controllers" | Assumes MVC PHP framework | Generalize to "every request handler" / "every endpoint" |
+
+## Allowed: cross-stack documentation
+
+Multi-stack tables or detection maps with **at least two ecosystems
+side-by-side** are documentation, not leakage. The linter's
+auto-detect heuristic (Step 0.5 of the audit roadmap) skips a hit when
+its ±2-line window contains patterns from a different ecosystem family
+(`php_family` vs `js_family` vs `python_family`).
+
+Example (allowed):
+
+```
+- PHP/Composer project → `composer.json` present
+- Node project        → `package.json` present
+- Python project      → `pyproject.toml` present
+```
+
+## Allowed: carve-out pointers
+
+A generic artifact may end a section with a one-line handoff to its
+framework-specific peers. Canonical shape:
+
+```
+→ Laravel-specific: see [laravel-validation](../skills/laravel-validation/SKILL.md)
+→ Next.js-specific: see [nextjs-patterns](../skills/nextjs-patterns/SKILL.md)
+```
+
+The pointer is a link, not a procedure — the generic artifact never
+inlines stack-specific code.
+
+## Enforcement
+
+`scripts/lint_framework_leakage.py` runs in the package CI pipeline.
+Exit codes:
+
+- `0` — no hits, or every hit is auto-detected as cross-stack, or
+  every hit is allowlisted in
+  `scripts/lint_framework_leakage_allowlist.json` with a `reason`.
+- `1` — at least one hit in a generic artifact (non-carve-out) that
+  is neither cross-stack nor allowlisted.
+
+The linter is intentionally noisy on first introduction — the audit
+roadmap drives hits to zero phase by phase.
+
+## See also
+
+- [`roadmap-ci-steps-policy`](roadmap-ci-steps-policy.md) — sibling
+  Tier-2a rule that drove this pattern.
+- [`skill-quality`](skill-quality.md) — every skill must remain
+  executable; carve-outs must still pass skill-quality.
+- [`scope-control`](scope-control.md) — neutralizing a skill is not
+  a refactor pretext; only touch the leaking sentences.

package/.agent-src/rules/git-history-discipline.md

@@ -0,0 +1,99 @@
+---
+type: "auto"
+tier: "2a"
+alwaysApply: false
+description: "Git history operations — never rebase/squash/amend without explicit request; once pushed, rewrites must pair with immediate re-push in same turn"
+source: package
+triggers:
+  - intent: "rebase the branch"
+  - intent: "squash commits"
+  - intent: "clean up commit history"
+  - intent: "fold this into the previous commit"
+  - intent: "tidy history after pushing"
+  - keyword: "git rebase"
+  - keyword: "fixup"
+  - keyword: "--amend"
+  - keyword: "force-push"
+  - keyword: "--force-with-lease"
+  - keyword: "squash-merge"
+  - phrase: "branch diverged"
+  - phrase: "pull --rebase failed"
+  - phrase: "ahead and behind"
+routes_to:
+  - "skill:git-workflow"
+---
+
+# Git History Discipline
+
+## Iron Law — Gate (no unsolicited rewrites)
+
+```
+NEVER REBASE, SQUASH, FIXUP, OR AMEND PUBLISHED OR LOCAL HISTORY
+WITHOUT THE USER ASKING FOR IT THIS TURN.
+LINEAR HISTORY IS A PREFERENCE, NOT A DEFAULT.
+COMMIT-CHUNK ORDER IS NOT A CORRECTNESS GOAL.
+```
+
+Add the next commit on top. Never reorder, fold, drop, or rewrite earlier
+commits to make the log "look right".
+
+## Iron Law — Protocol (once authorized)
+
+```
+ONCE PUSHED, A COMMIT IS PUBLISHED.
+ANY REWRITE OF PUSHED HISTORY MUST PAIR WITH AN IMMEDIATE RE-PUSH
+IN THE SAME TURN — OR DON'T REWRITE.
+NEVER END A SESSION WITH REWRITTEN-BUT-UNPUSHED LOCAL HISTORY.
+```
+
+## When rewrite is allowed
+
+Exactly three:
+
+1. **User says so this turn** — "rebase onto main", "squash these two", "amend that". This operation only, not a standing rule.
+2. **Standing instruction not yet revoked** — the user said earlier in the conversation "always squash before pushing"; honor it.
+3. **Conflict resolution forced by `git pull --rebase`** — the user already invoked the rebase via pull; finish it.
+
+Anything else — chunk-tidiness, "logical order", folding a follow-up fix into its parent — **forbidden**. The follow-up ships as its own commit (`fix: …`, `chore: …`).
+
+## Two protective stops (for the protocol phase)
+
+1. **Pre-rewrite stop.** Before any squash / amend / rebase on a branch that is on origin: `git fetch && git rev-list --left-right --count HEAD...@{u}`. If **either** side is non-zero — STOP and route to `skill:git-workflow § Divergent-State Recovery`. A blind `git pull --rebase` in this state is the documented failure mode.
+
+2. **Post-rewrite stop.** After the rewrite, push in the **same turn** with `--force-with-lease=<branch>:<fetched-sha>` and verify `git rev-parse origin/<branch>` equals `git rev-parse HEAD`. If the push fails (hook, network, token budget) — fix the cause and re-push **before** ending the session, committing new work, or handing off.
+
+If either stop fires and resolution is not immediate → tag the state (`git tag local-rewritten-tip-<ISO-date>`) and hand control back to the user. Do not let a new session inherit a dirty divergence.
+
+## Equivalents that are also forbidden by default
+
+- `git rebase -i` (interactive)
+- `git rebase --autosquash`
+- `git commit --fixup` / `--squash` (helpers that feed autosquash)
+- `git commit --amend` on already-pushed commits
+- `git push --force` / `--force-with-lease` (unless paired with the protocol)
+- `git reset --hard` past unpushed work the user might want
+- Squash-merge of a PR via API or CLI when the user has not picked the merge strategy
+- Cherry-pick rewriting that drops or reorders commits
+
+`--amend` on the *current local* commit before the first push is the narrow exception (treated as continuing to compose the commit, not rewriting history).
+
+## Why this rule exists
+
+Interactive rebase + fixup loops generate disproportionate token cost on every iteration: re-running CI per replayed commit, resolving the same content conflict in three derived files (`.compression-hashes.json`, `router.json`, `.windsurfrules`), losing the working tree to a stash that silently re-introduces older state. A single conflict can burn the budget of an entire feature.
+
+A previous session squashed a pushed branch, the push hook failed at the token boundary, the session ended — and the next session saw local and origin pointing at different SHAs for the same logical work. A blind `git pull --rebase` cascaded into conflicts across every derived file. Recovery required forensic SHA-archaeology. The pre/post-rewrite stops make that sequence structurally impossible.
+
+## When you'd be tempted
+
+- "I want commit 3 to come before commit 2 because the topic flows better." → don't. Reviewers read the PR diff.
+- "There are two `chore: regenerate` commits, ugly." → don't. They are honest checkpoints.
+- "A linter caught an issue in commit 2 — let me fold the fix in." → don't. Add `fix(scope): …` on top.
+- "I want to drop the WIP commit before pushing." → ask the user first.
+- "Squash-merge when I open the PR will clean it anyway." → also true, also irrelevant — let the merge strategy do that work, not you.
+
+## See also
+
+- [`scope-control`](scope-control.md) — git-ops permission gate ("rebase" already named in the canonical list).
+- [`commit-policy`](commit-policy.md) — commits are the user's call; rewriting them is a stronger version of the same restriction.
+- [`token-efficiency`](token-efficiency.md) — Iron Law on burning the user's tokens for cosmetic gain.
+- [`skill:git-workflow`](../skills/git-workflow/SKILL.md) — Safe Squash-After-Push protocol and Divergent-State Recovery decision tree.

package/.agent-src/rules/media-governance-routing.md

@@ -0,0 +1,82 @@
+---
+type: "auto"
+tier: "2a"
+description: "When generating AI video/image/voice — surface project-local media policies (likeness, style, public-figures, voice-cloning, disclosure)"
+source: package
+triggers:
+  - keyword: "/video:"
+  - keyword: "/image:"
+  - keyword: "/audio:"
+  - keyword: "deepfake"
+  - keyword: "voice clone"
+  - keyword: "voice cloning"
+  - keyword: "likeness"
+  - keyword: "brand impersonation"
+  - phrase: "in the style of"
+  - phrase: "in the voice of"
+  - phrase: "as [public figure]"
+  - phrase: "impersonate"
+applies_to_user_types:
+  - "creator"
+  - "marketing"
+  - "gtm"
+validator_ignore:
+  - type: "substring"
+    pattern: "../../agents/"
+    reason: "Routing rule whose subject matter is the project-local agents/policies/media/ tree; every body link points there by design."
+  - type: "substring"
+    pattern: ".agent-src.uncompressed/"
+    reason: "Rule contrasts project-local placement with the .agent-src.uncompressed/rules/ alternative — mentioning the path is the argument."
+---
+
+# Media Governance Routing
+
+## Iron Law
+
+```
+WHEN AI VIDEO, IMAGE, OR VOICE GENERATION FIRES, CONSULT THE PROJECT-LOCAL
+MEDIA POLICIES IN agents/policies/media/ BEFORE EMITTING THE PROMPT TO
+THE PROVIDER. REFUSE-AND-SURFACE OVER GUESS-AND-RENDER.
+```
+
+Routes agent to project-local media governance policy layer at [`agents/policies/media/`](../../agents/policies/media/) when video / image / voice surface fires. Policies are LLM-readable decision frameworks consulted in-session, not Python-enforced gates — see [`agents/policies/media/README.md § Enforcement model`](../../agents/policies/media/README.md) for full agent-in-the-loop contract.
+
+## What this rule surfaces
+
+Any trigger match → agent loads into context:
+
+- [`agents/policies/media/likeness.md`](../../agents/policies/media/likeness.md) — real person's visual likeness.
+- [`agents/policies/media/style.md`](../../agents/policies/media/style.md) — named living artist's distinctive style.
+- [`agents/policies/media/public-figures.md`](../../agents/policies/media/public-figures.md) — recognised public figures.
+- [`agents/policies/media/voice-cloning.md`](../../agents/policies/media/voice-cloning.md) — vocal likeness.
+- [`agents/policies/media/disclosure.md`](../../agents/policies/media/disclosure.md) — mandatory non-removable AI-generation disclosure.
+- [`agents/policies/media/brand-impersonation.md`](../../agents/policies/media/brand-impersonation.md) — brand / broadcaster identity imitation.
+- [`agents/policies/media/transparency.md`](../../agents/policies/media/transparency.md) — provenance metadata (C2PA, SynthID).
+
+Each policy carries own trigger block → within active context agent narrows from superset to policies whose specific patterns actually fired (e.g. prompt naming public figure → `public-figures.md` + `disclosure.md`; `--no-disclosure` → `disclosure.md` standalone).
+
+## Why project-local, not `.agent-src.uncompressed/rules/`
+
+Seven media policies live under [`agents/policies/media/`](../../agents/policies/media/), not as `.agent-src.uncompressed/rules/domain-safety-media-*.md`, for three reasons:
+
+1. **Consumed by skills + adapters**, not surfaced as standalone always-loaded prose. Cost non-trivial (7 × ~80 lines = ~560 lines always-context if hoisted to rules), and most sessions never touch video / image / voice surface.
+2. **Enforcement model project-local** — working precedent (`/ghostwriter:*` mandatory footer in `write-engine.md`) + audit log (session transcripts) are project artifacts. Rules under `.agent-src.uncompressed/` are tool-portable governance; these policies are domain-specific bindings.
+3. **Extraction to reusable domain pack explicitly deferred** until second non-video domain (audio, image, docs, exports) lands with overlapping execution surfaces. Until then, one-domain abstraction structurally premature — policies stay project-local, routing rule on-demand bridge.
+
+This routing rule is the bridge: sits in always-loaded rule set so trigger keywords surface project-local policies into context on demand, without paying full always-loaded cost.
+
+## CI reachability guarantee
+
+[`scripts/lint_media_policy_linkage.py`](../../scripts/lint_media_policy_linkage.py) fails build if any policy file under `agents/policies/media/` not linked from:
+
+- this routing rule, **or**
+- a skill's `## Policies` see-also block, **or**
+- another policy file's `## See also` block.
+
+Policy that no skill, rule, or sibling policy references → silent policy. CI check is structural reachability guarantee that agent-in-the-loop model rests on.
+
+## See also
+
+- [`agents/policies/media/README.md`](../../agents/policies/media/README.md) — full enforcement-model contract.
+- [`.augment/rules/ask-when-uncertain.md`](../../.augment/rules/ask-when-uncertain.md) — single-question refusal-path discipline every policy depends on.
+- [`docs/contracts/write-engine.md`](../docs/contracts/write-engine.md) — prose-disclosure precedent extended to media by [`disclosure.md`](../../agents/policies/media/disclosure.md).

package/.agent-src/rules/minimal-safe-diff.md

@@ -12,6 +12,12 @@ triggers:
 
 # Minimal Safe Diff
 
+```
+THE DIFF CONTAINS THE SMALLEST CHANGE THAT SOLVES THE STATED PROBLEM.
+NEVER REFORMAT, RENAME, OR RESTRUCTURE UNTOUCHED CODE IN THE SAME DIFF.
+NEVER ADD DRIVE-BY EDITS, OPPORTUNISTIC REFACTORS, OR DEPENDENCY BUMPS.
+```
+
 A diff is **safe** when every line in it is traceable to the stated task.
 Every other line is scope creep and must be removed or moved to a separate
 change.

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

@@ -126,8 +126,10 @@ Failure modes:
 
 ## See also
 
-- [`docs-sync`](docs-sync.md) — cross-reference sync after rename / delete
-- [`agent-docs`](agent-docs.md) — roadmap layer conventions
+- [`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
 - [`augment-source-of-truth`](augment-source-of-truth.md) — edit

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

@@ -0,0 +1,90 @@
+---
+type: "auto"
+tier: "2a"
+description: "When creating, editing, or proposing personas — enforce per-domain cap (≤ 2 specialists), ≥ 1 skill citation, and the deprecation path"
+source: package
+triggers:
+  - path_prefix: ".agent-src.uncompressed/personas/"
+  - path_prefix: ".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.uncompressed/"
+    reason: "Rule documents the persona authoring tree (.agent-src.uncompressed/personas/) as the deprecation-path operand."
+---
+
+# 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`](../../.agent-src/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`](../../.agent-src/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/.agent-src/rules/provider-lifecycle-discipline.md

@@ -0,0 +1,75 @@
+---
+type: "auto"
+tier: "2a"
+description: "When editing an AI video/image/audio adapter — declare lifecycle tier (experimental | stable | deprecated | community); never default to non-stable"
+source: package
+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"
+---
+
+# 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/.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/.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/.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/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/.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.
+- [`scripts/ai-video/lib/adapter-contract.md`](../../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.

package/.agent-src/rules/roadmap-ci-steps-policy.md

@@ -0,0 +1,145 @@
+---
+type: "auto"
+tier: "2a"
+description: "When authoring or executing roadmaps — forbid task ci / make test / npm run check steps when quality.local_auto_run is false; skip inline at execution"
+source: package
+triggers:
+  - path_prefix: "agents/roadmaps/"
+  - path_prefix: "app/Modules/"
+  - keyword: "task ci"
+  - keyword: "make test"
+  - keyword: "npm run check"
+  - keyword: "pnpm run check"
+  - keyword: "yarn check"
+  - keyword: "composer test"
+  - phrase: "run the quality pipeline"
+  - phrase: "run task ci"
+  - phrase: "run the full ci"
+applies_to_user_types:
+  - "maintainer"
+  - "developer"
+validator_ignore:
+  - type: "substring"
+    pattern: "agents/roadmaps/"
+    reason: "Rule's subject is roadmap files under agents/roadmaps/; every body link points there by design."
+  - type: "substring"
+    pattern: ".agent-settings.yml"
+    reason: "Rule reads quality.local_auto_run from .agent-settings.yml; naming the file is the contract."
+---
+
+# Roadmap CI-Steps Policy
+
+## Iron Law
+
+```
+WHEN quality.local_auto_run IS FALSE,
+ROADMAPS MUST NOT SCHEDULE FULL-PIPELINE CI STEPS,
+AND EXECUTION MUST SKIP THEM INLINE WITH [-] AND A REASON.
+```
+
+When `quality.local_auto_run: false` in `.agent-settings.yml`, every
+full-pipeline gate run during roadmap work is wasted wall-clock and
+tokens — remote CI on the PR is the authoritative gate. Roadmaps
+must neither schedule nor execute them locally. New CI gates and
+smoke/test files added by the roadmap itself are exempt — they must
+run once locally to count as verified evidence per
+[`verify-before-complete`](verify-before-complete.md).
+
+## Forbidden step patterns (authoring + execution)
+
+A step is **CI-shaped** when its text matches any pattern below.
+Case-insensitive. Line-bounded — literal must appear inside the
+step's `- [ ]` line or its immediate inline `<!-- … -->` / `(…)` note.
+
+| Pattern | Example |
+|---|---|
+| `task ci` | `Run task ci before the boundary` |
+| `task ci-strict` | `task ci-strict release gate` |
+| `task ci-fast` | `task ci-fast smoke` |
+| `make test` | `Run make test on phase boundary` |
+| `make ci` | `make ci pre-merge` |
+| `npm run check` / `pnpm run check` / `yarn check` | `npm run check before commit` |
+| `composer test` | `composer test on every phase` |
+| `vendor/bin/phpunit` (whole-suite, no path arg) | `vendor/bin/phpunit` |
+| `php artisan test` (no `--filter`) | `php artisan test` |
+
+Targeted commands (`vendor/bin/phpstan analyse app/Modules/X`,
+`php artisan test --filter=…`, `npm run lint -- --fix path/`) are
+**not** CI-shaped — narrow verifications, allowed regardless of the
+setting.
+
+## Carve-outs — when CI-shaped steps are still allowed
+
+1. **New CI gate / smoke test / test file landed by this roadmap.**
+   Once-locally execution is mandatory under
+   [`verify-before-complete`](verify-before-complete.md) carve-out
+   (see `templates/agent-settings.md` § `quality.local_auto_run`).
+   Mark the step with `<!-- carve-out: new-gate-verification -->`
+   on the same line; linter and execution loop honour it and let the
+   step run.
+2. **`quality.local_auto_run: true`.** Opt-in restores pre-policy
+   behaviour — linter no-ops, execution loop runs CI steps unmodified.
+3. **Acceptance-criteria block at end of roadmap.** Final-gate prose
+   like "All quality gates pass (`task ci`)" inside an
+   `## Acceptance criteria` section is documentation, not an
+   executable step (no `- [ ]` checkbox in front). Linter ignores;
+   execution loop never reaches it as a step.
+
+## Authoring — linter blocks at write-time
+
+`task lint-roadmap-ci-steps` (wired into `task ci-fast` /
+`lint-roadmap-complexity` cadence) scans `agents/roadmaps/*.md` and
+`app/Modules/*/agents/roadmaps/*.md`. Exit code:
+
+- `0` — no CI-shaped steps, or setting is `true`, or every match is
+  carve-out-marked.
+- `1` — at least one CI-shaped step in an active (non-archived,
+  non-skipped) roadmap with `quality.local_auto_run: false` and no
+  carve-out marker. Linter prints file, line, matched literal, and
+  suggested rewording.
+
+Archive (`agents/roadmaps/archive/`) and skipped
+(`agents/roadmaps/skipped/`) are out of scope — they record history,
+not future work.
+
+## Execution — process-loop skips inline
+
+Wrappers `/roadmap:process-step|phase|full` honour the policy at the
+top of [`roadmap-process-loop § 5`](../contexts/execution/roadmap-process-loop.md#5-step-loop):
+
+1. Before running a step, match its text against the patterns above.
+2. CI-shaped **and** `quality.local_auto_run: false` **and** no
+   carve-out marker → flip checkbox to `[-]` (cancelled), append a
+   one-line reason as inline note, regenerate the dashboard, continue
+   to next step. **Never** run the gate.
+3. CI-shaped **and** `quality.local_auto_run: true` → run normally.
+4. Carve-out-marked → run regardless of the setting.
+
+The `[-]` reason format is fixed:
+`<!-- skipped: quality.local_auto_run=false → remote CI is the gate -->`.
+Per [`roadmap-progress-sync`](roadmap-progress-sync.md) the flip and
+dashboard regen happen in the **same reply** that decides to skip;
+saving skips for the archive commit is a rule violation.
+
+## Failure modes
+
+- Authoring `- [ ] Run task ci` while `local_auto_run: false` — linter
+  fails the PR.
+- Executing a CI-shaped step without inline-skip flip — Iron Law
+  violation; loop never reaches the gate.
+- Carve-out marker on an *existing* pipeline run — abuse; the marker
+  is reserved for **new** gates introduced by the same roadmap.
+- Hiding the literal inside a fenced bash block to dodge the linter —
+  linter matches inside fenced blocks too (see
+  `scripts/lint_roadmap_ci_steps.py`).
+
+## See also
+
+- [`verify-before-complete`](verify-before-complete.md) — Iron Law
+  this rule narrows; carve-out cites it.
+- [`roadmap-progress-sync`](roadmap-progress-sync.md) — inline flip +
+  dashboard regen contract.
+- `templates/agent-settings.md` § `quality.local_auto_run` — source
+  of the toggle and its carve-out wording.
+- [`contexts/execution/roadmap-process-loop`](../contexts/execution/roadmap-process-loop.md)
+  — § 5 owns the inline-skip mechanics.