@event4u/agent-config 1.17.0 → 1.19.0

package/.agent-src/commands/council/default.md

@@ -97,71 +97,65 @@ Council calls to billable members spend money. Even under
 `personal.autonomy: on`, the agent **must** ask before invoking any
 billable member.
 
-Compute `orchestrator.estimate(question, members, table)` over the
-**billable** subset only (`getattr(m, "billable", True)`). Manual
-members contribute `$0` and skip the estimate.
-
-Render the cost-confirmation numbered-options block per the
-`ai-council` skill (§ Pre-call estimate format) — per-member tokens
-+ USD, projected total, budget caps, then `1. Run / 2. Cancel`. If
-the resolved member set is **all-manual**, skip the gate entirely
-(spend = $0) and proceed directly to Step 4.
-
-Wait for the user's pick. `1` proceeds; anything else aborts.
-
-### 4. Bundle the context
-
-Use `scripts.ai_council.bundler`:
+Run the CLI in **estimate** mode first — it bundles the artefact, runs
+redaction, and prints the per-member preview without spending:
+
+```bash
+./agent-config council:estimate <question-file> \
+    [--input-mode prompt|roadmap] \
+    [--max-tokens N] \
+    [--mode-override api|manual] \
+    [--original-ask "<framing sentence>"]
+```
 
-- `prompt` mode → `bundle_prompt(text)`
-- `roadmap` mode → `bundle_roadmap(path)`
-- `diff` mode → `bundle_diff(base, head)`
-- `files` mode → `bundle_files(paths)`
+For `prompt:"<text>"` mode, write the text to a temp file first
+(`mktemp` is fine) and pass that path. For `roadmap:<path>`, pass the
+roadmap file with `--input-mode roadmap`. `diff` and `files` modes
+remain Phase 4 — for now ask the user to convert into a `prompt`.
 
-The bundler runs redaction + size guard. If `BundleTooLarge` raises,
-surface the byte count and ask the user to narrow scope. Do **not**
-truncate silently.
+The CLI prints a `council:estimate · members=N (billable=M)` line
+followed by per-member projected USD and a TOTAL. Render that to the
+user inside the cost-confirmation numbered-options block per the
+`ai-council` skill (§ Pre-call estimate format) — then `1. Run /
+2. Cancel`. If the billable count is `0`, skip the gate entirely
+(spend = $0) and proceed directly to Step 4.
 
-Print the manifest (what was included) and the excluded list before
-sending — gives the user a chance to abort if scope is wrong.
+Wait for the user's pick. `1` proceeds; anything else aborts.
 
-### 5. Run the orchestrator
+### 4. Run the CLI
 
-Members are constructed from the settings file plus
-`load_anthropic_key()` / `load_openai_key()`. Cost budget comes from
-`ai_council.cost_budget`.
+Once the user picks `1`, invoke the same arguments with `run` plus
+`--confirm` and an output path under `agents/council-sessions/`:
 
-Detect project context once via
-`scripts.ai_council.project_context.detect_project_context()` (reads
-`composer.json`, `package.json`, root `README.md` — never raises;
-empty-fields fall back to bare neutrality preamble).
+```bash
+./agent-config council:run <question-file> \
+    --output agents/council-sessions/<UTC-timestamp>.json \
+    --confirm \
+    [--rounds 1|2|3] \
+    [--input-mode …] [--max-tokens …] [--mode-override …] \
+    [--original-ask "<framing sentence>"]
+```
 
-Call:
+The CLI:
 
-```python
-consult(
-    members, question, budget,
-    table=table,
-    on_overrun=_handle_overrun,
-    project=project,
-    original_ask=original_ask,
-    rounds=rounds,  # 1 by default; 2-3 enables multi-round debate
-)
-```
+- bundles the artefact via `scripts.ai_council.bundler` (redaction +
+  size guard — `BundleTooLarge` exits 2 with the byte count),
+- builds members from `.agent-settings.yml` (refusing if
+  `ai_council.enabled` is false or no member is wired up),
+- detects project context via `detect_project_context()`,
+- calls `orchestrator.consult(...)` with the `cost_budget` from
+  settings,
+- writes the responses JSON to `--output`.
 
