@event4u/agent-config 1.14.0 → 1.15.0

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

@@ -114,9 +114,20 @@ If yes → switch to the `roadmap-execute` command workflow with the newly creat
 
 - **Do NOT auto-generate content** — always ask the user for input.
 - **Do NOT commit or push.**
-- **Do NOT include commit steps** unless user explicitly requested them.
-  See [`commit-policy`](../rules/commit-policy.md#never-write-commit-steps-into-roadmaps-unsolicited).
+- **Do NOT include commit steps in the roadmap** unless the user explicitly
+  requested them. See [`commit-policy`](../rules/commit-policy.md#never-write-commit-steps-into-roadmaps-unsolicited).
   Roadmaps plan **work**; commits are a separate delivery decision.
+- **Every phase MUST contain at least one `- [ ]` checkbox.** A roadmap
+  without checkboxes is invisible to `agents/roadmaps-progress.md` and
+  violates [`roadmap-progress-sync`](../rules/roadmap-progress-sync.md)
+  Iron Law #2.
+- **Status is binary: `ready` (default) or `draft`.** Create new
+  roadmaps as **ready** — no `status:` field needed, ready is
+  implicit. Only mark `status: draft` (in YAML frontmatter) when the
+  user explicitly says it should be hidden from the dashboard (still
+  being authored, awaiting upstream decisions, capture-only synthesis
+  without executable phases). If the user wants draft, ask once at
+  step 3 — do not infer it.
 - **Write the roadmap in English** (per project convention for `.md` files).
 - Follow the roadmap template from `.augment/templates/roadmaps.md`.
 - Keep the file focused: 500–1000 lines max. If larger, suggest splitting.

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

@@ -65,13 +65,15 @@ For each open step:
 
 ### Rules
 
-- **Commits per [`commit-policy`](../rules/commit-policy.md).** Default: only
-  apply local changes and update the roadmap file — no commits.
-  - Roadmap **without** commit steps → never commit, never ask.
-  - Roadmap **with** commit steps:
-    - **Non-autonomous** (`autonomy: off`, or `auto` before opt-in) → ask before each.
-    - **Autonomous** (`autonomy: on`, or `auto` after opt-in) → pre-scan **before
-      starting**, ask **once** upfront, then proceed silently per the answer.
+- **Commits are governed by [`commit-policy`](../rules/commit-policy.md).**
+  By default: only apply local changes and update the roadmap file — no commits.
+  - If the roadmap **does not** contain explicit commit steps → never commit, never ask.
+  - If the roadmap **does** contain explicit commit steps:
+    - **Non-autonomous** (`personal.autonomy: off`, or `auto` before opt-in) →
+      ask before each commit step.
+    - **Autonomous** (`personal.autonomy: on`, or `auto` after opt-in) →
+      pre-scan the roadmap **before starting**, ask **once** upfront whether
+      to execute the listed commit steps, then proceed silently per the answer.
 - **Push, merge, branch, PR, tag** stay permission-gated by [`scope-control`](../rules/scope-control.md#git-operations--permission-gated).
 - **Always ask before implementing** a step — never auto-execute.
 - **Run quality checks** after each code change.

package/.agent-src/commands/set-cost-profile.md

@@ -8,6 +8,8 @@ suggestion:
   rationale: "Settings mutation — must be deliberate."
 ---
 
+<!-- cloud_safe: noop -->
+
 # /set-cost-profile
 
 Changes `cost_profile` in `.agent-settings.yml`. Four profiles are defined in
@@ -96,6 +98,12 @@ steps here, that's the docs' job.
 - `custom` ignores the profile matrix — every per-feature toggle must be
   set explicitly afterwards. Warn the user when switching to `custom`.
 
+## Cloud Behavior
+
+On cloud surfaces (Claude.ai Web, Skills API) this command is **fully inert** —
+there is no `.agent-settings.yml` to write and no `cost_profile` toggle to
+flip. Cost behaviour on those surfaces is governed by the platform itself.
+
 ## See also
 
 - [`agent-settings`](../templates/agent-settings.md) — profile matrix and settings reference

package/.agent-src/commands/sync-agent-settings.md

@@ -7,6 +7,8 @@ suggestion:
   rationale: "Settings sync — must be deliberate."
 ---
 
+<!-- cloud_safe: noop -->
+
 # /sync-agent-settings
 
 Reconciles `.agent-settings.yml` with the shipped template
@@ -115,6 +117,13 @@ check-only workflows; report the drift and let the pipeline decide.
   presets require a package update in the consumer project before
   this command can apply them.
 
+## Cloud Behavior
+
+On cloud surfaces (Claude.ai Web, Skills API) this command is **fully inert** —
+there is no `.agent-settings.yml` on disk, no `scripts/sync_agent_settings.py`
+to call, and no template/profile preset reachable. Settings reconciliation
+is a local-agent concern.
+
 ## See also
 
 - [`scripts/sync_agent_settings.py`](../../../scripts/sync_agent_settings.py) — the helper

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

@@ -22,9 +22,8 @@ Check in this order — use the **first match**:
 3. **`vendor/bin/pest` exists** → Pest → `vendor/bin/pest`
 4. **Fallback** → PHPUnit → `vendor/bin/phpunit`
 
-**Prefer Makefile targets** over raw commands — they handle container access,
-environment variables, and parallel settings automatically. If the project
-uses a different task runner, inspect its config before falling back to raw.
+**Prefer Makefile targets** over raw commands when they exist — they handle container access,
+environment variables, and parallel settings automatically.
 
 ### 2. Run the tests
 

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

@@ -127,7 +127,7 @@ log — that is a real bug, not a swallowed error.
 ## See also
 
 - [`road-to-artifact-engagement-telemetry`](../../../agents/roadmaps/road-to-artifact-engagement-telemetry.md) — phase contract
-- [`agents/contexts/artifact-engagement-flow.md`](../../../agents/contexts/artifact-engagement-flow.md) — recording contract details
+- [`docs/contracts/artifact-engagement-flow.md`](../../docs/contracts/artifact-engagement-flow.md) — recording contract details
 - [`/implement-ticket`](../commands/implement-ticket.md) and [`/work`](../commands/work.md) — boundary points where this rule fires
 - [`scripts/telemetry/`](../../../scripts/telemetry/) — engine source
 - [`agent-settings`](../templates/agent-settings.md) — `telemetry.artifact_engagement.*` reference

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

@@ -6,38 +6,47 @@ source: package
 
 # Package Portability
 
-Everything shipped with `event4u/agent-config` MUST be **project-agnostic**:
+Everything that ships with the `event4u/agent-config` package MUST be
+**project-agnostic**. That includes:
 
-- `.augment/` (skills, rules, commands, guidelines, templates, contexts)
-- Package root `AGENTS.md`
-- Package `.github/copilot-instructions.md`
+- Everything inside `.augment/` (skills, rules, commands, guidelines,
+  templates, contexts)
+- The package repo's own root `AGENTS.md`
+- The package repo's own `.github/copilot-instructions.md`
 
 All three are either installed into consumer projects (`.augment/` via
-`install.sh`) or read by AI tools working on the package itself. Leaking
-consumer-specific content pollutes downstream or misleads agents.
+`install.sh`) or read by AI tools when working on the package itself
+(`AGENTS.md`, `copilot-instructions.md`). Leaking consumer-specific
+content into any of them pollutes downstream projects or misleads agents.
 
 ## Rules
 
-- NEVER reference a specific consumer project, repo, domain, or tech
-  stack. The package repo itself (`event4u/agent-config`) MAY appear
-  in its own root `AGENTS.md` / `copilot-instructions.md` — meta about
-  the package, not a leak.
+- NEVER reference a specific consumer project, repo name, domain, or tech
+  stack directly. The package repo itself (`event4u/agent-config`) MAY be
+  named inside its own root `AGENTS.md` and `copilot-instructions.md` —
+  that is meta about the package, not a leak.
 - NEVER hardcode consumer-project paths, class names, or conventions.
-- Write content so it works as a reusable package across any project.
-- Project-specific behavior belongs in the **consumer's**
-  `.agent-settings.yml`, `AGENTS.md`, or `agents/` — never here.
-- If a skill/rule needs project-specific input: read from
-  `.agent-settings.yml` or accept as parameter.
-- Always ask when editing package files: "Would this still make sense
-  in a completely different project?"
+- Write content so it works as a **reusable package** across any project.
+- Project-specific behavior belongs in the **consumer's** `.agent-settings.yml`,
+  `AGENTS.md`, or `agents/` — never in files shipped by this package.
+- If a skill or rule needs project-specific input, read it from
+  `.agent-settings.yml` or accept it as a parameter.
+- When reviewing or editing package files, always ask: "Would this still
+  make sense in a completely different project?"
 
 ## Runtime invocations — no `task` commands
 
-Skills, rules, commands, guidelines, personas, contexts shipped by this
-package run in **consumer projects** that may not have Task installed.
-NEVER reference a `task <name>` invocation inside any artefact file
-under `.agent-src.uncompressed/{skills,rules,commands,guidelines,personas,contexts}/`
-(or the compressed mirror under `.agent-src/`). Use the direct script:
+Skills, rules, commands, guidelines, personas, and context docs
+shipped by this package run in **consumer projects**. Consumer
+projects may not have [Task](https://taskfile.dev) installed —
+they might use npm scripts, Composer scripts, Make, or nothing at
+all. A skill that instructs an agent to run `task <something>`
+silently breaks in every project without a `Taskfile.yml`.
+
+**Rule:** Never reference a `task <something>` invocation inside any
+artefact file under `.agent-src.uncompressed/{skills,rules,commands,guidelines,personas,contexts}/`
+(and therefore also not in the compressed mirror under `.agent-src/`).
+Use the direct script invocation instead:
 
 | ❌ Forbidden | ✅ Portable |
 |---|---|
@@ -54,19 +63,29 @@ under `.agent-src.uncompressed/{skills,rules,commands,guidelines,personas,contex
 | `task validate-schema` | `python3 scripts/validate_frontmatter.py` |
 | `task counts-check` | `python3 scripts/update_counts.py --check` |
 | `task roadmap-progress` | `./agent-config roadmap:progress` |
-| `task ci` | run each underlying script directly |
+| `task ci` | run each underlying script directly (no single portable equivalent) |
+
+Task remains a convenience shortcut for maintainers working on the
+package repo itself — `task ci` is the recommended local gate before
+a PR and lives in `Taskfile.yml`, `AGENTS.md`, and the package README.
+Those maintainer-facing surfaces are outside the scope of this rule.
+Artefact files must assume Task is absent.
 
-Task stays a convenience for package maintainers (`Taskfile.yml`,
-`AGENTS.md`, README). Artefact files must assume Task is absent.
+The detection pattern *"if the consumer has a `Makefile` / build
+script, prefer its targets over raw commands"* is still allowed when
+the skill adapts to the **consumer's own** tooling (e.g.
+`tests-execute` detecting `php artisan test` vs `vendor/bin/pest`).
+It is not allowed to reference `task <name>` as the detected target —
+every direct invocation must resolve to a real script path.
 
 ## Consumer CLI — `./agent-config`
 
-A subset of scripts is exposed through a project-local CLI wrapper
-`./agent-config` (written into the project root by the installer,
-gitignored). Artefacts MUST prefer the CLI over raw `python3 scripts/…`
-paths for every command it covers — raw paths only resolve inside the
-package repo, in consumer projects the scripts live under
-`node_modules/` or `vendor/`.
+A subset of package scripts is exposed through a project-local CLI
+wrapper `./agent-config` (written into the project root by the
+installer, gitignored). Artefacts MUST prefer the CLI over raw
+`python3 scripts/…` paths for every command the CLI already covers,
+because the raw paths only resolve inside the package repo — in a
+consumer project the scripts live under `node_modules/` or `vendor/`.
 
 | ❌ Forbidden in artefacts | ✅ Portable |
 |---|---|
@@ -85,13 +104,13 @@ package repo, in consumer projects the scripts live under
 | `python3 scripts/refine_ticket_detect.py` | `./agent-config refine-ticket:detect` |
 
 Commands not covered by the CLI stay as direct script invocations
-(e.g. `bash scripts/compress.sh --sync`) — maintainer-only, not
-reachable from a consumer project anyway.
+(e.g. `bash scripts/compress.sh --sync`) — those are maintainer-only
+and not reachable from a consumer project anyway.
 
 ## Enforcement
 
 `scripts/check_portability.py` scans `.augment/`, `.agent-src.uncompressed/`,
-and the package root `AGENTS.md` + `.github/copilot-instructions.md` for
-forbidden identifiers, for any `task <name>` invocation, and for direct
-script invocations that bypass the `./agent-config` CLI. Runs in CI —
-must pass before any PR.
+and the package repo's root `AGENTS.md` + `.github/copilot-instructions.md`
+for forbidden identifiers, for any `task <name>` invocation inside
+artefact files, and for direct script invocations that bypass the
+`./agent-config` CLI. It runs in CI and must pass before any PR.

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

@@ -0,0 +1,109 @@
+---
+type: "always"
+description: "Append cadence for .agent-chat-history — when to call append (per_turn/per_phase/per_tool), turn-check ownership refusal handling, never write the file directly, cadence is the trigger not reply length"
+alwaysApply: true
+source: package
+---
+
+<!-- cloud_safe: noop -->
+
+# Chat History — Cadence
+
+Owns gate 2 of the chat-history Iron Law: WHEN to call `append`.
+Ownership (gate 1) lives in [`chat-history-ownership`](chat-history-ownership.md);
+visibility (gate 3) lives in [`chat-history-visibility`](chat-history-visibility.md).
+File I/O is owned by [`scripts/chat_history.py`](../../../scripts/chat_history.py)
+— this rule decides the trigger boundaries, not the file format.
+
+## Iron Law — gate 2 (append at every cadence boundary)
+
+```
+EVERY CADENCE BOUNDARY GETS ONE append CALL — WITH --first-user-msg.
+SKIPPING IS A RULE VIOLATION. NEVER WRITE .agent-chat-history DIRECTLY.
+ON HOOK / ENGINE PATHS, THE PLATFORM / ENGINE PERFORMS append STRUCTURALLY
+— THE AGENT MUST NOT DUPLICATE.
+```
+
+Cadence is **gated by ownership**: gate 1 (turn-check from
+[`chat-history-ownership`](chat-history-ownership.md)) must have cleared
+this turn before any append fires. Skip turn-check → append refuses with
+exit `3` (`OWNERSHIP_REFUSED`).
+
+## Append cadence — boundaries
+
+Cadence comes from `chat_history.frequency` in `.agent-settings.yml`:
+
+- `per_turn` → one entry at the end of every agent turn.
+- `per_phase` → at phase boundaries (user question answered, decision
+  taken, task-list item completed, significant tool sequence finished).
+  Pure clarification turns may skip.
+- `per_tool` → after each tool-call sequence.
+
+Every append goes through
+
+```bash
+scripts/chat_history.py append --first-user-msg "<msg>" \
+  --type <user|agent|tool|decision|phase> --json '<obj>'
+```
+
+Never write the file directly. Prefer `phase` over `agent` for boundaries.
+**Cadence is the trigger, not reply length** — a one-line reply that
+crosses a boundary still appends; a 200-line reply that doesn't cross
+one still doesn't. **Do not batch missed turns** — crashes happen
+between turns, and a batched append loses the timeline that crash
+recovery depends on.
+
+## Ownership refusal — exit `3`
+
+`append` exits `3` when the file's ownership header doesn't match the
+current session (`turn-check` was skipped or the file was hijacked
+between turns). Surface the failure to the user, **do not swallow it**:
+
+1. Stop the current append.
+2. Render the Foreign-Prompt from [`chat-history-ownership`](chat-history-ownership.md)
+   so the user re-handshakes.
+3. Resume cadence only after gate 1 clears again.
+
+This is the structural enforcement layer that catches the case where
+an agent technically called `turn-check` but on the wrong platform path
+(e.g. HOOK platform also tried CHECKPOINT cooperative gates and the
+file got into a mixed state).
+
+## Path-specific behavior
+
+**CHECKPOINT path** — gates 1 + 2 are cooperative. The agent runs
+`turn-check` first, then runs `append` at every cadence boundary.
+`/chat-history-checkpoint` is the recommended boundary-trigger; it
+captures phase entries with the right metadata.
+
+**HOOK path** — `work_engine` and platform `SessionStart` /
+`PreToolUse` hooks fire `turn-check` and `append` structurally. The
+agent must **not** call either — double-write produces interleaved
+entries and breaks the JSONL schema. Hooks emit the same exit codes,
+so refusal handling stays identical.
+
+**ENGINE path** — `work_engine` fires `append --type phase` per
+successful step and `append --type decision` on halt. Free-form prose
+around the engine output falls back to whatever path the platform
+supplies (HOOK or CHECKPOINT). Engine-driven turns inherit the
+structural guarantee for the duration of the dispatch cycle only.
+
+## What this rule does NOT do
+
+Manage ownership decisions (handshake, foreign/returning) — those
+live in [`chat-history-ownership`](chat-history-ownership.md).
+Manage the heartbeat marker — that lives in [`chat-history-visibility`](chat-history-visibility.md).
+Decide cadence dynamically based on reply content — cadence is
+the configured frequency, period.
+
+## Cloud Behavior
+
+On cloud surfaces (Claude.ai Web, Skills API) cadence is **inert** —
+no append calls, no `scripts/`, no JSONL file. Treat
+`chat_history.enabled` as `false`.
+
+## Interactions & references
+
+- Sibling rules: [`chat-history-ownership`](chat-history-ownership.md) (gate 1 — turn-check) · [`chat-history-visibility`](chat-history-visibility.md) (gate 3 — heartbeat marker).
+- `token-efficiency` — never load the full log; cadence keeps appends small and bounded.
+- API: [`scripts/chat_history.py`](../../../scripts/chat_history.py) `append` subcommand. Settings: [`agent-settings`](../templates/agent-settings.md) `chat_history.frequency`. Engine hooks: [`agents/contexts/work-engine-hooks.md`](../../../agents/contexts/work-engine-hooks.md).

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

@@ -0,0 +1,123 @@
+---
+type: "always"
+description: "Detect file ownership of .agent-chat-history on first turn — match/returning/foreign/missing handshake, two-paths classification (HOOK/ENGINE/CHECKPOINT/MANUAL), Foreign/Returning numbered-options prompt"
+alwaysApply: true
+source: package
+---
+
+<!-- cloud_safe: noop -->
+
+# Chat History — Ownership
+
+Owns gate 1 of the chat-history Iron Law: the first-turn handshake
+that decides whose `.agent-chat-history` file the current session is
+talking to. Cadence (gate 2) lives in [`chat-history-cadence`](chat-history-cadence.md);
+visibility (gate 3) lives in [`chat-history-visibility`](chat-history-visibility.md).
+File I/O is owned by [`scripts/chat_history.py`](../../../scripts/chat_history.py)
+— this rule says **when** to handshake, not how the file is structured.
+
+## Two paths — platform decides which Iron Law applies
+
+Population of `.agent-chat-history` is **structural** (platform-driven)
+on platforms with native lifecycle hooks, and **cooperative**
+(agent-driven) on platforms without. Both paths converge on the same
+JSONL schema; only the trigger differs. Per-platform classification
+lives in
+[`agents/contexts/chat-history-platform-hooks.md`](../../../agents/contexts/chat-history-platform-hooks.md).
+
+| Path | Platforms / Surfaces | Trigger | Agent's role |
+|---|---|---|---|
+| **HOOK** | Claude Code, Augment CLI, Cursor 1.7+, Cline non-Windows, Windsurf, Gemini CLI | Platform fires native lifecycle hooks → `./agent-config chat-history:hook --platform <name>` | Read-only — observe, do not duplicate appends |
+| **ENGINE** | `/implement-ticket`, `/work`, any flow driven by `scripts/work_engine/cli.py` | `work_engine` fires `turn-check` (before-dispatch), `append --type phase` (per successful step), `--type decision` (on-halt), `heartbeat` (after-dispatch) via the hook layer | Read-only during engine-driven turns — do not duplicate appends. See [`agents/contexts/work-engine-hooks.md`](../../../agents/contexts/work-engine-hooks.md) |
+| **CHECKPOINT** | Augment IDE plugin, Cursor < 1.7, Cline on Windows | Agent invokes `/chat-history-checkpoint` at phase boundaries | Cooperative — gates 1 + 2 + 3 are mandatory |
+| **MANUAL** | Cloud surfaces (Claude.ai Web, Skills API) | Rule is inert — see Cloud Behavior | None |
+
+Detect the path on first turn: read `chat_history.platform` from
+`.agent-settings.yml` if set, else fall back to `chat_history.path`
+(`hook` / `checkpoint` / `manual`). Missing both → assume CHECKPOINT
+(safest cooperative default; HOOK platforms install the platform
+config explicitly via `scripts/install.py`).
+
+## Iron Law — gate 1 (turn-check is the first tool call)
+
+```
+ON CHECKPOINT, turn-check IS THE FIRST TOOL CALL OF EVERY SESSION.
+ON HOOK, THE PLATFORM FIRES turn-check STRUCTURALLY — DO NOT DUPLICATE.
+ON ENGINE, work_engine FIRES turn-check BEFORE DISPATCH — DO NOT DUPLICATE.
+```
+
+CHECKPOINT path — run silently before any other tool call:
+
+```bash
+scripts/chat_history.py turn-check --first-user-msg "<first-user-msg>"
+```
+
+Exit codes: `0` = `ok`/`disabled` (proceed), `10` = `missing`
+(run `init --first-user-msg "..." --freq <freq>`), `11` = `foreign`
+(render Foreign-Prompt + stop), `12` = `returning` (render
+Returning-Prompt + stop). The script writes a one-line
+`ACTION REQUIRED:` hint to stderr on non-zero exits.
+
+## Activation & handshake
+
+Read `chat_history.*` from `.agent-settings.yml` **once per conversation**
+(first turn) and cache. `enabled: false` or section missing → all three
+chat-history rules are a **no-op** (do not read, write, or mention the
+file). Otherwise cache `frequency`, `max_size_kb`, `on_overflow`, and
+the **path** (HOOK / CHECKPOINT / MANUAL — see the table above).
+
+**HOOK path** — skip `turn-check` entirely. The platform's
+`SessionStart` hook already initialized the file; the agent's job is to
+read `status` once for context awareness (header preview, entry count)
+and otherwise leave I/O to the hook dispatcher. Foreign / Returning
+prompts still apply because hooks call into the same ownership state
+machine — when the dispatcher reports `foreign` or `returning` via
+exit code or stderr, render the corresponding prompt.
+
+**CHECKPOINT path** — run `turn-check` as the first tool call. State
+token branches to one of: `missing` → `init`, `ok` → continue,
+`foreign` → Foreign-Prompt, `returning` → Returning-Prompt.
+`/chat-history-checkpoint` is the recommended way to satisfy gate 2
+at phase boundaries (see [`chat-history-cadence`](chat-history-cadence.md)).
+
+In `foreign` and `returning`, **always read the file's current contents
+into the agent's working context before any write** — the user chose to
+log history for a reason; losing it silently is never acceptable. The
+legacy `state` subcommand still works for shell scripts; agents prefer
+`turn-check` (folds in `enabled` + distinct exit codes).
+
+## Foreign / Returning prompts — full mechanics
+
+When `turn-check` exits `11` (foreign) or `12` (returning), render the
+matching numbered-options block from
+[`agents/contexts/chat-history-handshake.md`](../../../agents/contexts/chat-history-handshake.md).
+That doc holds the prompt bodies, the option → script-call mapping
+(`adopt` / `init` / `prepend` / `reset`), the in-memory entries-list
+shape, free-text fallbacks, and the overflow handling per
+`on_overflow` (`rotate` / `compress`). Read it once on first foreign
+or returning event; cache the chosen option for the rest of the
+conversation.
+
+## What this rule does NOT do
+
+Display/reload/clear (`/chat-history*` commands). Auto-flip `enabled` or
+`on_overflow`. Run when `enabled: false`. Decide ownership
+heuristically — only `turn-check` / `state` does that. Double-write on
+HOOK platforms — when hooks fire structurally, the agent does **not**
+also call `turn-check`. Cadence (gate 2) and heartbeat (gate 3) are
+covered in their sibling rules.
+
+## Cloud Behavior
+
+On cloud surfaces (Claude.ai Web, Skills API) the rule is **fully inert** —
+no `.agent-chat-history`, no `scripts/`, no Iron Law gates, no foreign/returning
+prompts. Treat `chat_history.enabled` as `false`; persistence is a
+local-agent concern.
+
+## Interactions & references
+
+- Sibling rules: [`chat-history-cadence`](chat-history-cadence.md) (gate 2 — append timing) · [`chat-history-visibility`](chat-history-visibility.md) (gate 3 — heartbeat marker).
+- `ask-when-uncertain` + `user-interaction` — foreign/returning prompts use numbered options, one question per turn.
+- `language-and-tone` — prompt translated at runtime; `.md` stays English.
+- `onboarding-gate` — runs first; this rule activates only after it clears.
+- API: [`scripts/chat_history.py`](../../../scripts/chat_history.py). Commands: [`/chat-history`](../commands/chat-history.md), [`/chat-history-resume`](../commands/chat-history-resume.md), [`/chat-history-clear`](../commands/chat-history-clear.md), [`/chat-history-checkpoint`](../commands/chat-history-checkpoint.md). Settings: [`agent-settings`](../templates/agent-settings.md). Platform classification: [`agents/contexts/chat-history-platform-hooks.md`](../../../agents/contexts/chat-history-platform-hooks.md). Types: [`rule-type-governance`](rule-type-governance.md).

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

@@ -0,0 +1,96 @@
+---
+type: "always"
+description: "Heartbeat marker visibility for .agent-chat-history — paste subprocess stdout verbatim or nothing, never type from memory, hybrid mode prints only on drift, slip handling per language-and-tone"
+alwaysApply: true
+source: package
+---
+
+<!-- cloud_safe: noop -->
+
+# Chat History — Visibility
+
+Owns gate 3 of the chat-history Iron Law: the heartbeat marker that
+makes append-cadence drift visible. Ownership (gate 1) lives in
+[`chat-history-ownership`](chat-history-ownership.md); cadence (gate 2)
+lives in [`chat-history-cadence`](chat-history-cadence.md). File I/O is
+owned by [`scripts/chat_history.py`](../../../scripts/chat_history.py).
+
+## Iron Law — gate 3 (heartbeat is subprocess stdout, not memory)
+
+```
+HEARTBEAT IS THE SCRIPT OUTPUT OF THE CURRENT TURN, VERBATIM, OR NOTHING.
+NEVER TYPE THE LINE FROM MEMORY. NEVER REUSE THE PRIOR TURN'S MARKER.
+EMPTY STDOUT → NO MARKER LINE.
+```
+
+Run silently before emitting the final reply:
+
+```bash
+scripts/chat_history.py heartbeat --first-user-msg "<first-user-msg>"
+```
+
+Stdout is **at most** one line, e.g.
+`📒 chat-history: ok · 9 entries · per_phase · last 30s ago`. Non-empty →
+paste **verbatim** as the last line of the reply. Empty → emit nothing.
+Always exits 0 — observability, not a gate.
+
+## Visibility modes — `chat_history.heartbeat`
+
+| Mode | When marker prints | Token cost |
+|---|---|---|
+| `on` | every reply (legacy) | ~20 tokens / reply |
+| `off` | never — full silence | 0 |
+| `hybrid` *(default)* | drift states only (`missing`/`foreign`/`returning`) | 0 in normal flow, ~20 on drift |
+
+`hybrid` ships zero tokens when healthy, loud on ownership drift. YAML 1.1
+booleanizes bare `on`/`off`; the reader coerces both back, so
+`heartbeat: on` works unquoted.
+
+## Memory-typing the marker — rule violation, not a slip
+
+Format is memorizable; counts and timestamps are not. A typed-from-
+memory line shows stale entries and a healthy-looking `ok` while the
+file is silently behind — observability collapses, invisible until
+`status` is checked. Heartbeat is the script output of the **current
+turn**, verbatim, or nothing.
+
+**Self-check before send — MANDATORY.** (1) Did `heartbeat` run on
+this turn? (2) Is the line byte-identical to that subprocess stdout?
+(3) Empty stdout → no marker line. Any "no" → drop it.
+
+**Slip handling.** Stale marker called out → acknowledge once in the
+user's language; run `status`; on CHECKPOINT call `append` for
+missed phase-boundaries (see [`chat-history-cadence`](chat-history-cadence.md));
+run a real `heartbeat`; paste stdout verbatim or nothing. Don't promise
+"from now on" — only behaviour proves compliance (mirrors
+`language-and-tone` § slip handling).
+
+## Path-specific behavior
+
+Heartbeat (gate 3) stays useful for visibility on **every** path —
+HOOK, ENGINE, CHECKPOINT — because the marker reports the file's
+state, not the agent's intent. On HOOK and ENGINE paths the agent
+still emits the marker even though it didn't fire `turn-check` or
+`append` itself: the marker is read-only observability over whatever
+the platform / engine wrote.
+
+## What this rule does NOT do
+
+Manage ownership decisions — those live in [`chat-history-ownership`](chat-history-ownership.md).
+Manage append timing — that lives in [`chat-history-cadence`](chat-history-cadence.md).
+Auto-decide visibility mode — `chat_history.heartbeat` is the only
+trigger. Insert decoration: the marker is functional output per
+[`direct-answers`](direct-answers.md) emoji whitelist, not a status
+badge.
+
+## Cloud Behavior
+
+On cloud surfaces (Claude.ai Web, Skills API) heartbeat is **inert** —
+no marker line, no `scripts/`. Treat `chat_history.enabled` as `false`.
+
+## Interactions & references
+
+- Sibling rules: [`chat-history-ownership`](chat-history-ownership.md) (gate 1 — turn-check) · [`chat-history-cadence`](chat-history-cadence.md) (gate 2 — append).
+- `direct-answers` — emoji whitelist permits the `📒` marker as functional output, not decoration.
+- `language-and-tone` § slip handling — stale-marker acknowledgement.
+- API: [`scripts/chat_history.py`](../../../scripts/chat_history.py) `heartbeat` and `status` subcommands. Settings: [`agent-settings`](../templates/agent-settings.md) `chat_history.heartbeat`.

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

@@ -36,7 +36,7 @@ the `rtk-output-filtering` skill.
 
 ### Use what you already have
 
-- Edited a file → `str-replace-editor` showed the result. Skip re-reading.
+- Edited a file → the edit tool already returned the result. Skip re-reading.
 - Ran a command → you have the output. Skip re-running to "verify".
 - File in context from recent messages → skip reloading.
 - Found a symbol → use it. Skip searching again differently.

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

@@ -12,9 +12,10 @@ as a **numbered option** alongside an "as-is" escape hatch. The user
 always picks. **Nothing auto-executes.** The suggestion layer is a
 read-only shortcut *finder*, not an invocation path.
 
-Engine: `scripts/command_suggester/`. Eligibility table:
+The deterministic engine lives in `scripts/command_suggester/`. The
+locked eligibility table lives in
 [`agents/contexts/command-suggestion-eligibility.md`](../../agents/contexts/command-suggestion-eligibility.md).
-Design:
+The full design lives in
 [`road-to-context-aware-command-suggestion`](../../agents/roadmaps/road-to-context-aware-command-suggestion.md).
 
 ## Iron Law — never auto-execute