@event4u/agent-config 8.13.0 → 9.1.0

package/dist/agent-src/commands/team/status.md

@@ -2,10 +2,10 @@
 model_tier: inherit
 name: team-status
 disable-model-invocation: true
-pack: product-reasoning
+pack: meta
 tier: 2
 visibility: internal
-description: Thin wrapper — plugin job status via /codex:status plus a ledger line with today's cli_call_budget openai count. Gated on ai_team.enabled; fails closed when the plugin is absent.
+description: Thin wrapper — plugin job status via /codex:status plus a quota block (shared openai counter vs team + council ceilings). Gated on ai_team.enabled; fails closed without the plugin.
 cluster: team
 sub: status
 suggestion:
@@ -14,7 +14,7 @@ suggestion:
 workspaces:
   - agent-config-maintainer
 packs:
-  - product-reasoning
+  - meta
 ---
 
 # /team status
@@ -22,7 +22,7 @@ packs:
 ## Instructions
 
 Thin wrapper: team-mode status. On Claude Code hosts it delegates to the
-official plugin's `/codex:status` and appends **our** quota ledger line —
+official plugin's `/codex:status` and appends **our** quota block —
 the one piece of state the plugin does not know about.
 
 ### 1. Gate — `ai_team.enabled`
@@ -38,7 +38,7 @@ print the fail-closed block from `/team` (master) § "Fail-closed contract"
 (`agent-config doctor --check team`) and **STOP** — never a silent no-op.
 
 On a non-Claude-Code host: state that plugin job status requires the Claude
-Code plugin, then still print the ledger line (Step 4) — the quota counter
+Code plugin, then still print the quota block (Step 4) — the quota counter
 is ours and host-independent.
 
 ### 3. Delegate
@@ -49,28 +49,59 @@ Invoke the plugin:
 
 Render its job/status output verbatim.
 
-### 4. Append the quota ledger line
+### 4. Append the quota block — two ceilings, one counter
 
