@event4u/agent-config 8.13.0 → 9.0.0

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.

package/dist/agent-src/rules/artifact-drafting-protocol.md

@@ -14,6 +14,8 @@ triggers:
   - phrase: "new guideline"
   - phrase: "neue Regel"
   - phrase: "bau mir ein Skill"
+routes_to:
+  - "guideline:agent-infra/artifact-drafting-protocol-mechanics"
 workspaces: [agent-config-maintainer, engineering]
 packs: [meta]
 ---
@@ -42,71 +44,9 @@ rewrites with a specific target phrasing, < 10-line edits, or explicit
 bypass (*"just write it"*, *"skip protocol"*, *"einfach machen"*).
 Fires once per creation task, not once per edit.
 
-## Phase A — Understand
+## The three phases
 
-Ask up to **5** clarifying questions (numbered options, each with a
-*"skip / I don't know yet"* escape):
-
-1. **Problem** — what does this solve that no existing artifact solves?
-2. **Trigger surface** — which user phrasings should fire this?
-3. **Should-trigger examples** — 2-3 in the user's words.
-4. **Near-miss cases** — 2-3 phrasings that must **not** fire.
-5. **Artifact type** — skill, rule, command, or guideline? Offer a
-   3-line primer if unsure.
-
-If the user skips Q1 or Q5, stop and surface the ambiguity — don't guess.
-
-## Phase B — Research
-
-Run the **search protocol** from
-[`learning-to-rule-or-skill` § 4](../skills/learning-to-rule-or-skill/SKILL.md#4-check-for-overlap--search-protocol-mandatory)
-— `ls` all four surfaces (`skills/`, `rules/`, `guidelines/`, `commands/`),
-grep with **solution-words AND problem-words**, scan sub-directory
-taxonomies, then **open and skim** the 3 nearest matches. A negative grep
-alone is not proof of no overlap. Report the top 3-5 most-similar
-artifacts and ask (numbered options):
-
-- Extend an existing one?
-- Create a new one — gap is real?
-- Show overlap first?
-- Promote via `learning-to-rule-or-skill` instead?
-
-Carry the summary into the commit message (*"Reviewed before drafting:
-X, Y"*).
-
-## Phase C — Draft
-
-Propose **2-3 description variants** — Conservative / Pushy
-(per `skill-quality`) / Concrete (embedded trigger example). User picks
-or merges. Only then draft the body. Surface every structural choice
-(size class, section order) as numbered options if in doubt.
-
-Enforce size live: *"Body is at 420/500 lines. Split?"* (budgets per
-`size-enforcement`). New skills also get an `evals/triggers.json` stub
-(5 should-trigger + 5 should-not-trigger). See `skill-writing` § 1c.
-
-## Roadmap-run batch mode — the ONE structured bypass
-
-When a `/roadmap:process-*` run starts under an **accepted execution
-contract** ([`roadmap-execution-contract`](../contexts/execution/roadmap-execution-contract.md))
-whose pre-scan detected artifact-authoring steps, the protocol runs in
-batch mode for exactly those artifacts:
-
-- **Phase B (Research) runs ONCE at contract time, against the CURRENT
-  artifact state** — one overlap scan covering every artifact the
-  roadmap plans; results (nearest matches, extend-vs-create verdicts)
-  are surfaced inside the contract summary the user accepts. This is
-  why authoring-time-only checking is not enough: a sibling roadmap may
-  have landed overlapping artifacts between authoring and execution.
-- **Phases A (Understand) and C (Draft) run non-interactively during
-  the run** — the roadmap step text is the Understand input; the
-  contract acceptance is the approval that the per-phase prompts exist
-  to obtain.
-- **Scope is the batch, nothing more.** An artifact NOT declared in the
-  roadmap (discovered mid-run) triggers the full interactive protocol —
-  or, under the contract, the scope-out-of-roadmap halt.
-- Batch mode never skips the Research pass itself — it relocates and
-  batches it. `artifact_protocol: skip` does not exist.
+**A — Understand** (≤ 5 clarifying questions: problem, trigger surface, should-trigger examples, near-misses, artifact type) · **B — Research** (mandatory four-surface overlap scan; open + skim the 3 nearest matches; extend-vs-create decision) · **C — Draft** (2-3 description variants first, then the body; live size enforcement). Per-phase procedure + the roadmap batch-mode carve-out: the mechanics guideline below.
 
 ## Golden rules
 
@@ -118,5 +58,8 @@ batch mode for exactly those artifacts:
 - Commit only on approval.
 - Bypass is legitimate — *"just write it"* drops the protocol immediately.
 
+Body migrated to [`guideline:agent-infra/artifact-drafting-protocol-mechanics`](../docs/guidelines/agent-infra/artifact-drafting-protocol-mechanics.md) (per P4 of `road-to-kernel-and-router.md`) — Phase A/B/C procedure detail + the roadmap-run batch-mode carve-out (Research-once-at-contract-time, batch scope, no `artifact_protocol: skip`).
+Trigger-set above activates this routing on demand, independent of the discipline profile (ADR-110).
+
 Extends (cross-link, don't restate): `ask-when-uncertain`,
 `improve-before-implement`, `user-interaction`, `skill-quality`.

package/dist/agent-src/rules/context-hygiene.md

@@ -8,6 +8,8 @@ triggers:
   - intent: "tool loop"
   - intent: "fresh chat"
   - keyword: "3-failure"
+routes_to:
+  - "guideline:agent-infra/context-hygiene-mechanics"
 workspaces: [agent-config-maintainer, construction, engineering, finance, founder, gtm, legal-review-prep, ops, product, small-business]
 packs: [meta]
 ---
@@ -24,31 +26,13 @@ packs: [meta]
 
 Monitor for **context decay** — long conversations degrade quality and waste tokens.
 
-**Suggest a new chat when:**
-
-- Conversation exceeds **~20 user messages**
-- Topic **changes completely**
-- Re-reading files already in context
-- **15+ completed tasks** and new unrelated topic
-- Branch changed since start
-- ~24 hours passed
+**Suggest a new chat when:** ~20+ user messages · complete topic change ·
+re-reading files already in context · 15+ completed tasks and a new unrelated
+topic · branch changed since start · ~24 hours passed.
 
 **Repeat** at multiples: messages 20/40/60, tasks 15/30/45.
-**ONLY at exact thresholds.** Between: silence.
-
-**How to suggest:**
-
-Estimate token cost: responses × ~1,500 tokens.
-
-```
-> ⚡ This conversation has ~{N} messages (~{N×1500} tokens history cost — charged on EVERY request).
-> A fresh chat saves ~{N×1500} input tokens per request.
->
-> 1. Start fresh — I'll initiate a session handoff
-> 2. Continue here
-```
-
-**If the user picks 1:** Initiate a session handoff or start fresh.
+**ONLY at exact thresholds.** Between: silence. Suggestion template
+(token-cost estimate + numbered options): the mechanics guideline below.
 
 ## The 3-Failure Rule
 
@@ -58,40 +42,20 @@ When **3 consecutive attempts** at the same task fail (code fix, test fix, confi
 2. **State dump** — summarize what was tried, what failed, and what you know so far.
 3. **Recommend fresh start** — suggest a fresh session with the state dump as context, or ask for a different approach.
 
-**What counts as a failure:**
-
-- Code change that doesn't fix the problem
-- Test that still fails after the fix
-- Quality check (type-checker, linter, formatter) that still errors
-- Build/deploy that fails after config change
-
-**Does NOT reset the counter:** Unrelated tasks. User providing new information (course correction).
+**What counts as a failure:** a change that doesn't fix the problem · a test still failing after the fix · a quality check still erroring · a build/deploy failing after a config change. **Does NOT reset the counter:** unrelated tasks; the user providing new information (course correction).
 
 **Failure identity — same error vs new error.** Failure signature = **same target + same error class** (same failing test + same assertion/exception, same lint rule id, same build error).
 
 - **Same failure signature twice → stop and pivot now.** Don't burn the third attempt on a near-identical retry of a fix that already failed the same way — a repeated identical signature means the hypothesis is wrong, not under-applied. Change strategy (re-read source, new hypothesis, ask).
 - **New error signature each attempt = progress.** Peeling one error to reveal a different one is forward motion; counter continues — learning, not looping.
 
-**Hard-blocker classes — skip retries, go straight to ask/surface.** On the **first** occurrence, do not count toward the 3 — stop and surface:
-
-- Missing credentials / unset required secret or token.
-- Permission denied (auth/authz, file mode, protected branch, scope).
-- Spend / quota / rate limit reached (billing cap, API quota, 429 that won't self-clear).
-- External-service `5xx` / outage / DNS-unreachable — a dependency is down, not your code.
-
-Retrying a hard-blocker is the canonical wasted-attempt; the fix is a decision or external change only the user/environment can make.
+**Hard-blocker classes — skip retries, go straight to ask/surface.** On the **first** occurrence, do not count toward the 3 — stop and surface: missing credentials / unset secret · permission denied · spend / quota / rate limit reached · external-service 5xx / outage. Retrying a hard-blocker is the canonical wasted attempt; the fix is a decision or external change only the user/environment can make.
 
 ## Tool Loop Detection
 
 Calling the **same tool** more than **2 times in a row** with similar parameters = loop.
-
-**Immediate action:**
-1. **STOP** all tool calls.
-2. **Do the task directly** — write the code, run the command, answer the question.
-3. If you can't proceed — ask the user for help.
-
-`sequentialthinking` is especially prone to loops. Use at most **once** per task,
-NEVER for simple file operations, command execution, or straightforward edits.
+**Immediate action:** 1. STOP all tool calls. 2. Do the task directly. 3. Can't proceed → ask the user.
+`sequentialthinking` is especially prone to loops: at most **once** per task, NEVER for simple file operations, command execution, or straightforward edits.
 
 ## Read-Loop Detection — the 15 / 25 rule
 
@@ -101,74 +65,16 @@ EVERY TURN MUST EDIT, RUN, OR ASK.
 ```
 
 **Read-only turn:** only `view` / `codebase-retrieval` / `grep` /
-`git log` / `git show`. No `str-replace-editor`, `save-file`, no
-test/build/quality run, no `git commit`.
-
-**15-min warning (3 read-only turns in a row) — change approach.**
-Next turn MUST contain at least one of: an edit, a test/build/quality
-command, or an explicit user question. Self-check:
-
-1. Source expectation known? If no → read **once**, then act.
-2. Can a single failing test name the error? If yes → run it now.
-3. Regression in working code? → `git log` + `git show <sha> -- <file>`.
-4. Guessing at mock / payload shape? → read the producer **once**.
-
-**25-min abort (5 read-only turns) — STOP and ask:**
+`git log` / `git show`. No edit/save, no test/build/quality run, no `git commit`.
 
-```
-> ⛔ Loop: N read-only turns, ~M min. Read: <files>. Hypothesis: <X>.
-> 1. Different approach (suggestion: <Y>)
-> 2. Point me at the right spot
-> 3. Fresh chat with state dump
-```
-
-Non-bypassable. Autonomous mandate (`/work`, `/roadmap:process-*`,
-"entscheide selbst") does **not** lift the abort — it is the safety
-net that protects autonomy from becoming a token sink.
-
-Debug procedure for "I'm in a read loop fixing tests" →
-[`systematic-debugging § Debug micro-loop`](../skills/systematic-debugging/SKILL.md#debug-micro-loop--one-test-one-fix-one-re-run).
-
-## State dump format
-
-```
-## State Dump: [Task]
-### Tried: 1. [Approach] → [Why failed] 2. ... 3. ...
-### Known: [Key facts]
-### Hypothesis: [Best guess for root cause]
-### Recommendation: [Next approach for fresh session]
-```
+**15-min warning (3 read-only turns in a row) — change approach.** The next turn MUST contain at least one of: an edit, a test/build/quality command, or an explicit user question (self-check in the mechanics guideline).
 
-Use `/agent-handoff` to generate a context summary for a fresh conversation.
+**25-min abort (5 read-only turns) — STOP and ask** with the abort block (template in the mechanics guideline). Non-bypassable: an autonomous mandate does **not** lift the abort — it is the safety net that protects autonomy from becoming a token sink.
 
-## Augment-specific: Ignored Skills Recovery
+Body migrated to [`guideline:agent-infra/context-hygiene-mechanics`](../docs/guidelines/agent-infra/context-hygiene-mechanics.md) (per P4 of `road-to-kernel-and-router.md`) — the freshness-suggestion template, the read-loop self-check + abort block, the state-dump format + `/agent-handoff` pointer, the Augment ignored-skills recovery flow, and the Copilot no-hook fallback (manual `context_hygiene_hook` refresh).
+Trigger-set above activates this routing on demand, independent of the discipline profile (ADR-110).
 
-Skills excluded via `.augmentignore` don't appear in `<available_skills>`.
-If you need an ignored skill: read its SKILL.md directly, apply guidance, then ask:
-
-```
-> 💡 I loaded `{name}` manually — currently ignored in `.augmentignore`.
-> 1. Remove from ignore — relevant for this project
-> 2. Keep ignored — one-off
-```
-
-## Copilot fallback
-
-GitHub Copilot has no `PostToolUse` hook surface, so
-`scripts/context_hygiene_hook.ts` cannot run structurally and
-`agents/runtime/state/context-hygiene.json` is not maintained automatically
-(turn count, loop signal, freshness milestones at 20/40/60).
-
-The cooperative path: track turns and tool-loop signals from memory
-during the conversation and apply the suggest-a-new-chat / 3-failure
-stop / loop-detection rules above. To refresh the state file
-manually so the dashboard or another tool can read the latest
-counters, run:
-
-```bash
-./scripts-run src/scripts/context_hygiene_hook < /dev/null
-```
+## See also
 
-The script reads from stdin if a JSON envelope is provided and
-otherwise writes a no-op snapshot under the shared dispatcher lock.
-Exit code is always 0 — hooks must never block the agent loop.
+- [`guideline:agent-infra/context-hygiene-mechanics`](../docs/guidelines/agent-infra/context-hygiene-mechanics.md) — templates + per-host procedures.
+- [`systematic-debugging § Debug micro-loop`](../skills/systematic-debugging/SKILL.md) — the read-loop debug procedure.