@event4u/agent-config 1.18.0 → 1.20.0

package/docs/hook-payload-capture.md

@@ -0,0 +1,221 @@
+# Hook payload capture guide
+
+**Purpose:** walk through the live-session payload capture for one platform
+in roughly 5 minutes, so the corresponding entry in
+[`agents/contexts/chat-history-platform-hooks.md`](../agents/contexts/chat-history-platform-hooks.md)
+can move from `docs-verified` to `payload-verified`.
+
+**Scope:** Cursor · Cline · Windsurf · Gemini CLI. Augment Code and Claude
+Code already shipped as `docs-verified` in Phase 1 of the now-archived
+[`road-to-verified-chat-history-platforms.md`](../agents/roadmaps/archive/road-to-verified-chat-history-platforms.md).
+Cowork is upstream-blocked separately
+([`#40495`](https://github.com/anthropics/claude-code/issues/40495)) and
+not in scope here.
+
+**Why this is opportunistic:** the payload-verified upgrade is a nice-to-have.
+The shipping `docs-verified` extractors already match the vendor docs —
+captures are insurance against silent vendor-side schema drift. Pick one
+platform when convenient; do not run all four in one sitting unless you
+already have all four IDEs installed and licensed.
+
+## Pre-flight (one-time, ~30 seconds)
+
+```bash
+cd /path/to/agent-config
+
+# Confirm the dispatcher is wired in this project (idempotent — safe to rerun).
+# Replace <platform> with cursor / cline / windsurf / gemini as appropriate
+# when you reach that platform's section.
+python3 scripts/install.py --<platform>
+
+# Confirm the trampoline + project-scope hooks file landed.
+./agent-config hooks:status | grep -E "^[ ✓✅⚠️❌·] (cursor|cline|windsurf|gemini)"
+```
+
+`hooks:status` should report `installed` for the platform you just wired
+(or `missing` if the project-scope file did not land — in that case rerun
+the install with `--force`).
+
+## Common capture loop (steps reused on every platform)
+
+```bash
+# 1. Pick a per-platform capture dir (gitignored; never committed).
+export AGENT_HOOK_CAPTURE_DIR="$HOME/.agent-config-captures/<platform>"
+mkdir -p "$AGENT_HOOK_CAPTURE_DIR"
+
+# 2. Restart / reload the platform so it picks up the env var.
+#    Per-platform commands below.
+
+# 3. Run ONE short, boring session in the platform.
+#    Recommended prompt: "echo hello" or "what time is it".
+#    Goal is to capture the envelope shape, not interesting content.
+
+# 4. Confirm capture files exist.
+ls -1 "$AGENT_HOOK_CAPTURE_DIR" | head
+
+# 5. Redact (replaces user-content fields with <REDACTED>;
+#    envelope keys preserved).
+python3 scripts/redact_hook_capture.py "$AGENT_HOOK_CAPTURE_DIR" --strict
+
+# 6. Pick the smallest representative file.
+ls -1Sr "$AGENT_HOOK_CAPTURE_DIR"/*.redacted.json | head -1
+
+# 7. cat it; copy the JSON; paste into the archived roadmap section
+#    (see § Where to paste below).
+```
+
+The redaction step is non-negotiable. The goal is to lock schemas, not to
+archive conversations.
+
+## Per-platform notes
+
+### Cursor (~5 min)
+
+- **Install:** `python3 scripts/install.py --cursor` (project) or
+  `--cursor-user-hooks` (covers every project you open).
+- **Restart:** quit Cursor (Cmd+Q on macOS), then relaunch from the
+  shell where you exported `AGENT_HOOK_CAPTURE_DIR` so the env var
+  propagates to the renderer process. Reopening a window from the
+  Dock will not inherit the env.
+- **Trigger event:** type a prompt in Cursor's agent panel and let it
+  finish. Expected captures: one `sessionStart`, one
+  `beforeSubmitPrompt`, one `afterAgentResponse` and/or `stop`,
+  zero or more `postToolUse`.
+- **File pattern:** `cursor__afterAgentResponse__<ts>__<pid>.json` is
+  the most useful one to paste.
+- **CLI vs IDE:** Cursor CLI fires only
+  `beforeShellExecution`/`afterShellExecution` — for the
+  per-turn payload you need the IDE.
+
+### Cline (~5 min)
+
+- **Install:** `python3 scripts/install.py --cline` (project) or
+  `--cline-user-hooks` (user-scope, covers every workspace).
+- **Restart:** in VS Code or JetBrains, run "Developer: Reload
+  Window" (Cmd+Shift+P) from a terminal where the env is exported.
+  Cline reads hooks at task start, so a fresh task is required —
+  closing and reopening the side panel is not enough.
+- **Trigger event:** start a new Cline task and let one turn complete.
+  Cline calls them "tasks" not "sessions"; the equivalent boundaries
+  are `TaskStart` → `UserPromptSubmit` → `PostToolUse`* →
+  `TaskComplete`.
+- **File pattern:** `cline__TaskComplete__<ts>__<pid>.json` if you let
+  the task finish; `cline__UserPromptSubmit__<ts>__<pid>.json` is also
+  acceptable (carries the `prompt` envelope).
+- **Windows caveat:** hooks are unsupported on Windows
+  ([`cline/cline#8073`](https://github.com/cline/cline/issues/8073));
+  capture from macOS or Linux.
+
+### Windsurf (~5 min)
+
+- **Install:** `python3 scripts/install.py --windsurf` (project) or
+  `--windsurf-user-hooks` (user-scope at `~/.codeium/windsurf/hooks.json`).
+- **Restart:** quit Cascade fully, then relaunch from the shell with
+  the env exported. The `pre_user_prompt` event fires on every turn —
+  no full restart needed once Cascade is up, but the *first* turn after
+  launch must be the captured one.
+- **Trigger event:** ask Cascade one short question and let it answer.
+  Expected captures: `pre_user_prompt`,
+  `post_cascade_response_with_transcript`. The
+  `_with_transcript` variant is the more useful one to paste because it
+  carries the full response inline.
+- **File pattern:** `windsurf__post_cascade_response_with_transcript__<ts>__<pid>.json`.
+- **Async caveat:** `post_cascade_response` fires asynchronously off
+  the critical path. The capture file might land a second or two after
+  the response renders — wait briefly before running the redact step.
+
+### Gemini CLI (~5 min)
+
+- **Install:** `python3 scripts/install.py --gemini` (project) or
+  `--gemini-user-hooks` (user-scope at `~/.gemini/settings.json`).
+- **Restart:** Gemini CLI is invoked per command — no daemon to
+  restart. Just open a new shell with `AGENT_HOOK_CAPTURE_DIR`
+  exported and run the next session there.
+- **Trigger event:** any short Gemini CLI session
+  (`gemini "what time is it"` or similar). Hooks fire on
+  `SessionStart` → `BeforeAgent` → `AfterTool`* → `AfterAgent` →
+  `SessionEnd`.
+- **File pattern:** `gemini__AfterAgent__<ts>__<pid>.json` carries the
+  per-turn close envelope and is the recommended paste target.
+- **Advisory hooks:** `SessionStart` and `SessionEnd` are advisory only
+  in Gemini CLI — do not be alarmed if those captures look thinner than
+  the others.
+
+## Where to paste the redacted payload
+
+The roadmap is now archived. Paste under the matching phase:
+
+[`agents/roadmaps/archive/road-to-verified-chat-history-platforms.md`](../agents/roadmaps/archive/road-to-verified-chat-history-platforms.md)
+
+- Cursor → § Phase 2 — Cursor
+- Cline → § Phase 3 — Cline
+- Windsurf → § Phase 4 — Windsurf
+- Gemini CLI → § Phase 5 — Gemini CLI
+
+In the chosen phase, paste the redacted JSON inside a fenced
+`json` block under a heading like `### <Platform> payload shape (captured 2026-MM-DD)`,
+then flip the `[ ] Optional upgrade — payload-verified` checkbox to
+`[x]`.
+
+Then update the matching row in
+[`agents/contexts/chat-history-platform-hooks.md`](../agents/contexts/chat-history-platform-hooks.md):
+the `Verification` column moves from `docs-verified` to
+`payload-verified`.
+
+If the captured shape diverges from the docs-verified extractor
+branch, that is the trigger for a code patch — open a tiny new roadmap
+under `agents/roadmaps/` for the divergence work, do **not** edit the
+archived roadmap to track new code work
+(see [`no-roadmap-references`](../.agent-src/rules/no-roadmap-references.md)).
+
+## Final verify
+
+After pasting and flipping the checkbox:
+
+```bash
+# Lint gates must stay green.
+python3 scripts/lint_hook_manifest.py
+python3 scripts/check_references.py
+python3 scripts/check_portability.py
+
+# Tests still green.
+python3 -m pytest tests/hooks/ -q
+
+# Optional: regenerate the dashboard if the archived roadmap's
+# checkbox change should bubble up. Iron Law from
+# `roadmap-progress-sync` says yes if it does.
+./agent-config roadmap:progress
+```
+
+Per
+[`commit-policy`](../.agent-src/rules/commit-policy.md):
+do **not** commit unless explicitly told to. The user owns the commit
+step.
+
+## Cleanup after capture
+
+```bash
+# Raw captures (not redacted) contain real prompt content.
+# Either delete the directory or leave it for repeat captures.
+rm -rf "$AGENT_HOOK_CAPTURE_DIR"
+
+# Or keep redacted ones only:
+# find "$AGENT_HOOK_CAPTURE_DIR" -type f ! -name '*.redacted.json' -delete
+
+# Unset the env var when done so subsequent sessions do not capture.
+unset AGENT_HOOK_CAPTURE_DIR
+```
+
+The capture directory is gitignored project-wide; raw captures are
+never accidentally committed. The redaction step is still mandatory
+before paste because the redacted output goes into a tracked file
+(the archived roadmap) and would otherwise leak.
+
+## Sources
+
+- Capture engine: [`scripts/hooks/dispatch_hook.py`](../scripts/hooks/dispatch_hook.py) — `_maybe_capture_payload`
+- Redactor: [`scripts/redact_hook_capture.py`](../scripts/redact_hook_capture.py)
+- Per-platform install logic: [`scripts/install.py`](../scripts/install.py) — search `ensure_<platform>_bridge` / `ensure_<platform>_user_hooks`
+- Platform matrix + payload schemas: [`agents/contexts/chat-history-platform-hooks.md`](../agents/contexts/chat-history-platform-hooks.md)
+- Hook architecture: [`docs/contracts/hook-architecture-v1.md`](contracts/hook-architecture-v1.md)
+- Archived roadmap with per-phase paste sections: [`agents/roadmaps/archive/road-to-verified-chat-history-platforms.md`](../agents/roadmaps/archive/road-to-verified-chat-history-platforms.md)

package/docs/migrations/commands-1.15.0.md

@@ -85,18 +85,23 @@ the deprecation cycle for Phase 1 closes. Tracked in
 [`agents/roadmaps/archive/road-to-governance-cleanup.md`](../../agents/roadmaps/archive/road-to-governance-cleanup.md)
 § F2.
 
-## Related rule split — `chat-history` (post-1.15.0)
-
-The monolithic `rules/chat-history.md` was split into three sibling
-`always` rules in the post-1.15.0 optimization phase:
-
-- [`chat-history-ownership`](../../.agent-src/rules/chat-history-ownership.md) — sole owner of file I/O + first-turn handshake.
-- [`chat-history-cadence`](../../.agent-src/rules/chat-history-cadence.md) — when to persist (SessionStart / StepEnd / append boundaries).
-- [`chat-history-visibility`](../../.agent-src/rules/chat-history-visibility.md) — heartbeat marker contract for user-facing reporting.
-
-Decision record: [`docs/contracts/adr-chat-history-split.md`](../contracts/adr-chat-history-split.md).
-Cross-references in commands and contexts now point to
-`chat-history-ownership` as the entry point.
+## Related rule split — `chat-history` (post-1.15.0, superseded)
+
+> **Superseded · 2026-05-04** by
+> [`agents/contexts/chat-history-platform-hooks.md`](../../agents/contexts/chat-history-platform-hooks.md).
+> The three sibling rules (`chat-history-ownership`,
+> `chat-history-cadence`, `chat-history-visibility`) and the heartbeat
+> marker no longer exist. Persistence is now a pure platform-hook
+> contract — `session_start` auto-adopts foreign sessions silently;
+> the agent never reads or writes `agents/.agent-chat-history` cooperatively.
+> Manual recovery lever: `./agent-config chat-history:adopt`.
+
+For historical context: the monolithic `rules/chat-history.md` was
+first split into three sibling `always` rules in the post-1.15.0
+optimization phase, recorded in
+[`docs/contracts/adr-chat-history-split.md`](../contracts/adr-chat-history-split.md)
+(also marked superseded). The hook-only roadmap then collapsed all
+three rules into structural-only artefacts.
 
 ## Rollback
 

package/docs/skills-catalog.md

@@ -1,6 +1,6 @@
 # Skills Catalog
 
-All **128 skills** available in this package, in alphabetical order.
+All **129 skills** available in this package, in alphabetical order.
 Click a skill name to open its SKILL.md and read the full guidance.
 
 > **Regenerate:** `python3 scripts/generate_catalog.py`
@@ -10,6 +10,7 @@ Click a skill name to open its SKILL.md and read the full guidance.
 |---|---|
 | [`adversarial-review`](../.agent-src/skills/adversarial-review/SKILL.md) | ONLY when user explicitly requests adversarial review, devil's advocate analysis, stress-testing a plan, or 'poke holes in this' — NOT for regular code review or design feedback. |
 | [`agent-docs-writing`](../.agent-src/skills/agent-docs-writing/SKILL.md) | Use when reading, creating, or updating agent documentation, module docs, roadmaps, or AGENTS.md. Understands the full .augment/, agents/, and copilot-instructions structure. |
+| [`ai-council`](../.agent-src/skills/ai-council/SKILL.md) | Use when polling external AIs (OpenAI, Anthropic) outside the host session for a neutral second opinion on a roadmap, diff, prompt, or file set — or 'cross-check with another model'. |
 | [`analysis-autonomous-mode`](../.agent-src/skills/analysis-autonomous-mode/SKILL.md) | ONLY when user explicitly requests autonomous analysis, deep investigation, multi-step research, or 'dig into this end-to-end without asking me each step' — NOT for normal feature work. |
 | [`analysis-skill-router`](../.agent-src/skills/analysis-skill-router/SKILL.md) | Use when picking which analysis or project-analysis-* skill fits a request — routes by scope, framework, and symptom — even if the user just says 'analyze this' or 'dig into the codebase'. |
 | [`api-design`](../.agent-src/skills/api-design/SKILL.md) | Use when designing APIs, planning endpoints, REST conventions, versioning, or deprecation — even when the user just says 'expose this as an endpoint' without naming API design. |
@@ -18,7 +19,7 @@ Click a skill name to open its SKILL.md and read the full guidance.
 | [`artisan-commands`](../.agent-src/skills/artisan-commands/SKILL.md) | Use when creating or modifying Artisan commands. Covers clear signatures, safe execution flow, helpful output, and project conventions for console tooling. |
 | [`authz-review`](../.agent-src/skills/authz-review/SKILL.md) | Use when reviewing authorization end-to-end — route → gate → policy → query scope → response filter — before changes to permissions, tenants, ownership, or admin flows. |
 | [`aws-infrastructure`](../.agent-src/skills/aws-infrastructure/SKILL.md) | Use when working with AWS resources — ECS Fargate, ECR, EFS, Secrets Manager, gomplate templates, multi-env deployments — even when the user says 'deploy to staging' without naming AWS. |
-| [`blade-ui`](../.agent-src/skills/blade-ui/SKILL.md) | Stack-implementation skill for Laravel Blade — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project's frontend stack is Blade. Covers views, components, partials, layouts, and view logic. |
+| [`blade-ui`](../.agent-src/skills/blade-ui/SKILL.md) | Use when the project's frontend stack is Blade — dispatched by `directives/ui/{apply,review,polish}.py`. Covers views, components, partials, layouts, and view logic. |
 | [`blast-radius-analyzer`](../.agent-src/skills/blast-radius-analyzer/SKILL.md) | Use BEFORE editing shared code — enumerates every call site, event consumer, queue worker, API client, migration, and test that a planned change will touch, with a file:line citation per dependency. |
 | [`bug-analyzer`](../.agent-src/skills/bug-analyzer/SKILL.md) | Use when the user shares a Sentry error, Jira bug ticket, or error description and wants root cause analysis. Also for proactive bug hunting and code audits for hidden bugs. |
 | [`check-refs`](../.agent-src/skills/check-refs/SKILL.md) | Use when verifying cross-references between skills, rules, commands, guidelines, and context documents are not broken after edits, renames, or deletions. |
@@ -49,7 +50,7 @@ Click a skill name to open its SKILL.md and read the full guidance.
 | [`feature-planning`](../.agent-src/skills/feature-planning/SKILL.md) | Use when the user says "plan a feature", "brainstorm", "explore this idea", or wants to go from idea to structured plan and roadmap. |
 | [`file-editor`](../.agent-src/skills/file-editor/SKILL.md) | Use when opening edited files in the user's IDE. Reads settings from .agent-settings.yml to determine IDE and whether auto-open is enabled. |
 | [`finishing-a-development-branch`](../.agent-src/skills/finishing-a-development-branch/SKILL.md) | Use when the feature is implementation-complete and the next step is 'ship it' — verifies, cleans up, and routes to merge/PR/park/discard — even when the user just says 'I'm done, what now?'. |
-| [`flux`](../.agent-src/skills/flux/SKILL.md) | Stack-implementation skill for Laravel Flux — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project uses `livewire/flux`. Covers Flux components, slots, variants, and form primitives. |
+| [`flux`](../.agent-src/skills/flux/SKILL.md) | Use when the project uses `livewire/flux` — dispatched by `directives/ui/{apply,review,polish}.py`. Covers Flux components, slots, variants, and form primitives. |
 | [`git-workflow`](../.agent-src/skills/git-workflow/SKILL.md) | Use when working with Git — branch naming, commit messages, PR creation, rebasing, or the code review process — even when the user says 'push this' or 'merge the branch' without naming Git. |
 | [`github-ci`](../.agent-src/skills/github-ci/SKILL.md) | Use when working with GitHub Actions — workflow YAML, quality gates, test matrices, deployment triggers, reusable workflows — even when the user just says 'my CI is failing' or 'add a check'. |
 | [`grafana`](../.agent-src/skills/grafana/SKILL.md) | Use when working with Grafana — dashboards, Loki LogQL queries, alerting rules, monitoring panels — even when the user just says 'build me a dashboard' or 'query the logs' without naming Grafana. |
@@ -72,7 +73,7 @@ Click a skill name to open its SKILL.md and read the full guidance.
 | [`laravel-validation`](../.agent-src/skills/laravel-validation/SKILL.md) | Use when writing validation — Form Requests, rules, custom rule objects, request-boundary design — even when the user just says 'validate this input' or 'check the request' without naming it. |
 | [`learning-to-rule-or-skill`](../.agent-src/skills/learning-to-rule-or-skill/SKILL.md) | Use when a repeated learning, mistake, or successful pattern should be turned into a new rule or skill. Also use after completing a task to capture learnings from the work. |
 | [`lint-skills`](../.agent-src/skills/lint-skills/SKILL.md) | Use when running the package's skill linter against all skills and rules to validate frontmatter, required sections, and execution metadata. |
-| [`livewire`](../.agent-src/skills/livewire/SKILL.md) | Stack-implementation skill for Livewire — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project's frontend stack is Livewire. Covers reactive state, events, lifecycle hooks, and component/view separation. |
+| [`livewire`](../.agent-src/skills/livewire/SKILL.md) | Use when the project's frontend stack is Livewire — dispatched by `directives/ui/{apply,review,polish}.py`. Covers reactive state, events, lifecycle hooks, and component/view separation. |
 | [`logging-monitoring`](../.agent-src/skills/logging-monitoring/SKILL.md) | Use when working with logging or monitoring — Sentry error tracking, Grafana/Loki log aggregation, structured logging channels, or monitoring helpers. |
 | [`mcp`](../.agent-src/skills/mcp/SKILL.md) | Use when working with MCP (Model Context Protocol) servers — their tools, capabilities, and best practices for effective agent workflows. |
 | [`md-language-check`](../.agent-src/skills/md-language-check/SKILL.md) | Use BEFORE saving any .md under .augment/, .agent-src*/, or agents/ — scans umlauts, German function words, and quoted German phrases outside DE:/EN: anchor blocks. Hard gate per language-and-tone. |

package/llms.txt

@@ -8,6 +8,7 @@ Catalog: docs/skills-catalog.md
 
 adversarial-review: ONLY when user explicitly requests adversarial review, devil's advocate analysis, stress-testing a plan, or 'poke holes in this' — NOT for regular code review or design feedback.
 agent-docs-writing: Use when reading, creating, or updating agent documentation, module docs, roadmaps, or AGENTS.md. Understands the full .augment/, agents/, and copilot-instructions structure.
+ai-council: Use when polling external AIs (OpenAI, Anthropic) outside the host session for a neutral second opinion on a roadmap, diff, prompt, or file set — or 'cross-check with another model'.
 analysis-autonomous-mode: ONLY when user explicitly requests autonomous analysis, deep investigation, multi-step research, or 'dig into this end-to-end without asking me each step' — NOT for normal feature work.
 analysis-skill-router: Use when picking which analysis or project-analysis-* skill fits a request — routes by scope, framework, and symptom — even if the user just says 'analyze this' or 'dig into the codebase'.
 api-design: Use when designing APIs, planning endpoints, REST conventions, versioning, or deprecation — even when the user just says 'expose this as an endpoint' without naming API design.
@@ -16,7 +17,7 @@ api-testing: Use when writing API endpoint tests — integration tests, contract
 artisan-commands: Use when creating or modifying Artisan commands. Covers clear signatures, safe execution flow, helpful output, and project conventions for console tooling.
 authz-review: Use when reviewing authorization end-to-end — route → gate → policy → query scope → response filter — before changes to permissions, tenants, ownership, or admin flows.
 aws-infrastructure: Use when working with AWS resources — ECS Fargate, ECR, EFS, Secrets Manager, gomplate templates, multi-env deployments — even when the user says 'deploy to staging' without naming AWS.
-blade-ui: Stack-implementation skill for Laravel Blade — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project's frontend stack is Blade. Covers views, components, partials, layouts, and view logic.
+blade-ui: Use when the project's frontend stack is Blade — dispatched by `directives/ui/{apply,review,polish}.py`. Covers views, components, partials, layouts, and view logic.
 blast-radius-analyzer: Use BEFORE editing shared code — enumerates every call site, event consumer, queue worker, API client, migration, and test that a planned change will touch, with a file:line citation per dependency.
 bug-analyzer: Use when the user shares a Sentry error, Jira bug ticket, or error description and wants root cause analysis. Also for proactive bug hunting and code audits for hidden bugs.
 check-refs: Use when verifying cross-references between skills, rules, commands, guidelines, and context documents are not broken after edits, renames, or deletions.
@@ -47,7 +48,7 @@ fe-design: Reference for frontend-design heuristics — component architecture,
 feature-planning: Use when the user says "plan a feature", "brainstorm", "explore this idea", or wants to go from idea to structured plan and roadmap.
 file-editor: Use when opening edited files in the user's IDE. Reads settings from .agent-settings.yml to determine IDE and whether auto-open is enabled.
 finishing-a-development-branch: Use when the feature is implementation-complete and the next step is 'ship it' — verifies, cleans up, and routes to merge/PR/park/discard — even when the user just says 'I'm done, what now?'.
-flux: Stack-implementation skill for Laravel Flux — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project uses `livewire/flux`. Covers Flux components, slots, variants, and form primitives.
+flux: Use when the project uses `livewire/flux` — dispatched by `directives/ui/{apply,review,polish}.py`. Covers Flux components, slots, variants, and form primitives.
 git-workflow: Use when working with Git — branch naming, commit messages, PR creation, rebasing, or the code review process — even when the user says 'push this' or 'merge the branch' without naming Git.
 github-ci: Use when working with GitHub Actions — workflow YAML, quality gates, test matrices, deployment triggers, reusable workflows — even when the user just says 'my CI is failing' or 'add a check'.
 grafana: Use when working with Grafana — dashboards, Loki LogQL queries, alerting rules, monitoring panels — even when the user just says 'build me a dashboard' or 'query the logs' without naming Grafana.
@@ -70,7 +71,7 @@ laravel-scheduling: Use when configuring Laravel task scheduling — cron expres
 laravel-validation: Use when writing validation — Form Requests, rules, custom rule objects, request-boundary design — even when the user just says 'validate this input' or 'check the request' without naming it.
 learning-to-rule-or-skill: Use when a repeated learning, mistake, or successful pattern should be turned into a new rule or skill. Also use after completing a task to capture learnings from the work.
 lint-skills: Use when running the package's skill linter against all skills and rules to validate frontmatter, required sections, and execution metadata.
-livewire: Stack-implementation skill for Livewire — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project's frontend stack is Livewire. Covers reactive state, events, lifecycle hooks, and component/view separation.
+livewire: Use when the project's frontend stack is Livewire — dispatched by `directives/ui/{apply,review,polish}.py`. Covers reactive state, events, lifecycle hooks, and component/view separation.
 logging-monitoring: Use when working with logging or monitoring — Sentry error tracking, Grafana/Loki log aggregation, structured logging channels, or monitoring helpers.
 mcp: Use when working with MCP (Model Context Protocol) servers — their tools, capabilities, and best practices for effective agent workflows.
 md-language-check: Use BEFORE saving any .md under .augment/, .agent-src*/, or agents/ — scans umlauts, German function words, and quoted German phrases outside DE:/EN: anchor blocks. Hard gate per language-and-tone.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "1.18.0",
+    "version": "1.20.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/agent-config

@@ -68,7 +68,7 @@ Commands:
   refine-ticket:detect       Run the deterministic refine-ticket detection helper
   chat-history:hook          Platform hook entry point (read JSON from stdin)
                              Usage: chat-history:hook --platform <claude|augment|cursor|cline|windsurf|gemini>
-  chat-history:checkpoint    Append a phase-boundary entry to .agent-chat-history
+  chat-history:checkpoint    Append a phase-boundary entry to agents/.agent-chat-history
                              (CHECKPOINT fallback for platforms without native hooks)
   roadmap-progress:hook      PostToolUse hook entry point (read JSON from stdin)
                              Regenerates roadmaps-progress.md when a tool wrote under agents/roadmaps/
@@ -76,9 +76,20 @@ Commands:
                              Writes .augment/state/onboarding-gate.json from .agent-settings.yml
   context-hygiene:hook       PostToolUse hook entry point (read JSON from stdin)
                              Maintains .augment/state/context-hygiene.json (turn count, loop, freshness)
+  dispatch:hook              Universal hook dispatcher (Phase 7, hook-architecture-v1.md)
+                             Usage: dispatch:hook --platform <name> --event <event> [--native-event <native>]
+                             Reads scripts/hook_manifest.yaml and runs the resolved concern chain.
+  hooks:status               Print the runtime hook matrix (per-platform install + bindings)
+                             Flags: --format json|table, --strict (CI), --project-root <path>
   telemetry:record           Append one artefact-engagement event (default-off)
   telemetry:status           Print artefact-engagement telemetry status (read-only)
   telemetry:report           Aggregate the engagement log into a quartile report
+  council:estimate           Pre-call council cost preview (no API call, no spend)
+                             Usage: council:estimate <question> [--input-mode prompt|roadmap]
+  council:run                Run the council. Requires --confirm to spend.
+                             Usage: council:run <question> --output <path> --confirm
+  council:render             Re-render a saved council responses JSON to markdown
+                             Usage: council:render <responses.json>
   help                       Show this help
   --version, -V              Print package version
 
@@ -102,6 +113,9 @@ Examples:
   ./agent-config telemetry:status --format json
   ./agent-config telemetry:report --since 30d --top 20
   ./agent-config telemetry:report --since 7d --format json --top 0
+  ./agent-config council:estimate prompt.txt
+  ./agent-config council:run prompt.txt --output agents/council-sessions/out.json --confirm
+  ./agent-config council:render agents/council-sessions/out.json
 
 All commands operate on the CURRENT DIRECTORY (your project root).
 The CLI is strictly consumer-facing. Maintainer tasks live in Taskfile.yml.
@@ -343,6 +357,20 @@ cmd_context_hygiene_hook() {
   exec python3 "$script" "$@"
 }
 
+cmd_dispatch_hook() {
+  require_python3
+  local script
+  script="$(resolve_script "scripts/hooks/dispatch_hook.py")" || return 1
+  exec python3 "$script" "$@"
+}
+
+cmd_hooks_status() {
+  require_python3
+  local script
+  script="$(resolve_script "scripts/hooks_status.py")" || return 1
+  exec python3 "$script" "$@"
+}
+
 cmd_chat_history_checkpoint() {
   require_python3
   local script
@@ -438,6 +466,17 @@ cmd_keys_install_openai() {
   exec bash "$script" "$@"
 }
 
+# Council CLI — non-interactive wrapper around scripts.ai_council.orchestrator.
+# Three subcommands share one Python entry point; we forward the subcommand
+# verb so `./agent-config council:run --confirm` lands on `council_cli.py run`.
+cmd_council() {
+  require_python3
+  local sub="$1"; shift || true
+  local script
+  script="$(resolve_script "scripts/council_cli.py")" || return 1
+  exec env PYTHONPATH="$PACKAGE_ROOT" python3 "$script" "$sub" "$@"
+}
+
 main() {
   local cmd="${1-}"
   [[ $# -gt 0 ]] && shift || true
@@ -466,9 +505,14 @@ main() {
     roadmap-progress:hook)   cmd_roadmap_progress_hook "$@" ;;
     onboarding-gate:hook)    cmd_onboarding_gate_hook "$@" ;;
     context-hygiene:hook)    cmd_context_hygiene_hook "$@" ;;
+    dispatch:hook)           cmd_dispatch_hook "$@" ;;
+    hooks:status)            cmd_hooks_status "$@" ;;
     telemetry:record)        cmd_telemetry_record "$@" ;;
     telemetry:status)        cmd_telemetry_status "$@" ;;
     telemetry:report)        cmd_telemetry_report "$@" ;;
+    council:estimate)        cmd_council estimate "$@" ;;
+    council:run)             cmd_council run "$@" ;;
+    council:render)          cmd_council render "$@" ;;
     help|--help|-h|"")        usage ;;
     --version|-V)            print_version ;;
     *)