-Read today's openai CLI-call count from the shared counter state at
-`~/.event4u/agent-config/cli-calls.json` (daily UTC reset — the same file
-the council's CLI transport maintains for
-`cli_call_budget.max_calls_per_day.openai`). Append one line:
+Team mode and the council share **one** daily counter but enforce **two
+independent ceilings** against it. The status output must show all three
+live numbers and say which path — if any — is currently blocked:
+
+1. **Counter** — today's openai CLI-call count from the shared counter
+   state at `~/.event4u/agent-config/cli-calls.json` (daily UTC reset —
+   the same file the council's CLI transport maintains). `0` when the
+   file or today's entry is absent.
+2. **Team ceiling** — `ai_team.max_calls_per_day` from
+   `.agent-settings.yml` (`unset` when absent).
+3. **Council ceiling** — `cli_call_budget.max_calls_per_day.openai` from
+   the council config (`unset` when absent).
+
+Render:
 
 ```
-Ledger: <N> openai CLI calls today (UTC) · cap: <max_calls_per_day or "unset">
+Quota: <N> openai CLI calls today (UTC) — one shared counter
+  team ceiling (ai_team.max_calls_per_day):                <T or "unset"> → <OPEN | BLOCKED>
+  council ceiling (cli_call_budget.max_calls_per_day.openai): <C or "unset"> → <OPEN | BLOCKED>
 ```
 
-- `<N>` = today's openai count from the counter file; `0` when the file or
-  today's entry is absent.
-- `<cap>` = `ai_team.max_calls_per_day` when set; fall back to
-  `cli_call_budget.max_calls_per_day.openai`; `unset` when neither exists.
+- A path is `BLOCKED` when the counter has reached its ceiling
+  (`N >= ceiling`); an `unset` ceiling is `OPEN`.
+- The two paths block **independently** — always name WHICH path is
+  blocked, never a bare "quota exhausted".
 - One counter, one subscription — never introduce a parallel team-only
   counting file.
 
+**Worked example.** Council ceiling 100, team ceiling 50, counter at 45:
+both paths are open. Five team calls later the shared counter reads 50 —
+team calls are now `BLOCKED` (50 >= 50) while council CLI calls continue
+until the counter reaches 100. Whichever path fires a call, the same
+counter moves; each surface only enforces its own ceiling against that
+shared count.
+
+### 5. Review-gate ledger lines (when present)
+
+When the council events ledger contains review-gate lines of the form
+`team.gate: BLOCK n/N`, render them verbatim after the quota block — they
+record how often the plugin's Stop-hook Review Gate blocked, out of N gate
+evaluations. Absent lines are not an error: print nothing (the review-gate
+envelope is a later team-mode phase; this step is read-only forward
+compatibility).
+
 ## Output format
 
 - The plugin's status output, verbatim.
-- Exactly one trailing `Ledger:` line in the format above.
+- Exactly one trailing `Quota:` block in the format above (counter + both
+  ceilings + per-path OPEN/BLOCKED verdict).
+- Any `team.gate: BLOCK n/N` ledger lines, verbatim, after the quota
+  block — only when present.
 - Gate failures print exactly one block (enable pointer or fail-closed
   block) and stop.
 
@@ -78,11 +109,11 @@ Ledger: <N> openai CLI calls today (UTC) · cap: <max_calls_per_day or "unset">
 
 - Do NOT run when `ai_team.enabled` is false — enable pointer, stop.
 - Do NOT fabricate a count when the counter file is unreadable — print
-  `Ledger: unavailable (<reason>)` instead of a guessed number.
+  `Quota: unavailable (<reason>)` instead of a guessed number.
 - Do NOT write to `cli-calls.json` — the transport owns the counter; this
   wrapper is read-only.
 - Do NOT reimplement job tracking inline when the plugin is absent — fail
-  closed with the doctor pointer (the ledger line alone is still printed on
+  closed with the doctor pointer (the quota block alone is still printed on
   non-Claude-Code hosts, per Step 2).
 
 ## See also

package/dist/agent-src/commands/team-knowledge.md

@@ -2,6 +2,7 @@
 model_tier: medium
 name: team-knowledge
 disable-model-invocation: true
+argument-hint: "[consolidate|bootstrap]"
 pack: meta
 intent: "Manage the repo-tracked team-knowledge layer — consolidate typed observation events into agents/knowledge/ pages, bootstrap a project baseline"
 routes_to: [team-knowledge-consolidate, team-knowledge-bootstrap]
@@ -26,13 +27,14 @@ packs:
 Top-level orchestrator for the `/team-knowledge` family — the
 consolidation gate over the typed knowledge-observation events
 captured during normal task work (see
-[`knowledge-pages`](../templates/contexts/knowledge-pages.md) and the
-event schema in `src/scripts/_lib/knowledge_events.ts`).
+[`knowledge-pages`](../../agent-src/templates/contexts/knowledge-pages.md)
+and the event schema in `src/scripts/_lib/knowledge_events.ts`).
 
-Not to be confused with the pre-existing `/knowledge` cluster (local
-file ingestion into `agents/memory/knowledge/`) — different concern
-(arbitrary local documents), unrelated to this repo-tracked,
-lifecycle-typed team-knowledge layer under `agents/knowledge/`.
+Not to be confused with the pre-existing [`/knowledge`](../../product-discovery/knowledge/command.md)
+cluster (local file ingestion into `agents/memory/knowledge/`) — that
+is a different concern (arbitrary local documents), unrelated to this
+repo-tracked, lifecycle-typed team-knowledge layer under
+`agents/knowledge/`.
 
 ## Sub-commands
 

package/dist/agent-src/commands/team.md

@@ -2,13 +2,14 @@
 model_tier: inherit
 name: team
 disable-model-invocation: true
-pack: product-reasoning
+argument-hint: "[review|adversarial|delegate|status] [args]"
+pack: meta
 intent: "Route a cross-model team-mode request (review, adversarial, delegate, status) to the official plugin under ai_team governance"
 routes_to: [team-review, team-adversarial, team-delegate, team-status]
 replaces: []
 tier: 2
 visibility: internal
-description: Team orchestrator — cross-model depth review (one strong model builds, a second reviews the real diff); routes to review, adversarial, delegate, status
+description: Team orchestrator — governed cross-model access layer (a second strong model reviews the real diff; read-only multi-host fallback); routes to review, adversarial, delegate, status
 cluster: team
 type: orchestrator
 suggestion:
@@ -18,25 +19,27 @@ suggestion:
 workspaces:
   - agent-config-maintainer
 packs:
-  - product-reasoning
+  - meta
 ---
 
 # /team
 
-Top-level orchestrator for the `/team` family — governed **team mode**: the
-depth complement to the council. One strong model builds; a second strong
-model reviews the **real diff with repo access** and iterates. On Claude Code
-hosts every sub-command is a **thin delegation** to the official
+Top-level orchestrator for the `/team` family — governed **team mode**: a
+governed access layer with a read-only multi-host fallback, the depth
+complement to the council. A second strong model reviews the **real diff
+with repo access** and returns its findings. On Claude Code hosts every
+sub-command is a **thin delegation** to the official
 `openai/codex-plugin-cc` plugin (`/codex:*`) — this family adds governance
 (default-off gate, delegate opt-in, quota visibility, fail-closed setup
-checks), never a reimplementation.
+checks), never a reimplementation. An iterated build → review → fix loop is
+**gated future work** — it unlocks only with a positive verdict from the
+pre-registered benchmark (§ No-claims note).
 
 ## What team mode is — and is not
 
 - **Is:** a single strong reviewer running inside the working tree via the
