@event4u/agent-config 1.19.0 → 1.21.0

package/config/agent-settings.template.yml

@@ -7,13 +7,15 @@
 
 # --- Cost profile ---
 #
-# Selects which agent surfaces are active. See docs/customization.md for
-# the authoritative description.
+# Master switch that controls which rule tiers load each session.
+# See docs/customization.md for the authoritative description and
+# docs/contracts/rule-router.md for the kernel + router architecture.
 #
-# minimal  = rules, skills, and commands only (zero extra surface, default)
-# balanced = + runtime dispatcher for skills that declare a shell command
-# full     = + tool adapters (GitHub / Jira, read-only, opt-in)
-# custom   = ignore profile — every matrix value must be set explicitly
+# minimal  = kernel only (always-loaded Iron-Law floor, ≤ 26k chars).
+#            No router, no auto-rules. Lowest token footprint.
+# balanced = kernel + tier-1 auto-rules (default — current behaviour superset).
+# full     = kernel + tier-1 + tier-2 (everything, highest token cost).
+# custom   = ignore profile — every matrix value must be set explicitly.
 cost_profile: __COST_PROFILE__
 
 # --- Personal preferences ---
@@ -74,6 +76,22 @@ github:
   # auto                  = detect on first use and update this setting
   pr_reply_method: create_review_comment
 
+# --- Augment Code projection (.augment/) ---
+#
+# Controls how rule files are written into .augment/rules/ during
+# install (scripts/install.sh) and the package's own projection
+# (scripts/compress.py --project-augment).
+#
+# Augment Code historically does not load symlinked rule files, so the
+# default is to write each rule as a real copy. Flip the toggle to true
+# once Augment Code supports symlinked rules — symlinks keep the files
+# in sync without re-running install/sync, and remove a class of stale-
+# copy path bugs.
+augment:
+  # When true, .augment/rules/*.md are symlinked into .agent-src/rules/.
+  # When false (default) or missing, they are copied as real files.
+  rules_use_symlinks: false
+
 # --- Eloquent (Laravel) ---
 eloquent:
   # Model property access style
@@ -84,7 +102,7 @@ eloquent:
 
 # --- Chat history (crash recovery) ---
 #
-# Persistent JSONL log at .agent-chat-history (project root, git-ignored).
+# Persistent JSONL log at agents/.agent-chat-history (git-ignored).
 # Keeps a durable record of the conversation so a crashed or switched
 # agent session can be resumed. See scripts/chat_history.py for the API.
 chat_history:
@@ -105,12 +123,19 @@ chat_history:
   #   compress = mark for summarization on the next agent turn
   on_overflow: __CHAT_HISTORY_ON_OVERFLOW__
 
-  # Heartbeat marker visibility (token-cost knob)
-  #   on     = print the 📒 marker every reply (~20 tokens/reply, legacy)
-  #   off    = never print (zero tokens, drift only visible by reading the file)
-  #   hybrid = print only on drift states (missing/foreign/returning); silent otherwise
-  # YAML 1.1 booleanizes bare on/off — both are accepted, no quoting needed.
-  heartbeat: hybrid
+  # Per-entry-type text-length caps (chars). 0 = verbatim, no slice.
+  # N > 0 = collapse whitespace, slice to N chars, append " … [+K chars]"
+  # so the log self-reports truncation. Defaults match the hardcoded
+  # fallback in scripts/chat_history.py (DEFAULT_TEXT_LIMITS).
+  #   user  = your messages — full text by default (most valuable for crash recovery)
+  #   agent = agent replies — capped to keep the log compact under load
+  #   tool  = tool inputs/outputs — short by default; bump for noisy debugging
+  #   phase = workflow phase markers — short by default
+  text_limits:
+    user: 0
+    agent: 5000
+    tool: 200
+    phase: 200
 
 # --- Optional pipelines ---
 pipelines:
@@ -179,12 +204,11 @@ ai_council:
   # Default transport mode for every member (overridable per-member
   # below, and per-invocation via `/council mode:<x>`).
   #
-  #   api        = direct SDK call against the provider's API (billable).
-  #   manual     = copy-paste loop, user is the transport (free).
-  #   playwright = browser automation (Phase 2c, not yet wired).
+  #   api    = direct SDK call against the provider's API (billable).
+  #   manual = copy-paste loop, user is the transport (free).
   #
-  # Precedence: invocation flag > per-member mode > global mode > "api".
-  mode: "api"
+  # Precedence: invocation flag > per-member mode > global mode > "manual".
+  mode: "manual"
 
   # Per-member configuration. Set enabled=true on the providers you want
   # to consult. The model field selects which model receives the query.
@@ -199,12 +223,27 @@ ai_council:
       model: "gpt-4o"
       # mode: "manual"   # uncomment to override ai_council.mode
 
+  # Default number of debate rounds per /council invocation.
+  #
+  # Round 1 sees the artefact alone. Round 2+ sees the artefact plus
+  # anonymised critiques from the previous round (provider/model
+  # identity stripped per the neutrality Iron Law). Applies identically
+  # to api and manual transports — manual mode runs round 1 across all
+  # members, the host agent consolidates, then round 2 starts with the
+  # anonymised round-1 critiques folded in.
+  #
+  # Default is 2 so council members critique each other at least once
+  # before convergence. The agent does NOT ask "how many rounds?" when
+  # the requested rounds <= min_rounds; pass `rounds:N` on the
+  # invocation (or `--rounds N` to the CLI) to override.
+  min_rounds: 2
+
   # Hard cost ceiling per /council invocation. The orchestrator pauses
   # before any member whose projected spend would breach a cap and asks
   # the user to continue. `max_total_usd: 0` disables the USD ceiling