package/scripts/ai_council/_default_prices.py

@@ -1,7 +1,7 @@
 """Shipped baseline prices for the AI Council.
 
-This file is the bootstrap source for `.agent-prices.md` when the
-runtime file is missing. It is also the network-fallback source for
+This file is the bootstrap source for `agents/.agent-prices.md` when
+the runtime file is missing. It is also the network-fallback source for
 `scripts/update_prices.py` when the upstream feed (LiteLLM) is
 unreachable.
 
@@ -9,8 +9,8 @@ Prices are USD per **1 000 000** tokens. Models are identified by the
 exact `model:` string the user puts into `.agent-settings.yml`.
 
 Numbers below are a hand-curated snapshot — they will drift. The
-runtime never reads them directly once `.agent-prices.md` exists; the
-weekly refresh and user edits are the live source of truth.
+runtime never reads them directly once `agents/.agent-prices.md`
+exists; the weekly refresh and user edits are the live source of truth.
 """
 
 from __future__ import annotations

package/scripts/ai_council/bundler.py

@@ -38,11 +38,11 @@ class CouncilContext:
 # placeholder. Order matters — the most specific pattern goes first.
 
 _REDACTION_LINE_PATTERNS: list[tuple[re.Pattern[str], str]] = [
-    (re.compile(r".*~?/?\.config/agent-config/[^/\s]+\.key.*"),
+    (re.compile(r"~?/?\.config/agent-config/[^/\s]+\.key"),
      "[redacted: agent-config key path]"),
-    (re.compile(r"^\s*Authorization:\s.*", re.IGNORECASE),
+    (re.compile(r"^\s*Authorization:\s", re.IGNORECASE),
      "[redacted: Authorization header]"),
-    (re.compile(r"(?i).*(api[_-]?key|secret|token|password)\s*[:=].*"),
+    (re.compile(r"(?i)(api[_-]?key|secret|token|password)\s*[:=]"),
      "[redacted: secret-like assignment]"),
     (re.compile(r"sk-ant-[A-Za-z0-9_\-]{8,}"), "[redacted: anthropic-key-like token]"),
     (re.compile(r"sk-[A-Za-z0-9_\-]{20,}"), "[redacted: openai-key-like token]"),

package/scripts/ai_council/clients.py

@@ -34,6 +34,16 @@ OPENAI_KEY_PATH = Path.home() / ".config" / "agent-config" / "openai.key"
 DEFAULT_ANTHROPIC_MODEL = "claude-sonnet-4-5"
 DEFAULT_OPENAI_MODEL = "gpt-4o"
 
+# OpenAI reasoning models (o1, o3, o4 families) reject `max_tokens` and the
+# `system` role; they require `max_completion_tokens` and accept only `user`
+# (and `developer`) messages.
+_REASONING_PREFIXES = ("o1", "o3", "o4")
+
+
+def _is_reasoning_model(model: str) -> bool:
+    name = model.lower()
+    return any(name == p or name.startswith(p + "-") for p in _REASONING_PREFIXES)
+
 
 class KeyGateError(RuntimeError):
     """Raised when a provider key file violates the 0600 contract."""
@@ -90,7 +100,7 @@ class ExternalAIClient(ABC):
 
     name: str = ""
     model: str = ""
-    billable: bool = True  # API-mode subclasses spend money; manual/playwright don't.
+    billable: bool = True  # API-mode subclasses spend money; manual doesn't.
 
     @abstractmethod
     def ask(
@@ -189,15 +199,21 @@ class OpenAIClient(ExternalAIClient):
 
     def ask(self, system_prompt: str, user_prompt: str, max_tokens: int = 1024) -> CouncilResponse:
         t0 = time.monotonic()
+        kwargs: dict[str, object] = {"model": self.model}
+        if _is_reasoning_model(self.model):
+            # o1/o3/o4 reasoning models reject `max_tokens` and `system` role.
+            kwargs["max_completion_tokens"] = max_tokens
+            kwargs["messages"] = [
+                {"role": "user", "content": f"{system_prompt}\n\n---\n\n{user_prompt}"},
+            ]
+        else:
+            kwargs["max_tokens"] = max_tokens
+            kwargs["messages"] = [
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_prompt},
+            ]
         try:
-            response = self._client.chat.completions.create(
-                model=self.model,
-                max_tokens=max_tokens,
-                messages=[
-                    {"role": "system", "content": system_prompt},
-                    {"role": "user", "content": user_prompt},
-                ],
-            )
+            response = self._client.chat.completions.create(**kwargs)
         except Exception as exc:  # noqa: BLE001 - normalise all SDK errors
             return CouncilResponse(
                 provider=self.name, model=self.model, text="",

package/scripts/ai_council/modes.py

@@ -4,14 +4,13 @@ Each council member runs in exactly one transport mode per invocation:
 
 - ``api``      — direct SDK call against the provider's API (billable).
 - ``manual``   — copy-paste loop with the user as transport (free).
-- ``playwright`` — browser automation (Phase 2c, not yet wired).
 
 Resolution precedence — first non-empty wins:
 
     1. Invocation flag      e.g. ``/council mode:manual``
     2. Per-member setting   ``ai_council.members.<name>.mode``
     3. Global setting       ``ai_council.mode``
-    4. Built-in default     ``api``
+    4. Built-in default     ``manual``
 
 This mirrors how ``cost_profile`` resolves in
 ``.augment/guidelines/agent-infra/layered-settings.md``.
@@ -24,9 +23,9 @@ from __future__ import annotations
 
 from typing import Mapping
 
-VALID_MODES: frozenset[str] = frozenset({"api", "manual", "playwright"})
+VALID_MODES: frozenset[str] = frozenset({"api", "manual"})
 
-DEFAULT_MODE: str = "api"
+DEFAULT_MODE: str = "manual"
 
 
 class InvalidModeError(ValueError):

package/scripts/ai_council/one_off_archive/2026-05/README.md

@@ -8,6 +8,28 @@
 > `scripts/check_one_off_location.py` enforces that no new
 > `_one_off_*.py` lands outside this folder.
 
+## Going forward — use the CLI, not new one-offs
+
+> **Canonical pattern (Phase 6.7+):** new council runs go through
+> `./agent-config council:{estimate,run,render}`. The CLI handles
+> bundling, redaction, the cost gate, the `0600` key contract, the
+> `enabled` check, and session persistence — every concern these
+> archived one-offs reimplemented inline.
+>
+> ```bash
+> ./agent-config council:estimate <question.md>
+> ./agent-config council:run <question.md> \
+>     --output agents/council-sessions/<UTC-ts>.json --confirm
+> ./agent-config council:render agents/council-sessions/<UTC-ts>.json
+> ```
+>
+> Wire-level access (`scripts.ai_council.orchestrator`,
+> `scripts.ai_council.bundler`) is still public for tests and library
+> use, but writing a new `_one_off_*.py` purely to fan out to the
+> council members is **not** the path. The scripts below are kept as
+> historical evidence of the runs that produced specific roadmap
+> decisions; they are not a template for new work.
+
 ## Lifecycle rule (uniform — Phase 0.2 of context-layer-maturity)
 
 > A one-off is **archived**, never deleted. The session manifest under

package/scripts/ai_council/one_off_archive/2026-05/_one_off_roundtrip.py

@@ -1,14 +1,19 @@
-"""One-off Phase-1 round-trip runner.
+"""One-off Phase-1 round-trip runner — HISTORICAL ARCHIVE.
 
-Used exactly once to generate the evidence artefact required to lift
-the capture-only fence on `road-to-ai-council.md` Phase 2+ and the
-end-to-end verification on `road-to-council-modes.md` Phase 2a.
+Going forward, council runs go through the CLI:
 
-Not part of the public CLI surface — `/council` remains the supported
-entry point. This script is committed under `scripts/ai_council/` so
-the evidence is reproducible from the git history alone.
+    ./agent-config council:estimate <question.md>
+    ./agent-config council:run <question.md> \
+        --output agents/council-sessions/<UTC-ts>.json --confirm
+    ./agent-config council:render agents/council-sessions/<UTC-ts>.json
 
-Invocation:
+This script predates `scripts/council_cli.py` (Phase 6.7) and is kept
+only as the evidence artefact that lifted the capture-only fence on
+`road-to-ai-council.md` Phase 2+ and the end-to-end verification on
+`road-to-council-modes.md` Phase 2a. Do **not** copy it as a template
+for new one-offs — write a question file and use the CLI instead.
+
+Invocation (historical):
     .venv/bin/python -m scripts.ai_council._one_off_roundtrip
 """
 from __future__ import annotations