-  Codex CLI under the user's subscription. It reads git state itself,
-  iterates build → review → fix, and returns an opinionated review of the
-  actual change.
+  Codex CLI under the user's subscription. It reads git state itself and
+  returns an opinionated review of the actual change.
 - **Is not:** the council. The council is breadth under a neutrality
   contract — N members see the artefact text only, never the repo, never the
   host's framing. Team mode is the inverse on every axis (table below). The
@@ -46,7 +49,7 @@ checks), never a reimplementation.
 
 | Axis | `/council` | `/team` |
 |---|---|---|
-| Shape | Breadth — N members, one round by default | Depth — one strong reviewer, iterated |
+| Shape | Breadth — N members, one round by default | Depth — one strong reviewer on the real diff |
 | Context | Artefact text only; never the repo, never host framing (neutrality contract) | Full repo access — the reviewer reads git state itself |
 | Cost model | Billable API members by default; USD cost gate | Subscription-authed Codex CLI; daily call quota (`cli_call_budget.max_calls_per_day.openai`) |
 | Model choice | Mid-tier default (cost decision) | Strongest available — `ai_team.model: 'auto'` defers to the CLI default |
@@ -79,7 +82,7 @@ a wrapper is invoked directly.
 | `/team review [--background]` | `/codex:review` | Cross-model review of the current working-tree / staged diff |
 | `/team adversarial <focus>` | `/codex:adversarial-review` | Adversarial cross-model review on a named focus — the escalation rung above the single-model `adversarial-review` skill |
 | `/team delegate <task>` | `/codex:rescue` | Hand a task to the second model as a native worker — the only write-access wrapper; gated behind `ai_team.allow_delegate` |
-| `/team status` | `/codex:status` + ledger line | Plugin job status plus today's `cli_call_budget` openai count |
+| `/team status` | `/codex:status` + quota block | Plugin job status plus the shared openai counter against both ceilings (team + council), naming any blocked path |
 
 ## Dispatch
 
@@ -110,9 +113,11 @@ never an inline reimplementation of the plugin:
 > agent-config doctor --check team
 > ```
 
-On non-Claude-Code hosts the fallback transport (repo-diff bundle via the
-council's `OpenAICliClient`) is a later phase; until it lands, wrappers state
-that plainly and stop — same fail-closed principle.
+On non-Claude-Code hosts the wrappers fall back to a **read-only** transport
+(repo-diff bundle via the council's `OpenAICliClient`) — no plugin job
+control, no background jobs, no delegate write path; the capability delta
+vs. the native plugin is stated in the output. When the codex CLI itself is
+absent, the same fail-closed principle applies: state it plainly and stop.
 
 ## No-claims note
 

package/dist/agent-src/commands/tests/e2e-heal.md

@@ -9,6 +9,7 @@ sub: e2e-heal
 cluster: tests
 skills: [playwright-testing]
 description: Find, debug, and fix failing Playwright E2E tests
+argument-hint: "[test-file | ci-run-url]"
 suggestion:
   eligible: true
   trigger_description: "fix the failing E2E tests, playwright tests are red"

package/dist/agent-src/commands/tests/e2e-plan.md

@@ -9,6 +9,7 @@ sub: e2e-plan
 cluster: tests
 skills: [playwright-testing]
 description: Explore the application and create a structured E2E test plan in Markdown
+argument-hint: "[url | feature-area]"
 suggestion:
   eligible: true
   trigger_description: "plan E2E tests for this feature, what should we cover in playwright"

package/dist/agent-src/commands/tests/execute.md

@@ -8,6 +8,7 @@ cluster: tests
 sub: execute
 skills: [pest-testing, quality-tools]
 description: Run the project's test suite — stack-adaptive (pest / phpunit / vitest / jest / pytest / …)
+argument-hint: "[file | filter] [--include-e2e] [--include-slow] [--php]"
 suggestion:
   eligible: true
   trigger_description: "run the tests, execute the test suite"

package/dist/agent-src/commands/tests.md

@@ -2,6 +2,7 @@
 model_tier: medium
 name: tests
 disable-model-invocation: true
+argument-hint: "[create|execute|e2e-plan|e2e-heal] [args]"
 pack: engineering-base
 tier: 2
 visibility: internal
@@ -34,7 +35,7 @@ commands with a single entry point + sub-command dispatch.
 | `/tests e2e-heal` | `commands/tests/e2e-heal.md` | Find, debug, and fix failing Playwright E2E tests |
 
 Sub-command names match the locked contract in
-[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+[`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
 Both sub-commands resolve the runner via the
 [`toolchain-resolver`](../contexts/execution/toolchain-resolver.md) — they
 adapt to the consumer's stack instead of assuming one.