-  # (token caps still apply).
+  # (token caps still apply). Total spend = rounds * single-round cost.
   #
-  # Prices come from `.agent-prices.md` (gitignored, refreshed weekly
+  # Prices come from `agents/.agent-prices.md` (gitignored, refreshed weekly
   # by `python3 scripts/update_prices.py`; bootstrapped from
   # scripts/ai_council/_default_prices.py on first run).
   cost_budget:
@@ -213,10 +252,11 @@ ai_council:
     max_calls: 10
     max_total_usd: 0.50
 
-  # Retention for `agents/council-sessions/` audit folders. Sessions
-  # older than this are pruned automatically on the next `save()`.
+  # Retention for council artefacts. Files older than this in
+  # `agents/council-{questions,responses,sessions}/` are pruned
+  # automatically on the next `save()` and on `task council-prune`.
   # `0` disables pruning (keep forever — disk grows unbounded).
-  session_retention_days: 14
+  session_retention_days: 7
 
 # --- Onboarding ---
 #

package/config/gitignore-block.txt

@@ -19,13 +19,20 @@
 .agent-settings.backup.key-value
 
 # Agent config — persistent chat history (crash recovery, never commit)
-.agent-chat-history
-.agent-chat-history.bak
-.agent-chat-history.*.bak
+/agents/.agent-chat-history
+/agents/.agent-chat-history.bak
+/agents/.agent-chat-history.*.bak
 
 # Agent config — artefact engagement telemetry (default-off, maintainer-only, never commit)
 .agent-engagement.jsonl
 .agent-engagement.jsonl.bak
 
 # Agent config — AI Council price table (refreshed weekly, never commit)
-.agent-prices.md
+/agents/.agent-prices.md
+
+# Agent config — AI Council artefacts (questions, responses, sessions).
+# Dev-time scratch — informs decisions, never the durable contract.
+# See ai-council § Output path convention.
+/agents/council-questions/
+/agents/council-responses/
+/agents/council-sessions/

package/docs/architecture.md

@@ -27,7 +27,8 @@ Stability tiers follow [`docs/contracts/STABILITY.md`](contracts/STABILITY.md):
 .agent-src.uncompressed/          ← Source of truth (verbose, human-readable)
     ↓ /compress command
 .agent-src/                     ← Compressed output (token-efficient, shipped in the package)
-    ↓ project_to_augment() — copies rules, symlinks rest
+    ↓ project_to_augment() — copies rules by default, symlinks rest
+                              (toggle: augment.rules_use_symlinks)
 .augment/                       ← Local projection for Augment Code (gitignored)
     ↓ install.sh (Cursor, Cline, Windsurf, Augment VSCode) / plugin system
 .claude/ .cursor/ .clinerules/  ← Tool-specific symlinks/copies (auto-generated)
