@event4u/agent-config 1.19.0 → 1.21.0

package/.agent-src/templates/agent-settings.md

@@ -14,7 +14,7 @@ Keep the format regular — 2-space indent, no tabs, no lists, one nesting
 level only. The installer's YAML handler is a restricted stdlib parser, not
 a full YAML engine. Ask the agent to normalize after manual edits — it
 follows the merge rules in
-[`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules).
+[`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules).
 
 ### Migration from the legacy `.agent-settings` (key=value)
 
@@ -36,7 +36,7 @@ This block defines the personal and project-level settings that
 `scripts/install.py` (via `config/agent-settings.template.yml`)
 writes to `.agent-settings.yml` on first install. Subsequent edits are
 made by the user directly or by the agent on request, following the
-[section-aware merge rules](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules).
+[section-aware merge rules](../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules).
 
 ```yaml
 # Agent Settings
@@ -45,14 +45,19 @@ made by the user directly or by the agent on request, following the
 
 # --- Cost profile ---
 #
-# Controls 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
-cost_profile: minimal
+# minimal  = kernel only (always-loaded Iron-Law floor, ≤ 26k chars).
+#            No router, no auto-rules. Lowest token footprint.
+# balanced = kernel + router + tier-1 auto-rules (default — current behaviour
+#            superset; matches what existing consumer projects expect).
+# full     = kernel + tier-1 + tier-2 (everything). Highest fidelity,
+#            highest token cost. Pick this when working on agent-config
+#            itself or when you need every behavioural rule active.
+# custom   = ignore profile — every matrix value must be set explicitly.
+cost_profile: balanced
 
 # --- Personal preferences ---
 personal:
@@ -122,7 +127,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 (project root, 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.
 #
@@ -141,26 +146,6 @@ chat_history:
   # Overflow behavior: rotate (drop oldest) | compress (summarize)
   on_overflow: rotate
 
-  # Heartbeat marker visibility: on | off | hybrid
-  #   on     — print marker every reply (~20 tokens/reply, legacy)
-  #   off    — never print (zero tokens, no drift signal)
-  #   hybrid — print only on drift (missing/foreign/returning); silent otherwise
-  # YAML 1.1 booleanizes bare on/off — both are accepted, no quoting needed.
-  heartbeat: hybrid
-
-  # Population path: hook | checkpoint | manual
-  #   hook       — platform fires lifecycle hooks; agent observes only
-  #                (Claude Code, Augment CLI, Cursor 1.7+, Cline non-Windows,
-  #                 Windsurf, Gemini CLI). scripts/install.py wires hooks.
-  #   checkpoint — agent invokes /chat-history-checkpoint at phase boundaries
-  #                (Augment IDE plugin, Cursor < 1.7, Cline on Windows).
-  #                Cooperative three-gate Iron Law applies.
-  #   manual     — rule is inert (cloud surfaces). Persistence is local-only.
-  # Default `checkpoint` is the safest cooperative fallback. HOOK platforms
-  # set this to `hook` automatically when scripts/install.py merges the
-  # platform's settings file.
-  path: checkpoint
-
 # --- Work-engine hooks ---
 #
 # Lifecycle hook surface of the `work_engine` Python engine
@@ -197,7 +182,7 @@ hooks:
   # routing drift.
   directive_set_guard: true
 
-  # Chat-history hooks — populate .agent-chat-history structurally from
+  # Chat-history hooks — populate agents/.agent-chat-history structurally from
   # the engine. Gated by BOTH this block AND the global
   # chat_history.enabled above; either off → no chat-history hook
   # registers. Keep both on for the HOOK path; flip either off to fall
@@ -314,8 +299,8 @@ commands:
 # rules, commands, guidelines, personas) the agent consulted and
 # applied. Local only, append-only JSONL, never reaches a consumer
 # repo (gitignored). Maintainer-targeted feature; consumers leave it
-# off. See `docs/contracts/artifact-engagement-flow.md` (once Phase 3
-# of road-to-artifact-engagement-telemetry lands).
+# off. See `.augment/contexts/contracts/artifact-engagement-flow.md`
+# (once Phase 3 of road-to-artifact-engagement-telemetry lands).
 telemetry:
   artifact_engagement:
     # Master switch. `false` (default) produces zero file IO and zero
@@ -343,7 +328,7 @@ telemetry:
 
 Personal and project-level settings (initial file written by
 `scripts/install.py`, edits follow the merge rules in
-[`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)).
+[`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)).
 **Key paths use dot-notation** to denote nesting: `personal.user_name`
 lives under `personal:` in YAML.
 
@@ -363,27 +348,26 @@ lives under `personal:` in YAML.
 | `project.improvement_pr_branch_prefix` | string | `improve/agent-` | Branch prefix for agent improvement PRs. |
 | `github.pr_reply_method` | `replies_endpoint`, `create_review_comment`, `auto` | `create_review_comment` | GitHub API method for replying to PR review comments. `auto` detects on first use. |
 | `eloquent.access_style` | `getters_setters`, `get_attribute`, `magic_properties` | `getters_setters` | How to access Eloquent model attributes. See `eloquent` skill for details. |
-| `chat_history.enabled` | `true`, `false` | `true` | Persist chat events to `.agent-chat-history` (JSONL) for crash recovery. |
+| `chat_history.enabled` | `true`, `false` | `true` | Persist chat events to `agents/.agent-chat-history` (JSONL) for crash recovery. |
 | `chat_history.frequency` | `per_turn`, `per_phase`, `per_tool` | per profile | Logging granularity. Defaults: `minimal`→`per_turn`, `balanced`→`per_phase`, `full`→`per_tool`. |
 | `chat_history.max_size_kb` | integer | per profile | Max file size before overflow handling. Defaults: `minimal`→`128`, `balanced`→`256`, `full`→`512`. |
 | `chat_history.on_overflow` | `rotate`, `compress` | per profile | On overflow: `rotate` drops oldest entries; `compress` marks the file for summarization on the next turn. Defaults: `minimal`/`balanced`→`rotate`, `full`→`compress`. |
-| `chat_history.heartbeat` | `on`, `off`, `hybrid` | `hybrid` | Visibility of the `📒 chat-history:` marker. `on` = every reply (~20 tokens), `off` = silent, `hybrid` = print only on drift states (`missing`/`foreign`/`returning`). YAML `on`/`off` accepted bare. |
-| `chat_history.path` | `hook`, `checkpoint`, `manual` | `checkpoint` | Population path. `hook` = platform fires lifecycle hooks; `checkpoint` = agent invokes `/chat-history-checkpoint` at phase boundaries; `manual` = rule inert (cloud). `scripts/install.py` flips this to `hook` when the platform's hook config is deployed. See [`agents/contexts/chat-history-platform-hooks.md`](../../../agents/contexts/chat-history-platform-hooks.md). |
+| `chat_history.text_limits.{user,agent,tool,phase}` | integer (chars) | `user=0`, `agent=5000`, `tool=200`, `phase=200` | Per-entry-type text-length cap. `0` = verbatim, no slice. `N > 0` = collapse whitespace, slice to N chars, append `" … [+K chars]"` so the log self-reports truncation. Defaults match `DEFAULT_TEXT_LIMITS` in `scripts/chat_history.py`. |
 | `hooks.enabled` | `true`, `false` | `false` | Master switch for the work-engine hook layer. When `false` (default) the registry stays empty and golden replay is byte-stable. See [`agents/contexts/work-engine-hooks.md`](../../../agents/contexts/work-engine-hooks.md). |
 | `hooks.trace` | `true`, `false` | `false` | Emit per-event trace lines on stderr. Useful for debugging; off by default because it is noisy. |
 | `hooks.halt_surface_audit` | `true`, `false` | `true` | Defense-in-depth check that every halt surfaced by the dispatcher carries the expected shape. Cheap. |
 | `hooks.state_shape_validation` | `true`, `false` | `true` | Re-run the state schema validator on `AFTER_LOAD` and `BEFORE_SAVE`. Cheap, catches drift. |
 | `hooks.directive_set_guard` | `true`, `false` | `true` | Verify the dispatcher-resolved directive set matches the input envelope intent. Cheap, catches routing drift. |
-| `hooks.chat_history.enabled` | `true`, `false` | `true` | Register the four chat-history hooks (turn-check, append, halt-append, heartbeat). Gated by **both** this flag AND `chat_history.enabled`; either off → no chat-history hook registers. |
+| `hooks.chat_history.enabled` | `true`, `false` | `true` | Register the chat-history hooks (`append` on `after_step`, `halt_append` on `on_halt`). Gated by **both** this flag AND `chat_history.enabled`; either off → no chat-history hook registers. Schema v4: every entry self-identifies via a 16-char session fingerprint, no ownership/sidecar layer. |
 | `hooks.chat_history.script` | path | `scripts/chat_history.py` | Override path to the chat-history CLI. Set only when the script lives outside the standard location. |
 | `pipelines.skill_improvement` | `true`, `false` | `true` | When `true`: propose learning capture after meaningful tasks. When `false`: silent. Included in every profile except `custom`. |
 | `roadmap.quality_cadence` | `end_of_roadmap`, `per_phase`, `per_step` | `end_of_roadmap` | When `/roadmap execute` runs the project's quality pipeline. Default skips per-step / per-phase runs and gates only the final archival. `per_phase` runs once after every phase; `per_step` is the legacy verbose mode. Step checkboxes and the dashboard are always updated regardless. `verify-before-complete` still requires fresh output before any "roadmap complete" claim. |
 | `subagents.implementer_model` | model alias or empty | _(empty)_ | Model for implementer subagents. Empty = same tier as session model. See [subagent-configuration](../contexts/subagent-configuration.md). |
 | `subagents.judge_model` | model alias or empty | _(empty)_ | Model for judge subagents. Empty = one tier above implementer (opus if sonnet, sonnet if haiku). |
 | `subagents.max_parallel` | integer | `3` | Maximum parallel subagent invocations. `1` serializes. |
-| `roles.default_role` | `""`, `developer`, `reviewer`, `tester`, `po`, `incident`, `planner` | _(empty)_ | Role the agent defaults to at the start of a session. See [`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md). |
+| `roles.default_role` | `""`, `developer`, `reviewer`, `tester`, `po`, `incident`, `planner` | _(empty)_ | Role the agent defaults to at the start of a session. See [`role-contracts`](../docs/guidelines/agent-infra/role-contracts.md). |
 | `roles.active_role` | same as `default_role` | _(empty)_ | Role currently active; set by `/mode <name>`, cleared by `/mode none`. Enables the `role-mode-adherence` rule. |