package/dist/agent-src/commands/update-form-request-messages.md

@@ -7,6 +7,7 @@ visibility: internal
 framework: laravel
 skills: [laravel-validation]
 description: "Sync the messages() method of a FormRequest class — add missing entries, link them to language keys, and clean up stale ones."
+argument-hint: "[ClassName | file-path]"
 suggestion:
   eligible: true
   trigger_description: "sync the form request messages, update the validation messages"

package/dist/agent-src/commands/upstream-contribute.md

@@ -6,6 +6,7 @@ tier: 2
 visibility: internal
 skills: [upstream-contribute, skill-writing, learning-to-rule-or-skill]
 description: Contribute a learning, skill, rule, or fix from a consumer project back to the shared agent-config package
+argument-hint: "[path | description]"
 suggestion:
   eligible: true
   trigger_description: "contribute this back to agent-config, upstream this learning"

package/dist/agent-src/commands/video/from-script.md

@@ -7,6 +7,7 @@ visibility: internal
 cluster: video
 sub: from-script
 description: Drive a script end-to-end through the AI video pipeline — scenes → blueprint → image → operator pick → motion → video → stitch. Preview default; --mode commit spends behind the cost gate.
+argument-hint: "<path-to-script.md> [--mode preview|commit] [--max-spend-usd <usd>] [--image-provider <id>] [--video-provider <id>]"
 personas: [hollywood-director, ai-video-technical-director]
 skills: [scene-expander, video-director, pixar-storyteller, character-consistency, motion-choreographer]
 suggestion:
@@ -146,8 +147,8 @@ cost (commit) or summed modeled `cost_estimate` labeled *modeled*
 - **One project per invocation.** Re-running on the same project
   resumes from existing artefacts (skips completed scenes) via the
   ADR-059 resume scan: `scripts/ai-video/lib/resume-scan.sh scan
-  <project> --plan <project>/plan.json` — `green` reused, `stale` /
-  `missing` re-render, `failed` surfaces its `error.json`. State =
+  <project> --plan <project>/plan.json` — `green` is reused, `stale` /
+  `missing` re-render, `failed` surfaces its `error.json`. State is the
   per-scene sentinel set (`prompt.json` with `input_sha256`, the clip,
   `error.json`, `cost.json`) — no central checkpoint file.
 

package/dist/agent-src/commands/video/from-song.md

@@ -7,6 +7,7 @@ visibility: internal
 cluster: video
 sub: from-song
 description: Music-video from a song + reference images — accept or derive a timed scene script, optional character-lock, render, stitch, mux song as master track. Preview default; --mode commit gates the spend.
+argument-hint: "<images-dir> <song-file> [--mode preview|commit] [--brief <text>|--auto-script] [--max-spend-usd <usd>]"
 personas: [hollywood-director, ai-video-technical-director]
 skills: [song-to-script, scene-expander, video-director, character-consistency, motion-choreographer, prompt-validator]
 suggestion:
@@ -61,7 +62,7 @@ silent best-guess.
 | Input | Required | Meaning |
 |---|---|---|
 | `<images-dir>` | yes | Folder of reference stills (`.png` / `.jpg`). When they contain a consistent human subject the on-screen identity is locked from them; otherwise the run is style-only (Step 6). |
-| `<song-file>` | yes | Audio track (`.mp3` / `.wav` / `.m4a`) — or an `https://` song link (Suno / Udio / YouTube / any yt-dlp-supported page): ingested to a local file first via `scripts/ai-video/lib/ingest-song.sh <url> <project>` (operator-installed `yt-dlp` + `ffmpeg`; rights note surfaced; size-capped; never a silent overwrite); pipeline continues on `<project>/song.m4a`. Defines total duration and, in `--auto-script` mode, the scene structure. |
+| `<song-file>` | yes | Audio track (`.mp3` / `.wav` / `.m4a`) — or an `https://` song link (Suno / Udio / YouTube / any yt-dlp-supported page): the link is ingested to a local file first via `scripts/ai-video/lib/ingest-song.sh <url> <project>` (operator-installed `yt-dlp` + `ffmpeg`; rights note surfaced; size-capped; never a silent overwrite) and the pipeline continues on `<project>/song.m4a`. Defines total duration and, in `--auto-script` mode, the scene structure. |
 | `--brief "<text>"` | one of brief/auto | Operator-written description of the video (mood, story, settings). |
 | `--auto-script` | one of brief/auto | Derive the script from the song via the `song-to-script` skill. |
 | `--scene-durations <list>` | no | Manual cut points (e.g. `0:00-0:15,0:15-0:30,…`). Overrides probe timing — the honest path when the track is flat (probe `method: interval`). |