-`project` + `original_ask` flow into `handoff_preamble()` so each
-member receives a neutral context-handoff alongside the artefact
-(see `ai-council` skill § Neutrality — context-handoff). Members run
-**sequentially**; per-member errors are normalised — one failure
-does not abort the others. Define `_handle_overrun(event)` per the
-`ai-council` skill (§ Mid-flow overrun callback) to surface the user
-prompt before each breaching member.
+Per-member errors are normalised — one failure does not abort the
+others. Exit code `1` means **all** members errored; `0` means at
+least one succeeded; `2` means the gate refused before any spend.
 
-### 6. Render the report
+### 5. Render the report
 
-Use `scripts.ai_council.orchestrator.render(responses)` for the
-per-member sections (stacked, not side-by-side — narrow terminals).
-Then write the **Convergence / Divergence** section yourself:
+Use `./agent-config council:render <output.json>` for the per-member
+sections (stacked, not side-by-side — narrow terminals). Then write
+the **Convergence / Divergence** section yourself:
 
 - **Agreements** — points all members made (or did not contradict).
 - **Disagreements** — points where members took opposing positions.
@@ -173,49 +167,53 @@ End with a numbered-options block asking the user how to proceed
 (e.g. update the roadmap, request a second round, ignore the
 critique).
 
-### 7. Hard floor — text only
+### 6. Hard floor — text only
 
 `/council` produces **text**. It does **NOT**:
 
 - Edit any file in the project.
 - Open, comment on, or merge any PR.
 - Run `git` commands beyond `git diff` (read-only).
-- Persist API responses outside the current chat unless the user
-  explicitly asks (Phase 4 — out of scope for v1).
 
-This is restated in step 7 deliberately. The neutrality framing
-loses meaning if the council can act on the project directly.
+The CLI persists the responses JSON under `agents/council-sessions/`
+for traceability, but the agent never edits other project files on
+the user's behalf. The neutrality framing loses meaning if the
+council can act on the project directly.
 
 ## Failure modes
 
-- **Member SDK not installed** → tell the user exactly which `pip
-  install` runs (`pip install anthropic` / `pip install openai`).
-  Do not fall back to mocks.
-- **Key file mode drift** → refuse and point at the install script.
+- **CLI exits 2, "ai_council.enabled is false"** → tell the user how
+  to flip it on; do not flip it autonomously.
+- **CLI exits 2, "no council member has `enabled: true`"** → list the
+  install commands (`./agent-config keys:install-anthropic`,
+  `./agent-config keys:install-openai`) and stop.
+- **CLI raises `BundleTooLarge`** → surface the byte count and ask the
+  user to narrow scope. Do not truncate silently.
+- **Member SDK not installed** → CLI prints the missing-package
+  message; tell the user exactly which `pip install` runs
+  (`pip install anthropic` / `pip install openai`). Do not fall back
+  to mocks.
+- **Key file mode drift** → CLI refuses; point at the install script.
   The 0600 contract is non-negotiable.
-- **Manual mode + non-interactive stdin** → `ManualClient` reads
-  pasted replies from stdin terminated by a line containing only
-  `END`. If stdin is closed before any reply lands, the member
-  returns empty text with `error="manual_aborted"`; render the
-  partial result and ask the user.
-- **Invalid mode value** → `resolve_mode()` raises
-  `InvalidModeError` with the exact settings path. Surface verbatim
-  and stop.
-- **Cost budget exceeded mid-fan-out** → render the partial
-  responses and clearly mark the unfinished members with their
-  `cost_budget_exceeded` error. Do not silently retry.
+- **Invalid mode value** → CLI surfaces `InvalidModeError` with the
+  exact settings path. Surface verbatim and stop.
+- **Cost budget exceeded mid-fan-out** → render the partial responses
+  and clearly mark unfinished members with `cost_budget_exceeded`. Do
+  not silently retry.
 - **Stale price table, refresher fails (offline)** → state the
   failure, re-offer "continue with stale table / cancel", do not
   proceed silently.
 - **`.agent-prices.md` corrupt (missing frontmatter or columns)** →
   surface the parse error, suggest deleting the file to bootstrap
   fresh from defaults; never silently fall back.