-| `personas.override` | list of persona ids | `[]` | Developer-local override of the team default lens cast. Empty = inherit `personas.default` from `.agent-project-settings.yml`. See [`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md). |
+| `personas.override` | list of persona ids | `[]` | Developer-local override of the team default lens cast. Empty = inherit `personas.default` from `.agent-project-settings.yml`. See [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md). |
 | `personas.ignore` | list of persona ids | `[]` | Persona ids dropped from the default cast locally. Ignored personas stay invokable via `--personas=<id>`. |
 | `onboarding.onboarded` | `true`, `false` | `false` | Whether `/onboard` has run on this project. The `onboarding-gate` rule prompts for `/onboard` when this is `false`. Missing entirely = legacy project, treated as onboarded. |
 | `commands.suggestion.enabled` | `true`, `false` | `true` | Master switch for the command-suggestion layer. `false` = the layer is silent; explicit `/commands` still work. See `rules/command-suggestion-policy.md`. |
@@ -448,7 +432,7 @@ they ship with a live consumer in code and get documented here, not before.
 ## Sync rules
 
 When new settings are added to this template, the
-[section-aware merge rules](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
+[section-aware merge rules](../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
 govern the update:
 
 1. Missing keys are added with their **default value** from this template,

package/.agent-src/templates/contexts/tenant-boundaries.md

@@ -16,10 +16,10 @@
 - [ ] **Single-tenant** — one database per deployment. No cross-tenant
       leakage is possible at the infra layer. Delete this file if true
       and the app will never shard.
-- [ ] **Multi-tenant, shared database** — one table with a tenant key
+- [ ] **Multi-tenant, shared DB** — one table with a tenant key
       column (e.g., `tenant_id`, `workspace_id`).
 - [ ] **Multi-tenant, schema per tenant** — one DB, one schema each.
-- [ ] **Multi-tenant, database per tenant** — each tenant has its own
+- [ ] **Multi-tenant, DB per tenant** — each tenant has its own
       connection.
 
 ## Tenant identifier

package/.agent-src/templates/contexts.md

@@ -24,7 +24,7 @@ agents (and developers) quickly orient themselves when working in that area.
 |---|---|---|
 | **Module** | Document a module's structure and purpose | `client-software.md` |
 | **Domain** | Document a business domain across modules | `import-pipeline.md` |
-| **Service** | Document a complex service and its dependencies | `customer-service.md` |
+| **Service** | Document a complex service and its deps | `customer-service.md` |
 | **Integration** | Document an external API/system integration | `probaus-api.md` |
 | **Infrastructure** | Document infrastructure or DevOps concerns | `queue-system.md` |
 

package/.agent-src/templates/copilot-instructions.md

@@ -86,6 +86,27 @@ This repository contains {{project_description_oneline}}.
 - Do NOT review or suggest changes to unmodified code in the same file.
 - Do NOT nitpick style issues that linters/formatters auto-fix.
 
+## ✅ Known False Positives — Do NOT Flag
+
+The repo ships agent-config rules and skills under `.augment/`,
+`.agent-src/`, and `.agent-src.uncompressed/`. These trees use a
+deliberate path convention; the following patterns are **correct by
+design** — do not flag them as broken:
+
+- **Relative cross-references inside markdown rules / skills** like
+  `[x](../docs/guidelines/foo.md)` or `[y](../contexts/bar.md)`. The
+  base resolves from the file's delivered location (e.g.
+  `.augment/rules/<rule>.md`) — these paths are valid via the
+  `.augment/` tree, even when the file is symlinked into
+  `.claude/rules/`, `.cursor/rules/`, or `.clinerules/`.
+- **`path_prefix:` triggers containing `.agent-src.uncompressed/`**
+  in YAML frontmatter. This is a literal match pattern for the
+  host's router, **not** a file reference — keeping the verbatim
+  source path is required for the rule to fire on the right edits.
+- **Symlinked rule files** under `.claude/rules/`, `.cursor/rules/`,
+  `.clinerules/`. Targets resolve into `.augment/rules/`; missing-file
+  reports here are renderer artifacts, not real bugs.
+
 ## ✅ Code Review Comment Behavior
 
 - **Never create duplicate comments** — one comment per concern per location.

package/.agent-src/templates/copilot-review-instructions.md

@@ -0,0 +1,76 @@
+# Copilot Code Review — Repository-Specific Suppressions
+
+> Read by GitHub Copilot Code Review (PR bot) when reviewing this repo.
+> Companion to `.github/copilot-instructions.md`. **This file is the
+> path-resolution suppression floor** — it carries the rules Copilot
+> needs to *not* flag, sharply scoped to the agent-config layout.
+
+## Why this file exists
+
+The repo ships agent-config rules, skills, commands, and contexts under
+`.augment/`, `.agent-src/`, and (during authoring) `.agent-src.uncompressed/`.
+Cross-references inside those trees are valid via the **delivered**
+`.augment/` layout — not via raw git checkout. Copilot's static checker
+walks the git tree, so it sees broken paths where there are none.
+
+This is **intentional, not a bug**. The installer (`scripts/install.sh`)
+projects `.agent-src/` → `.augment/` and creates the symlinks that make
+the paths resolve at agent runtime.
+
+## ✅ Known False Positives — Do NOT Flag
+
+### Relative cross-references inside markdown rules / skills / commands
+
+```markdown
+[link](../docs/guidelines/foo.md)
+[link](../contexts/bar.md)
+[link](../docs/guidelines/baz.md)
+```
+
+These resolve from the file's delivered location (e.g.
+`.augment/rules/<rule>.md`). Even when the file is symlinked into
+`.claude/rules/`, `.cursor/rules/`, or `.clinerules/`, the relative
+form is correct by construction.
+
+### `path_prefix:` triggers containing `.agent-src.uncompressed/`
+
+```yaml
+triggers:
+  - path_prefix: ".agent-src.uncompressed/rules/"
+```
+
+This is a **literal match string** for the host's router — *not* a file
+reference. Source-of-truth meta-rules (`augment-source-of-truth`,
+`augment-portability`, `skill-quality`, `docs-sync`,
+`rule-type-governance`) legitimately match against the authoring tree.
+
+### Symlinked rule / skill / command files
+
+Targets resolve into `.augment/rules/`, `.augment/skills/`,
+`.augment/commands/` via installer-managed symlinks. Missing-file
+reports under `.claude/`, `.cursor/`, `.clinerules/` are renderer
+artifacts, not real bugs.
+
+### Body-link forms `../docs/guidelines/...`
+
+Single-up form is the post-rewrite shape produced by
+`scripts/compress.py`. The compressed `.agent-src/rules/` tree is one
+level deeper than the source `.agent-src.uncompressed/rules/`, so the
+rewriter collapses `../../docs/...` to `../docs/...`. Both forms are
+expected — one in source, one in compressed output.
+
+## ✅ What TO flag
+
+- Code defects, security issues, broken tests, type errors — normal
+  review.
+- New `.agent-src.uncompressed/` substrings introduced into
+  `.agent-src/rules/` body content (the `check-compressed-paths` task
+  already gates this — flag it as a regression if it slips through).
+- Rule frontmatter with `load_context:` entries that don't follow the
+  logical-name convention (`contexts/<area>/<file>.md`).
+
+## Pointer
+
+The full architecture is in `docs/architecture.md` § "Path resolution
+and Copilot integration". The compressed-path validator is
+`scripts/check_compressed_paths.py`, wired into `task ci`.

package/.agent-src/templates/features.md

@@ -22,7 +22,7 @@ Templates for feature plan files stored in `agents/features/` or `app/Modules/{M
 | 💡 | Idea | Rough concept, not yet validated |
 | 🔍 | Exploring | Being researched and brainstormed |
 | 📋 | Planned | Structured plan complete, ready for roadmap |
-| 🗺️ | Roadmapped | Roadmap(s) generated, ready for implementation |
+| 🗺️ | Roadmapped | Roadmap(s) generated, ready for impl |
 | 🔄 | In Progress | Implementation started |
 | ✅ | Complete | Feature shipped |
 | ❌ | Rejected | Decided not to build |

package/.agent-src/templates/rule.md

@@ -0,0 +1,127 @@
+# Rule Template
+
+> Template for creating new rules in `.agent-src.uncompressed/rules/{rule-name}.md`.
+> Rules ship to `.agent-src/rules/` (compressed) and `.augment/rules/` (projected).
+> Schema: `scripts/schemas/rule.schema.json`.
+
+## Instructions
+
+1. Pick a kebab-case `{rule-name}` matching the file stem.
+2. Copy the template below into `.agent-src.uncompressed/rules/{rule-name}.md`.
+3. Replace placeholders, drop sections that don't apply.
+4. Run `task lint-skills` and `python3 scripts/lint_load_context.py`.
+5. Compress: `bash scripts/compress.sh --changed` then follow the agent flow.
+
+## Path conventions — load-bearing
+
+Two different fields, two different rules. Mixing them up will either
+break linting or produce paths that resolve to nothing in the
+consumer's `.augment/`.
+
+### `load_context:` / `load_context_eager:` — logical names
+
+Use **logical names** rooted at the source — never the
+`.agent-src.uncompressed/` prefix. The compress-time rewriter
+(`scripts/compress.py::_rewrite_paths`) resolves logical names to
+deployment-correct relative paths; the schema regex
+(`scripts/schemas/rule.schema.json`) and `scripts/lint_load_context.py`
+both reject the legacy prefix.
+
+| Write this (logical) | Forbidden (legacy) |
+|---|---|
+| `contexts/execution/verification-mechanics.md` | `.agent-src.uncompressed/contexts/execution/verification-mechanics.md` |
+| `contexts/authority/commit-mechanics.md` | `.agent-src.uncompressed/contexts/authority/commit-mechanics.md` |
+| `agents/contexts/local.md` (project-local) | `.agent-src.uncompressed/contexts/...` for project-only material |
+
+### `triggers[].path_prefix:` — literal match pattern, not a file path
+
+`path_prefix:` is a **literal match pattern** the host evaluates against
+the file the agent is editing — it is **not** a file reference and is
+**not rewritten**. Rules that fire when the agent edits source-of-truth
+files legitimately keep the `.agent-src.uncompressed/` prefix (see
+`skill-quality`, `docs-sync`, `rule-type-governance`,
+`augment-portability`). Rules that fire on consumer-project paths use
+`agents/`, `lang/`, `.augment/`, etc.
+
+| Use case | Example `path_prefix:` |
+|---|---|
+| Fires when editing source-of-truth artifacts | `.agent-src.uncompressed/skills/` |
+| Fires when editing consumer project files | `agents/`, `lang/`, `app/`, `src/` |
+| Fires when editing the projected layer | `.augment/` |
+
+### Body links — `../../docs/...` is fine in source
+
+Source files keep verbatim `../../docs/guidelines/...` and
+`../../docs/contracts/...` links so they work in any markdown viewer.
+The rewriter rewrites them to depth-aware single-up form at compress
+time and is idempotent. Do not pre-rewrite in source.
+
+### Why "logical, depth-aware, idempotent"
+
+A rule at `rules/{name}.md` resolves `contexts/{area}/{file}.md` to
+`../contexts/{area}/{file}.md` in the compressed output; a nested
+file at `commands/{cluster}/{sub}.md` resolves to
+`../../contexts/{area}/{file}.md`. Re-running the rewriter does not
+double-prefix. The full decision history lives in the archived
+path-fixes roadmap under `agents/roadmaps/archive/`.
+
+## Template
+
+````markdown
+---
+type: "always"
+tier: "kernel"
+description: "{One-line trigger sentence — what fires this rule}"
+source: package
+load_context:
+  - contexts/{area}/{file}.md
+triggers:
+  - path_prefix: "{project-relative path or .augment/...}"
+  - keyword: "{trigger-keyword}"
+routes_to:
+  - "skill:{target-skill}"
+---
+
+# {Rule Title}
+
+**Iron Law.** {The single non-negotiable behavior the rule enforces.}
+
+## When this fires
+
+{1–3 bullets on the trigger surface — what the agent is doing when this rule applies.}
+
+## What to do
+
+{Numbered procedure or short directive list. Reference skills / guidelines
+for full detail; rules are pointers, not playbooks.}
+
+## What NOT to do
+
+- {Anti-pattern 1}
+- {Anti-pattern 2}
+
+## See also
+
+- [`{related-rule}`](./{related-rule}.md)
+- [`{guideline-ref}`](docs/guidelines/{group}/{name}.md) — full pattern catalog
+````
+
+## Field reference
+
+| Field | Required | Notes |
+|---|---|---|
+| `type` | yes | `always` or `auto`. Always-rules load every turn; auto-rules require trigger match. |
+| `tier` | yes | `kernel` (Iron Law floor), `tier-1` (default), `tier-2` (full profile only). Legacy values still accepted. |
+| `description` | yes | One sentence, ≤ 500 chars. Trigger-clarity wins over poetry. |
+| `source` | yes | `package` (this repo) or `project` (consumer override). |
+| `load_context` | no | Lazy context list — logical names only. Budget enforced by `lint_load_context.py`. |
+| `load_context_eager` | no | Eager context list — counts against per-rule char budget. |
+| `triggers` | no | Required on non-kernel rules per `rule-router.md`. |
+| `routes_to` | no | `skill:`, `guideline:`, `command:`, `contract:` targets. Forbidden on kernel rules. |
+| `alwaysApply` | no | Cursor/Cline sidecar — by convention `true` for `type: always`. |
+
+## Size budget
+
+- Kernel rules: ≤ 4 000 chars (Iron-Law overrides documented in `docs/contracts/iron-law-overrides.txt`).
+- Non-kernel rules: ≤ 2 500 chars.
+- Enforced by `task lint-rule-budget`.

package/.agent-src/templates/scripts/work_engine/hook_bootstrap.py

@@ -17,8 +17,6 @@ from .hooks import HookRegistry
 from .hooks.builtin import (
     ChatHistoryAppendHook,
     ChatHistoryHaltAppendHook,
-    ChatHistoryHeartbeatHook,
-    ChatHistoryTurnCheckHook,
     DecisionTraceHook,
     DirectiveSetGuardHook,
     HaltSurfaceAuditHook,
@@ -74,12 +72,16 @@ def _build_hook_registry(args: argparse.Namespace) -> HookRegistry:
 def _register_chat_history_hooks(
     registry: HookRegistry, settings: HookSettings,
 ) -> None:
-    """Register the four chat-history hooks bound to the configured script."""
+    """Register the structural chat-history hooks bound to the configured script.
+
+    Hook-only contract (post road-to-chat-history-hook-only): only the
+    append + halt-append hooks remain; cooperative ``turn-check`` /
+    ``heartbeat`` hooks were removed when the cooperative always-rules
+    were retired.
+    """
     script = Path(settings.chat_history_script)
-    ChatHistoryTurnCheckHook(script).register(registry)
     ChatHistoryAppendHook(script).register(registry)
     ChatHistoryHaltAppendHook(script).register(registry)
-    ChatHistoryHeartbeatHook(script).register(registry)
 
 
 __all__ = ["_build_hook_registry", "_register_chat_history_hooks"]

package/.agent-src/templates/scripts/work_engine/hooks/__init__.py

@@ -22,8 +22,6 @@ from __future__ import annotations
 from .builtin import (
     ChatHistoryAppendHook,
     ChatHistoryHaltAppendHook,
-    ChatHistoryHeartbeatHook,
-    ChatHistoryTurnCheckHook,
     DecisionTraceHook,
     DirectiveSetGuardHook,
     HaltSurfaceAuditHook,
@@ -40,8 +38,6 @@ from .runner import HookRunner
 __all__ = [
     "ChatHistoryAppendHook",
     "ChatHistoryHaltAppendHook",
-    "ChatHistoryHeartbeatHook",
-    "ChatHistoryTurnCheckHook",
     "DecisionTraceHook",
     "DirectiveSetGuardHook",
     "HaltSurfaceAuditHook",

package/.agent-src/templates/scripts/work_engine/hooks/builtin/__init__.py

@@ -13,8 +13,6 @@ from __future__ import annotations
 
 from .chat_history_append import ChatHistoryAppendHook
 from .chat_history_halt_append import ChatHistoryHaltAppendHook
-from .chat_history_heartbeat import ChatHistoryHeartbeatHook
-from .chat_history_turn_check import ChatHistoryTurnCheckHook
 from .decision_trace import DecisionTraceHook
 from .directive_set_guard import DirectiveSetGuardHook
 from .halt_surface_audit import HaltSurfaceAuditHook
@@ -25,8 +23,6 @@ from .trace import TraceHook
 __all__ = [
     "ChatHistoryAppendHook",
     "ChatHistoryHaltAppendHook",
-    "ChatHistoryHeartbeatHook",
-    "ChatHistoryTurnCheckHook",
     "DecisionTraceHook",
     "DirectiveSetGuardHook",
     "HaltSurfaceAuditHook",

package/.agent-src/templates/scripts/work_engine/hooks/builtin/_chat_history_base.py

@@ -12,9 +12,6 @@ import sys
 from pathlib import Path
 from typing import Callable, Sequence
 
-from ..context import HookContext
-from ..exceptions import HookError
-
 ProcessRunner = Callable[[Sequence[str]], "subprocess.CompletedProcess[str]"]
 """Callable that runs a subprocess. Production default: ``_default_runner``."""
 
@@ -28,65 +25,24 @@ def _default_runner(cmd: Sequence[str]) -> "subprocess.CompletedProcess[str]":
     return subprocess.run(list(cmd), capture_output=True, text=True, check=False)
 
 
-def _derive_first_user_msg(ctx: HookContext) -> str | None:
-    """Pull a stable first-user-msg out of the available context.
+class _ChatHistoryHookBase:
+    """Shared plumbing — script path and runner.
 
-    CLI-layer events carry ``ctx.work`` (the v1 envelope); dispatcher-layer
-    events (``before_step`` / ``after_step`` / ``on_halt``) carry only
-    ``ctx.delivery`` (the legacy :class:`DeliveryState`). Both shapes feed
-    the same ``id: title`` / ``raw`` derivation so chat-history entries
-    stay stable across the lifecycle. Returns ``None`` when the shape is
-    unknown — callers raise ``HookError`` so the runner converts it to
-    a warning.
+    Schema v4 derives session attribution from the platform ``session_id``
+    (passed by the platform-hook dispatcher), not from a derived
+    first-user-msg. work-engine internal hooks have no platform session
+    in scope, so they omit ``--session-id`` and entries land in the
+    ``<unknown>`` session bucket.
     """
-    work = ctx.work
-    if work is not None and getattr(work, "input", None) is not None:
-        inp = work.input
-        data = getattr(inp, "data", None) or {}
-        kind = getattr(inp, "kind", None)
-        if kind == "prompt":
-            raw = data.get("raw")
-            if raw:
-                return str(raw)
-        elif kind == "ticket":
-            joined = _ticket_msg(data)
-            if joined:
-                return joined
-
-    delivery = ctx.delivery
-    if delivery is not None:
-        ticket = getattr(delivery, "ticket", None) or {}
-        joined = _ticket_msg(ticket)
-        if joined:
-            return joined
-    return None
-
-
-def _ticket_msg(ticket: dict) -> str:
-    ticket_id = ticket.get("id") or ""
-    title = ticket.get("title") or ""
-    return f"{ticket_id}: {title}".strip(": ").strip()
-
-
-class _ChatHistoryHookBase:
-    """Shared plumbing — script path, runner, and first-msg derivation."""
 
     def __init__(
         self,
         script_path: Path,
         *,
         runner: ProcessRunner | None = None,
-        first_user_msg: str | None = None,
     ) -> None:
         self.script_path = Path(script_path)
         self._runner = runner or _default_runner
-        self._fixed_msg = first_user_msg
-
-    def _resolve_msg(self, ctx: HookContext) -> str:
-        msg = self._fixed_msg or _derive_first_user_msg(ctx)
-        if not msg:
-            raise HookError("chat-history hook: cannot derive first-user-msg")
-        return msg
 
     def _invoke(self, *args: str) -> "subprocess.CompletedProcess[str]":
         cmd = [sys.executable, str(self.script_path), *args]

package/.agent-src/templates/scripts/work_engine/hooks/builtin/chat_history_append.py

@@ -29,10 +29,9 @@ class ChatHistoryAppendHook(_ChatHistoryHookBase):
         result = ctx.result
         if result is None or getattr(result, "outcome", None) != Outcome.SUCCESS:
             return
-        msg = self._resolve_msg(ctx)
         payload: dict[str, Any] = {"step": ctx.step_name or "<unknown>"}
         proc = self._invoke(
-            "append", "--first-user-msg", msg,
+            "append",
             "--type", "phase", "--json", json.dumps(payload),
         )
         if proc.returncode != EXIT_OK:

package/.agent-src/templates/scripts/work_engine/hooks/builtin/chat_history_halt_append.py

@@ -22,7 +22,6 @@ class ChatHistoryHaltAppendHook(_ChatHistoryHookBase):
         registry.register(HookEvent.ON_HALT, self._on_halt)
 
     def _on_halt(self, ctx: HookContext) -> None:
-        msg = self._resolve_msg(ctx)
         questions: list[str] = []
         if ctx.result is not None:
             questions = list(getattr(ctx.result, "questions", []) or [])
@@ -30,7 +29,7 @@ class ChatHistoryHaltAppendHook(_ChatHistoryHookBase):
             questions = list(getattr(ctx.delivery, "questions", []) or [])
         payload = {"step": ctx.step_name or "<unknown>", "questions": questions}
         proc = self._invoke(
-            "append", "--first-user-msg", msg,
+            "append",
             "--type", "decision", "--json", json.dumps(payload),
         )
         if proc.returncode != EXIT_OK:

package/.agent-src/templates/scripts/work_engine/hooks/builtin/memory_visibility.py

@@ -4,10 +4,9 @@ Implements the producer side of
 ``docs/contracts/memory-visibility-v1.md``: derive ``asks/hits/ids``
 from ``state.memory`` and thread the rendered line into
 ``state.report`` so the agent's reply naturally carries the memory
-heartbeat.
+visibility marker.
 
-Fires on ``before_save`` for the same reason as
-``ChatHistoryHeartbeatHook``: ``cli._sync_back`` runs between
+Fires on ``before_save``: ``cli._sync_back`` runs between
 ``after_dispatch`` and ``before_save`` and reassigns
 ``work.report = delivery.report``. A line written on
 ``after_dispatch`` would be overwritten before ``_save``; firing on