@@ -95,28 +96,28 @@ with usage, never a deadlocked prompt.
 
 - `<images-dir>` exists and holds ≥1 `.png`/`.jpg`. Empty or missing →
   halt, list what was found.
-- `<song-file>` given as an `https://` link → ingest first:
+- `<song-file>` given as an `https://` link → ingest it first:
   `scripts/ai-video/lib/ingest-song.sh <url> <project>` (exit 3 names
-  the missing tool; exit 75 = retryable download failure). The ingested
-  local file replaces the URL for every later step — ground truth stays
-  the real bytes, and the media-governance gate below runs on the
-  ingested file (a platform link is *more* likely a recognisable
-  commercial song — check `voice-cloning` deliberately).
+  the missing tool; exit 75 is a retryable download failure). The
+  ingested local file replaces the URL for every later step — ground
+  truth stays the real bytes, and the media-governance gate below runs
+  on the ingested file (a platform link is *more* likely to be a
+  recognisable commercial song — check `voice-cloning` deliberately).
 - `<song-file>` exists and is a readable audio container (`ffprobe`
   returns an audio stream). Derive its length + structure now,
   **adapter-first with the probe as the floor** (fallback semantics per
   [`audio-adapter-contract.md § Fallback`](../../../scripts/ai-video/lib/audio-adapter-contract.md)):
-  1. An `audio-analysis` provider configured in `agents/.ai-video.xml`
+  1. An `audio-analysis` provider is configured in `agents/.ai-video.xml`
      **and** `scripts/ai-video/audio-adapters/<id>.sh` exists → run
      ```bash
      echo '{"audio_path":"<song-file>"}' | scripts/ai-video/audio-adapters/<id>.sh analyze
      ```
      Real `{bpm, beats, downbeats, sections:[{start,end,label}]}` drives
-     the cut; report names the `source`. **Transient** failure (exit 75)
-     → retry once, then fall back to the probe with ONE warning line.
-     **Config** failure (exit 3/6/7 — CLI missing, disabled, bad key) →
-     **halt with the actionable message** — a configured adapter never
-     silently degrades.
+     the cut; the report names the `source`. On a **transient** failure
+     (exit 75) retry once, then fall back to the probe with ONE warning
+     line. On a **config** failure (exit 3/6/7 — CLI missing, disabled,
+     bad key) **halt with the actionable message** — a configured
+     adapter never silently degrades.
   2. No audio-analysis provider configured → run the zero-dependency
      probe (the normal path, not a degradation):
      ```bash
@@ -224,7 +225,7 @@ When the track has vocals **and** the run assigns singers / lip-sync:
    scripts/ai-video/lib/validate-vocal-map.sh <project>/vocal-map.json \
      <project>/transcript.json --roster "<cast>"
    ```
-   — mechanically rejects re-timed lines, lyrics absent from the
+   — it mechanically rejects re-timed lines, lyrics absent from the
    transcript, and missing singers (exit 7 with the offending line). A
    skeleton-derived map cannot reach the operator, let alone a render.
 3. **Each vocal line maps to its OWN singer.** Never put one character's