-- **All members error** → render the errors and ask the user
-  whether to fix and retry, or abort.
+- **All members error (CLI exit 1)** → render the errors via
+  `council:render` and ask the user whether to fix and retry, or
+  abort.
 
 ## See also
 
 - `/council` — cluster dispatcher.
 - `ai-council` skill — neutrality guidelines, anti-patterns, redaction expectations.
 - `subagent-orchestration` skill — internal multi-agent variant (no network calls).
+- `scripts/council_cli.py` — the CLI entry point this command wraps.
 - `docs/customization.md` § Available settings → `ai_council.*`.

package/.agent-src/commands/feature/roadmap.md

@@ -111,6 +111,28 @@ For each roadmap, work through the phases interactively:
 - Single: `agents/roadmaps/{feature-name}.md`
 - Multiple: `agents/roadmaps/{feature-name}-{aspect}.md`
 
+**Collision check before writing.** For each planned filename, scan
+the entire roadmap namespace — active, `archive/`, `skipped/`, and
+nested subdirs:
+
+```bash
+find agents/roadmaps -type f -iname "{feature-name}.md" 2>/dev/null
+# Module-scoped:
+find app/Modules/{Module}/agents/roadmaps -type f -iname "{feature-name}.md" 2>/dev/null
+```
+
+If any planned name already exists anywhere under the namespace,
+**STOP** and ask (in the user's language):
+
+> Filename `{feature-name}.md` already exists at `<path>` (archived/skipped/active).
+>
+> 1. Pick a different name — suggest `{feature-name}-v2` or `{feature-name}-{scope}`
+> 2. Open the existing roadmap first — revival or extension may fit
+> 3. Abort
+
+Re-run the check after a rename. Never silently overwrite, never
+auto-suffix without the user's pick.
+
 ### 5. Link roadmaps in the feature plan
 
 Update the feature file's `## Roadmaps` section:

package/.agent-src/commands/roadmap/create.md

@@ -92,8 +92,40 @@ Show the complete roadmap to the user and ask (in their language) if anything sh
 ### 6. Save the file
 
 - Generate a filename from the title: kebab-case, e.g. `optimize-webhook-jobs.md`.
-- Save to the chosen location.
-- Show the final path.
+
+**Before saving, check for filename collisions across the entire
+roadmap namespace** — active, `archive/`, `skipped/`, and any nested
+subdirs (e.g. `agent-memory/`). A new roadmap that shadows an
+archived or skipped one silently buries history; never overwrite,
+never auto-suffix without the user's pick.
+
+```bash
+NAME="<kebab-case-name>.md"
+# Project-root roadmaps:
+find agents/roadmaps -type f -iname "$NAME" 2>/dev/null
+# Module-scoped roadmaps (only if step 1 picked a module):
+find app/Modules/<Module>/agents/roadmaps -type f -iname "$NAME" 2>/dev/null
+```
+
+Use `-iname` (case-insensitive) so case-only differences still count
+as a collision on case-sensitive filesystems.
+
+If the search returns one or more hits → **STOP**. Show the matches
+and ask (in the user's language):
+
+> Found N existing roadmap(s) with this name:
+>   - `agents/roadmaps/archive/<file>.md` (archived)
+>   - `agents/roadmaps/skipped/<file>.md` (skipped)
+>
+> 1. Pick a different name — suggest `<name>-v2`, `<name>-<scope>`, or `<name>-<YYYY-MM>`
+> 2. Open the existing file first — revival or extension may be the right move
+> 3. Abort creation
+
+- **1** → re-prompt for name, re-run the collision check, repeat until clean.
+- **2** → read the existing roadmap, summarize state, hand back to the user.
+- **3** → stop without writing anything.
+
+Only when the search is empty: save to the chosen location and show the final path.
 
 ### 7. Update the progress dashboard
 
@@ -150,12 +182,12 @@ If yes → switch to the `roadmap-execute` command workflow with the newly creat
   violates [`roadmap-progress-sync`](../rules/roadmap-progress-sync.md)
   Iron Law #2.
 - **Status is binary: `ready` (default) or `draft`.** Create new
-  roadmaps as **ready** — no `status:` field needed, ready is
-  implicit. Only mark `status: draft` (in YAML frontmatter) when the
+  roadmaps as **ready** — no `status:` field needed.
+  Only mark `status: draft` (in YAML frontmatter) when the
   user explicitly says it should be hidden from the dashboard (still
   being authored, awaiting upstream decisions, capture-only synthesis
   without executable phases). If the user wants draft, ask once at
   step 3 — do not infer it.
-- **Write the roadmap in English** (per project convention for `.md` files).
-- Follow the roadmap template from `.augment/templates/roadmaps.md`.
+- Follow the roadmap template from `.augment/templates/roadmaps.md`; write in English (project convention).
 - Keep the file focused: 500–1000 lines max. If larger, suggest splitting.
+- **Never overwrite an existing roadmap.** Step 6 scans `active/`, `archive/`, `skipped/` (+ subdirs); on collision → STOP, present rename / open / abort. Auto-suffix requires explicit pick.

package/.agent-src/commands/roadmap/execute.md

@@ -33,7 +33,26 @@ suggestion:
   > "Phase 2: {name} — noch nicht begonnen"
   > "Next open step: {step description}"
 
-### 3. Execute step by step
+### 3. Resolve quality cadence (read once, before any step runs)
+
+Read `roadmap.quality_cadence` from `.agent-settings.yml`:
+
+| Value | When the project's quality pipeline runs |
+|---|---|
+| `end_of_roadmap` (default) | Once, in step 7 — before archiving |
+| `per_phase` | Once after every completed phase, plus step 7 |
+| `per_step` | After every completed step, plus step 7 (legacy verbose) |
+
+Missing key, unreadable file, or unknown value → fall back to `end_of_roadmap`.
+Cite the resolved cadence once in step 2's summary so the user can override it.
+
+The Iron Law `verify-before-complete` still applies — fresh quality
+output is mandatory before any "roadmap complete" claim, regardless of
+cadence. Step checkboxes and `agents/roadmaps-progress.md` are ALWAYS
+updated in the same response per `roadmap-progress-sync`; cadence only
+gates the *quality pipeline*, not progress tracking.
+
+### 4. Execute step by step
 
 For each open step:
 
@@ -41,28 +60,35 @@ For each open step:
 2. **Analyze** the codebase to understand what's needed for this step.
 3. **Present a plan** — what files to change, what approach to take.
 4. **Ask for confirmation**: "Should I implement this step?"
-   - If yes → implement, run quality checks, mark step as done in the roadmap file.
+   - If yes → implement, mark the step `[x]` in the roadmap file.
    - If no / skip → move to the next step.
    - If the user wants to stop → stop and summarize progress.
 
-### 4. After each step
+### 5. After each step
 
-- Update the roadmap file: mark the completed step (e.g. `[x]` or add a completion note).
-- Run quality tools if code was changed (PHPStan at minimum).
+- Update the roadmap file: mark the completed step `[x]` (or `[~]` / `[-]`).
 - Regenerate `agents/roadmaps-progress.md` — `./agent-config roadmap:progress`.
+- **Quality pipeline** — run only when `quality_cadence: per_step`.
+  Otherwise skip and proceed.
 - Ask: "Continue with the next step?"
 
-### 5. After all steps in a phase
+### 6. After all steps in a phase
 
 - Summarize what was accomplished in the phase.
+- **Quality pipeline** — run when `quality_cadence: per_phase` (or `per_step`).
+  Skip when `end_of_roadmap`.
 - Ask: "Phase {N} complete. Continue with Phase {N+1}?"
 
-### 6. When done (or stopped)
+### 7. When done (or stopped)
 
 - Summarize total progress: steps completed, steps remaining.
 - Update the roadmap file with the current status.
 - Regenerate the dashboard one last time so it matches the final state.
-- **If ALL steps are done** → trigger the completion & archiving workflow from the `roadmap-management` skill.
+- **If ALL steps are done** → run the project's quality pipeline now
+  (this is the `verify-before-complete` evidence gate; required for
+  every cadence value, including `end_of_roadmap`). On green, trigger
+  the completion & archiving workflow from the `roadmap-management`
+  skill. On red, stop, surface the failures, do not archive.
 
 ### Rules
 
@@ -77,6 +103,7 @@ For each open step:
       to execute the listed commit steps, then proceed silently per the answer.
 - **Push, merge, branch, PR, tag** stay permission-gated by [`scope-control`](../rules/scope-control.md#git-operations--permission-gated).
 - **Always ask before implementing** a step — never auto-execute.
-- **Run quality checks** after each code change.
+- **Quality cadence** is set by `roadmap.quality_cadence` (see step 3).
+  Step 7 always runs the pipeline before archival regardless of cadence.
 - If a step is unclear or too large, suggest breaking it down further.
 - If a step reveals a problem not covered in the roadmap, flag it to the user.

package/.agent-src/rules/agent-authority.md

@@ -1,5 +1,6 @@
 ---
 type: "always"
+tier: "3"
 description: "Priority Index for the four authority rules — Hard Floor → Permission Gate → Commit Default → Trivial-vs-Blocking; read first, route to canonical rule"
 alwaysApply: true
 source: package

package/.agent-src/rules/agent-docs.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2a"
 description: "Reading, creating, or updating agent documentation, module docs, roadmaps, or AGENTS.md"
 source: package
 ---

package/.agent-src/rules/analysis-skill-routing.md

@@ -1,5 +1,6 @@
 ---
 type: auto
+tier: "3"
 description: "When choosing an analysis skill, route to the narrowest matching skill instead of defaulting to broad analysis"
 source: package
 ---

package/.agent-src/rules/architecture.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "3"
 alwaysApply: false
 description: "Architecture rules for creating new files, classes, controllers, modules, or making structural decisions about project organization"
 source: package

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

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2a"
 alwaysApply: false
 description: "Creating a new skill, rule, command, or guideline, or significantly rewriting one — runs a mandatory Understand → Research → Draft sequence before any artifact content is written."
 source: package

package/.agent-src/rules/artifact-engagement-recording.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "mechanical-already"
 alwaysApply: false
 description: "After a /implement-ticket or /work phase-step (refine/memory/analyze/plan/implement/test/verify/report) or full task — emit one telemetry:record call with consulted+applied ids when enabled"
 source: package

package/.agent-src/rules/ask-when-uncertain.md

@@ -1,5 +1,6 @@
 ---
 type: "always"
+tier: "3"
 description: "Ask when uncertain — don't guess, assume, or improvise"
 alwaysApply: true
 source: package

package/.agent-src/rules/augment-portability.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "mechanical-already"
 description: "Editing or creating files inside .augment/ directory — skills, rules, commands, templates, contexts must be project-agnostic"
 source: package
 load_context:

package/.agent-src/rules/augment-source-of-truth.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "1"
 description: "Creating, editing, or modifying files inside .agent-src/ or .augment/ — the source of truth is .agent-src.uncompressed/, never edit the generated directories directly"
 source: package
 load_context:

package/.agent-src/rules/autonomous-execution.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "3"
 description: "Deciding whether to ask the user or just act on a workflow step — trivial-vs-blocking classification, autonomy opt-in detection, commit default; defers to non-destructive-by-default for the Hard Floor"
 alwaysApply: false
 source: package

package/.agent-src/rules/capture-learnings.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2a"
 description: "After completing a task where a repeated mistake or successful pattern appeared — capture as rule or skill"
 alwaysApply: false
 source: package

package/.agent-src/rules/chat-history-cadence.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "mechanical-already"
 description: "Appending to .agent-chat-history — cadence boundaries (per_turn/per_phase/per_tool), turn-check ownership refusal handling, never writing the file directly; cadence is the trigger, not reply length"
 alwaysApply: false
 source: package
@@ -102,6 +103,39 @@ On cloud surfaces (Claude.ai Web, Skills API) cadence is **inert** —
 no append calls, no `scripts/`, no JSONL file. Treat
 `chat_history.enabled` as `false`.
 
+## Copilot fallback
+
+GitHub Copilot has no `SessionStart` / `PostToolUse` / `Stop` hook
+surface, so `scripts/chat_history.py hook-dispatch` cannot fire
+structurally. `.agent-chat-history` is not maintained for the agent
+unless the agent runs the cooperative path itself.
+
+Treat Copilot as the **CHECKPOINT path** described above — gates 1 +
+2 are cooperative:
+
+1. Run `turn-check` on the first turn (and after any ownership
+   reset) to establish ownership against the first user message.
+2. Run `append --first-user-msg "<msg>" --type <…> --json '<…>'` at
+   every cadence boundary, exactly as the cooperative path
+   specifies.
+3. Surface ownership-refusal exit `3` to the user; do not swallow it.
+
+The state "file" the hook would have written is `.agent-chat-history`
+itself (JSONL, project root). The manual command that reproduces a
+single hook-dispatch step is the same one the dispatcher would
+have invoked:
+
+```bash
+scripts/chat_history.py hook-dispatch \
+  --platform copilot \
+  --event <session_start|post_tool_use|stop> \
+  < envelope.json
+```
+
+— but in practice the cooperative `turn-check` + `append` calls
+above are the supported Copilot path; `hook-dispatch` is mainly the
+dispatcher's entry point.
+
 ## Interactions & references
 
 - Sibling rules: [`chat-history-ownership`](chat-history-ownership.md) (gate 1 — turn-check) · [`chat-history-visibility`](chat-history-visibility.md) (gate 3 — heartbeat marker).

package/.agent-src/rules/chat-history-ownership.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "1"
 description: "First turn or reference to .agent-chat-history — detects ownership (match/returning/foreign/missing) and HOOK/ENGINE/CHECKPOINT/MANUAL path classification with numbered-options prompt"
 alwaysApply: false
 source: package

package/.agent-src/rules/chat-history-visibility.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "mechanical-already"
 description: "Emitting the chat-history heartbeat marker — paste subprocess stdout verbatim or nothing, never type from memory, hybrid mode prints on drift only, slip handling per language-and-tone"
 alwaysApply: false
 source: package

package/.agent-src/rules/cli-output-handling.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2a"
 alwaysApply: false
 description: "Running CLI commands that produce verbose output — git, tests, linters, docker, build tools, artisan, npm, composer. Wrap with rtk when installed; tail/grep is fallback."
 source: package
@@ -9,8 +10,7 @@ load_context:
 
 # Development Efficiency
 
-Loaded when actively working with code, tests, quality tools, CLI, or analysis.
-For communication and response style rules → see the always-loaded `token-efficiency` rule.
+Loaded for code, tests, quality tools, CLI, analysis. Communication / response style → always-loaded `token-efficiency`.
 
 ## Iron Law — rtk first, tail/grep fallback
 

package/.agent-src/rules/command-suggestion-policy.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "mechanical-already"
 description: "User prompt without /command but matching an eligible slash command — surface matches as numbered options with as-is escape hatch; never auto-executes, user always picks"
 alwaysApply: false
 source: package

package/.agent-src/rules/commit-conventions.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2a"
 alwaysApply: false
 description: "Git commit message format, branch naming, conventional commits, committing, pushing, or creating pull requests"
 source: package

package/.agent-src/rules/commit-policy.md

@@ -1,5 +1,6 @@
 ---
 type: "always"
+tier: "safety-floor"
 description: "Commit policy — never commit and never ask about committing unless the user said so this turn, the roadmap authorizes it, or a commit command is invoked"
 alwaysApply: true
 source: package

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

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "1"
 alwaysApply: false
 description: "When debugging, fixing errors, or running long conversations — 3-failure stop rule, tool-loop detection, fresh-chat triggers"
 source: package
@@ -7,6 +8,12 @@ source: package
 
 # Context Hygiene
 
+> **Enforced by:** [`scripts/context_hygiene_hook.py`](../../scripts/context_hygiene_hook.py)
+> on Augment + Claude Code (`PostToolUse`). The hook maintains
+> `agents/state/context-hygiene.json` (turn count, loop signal,
+> freshness milestones at 20/40/60); the prose below is the spec the
+> hook implements and the agent-side fallback.
+
 ## Conversation Freshness
 
 Monitor for **context decay** — long conversations degrade quality and waste tokens.
@@ -88,3 +95,24 @@ If you need an ignored skill: read its SKILL.md directly, apply guidance, then a
 > 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.py` cannot run structurally and
+`agents/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
+python3 scripts/context_hygiene_hook.py < /dev/null
+```
+
+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.