@@ -36,6 +37,39 @@ Stability tiers follow [`docs/contracts/STABILITY.md`](contracts/STABILITY.md):
 dist/cloud/<skill>.zip          ← Anthropic Skills bundles (Claude.ai Web / Skills API)
 ```
 
+### Installer layout
+
+In a consumer project, the installer (`scripts/install.sh`) and the
+package's own `project_to_augment()` projection produce a `.augment/`
+tree where:
+
+- `.augment/rules/` — **copies** of compressed rule files by default.
+  Augment Code historically does not load symlinked rules, so each
+  rule is a real file. Set `augment.rules_use_symlinks: true` in
+  `.agent-settings.yml` to switch them to symlinks once Augment Code
+  supports it (the toggle is honored by both `scripts/install.sh` on
+  the consumer side and `project_to_augment()` in the package).
+- `.augment/skills/`, `.augment/commands/`, `.augment/personas/`,
+  `.augment/contexts/`, `.augment/templates/` — **symlinks** into
+  `.agent-src/<subdir>/`. Reading a context follows the symlink to
+  the package payload.
+- `.augment/docs/guidelines/` — **symlink** into the package's
+  `docs/guidelines/` (consumer side: `vendor/event4u/agent-config/docs/guidelines/`;
+  package self-projection: `../docs/guidelines/`). This is the only
+  `docs/` subdirectory exposed in `.augment/`; `docs/contracts/` and
+  `docs/decisions/` are package-internal — rules that reference
+  contracts inline a 2–3 line excerpt instead of linking out.
+
+Cross-references inside `.agent-src/rules/*.md` are written
+**relative to `.agent-src/rules/`** (e.g. `../contexts/execution/foo.md`,
+`../docs/guidelines/agent-infra/foo.md`). Source files under
+`.agent-src.uncompressed/rules/` use **logical names** without a
+directory prefix (e.g. `contexts/execution/foo.md`); the
+compress-time path rewriter in `scripts/compress.py` translates
+them to the relative form when writing into `.agent-src/`. Hardcoding
+`.agent-src.uncompressed/` in source frontmatter or body links is
+forbidden and caught by `scripts/check_compressed_paths.py`.
+
 ### Cloud-bundle pipeline
 
 `task build-cloud-bundles-all` produces one ZIP per skill at
@@ -62,10 +96,10 @@ fails on any source-side violation, without producing artifacts.
 
 | Layer | Count | Purpose |
 |---|---|---|
-| **Skills** | 129 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
+| **Skills** | 136 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
 | **Rules** | 58 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
 | **Commands** | 95 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
-| **Guidelines** | 51 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
+| **Guidelines** | 56 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
 | **Templates** | 7 | Scaffolds for features, roadmaps, contexts, skills, overrides |
 | **Contexts** | 5 | Shared knowledge about the system itself |
 
@@ -215,4 +249,51 @@ adjustments (description budget, sandbox note, package-internal path-swap).
 
 ---
 
+## Path resolution and Copilot integration
+
+Cross-references inside `.augment/rules/`, `.augment/skills/`, and the
+mirrored `.claude/`, `.cursor/`, `.clinerules/` trees use **relative
+paths from the delivered location**. They resolve through the symlinks
+created by `scripts/install.sh`, not via raw git checkout. This means
+GitHub Copilot's static checker — which walks the git tree — will see
+broken paths where there are none. **The gap is intentional, not a bug.**
+
+The package ships two complementary suppression artefacts:
+
+| File | Read by | Purpose |
+|---|---|---|
+| `.github/copilot-instructions.md` | Copilot Chat + PR review | Repo-wide coding standards, self-contained behavior |
+| `.github/copilot-review-instructions.md` | Copilot PR review | Path-resolution suppression floor (this section's mate) |
+
+Both are installed (copy-if-missing) by `scripts/install.sh` from
+`.agent-src.uncompressed/templates/`. Consumers can edit them freely;
+the installer never overwrites.
+
+The mechanical floor is `scripts/check_compressed_paths.py`, wired into
+`task ci` as `check-compressed-paths`. It validates `.agent-src/rules/*.md`:
+
+- `load_context:` entries must resolve to existing files.
+- Forbidden substrings (`.agent-src.uncompressed/`, `../../docs/`,
+  `../../agents/`) must not survive compression — unless declared
+  per-rule via the `validator_ignore:` frontmatter primitive (audited).
+- Body links to `../docs/guidelines/...` are intentionally **not**
+  checked (they are package-internal reference material, silenced by
+  the Copilot suppression floor above).
+
+### Verifying path fixes in a consumer
+
+If a regression is suspected, replay the smoke test against the
+package's own `.augment/` projection:
+
+```bash
+task sync                              # regenerate .agent-src/ → .augment/
+python3 scripts/smoke_path_resolution.py
+```
+
+The script walks `.augment/rules/*.md` and resolves every
+`load_context:` entry to a file under `.augment/`. A non-zero exit
+means a consumer would also see the same broken reference.
+
+---
+
 ← [Back to README](../README.md)

package/docs/catalog.md

@@ -1,13 +1,13 @@
 # agent-config — Public Catalog
 
-Consumer-facing catalog of all **330 public artefacts** shipped by
+Consumer-facing catalog of all **342 public artefacts** shipped by
 this package. Internal package-maintenance rules and deprecation shims
 are excluded.
 
 > **Regenerate:** `python3 scripts/generate_index.py`
 > Auto-generated — do not edit manually.
 
-## Skills (129)
+## Skills (136)
 
 | kind | name | extra | description |
 |---|---|---|---|
@@ -39,6 +39,7 @@ are excluded.
 | skill | [`dashboard-design`](../.agent-src/skills/dashboard-design/SKILL.md) |  | Use when designing monitoring dashboards — visualization selection, layout principles, observability strategies (RED/USE/Golden Signals), and data storytelling. |
 | skill | [`data-flow-mapper`](../.agent-src/skills/data-flow-mapper/SKILL.md) |  | Use BEFORE editing code that touches user data — traces the value from entry → validation → transformation → storage → egress, every hop cited with file:line. |
 | skill | [`database`](../.agent-src/skills/database/SKILL.md) |  | Use when working with database architecture, MariaDB/MySQL tuning, indexing strategies, slow queries, or multi-connection patterns — even when the user just says 'this query is slow'. |
+| skill | [`dcf-modeling`](../.agent-src/skills/dcf-modeling/SKILL.md) |  | Wing-4 valuation cognition for a CFO / finance-partner. Use when a deal, internal investment, or board ask names DCF, intrinsic value, WACC, terminal value, or 'what's it worth on a 5-year hold'. |
 | skill | [`dependency-upgrade`](../.agent-src/skills/dependency-upgrade/SKILL.md) |  | Use when upgrading dependencies — "update Laravel", "bump PHP version", or "upgrade packages". Covers changelog review, breaking change detection, and verification. |
 | skill | [`description-assist`](../.agent-src/skills/description-assist/SKILL.md) |  | Use when polishing a skill/rule/command/guideline frontmatter description — pushier phrasing, trigger coverage, undertrigger audit — even if the user just says 'make this pushier'. |
 | skill | [`design-review`](../.agent-src/skills/design-review/SKILL.md) |  | Use when the user says "review the design", "check the UI", or wants a comprehensive UI/UX review. Uses a 7-phase methodology covering interaction, responsiveness, accessibility, and more. |
@@ -54,6 +55,7 @@ are excluded.
 | skill | [`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. |
 | skill | [`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?'. |
 | skill | [`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. |
+| skill | [`funnel-analysis`](../.agent-src/skills/funnel-analysis/SKILL.md) |  | Use when diagnosing where a SaaS or product funnel leaks — visitor → signup → activation → paid → retained — channel-agnostic, conversion-rate-driven. |
 | skill | [`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. |
 | skill | [`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'. |
 | skill | [`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. |
@@ -84,6 +86,7 @@ are excluded.
 | skill | [`migration-creator`](../.agent-src/skills/migration-creator/SKILL.md) |  | Use when the user says "create migration", "add column", or "new table". Creates migrations with correct table prefixes, column naming, and multi-tenant awareness. |
 | skill | [`module-management`](../.agent-src/skills/module-management/SKILL.md) |  | Use when the user says "create module", "explore module", or works within app/Modules/. Understands module structure, auto-loading, route registration, and namespace conventions. |
 | skill | [`multi-tenancy`](../.agent-src/skills/multi-tenancy/SKILL.md) |  | Use when working with the multi-tenant architecture — customer DB switching, FQDN routing, tenant isolation, or cross-tenant operations. |
+| skill | [`okr-tree-modeling`](../.agent-src/skills/okr-tree-modeling/SKILL.md) |  | Use when decomposing a company objective into team OKRs, auditing a draft OKR tree, or stress-testing an existing one for measurability and laddering. |
 | skill | [`openapi`](../.agent-src/skills/openapi/SKILL.md) |  | Use when documenting APIs — OpenAPI/Swagger, PHP attributes, Redocly validation, versioned specs — even when the user just says 'document this endpoint' without naming OpenAPI. |
 | skill | [`override-management`](../.agent-src/skills/override-management/SKILL.md) |  | Creates and manages project-level overrides for shared skills, rules, and commands — extending or replacing originals from .augment/ with project-specific behavior in agents/overrides/. |
 | skill | [`performance`](../.agent-src/skills/performance/SKILL.md) |  | Use when optimizing application performance — caching strategies, eager loading, query optimization, Redis patterns, or background job design. |
@@ -103,6 +106,7 @@ are excluded.
 | skill | [`project-analysis-zend-laminas`](../.agent-src/skills/project-analysis-zend-laminas/SKILL.md) |  | Use for deep Zend Framework or Laminas project analysis: bootstrap, config merge order, service manager, MVC flow, data layer, and migration-specific risks. |
 | skill | [`project-analyzer`](../.agent-src/skills/project-analyzer/SKILL.md) |  | ONLY when user explicitly requests: full project analysis, tech stack detection, or structured analysis documents for agents/analysis/. NOT for regular feature work. |
 | skill | [`project-docs`](../.agent-src/skills/project-docs/SKILL.md) |  | Use when looking for project-specific documentation. Knows which docs exist in agents/docs/ and agents/contexts/ and maps work areas to relevant docs. |
+| skill | [`prompt-optimizer`](../.agent-src/skills/prompt-optimizer/SKILL.md) |  | Use when the user wants a prompt optimized for ChatGPT, Claude, Gemini, or another AI — 'make this prompt better', 'optimize for ChatGPT', 'rewrite my prompt' — even without saying 'optimize'. |
 | skill | [`quality-tools`](../.agent-src/skills/quality-tools/SKILL.md) |  | Use when PHPStan, Rector, or ECS output appears — \"phpstan says mixed\", type errors, \"fix code style\", \"run rector\" — even when Eloquent/Laravel/model code is also mentioned. |
 | skill | [`react-shadcn-ui`](../.agent-src/skills/react-shadcn-ui/SKILL.md) |  | Use when building React UI on shadcn/ui primitives + Tailwind — the apply/review/polish skill dispatched by `directives/ui/*` for the `react-shadcn` stack. |
 | skill | [`readme-reviewer`](../.agent-src/skills/readme-reviewer/SKILL.md) |  | Use when reviewing a README for accuracy, usability, and alignment with the actual repository. Detects invented content, broken setup steps, and structural issues. |
@@ -113,6 +117,7 @@ are excluded.
 | skill | [`refine-ticket`](../.agent-src/skills/refine-ticket/SKILL.md) |  | Refine a Jira/Linear ticket before planning — 'refine ticket', 'tighten AC on PROJ-123', 'ist das Ticket klar?' — rewritten ticket, Top-5 risks, persona voices, sub-skills orchestrated, close-prompt. |
 | skill | [`requesting-code-review`](../.agent-src/skills/requesting-code-review/SKILL.md) |  | Use when asking for a review or creating a PR — self-review first, frame the right context, test plan included — even when the user just says 'open a PR' or 'ready to merge'. |
 | skill | [`review-routing`](../.agent-src/skills/review-routing/SKILL.md) |  | Use when preparing a PR description, suggesting reviewers, or flagging risk — produces owner-mapped roles plus historical bug-pattern matches from project-local YAML. |
+| skill | [`rice-prioritization`](../.agent-src/skills/rice-prioritization/SKILL.md) |  | Use when ranking competing initiatives for a roadmap, breaking a tie between two features, or auditing a backlog for hidden low-value work via Reach × Impact × Confidence ÷ Effort. |
 | skill | [`roadmap-management`](../.agent-src/skills/roadmap-management/SKILL.md) |  | Use when the user says "create roadmap", "show roadmap", or "execute roadmap". Creates, reads, and manages roadmap files with phase tracking. |
 | skill | [`rtk-output-filtering`](../.agent-src/skills/rtk-output-filtering/SKILL.md) |  | Use when running verbose CLI commands — wraps them with rtk (Rust Token Killer) for 60-90% token savings. Covers installation, configuration, and usage patterns. |
 | skill | [`rule-writing`](../.agent-src/skills/rule-writing/SKILL.md) |  | Use when creating or editing a rule in .agent-src.uncompressed/rules/ — trigger wording, always vs auto classification, size budget — even when the user just says 'add a rule for X'. |
@@ -125,7 +130,7 @@ are excluded.
 | skill | [`skill-reviewer`](../.agent-src/skills/skill-reviewer/SKILL.md) |  | Use when reviewing, auditing, or optimizing skills — validates against the 7 Skill Killers checklist and produces fix recommendations. |
 | skill | [`skill-writing`](../.agent-src/skills/skill-writing/SKILL.md) |  | Use when deciding 'should this be a skill or a rule?', creating/improving/reviewing agent skills, SKILL.md frontmatter, or procedure sections — even without saying 'skill-writing'. |
 | skill | [`sql-writing`](../.agent-src/skills/sql-writing/SKILL.md) |  | Use when writing raw SQL — MariaDB/MySQL syntax, parameterization, raw migrations, seeders with `DB::statement` — even when the user just pastes a query and asks 'why is this slow' without naming SQL. |
-| skill | [`subagent-orchestration`](../.agent-src/skills/subagent-orchestration/SKILL.md) |  | Use when orchestrating implementer/judge subagents — five modes (do-and-judge, do-in-steps, do-in-parallel, do-competitively, judge-with-debate) — models from .agent-settings.yml. |
+| skill | [`subagent-orchestration`](../.agent-src/skills/subagent-orchestration/SKILL.md) |  | Use when orchestrating implementer/judge subagents — six modes (do-and-judge, do-in-steps, do-in-parallel, do-competitively, judge-with-debate, do-in-worktrees) — models from .agent-settings.yml. |
 | skill | [`systematic-debugging`](../.agent-src/skills/systematic-debugging/SKILL.md) |  | Use when hitting a bug, test failure, crash, or unexpected behavior — enforces reproduce → isolate → hypothesize → verify before any fix — even when the user just says 'this is broken' or 'quick fix'. |
 | skill | [`technical-specification`](../.agent-src/skills/technical-specification/SKILL.md) |  | Use when the user says "write a spec", "create RFC", or "document this decision". Writes technical specifications, RFCs, and ADRs with clear structure. |
 | skill | [`terraform`](../.agent-src/skills/terraform/SKILL.md) |  | Use when writing Terraform — AWS modules, resources, variables, outputs, remote state — even when the user just says 'provision this infra' or 'add an S3 bucket' without naming Terraform. |
@@ -133,7 +138,9 @@ are excluded.
 | skill | [`test-driven-development`](../.agent-src/skills/test-driven-development/SKILL.md) |  | Use when implementing a feature, fixing a bug, or refactoring — write a failing test first, then the code — even if the user just says 'add this function' or 'fix this bug'. |
 | skill | [`test-performance`](../.agent-src/skills/test-performance/SKILL.md) |  | Use when optimizing test suite performance — database setup, seeder optimization, parallel testing, CI pipeline efficiency, or RefreshDatabase alternatives. |
 | skill | [`threat-modeling`](../.agent-src/skills/threat-modeling/SKILL.md) |  | Use when adding auth, webhooks, uploads, queues, secrets, tenant boundaries, or public endpoints — produces trust boundaries + abuse cases mapped to files, BEFORE implementation. |
+| skill | [`token-optimizer`](../.agent-src/skills/token-optimizer/SKILL.md) |  | Use BEFORE any verbose CLI run, large file read, doc conversion, or near-context handoff — single decision tree keyed by intent that cites the canonical token-saving asset. Consult before the action. |
 | skill | [`traefik`](../.agent-src/skills/traefik/SKILL.md) |  | Use when setting up Traefik as a local reverse proxy — real domains on 127.0.0.1, trusted HTTPS via mkcert, automatic service discovery, and multi-project routing. |
+| skill | [`unit-economics-modeling`](../.agent-src/skills/unit-economics-modeling/SKILL.md) |  | Use when modeling CAC, LTV, gross-margin payback, or contribution margin per customer — for SaaS, marketplace, or transactional businesses. |
 | skill | [`universal-project-analysis`](../.agent-src/skills/universal-project-analysis/SKILL.md) |  | ONLY when user explicitly requests: full project analysis, deep codebase audit, or comprehensive architecture review. Routes to core and framework-specific analysis skills. |
 | skill | [`upstream-contribute`](../.agent-src/skills/upstream-contribute/SKILL.md) |  | Use when a learning, new skill, rule improvement, or bug fix from a consumer project should be contributed back to the shared agent-config package. |
 | skill | [`using-git-worktrees`](../.agent-src/skills/using-git-worktrees/SKILL.md) |  | Use when starting parallel work in isolation from the current branch — spawn a git worktree with ignore-safety checks and a clean test baseline — even when the user says 'try this on the side'. |
@@ -154,9 +161,6 @@ are excluded.
 | rule | [`ask-when-uncertain`](../.agent-src/rules/ask-when-uncertain.md) | always | Ask when uncertain — don't guess, assume, or improvise |
 | rule | [`autonomous-execution`](../.agent-src/rules/autonomous-execution.md) | auto | 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 |
 | rule | [`capture-learnings`](../.agent-src/rules/capture-learnings.md) | auto | After completing a task where a repeated mistake or successful pattern appeared — capture as rule or skill |
-| rule | [`chat-history-cadence`](../.agent-src/rules/chat-history-cadence.md) | auto | 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 |
-| rule | [`chat-history-ownership`](../.agent-src/rules/chat-history-ownership.md) | auto | 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 |
-| rule | [`chat-history-visibility`](../.agent-src/rules/chat-history-visibility.md) | auto | 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 |
 | rule | [`cli-output-handling`](../.agent-src/rules/cli-output-handling.md) | auto | 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. |
 | rule | [`command-suggestion-policy`](../.agent-src/rules/command-suggestion-policy.md) | auto | 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 |
 | rule | [`commit-conventions`](../.agent-src/rules/commit-conventions.md) | auto | Git commit message format, branch naming, conventional commits, committing, pushing, or creating pull requests |
@@ -174,7 +178,9 @@ are excluded.
 | rule | [`minimal-safe-diff`](../.agent-src/rules/minimal-safe-diff.md) | auto | When writing or reviewing a diff — the smallest change that solves the stated problem; no drive-by edits, no opportunistic refactors, no reformatting of untouched code |
 | rule | [`missing-tool-handling`](../.agent-src/rules/missing-tool-handling.md) | auto | When a CLI tool needed for the task is not installed — ask before working around it; do NOT install silently |
 | rule | [`model-recommendation`](../.agent-src/rules/model-recommendation.md) | auto | Starting a new task, switching task type, or invoking a command — detect task complexity and recommend the optimal model (Opus/Sonnet/GPT) before any work |
+| rule | [`no-attribution-footers`](../.agent-src/rules/no-attribution-footers.md) | auto | Generating PR/issue/comment/commit-message bodies — forbids unsolicited 'Generated with', 'Co-authored by', or 'Pull Request opened by' attribution footers in any user-owned artifact |
 | rule | [`no-cheap-questions`](../.agent-src/rules/no-cheap-questions.md) | always | No cheap questions — never ask what context answers, never offer Iron-Law-violating options, never stage no-trade-off choices; mode-independent (off / auto / on) |
+| rule | [`no-council-references`](../.agent-src/rules/no-council-references.md) | auto | Linking a specific file in agents/council-{questions,responses,sessions}/ from any artifact — council files are gitignored, local-only, auto-pruned; inline the convergence instead |
 | rule | [`no-roadmap-references`](../.agent-src/rules/no-roadmap-references.md) | auto | Adding a link to a specific file in agents/roadmaps/ from any stable artifact (rule, skill, command, context, guideline) — roadmaps are transient; promote durable findings to agents/contexts/ instead |
 | rule | [`non-destructive-by-default`](../.agent-src/rules/non-destructive-by-default.md) | always | Agent is never destructive — Hard Floor always asks for prod-trunk merges, deploys, pushes, prod data/infra, bulk deletions, and bulk-deletion/infra commits; no autonomy or roadmap bypass |
 | rule | [`onboarding-gate`](../.agent-src/rules/onboarding-gate.md) | auto | First turn of a conversation on a project — check onboarding.onboarded in .agent-settings.yml; when false, prompt the user to run /onboard before executing any other request |
@@ -195,6 +201,7 @@ are excluded.
 | rule | [`slash-command-routing-policy`](../.agent-src/rules/slash-command-routing-policy.md) | auto | When user types a slash command like /create-pr, /commit, or pastes command file content |
 | rule | [`think-before-action`](../.agent-src/rules/think-before-action.md) | auto | Before coding, modifying, or debugging — analyze first, verify with real tools, never guess or trial-and-error |
 | rule | [`token-efficiency`](../.agent-src/rules/token-efficiency.md) | auto | When running CLI tools, fetching logs, or producing replies — redirect verbose output, minimize tool calls, keep replies concise |
+| rule | [`token-optimizer-maintenance`](../.agent-src/rules/token-optimizer-maintenance.md) | auto | Editing a token-optimizer-cited asset (cli-output-handling, rtk-output-filtering, token-efficiency, agent-handoff, direct-answers, markitdown) — keep the catalog row in sync in the same commit. |
 | rule | [`tool-safety`](../.agent-src/rules/tool-safety.md) | auto | When a skill uses external tools — enforce allowlist, deny-by-default, and no hidden credential patterns |
 | rule | [`ui-audit-gate`](../.agent-src/rules/ui-audit-gate.md) | auto | Writing or editing UI — components, screens, partials, layouts, design tokens — require existing-ui-audit findings in state.ui_audit before non-trivial UI change; gate, not suggestion |
 | rule | [`upstream-proposal`](../.agent-src/rules/upstream-proposal.md) | auto | After creating or significantly improving a skill, rule, guideline, or command — ask if it should be contributed upstream to the shared package |
@@ -214,11 +221,10 @@ are excluded.
 | command | [`analyze-reference-repo`](../.agent-src/commands/analyze-reference-repo.md) |  | Analyze an external reference repository (competitor, inspiration, peer) and produce a structured comparison + adoption plan for this project. |
 | command | [`bug-fix`](../.agent-src/commands/bug-fix.md) |  | Plan and implement a bug fix — based on investigation, with quality checks and test verification |
 | command | [`bug-investigate`](../.agent-src/commands/bug-investigate.md) |  | Investigate a bug — auto-detect ticket from branch, gather Jira/Sentry/description context, trace root cause |
-| command | [`chat-history:checkpoint`](../.agent-src/commands/chat-history/checkpoint.md) | cluster: chat-history | Append a phase-boundary entry to .agent-chat-history — CHECKPOINT fallback for platforms without a native hook (Augment IDE, Cursor pre-1.7, Cline non-Mac/Linux). ~1s. |
-| command | [`chat-history:clear`](../.agent-src/commands/chat-history/clear.md) | cluster: chat-history | Manually delete the persistent chat-history log — asks for confirmation, optionally archives to a timestamped backup before wiping |
-| command | [`chat-history:resume`](../.agent-src/commands/chat-history/resume.md) | cluster: chat-history | Load the persistent chat-history log into the current conversation — picks match/returning/foreign flow and supports resume, merge, replace, or continue |
+| command | [`chat-history:import`](../.agent-src/commands/chat-history/import.md) | cluster: chat-history | Surface prior chat-history sessions as a numbered table, let the user pick one, read it silently, and emit a short summary plus a resume offer — selective, user-driven cross-session import |
+| command | [`chat-history:learn`](../.agent-src/commands/chat-history/learn.md) | cluster: chat-history | Pick a prior chat-history session and mine it for project-improving learnings — runs learning-to-rule-or-skill on the picked session, drafts proposal(s) under agents/proposals/ |
 | command | [`chat-history:show`](../.agent-src/commands/chat-history/show.md) | cluster: chat-history | Show the status of the persistent chat-history log — file size, entry count, header fingerprint, age, and the last few entries |
-| command | [`chat-history`](../.agent-src/commands/chat-history.md) | cluster: chat-history | Chat-history orchestrator — routes to show, resume, clear, checkpoint |
+| command | [`chat-history`](../.agent-src/commands/chat-history.md) | cluster: chat-history | Chat-history orchestrator — routes to show, import, learn |
 | command | [`check-current-md`](../.agent-src/commands/check-current-md.md) |  | Check the open .md file (or a passed path) for German outside DE:/EN: anchor blocks — umlauts, function words, untranslated quotes. Reports and offers fixes. |
 | command | [`commit:in-chunks`](../.agent-src/commands/commit/in-chunks.md) | cluster: commit | Stage and commit all uncommitted changes in logical chunks WITHOUT confirmation — sibling of /commit for autonomous flows |
 | command | [`commit`](../.agent-src/commands/commit.md) | cluster: commit | Stage and commit all uncommitted changes — splits into logical commits following Conventional Commits |
@@ -273,6 +279,7 @@ are excluded.
 | command | [`optimize:augmentignore`](../.agent-src/commands/optimize/augmentignore.md) | cluster: optimize | Creates or updates .augmentignore based on the project's actual tech stack, large files, generated artifacts, and irrelevant agent skills/rules. |
 | command | [`optimize:rtk`](../.agent-src/commands/optimize/rtk.md) | cluster: optimize | Create or optimize project-local rtk filters based on the actual toolchain |
 | command | [`optimize:skills`](../.agent-src/commands/optimize/skills.md) | cluster: optimize | Audits skills — measures baseline, finds duplicates/merge candidates, runs linter. Suggest only, never auto-apply. |
+| command | [`optimize-prompt`](../.agent-src/commands/optimize-prompt.md) | cluster: optimize | Optimize a raw prompt for ChatGPT, Claude, Gemini, or another AI via the 4-D methodology — BASIC vs DETAIL auto-detect, one clarifying question per turn, returns the polished prompt. |
 | command | [`optimize`](../.agent-src/commands/optimize.md) | cluster: optimize | Optimize orchestrator — routes to skills, agents, augmentignore, rtk-filters |
 | command | [`override:create`](../.agent-src/commands/override/create.md) | cluster: override | Creates a project-level override for a shared skill, rule, or command. |
 | command | [`override:manage`](../.agent-src/commands/override/manage.md) | cluster: override | Reviews, updates, and refactors existing project-level overrides. |
@@ -301,7 +308,7 @@ are excluded.
 | command | [`upstream-contribute`](../.agent-src/commands/upstream-contribute.md) |  | Contribute a learning, skill, rule, or fix from a consumer project back to the shared agent-config package |
 | command | [`work`](../.agent-src/commands/work.md) |  | Drive a free-form prompt end-to-end through refine → score → plan → implement → test → verify → report — Option-A loop over the `work_engine` Python engine, confidence-band gated, no auto-git. |
 
-## Guidelines (51)
+## Guidelines (56)
 
 | kind | name | category | description |
 |---|---|---|---|
@@ -318,13 +325,17 @@ are excluded.
 | guideline | [`naming`](../docs/guidelines/agent-infra/naming.md) | agent-infra |  |
 | guideline | [`output-patterns`](../docs/guidelines/agent-infra/output-patterns.md) | agent-infra |  |
 | guideline | [`review-routing-data-format`](../docs/guidelines/agent-infra/review-routing-data-format.md) | agent-infra |  |
+| guideline | [`roadmap-progress-mechanics`](../docs/guidelines/agent-infra/roadmap-progress-mechanics.md) | agent-infra |  |
 | guideline | [`role-contracts`](../docs/guidelines/agent-infra/role-contracts.md) | agent-infra |  |
 | guideline | [`role-mode-router`](../docs/guidelines/agent-infra/role-mode-router.md) | agent-infra |  |
+| guideline | [`rule-type-governance`](../docs/guidelines/agent-infra/rule-type-governance.md) | agent-infra |  |
 | guideline | [`runtime-layer`](../docs/guidelines/agent-infra/runtime-layer.md) | agent-infra |  |
 | guideline | [`self-improvement-pipeline`](../docs/guidelines/agent-infra/self-improvement-pipeline.md) | agent-infra |  |
 | guideline | [`size-and-scope`](../docs/guidelines/agent-infra/size-and-scope.md) | agent-infra |  |
+| guideline | [`skill-quality-checklist`](../docs/guidelines/agent-infra/skill-quality-checklist.md) | agent-infra |  |
 | guideline | [`tool-integration`](../docs/guidelines/agent-infra/tool-integration.md) | agent-infra |  |
 | guideline | [`verify-before-complete-demos`](../docs/guidelines/agent-infra/verify-before-complete-demos.md) | agent-infra |  |
+| guideline | [`augment-portability-patterns`](../docs/guidelines/augment-portability-patterns.md) | (root) |  |
 | guideline | [`readme-size-and-splitting`](../docs/guidelines/docs/readme-size-and-splitting.md) | docs |  |
 | guideline | [`playwright`](../docs/guidelines/e2e/playwright.md) | e2e |  |
 | guideline | [`api-design`](../docs/guidelines/php/api-design.md) | php |  |
@@ -351,6 +362,7 @@ are excluded.
 | guideline | [`strategy`](../docs/guidelines/php/patterns/strategy.md) | patterns |  |
 | guideline | [`patterns`](../docs/guidelines/php/patterns.md) | php |  |
 | guideline | [`performance`](../docs/guidelines/php/performance.md) | php |  |
+| guideline | [`php-coding-patterns`](../docs/guidelines/php/php-coding-patterns.md) | php |  |
 | guideline | [`resources`](../docs/guidelines/php/resources.md) | php |  |
 | guideline | [`security`](../docs/guidelines/php/security.md) | php |  |
 | guideline | [`sql`](../docs/guidelines/php/sql.md) | php |  |

package/docs/contracts/adr-chat-history-split.md

@@ -4,7 +4,16 @@ stability: beta
 
 # ADR — Chat-history rule split
 
-> **Status:** Decided · 2026-05-02
+> **Status:** Superseded · 2026-05-04 · by
+> [`agents/contexts/chat-history-platform-hooks.md`](../../agents/contexts/chat-history-platform-hooks.md).
+> The cooperative three-rule split this ADR locked in
+> (`chat-history-ownership` / `-cadence` / `-visibility`) has been
+> reduced to a hook-only structural artifact. The three always-rules,
+> the heartbeat marker, and the Foreign-Prompt handshake are gone;
+> `session_start` hooks auto-adopt foreign sessions silently. The text
+> below is preserved for historical context only.
+>
+> **Original status:** Decided · 2026-05-02
 > **Context:** AI #1, AI #3, AI #5 review of PR #29 flagged the
 > 200-line monolithic `rules/chat-history.md` as the rule the agent
 > revisited 12+ times during the 1.14.0 cycle — three independent

package/docs/contracts/agent-memory-contract.md

@@ -13,7 +13,7 @@ helpers.
 **Ownership.** `agent-memory` is ours; we decide release timing. This
 doc is internal, not a spec handed to an external team. The
 authoritative spec-side documents live under
-[`agents/roadmaps/agent-memory/`](../../agents/roadmaps/agent-memory/); this context
+[`agents/roadmaps/agent-memory/`](../../agents/roadmaps/archive/agent-memory/); this context
 is the **consumer-side snapshot** — what our wired code assumes today.
 
 Last refreshed: 2026-04-22.

package/docs/contracts/command-clusters.md

@@ -30,7 +30,7 @@ column 1 of this table.
 | `fix` | 1 | `ci` · `pr` · `pr-bots` · `pr-developers` · `portability` · `refs` · `seeder` | `fix-ci` · `fix-pr-comments` · `fix-pr-bot-comments` · `fix-pr-developer-comments` · `fix-portability` · `fix-references` · `fix-seeder` |
 | `optimize` | 1 | `agents` · `augmentignore` · `rtk` · `skills` | `optimize-agents` · `optimize-augmentignore` · `optimize-rtk-filters` · `optimize-skills` |
 | `feature` | 1 | `explore` · `plan` · `refactor` · `roadmap` · `dev` | `feature-explore` · `feature-plan` · `feature-refactor` · `feature-roadmap` · `feature-dev` |
-| `chat-history` | 2 | `show` · `resume` · `clear` · `checkpoint` | `chat-history` (legacy status) · `chat-history-resume` · `chat-history-clear` · `chat-history-checkpoint` |
+| `chat-history` | 2 | `show` · `import` · `learn` | `chat-history` (legacy status) — `resume` / `clear` / `checkpoint` removed in `road-to-chat-history-hook-only` (auto-adopt + structural hooks); `import` (verbatim cross-session render) and `learn` (project-improving learning extraction) added in the v4 stateless schema |
 | `agents` | 2 | `audit` · `cleanup` · `prepare` | `agents-audit` · `agents-cleanup` · `agents-prepare` |
 | `memory` | 2 | `add` · `load` · `promote` · `propose` | `memory-add` · `memory-full` · `memory-promote` · `propose-memory` |
 | `roadmap` | 2 | `create` · `execute` | `roadmap-create` · `roadmap-execute` |

package/docs/contracts/context-paths.md

@@ -34,6 +34,7 @@ a roadmap revision (per `road-to-structural-optimization.md` § Definitions).
 | `contexts/chat-history/` | Phase 6 | `cadence.md`, `ownership.md`, `visibility.md` |
 | `contexts/execution/` | PR #34 (existing) | `<topic>-mechanics.md`, `<topic>-detection.md`, `<topic>-examples.md` |
 | `contexts/authority/` | PR #34 (existing) | `<topic>-mechanics.md` |
+| `contexts/contracts/` | road-to-path-fixes Phase 4 | `<topic>-flow.md` (load-bearing flow contracts cited via `load_context:`) |
 
 ## Grandfathered files
 
@@ -54,7 +55,7 @@ contexts/subagent-configuration.md
 
 1. **Sub-tree allow-list.** Every `*.md` under
    `.agent-src.uncompressed/contexts/` must be either (a) in one of the
-   eight locked sub-trees above, or (b) one of the six grandfathered
+   nine locked sub-trees above, or (b) one of the six grandfathered
    root-level files. Anything else fails CI.
 2. **No collisions.** No two context files may share the same basename
    across sub-trees. `judges/persona-voice-rubric.md` and