@@ -363,20 +364,20 @@ Before rendering, run the mechanical scan:
 scripts/ai-video/lib/resume-scan.sh scan <project> --plan <project>/plan.json
 ```
 
-`plan.json` holds each scene's current `input_sha256`
+where `plan.json` holds each scene's current `input_sha256`
 (`resume-scan.sh hash < scenes/<id>/prompt.json` — same canonicalization
-the render path stamps). `green` scenes skipped verbatim; `stale`
-(prompt edited, provider/model switched, hash tampered) + `missing`
-re-render; `failed` surfaces its `error.json` reason. After each live
-scene completes, write `scenes/<id>/cost.json`
+the render path stamps). `green` scenes are skipped verbatim; `stale`
+(prompt edited, provider/model switched, hash tampered) and `missing`
+scenes re-render; `failed` scenes surface their `error.json` reason.
+After each live scene completes, write `scenes/<id>/cost.json`
 (`{charged_usd, adapter, model}`, atomic `tmp`+`mv`) — the scan sums it
 as `spent_usd` and the batch loop re-checks `--max-spend-usd` against it
 before **every** live submit, not only at the upfront gate. Per-scene
 kill-switch (ADR-059 §6): max one surfaced auto-retry on
-`retryable: true`; content-policy refusals always halt. Rollback =
+`retryable: true`, content-policy refusals always halt. Rollback is
 deletion (`rm -rf scenes/<id>/` → re-render); `--clean`
 (`resume-scan.sh clean <project>`) removes failed-scene residue only —
-green artifacts never auto-deleted.
+green artifacts are never auto-deleted.
 
 ### 9. Stitch + master-audio mux + duration reconciliation
 

package/dist/agent-src/commands/video/scene.md

@@ -7,6 +7,7 @@ visibility: internal
 cluster: video
 sub: scene
 description: Render a single scene from a one-line idea — scene-expander → blueprint → image → operator pick → motion → video. Preview mode default (no spend); --mode commit renders live behind the cost gate.
+argument-hint: "<idea> [--mode preview|commit] [--image-provider <id>] [--video-provider <id>] [--project <slug>]"
 personas: [hollywood-director, ai-video-technical-director]
 skills: [scene-expander, video-director, character-consistency, motion-choreographer]
 suggestion:

package/dist/agent-src/commands/video/stitch.md

@@ -7,6 +7,7 @@ visibility: internal
 cluster: video
 sub: stitch
 description: Re-stitch existing clips in `<project>/scenes/*/` after operator edits — no re-render. ffmpeg concat driven by manifest.json.
+argument-hint: "<project-slug> [--skip-scene <id>] [--continue]"
 personas: [ai-video-technical-director]
 skills: []
 suggestion:
@@ -86,4 +87,4 @@ No live cost (no network calls happened). No commit. No push.
 - [`/video:from-script`](from-script.md) — full pipeline including
   initial stitch
 - [`/video:scene`](scene.md) — render one scene
-- [`scripts/ai-video/stitch.sh`](../../scripts/ai-video/stitch.sh) — the underlying tool
+- [`scripts/ai-video/stitch.sh`](../../../scripts/ai-video/stitch.sh) — the underlying tool

package/dist/agent-src/commands/video/storyboard.md

@@ -7,6 +7,7 @@ visibility: internal
 cluster: video
 sub: storyboard
 description: Image-only storyboard — script → scenes → blueprint → image render → contact-sheet PNG via ffmpeg montage. No video calls.
+argument-hint: "<path-to-script.md> [--image-provider <id>]"
 personas: [hollywood-director]
 skills: [scene-expander, video-director, character-consistency]
 suggestion:

package/dist/agent-src/commands/video.md

@@ -6,6 +6,7 @@ tier: 2
 visibility: internal
 cluster: video
 description: Video-creation orchestrator — Hollywood-level AI video pipeline. Routes to from-script, from-song, scene, storyboard, stitch.
+argument-hint: "[from-script|from-song|scene|storyboard|stitch] [args]"
 type: orchestrator
 suggestion:
   eligible: true

package/dist/agent-src/commands/work.md

@@ -9,6 +9,7 @@ tier: 0
 visibility: visible
 skills: [refine-prompt, command-routing]
 description: Drive a free-form prompt end-to-end through refine → score → plan → implement → test → verify → report — Option-A loop over the `work_engine` engine, confidence-band gated, no auto-git.
+argument-hint: "[prompt]"
 suggestion:
   eligible: true
   trigger_description: "build this, implement this, drive this end-to-end"

package/dist/agent-src/commands/worktree/cleanup.md

@@ -8,6 +8,7 @@ cluster: worktree
 sub: cleanup
 skills: [worktree-lifecycle, git-workflow]
 description: Safe worktree removal gate — refuses while the branch holds commits on no other ref; never force-deletes
+argument-hint: "[worktree-path]"
 suggestion:
   eligible: true
   trigger_description: "clean up the worktrees, remove the finished worktree"
@@ -41,8 +42,8 @@ untracked files, paths with spaces — `tests/scripts/worktree_cleanup_check.tes
 ./scripts-run src/scripts/worktree_cleanup_check check <worktree-path>
 ```
 
-Exit `0` → removal allowed. Exit `1` → **refuse** that candidate; output
-names the exact gate:
+Exit `0` → removal allowed. Exit `1` → **refuse** that candidate; the
+output names the exact gate:
 
 1. **Detached HEAD** — no branch to judge reachability for; resolve the
    state manually first.
@@ -50,11 +51,11 @@ names the exact gate:
    files count as work). Never `git worktree remove --force`.
 3. **Unique commits** — commits reachable from the worktree branch but
    from no other ref (branches, remotes, AND tags — a tag counts as
-   reachability). Branch holds work that exists nowhere else: surface
-   the commit list and hand the decision back — dropping commits the
-   session did not author is forbidden by the `git-history-discipline`
-   rule (shared-branch Iron Law); merging or preserving them is the
-   user's call.
+   reachability). The branch holds work that exists nowhere else:
+   surface the commit list and hand the decision back — dropping
+   commits the session did not author is forbidden by the
+   `git-history-discipline` rule (shared-branch Iron Law); merging or
+   preserving them is the user's call.
 
 ### 3. Remove the allowed candidates
 

package/dist/agent-src/commands/worktree/create.md

@@ -8,6 +8,7 @@ cluster: worktree
 sub: create
 skills: [worktree-lifecycle, using-git-worktrees]
 description: Create a governed worktree and write its scope-lock note — propose-once branch naming, host-native primitive preferred
+argument-hint: "[task] [branch-name]"
 suggestion:
   eligible: true
   trigger_description: "do this in a worktree, isolate this task, spawn a worktree for X"

package/dist/agent-src/commands/worktree/verify.md

@@ -8,6 +8,7 @@ cluster: worktree
 sub: verify
 skills: [worktree-lifecycle, verify-completion-evidence]
 description: Run the scoped verification for a worktree's declared change — narrow probes matched to the diff, never the full CI pipeline
+argument-hint: "[worktree-path | branch]"
 suggestion:
   eligible: true
   trigger_description: "verify the worktree change, prove this worktree is ready"

package/dist/agent-src/commands/worktree.md

@@ -2,6 +2,7 @@
 model_tier: medium
 name: worktree
 disable-model-invocation: true
+argument-hint: "[create|status|verify|cleanup] [args]"
 pack: engineering-base
 tier: 2
 visibility: internal

package/dist/agent-src/rules/active-remediation.md

@@ -14,13 +14,15 @@ triggers:
   - keyword: "upgrade"
   - keyword: "cleanup"
   - keyword: "technical debt"
+routes_to:
+  - "guideline:agent-infra/active-remediation-mechanics"
 workspaces: [engineering]
 packs: [engineering-base]
 ---
 
 # Active Remediation
 
-The user doesn't see the code at the spot you're editing — you do. So this package guides the agent to **actively improve** what it touches: don't accept legacy, debt, security gaps, or duplication as given. But active improvement is bounded — never the scope creep `minimal-safe-diff` exists to stop. The rule is a **ladder**: act by size and alignment, and **never silently ignore** a real issue.
+The user does not see the code at the spot you are editing — you do. So this package guides the agent to **actively improve** what it touches: don't accept legacy, debt, security gaps, or duplication as given. But active improvement is bounded — it must never become the scope creep `minimal-safe-diff` exists to stop. The rule is a **ladder**: act by size and alignment, and **never silently ignore** a real issue.
 
 ## The Iron Law
 
@@ -34,44 +36,15 @@ A LIVE SECURITY / DATA-EXPOSURE GAP IS NEVER MERELY "NOTED FOR LATER".
 
 ## What to remediate
 
-Security gaps (broken access control, injection, secrets, missing authz — see `broken-access-control`) · missing/weak test coverage · bad code (dead code, silent error-swallow, unguarded edge cases) · **duplication** (same/near-same logic repeated instead of one method/abstraction) · **stale version-idioms** (code for an older language/framework version than the project runs).
+Security gaps (broken access control, injection, secrets, missing authz — see `broken-access-control`) · missing/weak test coverage · bad code (dead code, silent error-swallow, unguarded edge cases) · **duplication** (the same or near-same logic repeated instead of one method/abstraction) · **stale version-idioms** (code written for an older language/framework version than the project actually runs).
 
-## The ladder — classify, then act
+## The ladder — three tiers
 
-### Fix now (autonomous, inline) — a bounded amendment to `minimal-safe-diff`
-
-Allowed **only** when ALL hold — the testable "small + task-aligned" definition:
-- **Same request path / module** as the current task (not an unrelated feature).
-- **≤ ~10 changed lines** in one production file plus its test file — no wider cross-file ripple.
-- **No public-API / response-shape change**, no new parameter.
-- **No dependency bump, no migration, no data change.**
-- **Its verification ships in the same commit** — the security fix's negative test, the correctness fix's case.
-
-Under those constraints the fix is auditable in the same diff and is *not* scope creep — it corrects a boundary the agent touched. Anything outside them → **note + ask**, never auto. (`minimal-safe-diff` still governs the rest: no reformatting, no opportunistic refactor, no drive-by rename.)
-
-### Note + ask (batched)
-
-Bigger, or diverges from the task → do **not** refactor inline, do **not** interrupt the flow. Note the site (file:line + issue). Surface the batch as **one** numbered-options prompt (`user-interaction`, one recommendation line) **after the task is delivered** — or mid-work only when the flow makes it natural. Each option carries a real trade-off (`no-cheap-questions`). Refactor only on an explicit yes, as a separate scoped change (`scope-control`, `downstream-changes`).
-
-### Propose a follow-up PR (many spots)
-
-Too many to fold in without blowing the current diff's scope → propose **one or more separate follow-up PRs** (or a roadmap under `agents/roadmaps/`, using the shared-prefix convention) so the user reviews before merge. Creating the PR/roadmap is **permission-gated** — propose, get a yes, then create (`scope-control`, `commit-policy`).
-
-## Version-gated modernization
-
-Update stale idioms to the version the project **actually runs** — only when that version is **verified**:
-- **Establish the version first** from the manifest constraint (`composer.json` `require`, `package.json` `engines`, `.tool-versions`, lockfile) — use the **lowest** bound; on an ambiguous/monorepo range, ask once. **Unknown version → do not touch** (must fit the project structure — the `source-discovery` gate).
-- **Syntax-only, behavior-preserving idioms** (e.g. `array()` → `[]`, `isset($x)?$x:$d` → `$x ?? $d`, concat → template) provably equivalent → treat as a small fix (auto per the ladder).
-- **Behavioral changes** (`readonly`/typed properties, new semantics) and **any dependency/version bump** → **ask only**, never auto (a version bump stays under `minimal-safe-diff`'s no-dependency-bump prohibition; a pure syntax idiom is categorically different).
+**Fix now** — small + task-aligned; ALL five conditions hold: same request path/module · ≤ ~10 changed lines in one production file (plus its test file) · no public-API / response-shape change · no dependency bump, no migration · verification ships in the same commit. Anything outside → next tier. · **Note + ask** (batched, one numbered-options prompt after delivery) · **Follow-up PR** (many spots; creation stays permission-gated). Per-tier criteria + version-gated modernization + guardrails: the mechanics guideline below.
 
 ## Live-security carve-out (priority)
 
-A **live cross-user / cross-tenant data exposure** (`broken-access-control`) is not "note for later": a potential GDPR-notifiable breach (Art. 33, 72 h from discovery). Meets the fix-now bar → fix now with its negative test. Otherwise → **stop and surface it immediately** (a safety surface, visible even under an autonomous mandate — like the `no-pr-progress-comments` safety carve-out). Never defer silently, never look away.
-
-## Guardrails — don't become a nagging machine
-
-- Subordinate to `no-cheap-questions` (self-check items 3 & 14 — real trade-off, not a disguised continuation/commit ask), `autonomous-execution` (the end-of-session batch must not read as "shall I continue?"), `user-interaction`, `ask-when-uncertain` (one batched prompt = one question).
-- Threshold to surface at all: a **real, nameable** improvement with concrete benefit. Cosmetic nitpicks with no trade-off → drop silently. The live-security carve-out is the only case that interrupts or overrides autonomy.
+A **live cross-user / cross-tenant data exposure** (per `broken-access-control`) is not a "note for later": it is a potential GDPR-notifiable breach (Art. 33, 72 h from discovery). If it meets the fix-now bar → fix it now with its negative test. If not → **stop and surface it immediately** (a safety surface, visible even under an autonomous mandate — like the `no-pr-progress-comments` safety carve-out). Never defer it silently, never look away.
 
 ## When it fires
 
@@ -79,12 +52,15 @@ While implementing/modifying code you pass an issue outside the literal task. Al
 
 ## When NOT to fire
 
-- No issue spotted. Prose/docs-only. User fenced the scope ("just this one line").
+- No issue spotted. Prose/docs-only. The user fenced the scope ("just this one line").
 - The issue is the task itself — then it's just the task (no ladder needed).
 
+Body migrated to [`guideline:agent-infra/active-remediation-mechanics`](../docs/guidelines/agent-infra/active-remediation-mechanics.md) (per P4 of `road-to-kernel-and-router.md`) — per-tier fix-now/note+ask/follow-up-PR criteria, version-gated modernization, anti-nagging guardrails.
+Trigger-set above activates this routing on demand, independent of the discipline profile (ADR-110).
+
 ## See also
 
-- [`minimal-safe-diff`](minimal-safe-diff.md) — the carve-out above is bounded by it; everything outside the five conditions stays note+ask.
+- [`minimal-safe-diff`](minimal-safe-diff.md) — the fix-now carve-out is bounded by it; everything outside the five conditions stays note+ask.
 - [`broken-access-control`](broken-access-control.md) — the security category + the live-exposure carve-out.
 - [`prefer-enums-over-literals`](prefer-enums-over-literals.md) — an instance of this ladder (enum literals).
 - [`source-discovery-gate`](source-discovery-gate.md) — establishing the verified project version before modernizing.