@event4u/agent-config 1.14.0 → 1.16.0

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

@@ -1,158 +1,122 @@
 ---
-type: "always"
-description: "Suppress trivial workflow questions and act on the obvious next step; defers to non-destructive-by-default for the safety floor; never commit and never ask about committing except via /commit-in-chunks or explicit user instruction"
-alwaysApply: true
+type: "auto"
+description: "Deciding whether to ask the user or just act on a workflow step — trivial-vs-blocking classification, autonomy opt-in detection, commit default; defers to non-destructive-by-default for the Hard Floor"
+alwaysApply: false
 source: package
+load_context:
+  - .agent-src.uncompressed/contexts/execution/autonomy-detection.md
+  - .agent-src.uncompressed/contexts/execution/autonomy-mechanics.md
+  - .agent-src.uncompressed/contexts/execution/autonomy-examples.md
 ---
 
 # Autonomous Execution
 
 User's time is the scarce resource. Trivial workflow questions are
-noise. Defines **trivial** (just act), **blocking** (still ask), the
-**hard floor** (always ask, no override), and the **commit default**
-(never commit, never ask — review-first by design).
+noise. This rule defines **trivial** (just act), **blocking** (still
+ask), the **hard floor** (always ask, no override), and the **commit
+default** (never commit, never ask — review-first by design).
 
 ## Hard Floor — see [`non-destructive-by-default`](non-destructive-by-default.md)
 
-Universal safety floor (production-branch merges, deploys, pushes,
+The universal safety floor (production-branch merges, deploys, pushes,
 prod data/infra, whimsical bulk deletions, and commits containing
 bulk deletions or infra changes) is governed by the canonical
 [`non-destructive-by-default`](non-destructive-by-default.md) rule.
-
-Applies regardless of `personal.autonomy`, a standing autonomy
-directive (anchor list in [Opt-in detection](#opt-in-detection--match-by-intent-not-exact-string)),
-or any roadmap authorization. Nothing in **this** rule lifts it. If a
-trigger from that rule fires, stop and ask — every section below
-assumes the floor has cleared.
+It applies regardless of `personal.autonomy`, a standing autonomy
+directive, or any roadmap authorization. Nothing in **this** rule
+lifts it. If a trigger fires, stop and ask — every other section
+below assumes the floor has already been cleared.
 
 ## Setting — `personal.autonomy`
 
-| Value | Behavior |
-|---|---|
-| `on` | Suppress trivial questions. Act on obvious next step. Still ask on blocking decisions; ALWAYS ask on Hard-Floor triggers. |
-| `off` | Ask trivial questions too. Use to check in on each workflow step. |
-| `auto` (default) | Like `off` until user expresses "stop asking, just work" — then `on` for the rest of the chat. See **Opt-in detection** below; match by **intent**, not exact string. The flip never lifts the Hard Floor. |
-
-Read once on first turn (per [`layered-settings`](../guidelines/agent-infra/layered-settings.md#section-aware-merge-rules))
-and cache. Missing key → treat as `on`.
+Three values: `on` (suppress trivial questions), `off` (ask trivial
+questions too), `auto` (default — same as `off` until the user opts
+in via a standing autonomy directive). Read once on the first turn
+(per [`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules))
+and cache. Missing key → treat as `on`. Full table, semantics, and
+cloud behavior:
+[`contexts/execution/autonomy-mechanics.md`](../contexts/execution/autonomy-mechanics.md).
 
 ## Opt-in detection — match by intent, not exact string
 
-In `auto`, flip to `on` for the rest of the chat when the user expresses
-**"stop asking on trivial steps, just work"**. Recognize the **intent**,
-not the literal substring — semantic equivalent in either language.
-
-Anchor examples (illustrative, not exhaustive):
-
-- DE: "arbeite selbstständig" · "frag nicht jedes Mal" · "tue es einfach"
-- EN: "work autonomously" · "don't ask" · "just do it"
-
-Litmus test: standing permission to skip trivial questions? → flip.
-Single-decision delegation ("you decide for this step") → handle that
-step, do **not** flip standing mode.
-
-### Speech-act check — meta-instruction, not content
-
-Before flipping, verify the phrase is **addressed to the agent as
-guidance about how to work**, not a literal substring inside another
-instruction. Do **not** flip when the phrase is:
-
-- **Content / copy** — "Put the slogan 'just do it' on the landing page."
-- **Quote / reference** — "Nike's tagline is 'just do it' — write a blog post."
-- **Subject of a request** — "Write docs about the 'work autonomously' modes."
-- **Code / data** — string literals, fixtures, translations, JSON.
-- **About a third party** — "My colleague works autonomously."
-- **Question / hypothetical** — "Should I set `don't ask` as the default?"
-
-Heuristic: strip quotes, code blocks, embedded content. Read what's
-**left**. Still a directive to the agent about its working style →
-flip. Otherwise → don't.
-
-Opt-out (reversed intent) flips back to `off`:
+In `auto` mode, flip to `on` for the rest of the conversation when
+the user expresses **"stop asking on trivial steps, just work"**.
+Recognize **intent**, not the literal substring. Opt-out (same intent,
+reversed) flips back to `off`. Both directions are
+**speech-act-checked**: the phrase must be a meta-instruction to the
+agent, not content / quote / subject / code / third-party reference /
+hypothetical. In doubt → keep current mode, no speculative flips.
 
-- DE: "frag mich wieder" · "frag mich erst" · "stop autonomous mode"
-- EN: "ask me first" · "ask me again" · "stop being autonomous"
-
-Same speech-act check applies.
-
-Counter-examples — do **not** flip on meta-questions, self-descriptions,
-or one-shot delegations: "why don't you ask that yourself?", "I'm
-working autonomously right now", "can you decide that yourself?".
-
-In doubt → keep current mode, no speculative flips.
+Algorithm and speech-act heuristic:
+[`contexts/execution/autonomy-detection.md`](../contexts/execution/autonomy-detection.md).
+Anchor phrases (DE+EN), no-flip patterns, counter-examples:
+[`contexts/execution/autonomy-examples.md`](../contexts/execution/autonomy-examples.md).
 
 ## Trivial — JUST ACT, do not ask
 
-Examples (matches `personal.autonomy: on` or `auto`-after-opt-in):
-
-- "Step 2 or Step 3?" — pick the obvious next roadmap step; if blocked, name the blocker, otherwise go.
-- "Commit now or after the next change?" — answered by the commit-default below.
-- "How should I split the commits?" — never asked; either `/commit-in-chunks` was invoked (split + commit) or it wasn't (don't commit).
-- "Run linter / tests now or later?" — `verify-before-complete` decides; act.
-- "Found 3 follow-ups — fix all or stop?" — if within scope and minimal-safe-diff allows, fix; if scope expands, stop and surface as list.
-- "Filename `X.md` or `Y.md`?" when one matches convention — pick convention-matching one.
-- "Verification table or paragraph?" — pick whichever fits; format isn't a decision worth a turn.
-- "Show me a diff before regenerating output from a tracked source?"
-  — compression, code-gen, formatter passes, lock-file rebuilds — run
-  it and report the result. Reversibility comes from the source, not
-  from per-file confirmation. See [`non-destructive-by-default`](non-destructive-by-default.md#not-in-scope--deterministic-regeneration)
-  § Not in scope.
-
-`personal.autonomy: off`: ask these. `on` or `auto`-after-opt-in: act.
+In `personal.autonomy: on` or `auto`-after-opt-in, do not ask
+trivial workflow questions — pick the obvious next step and proceed.
+In `personal.autonomy: off`, ask them. Worked cases:
+[`contexts/execution/autonomy-examples.md`](../contexts/execution/autonomy-examples.md).
 
 ## Blocking — STILL ASK regardless of `personal.autonomy`
 
-Beyond the Hard Floor, the autonomy setting also never overrides:
+Beyond the Hard Floor above, the autonomy setting also never
+overrides:
 
-- **Vague-request triggers** in [`ask-when-uncertain`](ask-when-uncertain.md) — ambiguous stays ambiguous; pick-one-and-pray is wrong.
-- **Architectural / structural choices** the codebase hasn't settled (multi-stack picks, library introductions).
+- **Vague-request triggers** in [`ask-when-uncertain`](ask-when-uncertain.md)
+  — ambiguous requirements stay ambiguous; pick-one-and-pray is wrong.
+- **Architectural / structural choices** that the codebase doesn't
+  already settle (multi-stack picks, library introductions).
 - **Security-sensitive paths** — see [`security-sensitive-stop`](security-sensitive-stop.md).
-- **Scope expansion** beyond stated task — see [`scope-control`](scope-control.md).
-- **Remote-state ops** — push, merge, rebase, force-push, branch create/delete/switch, PR create/close/retarget, tag/release. Permission-gated by [`scope-control`](scope-control.md); the prod-trunk and deploy-tied subset is governed by [`non-destructive-by-default`](non-destructive-by-default.md).
-- **Destructive ops** — see [`non-destructive-by-default`](non-destructive-by-default.md) for the full taxonomy (whimsical bulk deletions, content destruction, commits containing bulk deletions or infra changes).
-
-In doubt → blocking. Ask.
+- **Scope expansion** beyond the stated task — see [`scope-control`](scope-control.md).
+- **Remote-state operations** — push, merge, rebase, force-push,
+  branch create/delete/switch, PR create/close/retarget, tag/release.
+  Permission-gated by [`scope-control`](scope-control.md); the
+  prod-trunk and deploy-tied subset is governed by
+  [`non-destructive-by-default`](non-destructive-by-default.md).
+- **Destructive ops** — see [`non-destructive-by-default`](non-destructive-by-default.md)
+  for the full taxonomy (whimsical bulk deletions, content
+  destruction, commits containing bulk deletions or infra changes).
+
+When in doubt whether something is trivial or blocking → it is
+blocking. Ask.
 
 ## Commit policy — see [`commit-policy`](commit-policy.md)
 
-Committing is governed by [`commit-policy`](commit-policy.md), which
-applies regardless of `personal.autonomy`. Summary:
+Committing is governed by the canonical [`commit-policy`](commit-policy.md)
+rule, which applies regardless of `personal.autonomy`. Summary:
 
 - NEVER commit unless user said so this turn, a commit command was
   invoked, a standing instruction is active, or the roadmap authorizes it.
-- NEVER ask about committing.
-- In autonomous mode, the **only** permitted commit-related question
-  is the one-shot pre-scan ask at the start of roadmap execution.
+- NEVER ask about committing. The user invokes a command or says so.
+- In autonomous mode, the **only** permitted commit-related question is
+  the one-shot pre-scan ask at the start of roadmap execution.
 
-Push, merge, rebase, branch creation, PR ops, tags remain
-permission-gated per [`scope-control`](scope-control.md#git-operations--permission-gated).
+Push, merge, rebase, branch creation, PR operations, and tags remain
+permission-gated by [`scope-control`](scope-control.md#git-operations--permission-gated).
 
 ## Failure modes
 
-- Asking "Step 2 or Step 3?" when the roadmap orders them.
-- "Should I run the CI checks?" — `verify-before-complete` decides; act.
-- "Do we want to commit this?" — no, by default. Don't ask.
-- Numbered-options block whose only difference is sequencing ("A then B" vs "B then A") with no real trade-off.
-- Asking after user already issued a standing autonomy directive earlier (cache the opt-in for `auto`).
-
-For Hard-Floor failure modes (treating autonomy as cover for a
-floor-crossing action, reading a roadmap step as deploy authorization,
-refusing task-aligned WIP deletions, committing bulk-deletion / infra
-diffs without surfacing them) see
+Autonomy-side wrong-behavior patterns (sequencing-only asks, CI-run
+asks, commit asks, no-trade-off option blocks, re-asking after a
+standing opt-in):
+[`contexts/execution/autonomy-examples.md`](../contexts/execution/autonomy-examples.md).
+For Hard-Floor failure modes see
 [`non-destructive-by-default`](non-destructive-by-default.md#failure-modes).
 
-## Cloud Behavior
-
-Settings reads degrade gracefully on cloud platforms (no
-`.agent-settings.yml`). Treat as `personal.autonomy: on` — user had to
-deliberately ship a custom skill bundle and is unlikely to want
-trivial-question friction.
-
 ## See also
 
-- [`non-destructive-by-default`](non-destructive-by-default.md) — universal safety floor; never overridden by autonomy
-- [`scope-control`](scope-control.md) — git-ops permission gate (push/merge/branch/PR/tag stays explicit)
-- [`ask-when-uncertain`](ask-when-uncertain.md) — vague-request triggers that always require asking
-- [`direct-answers`](direct-answers.md) — Iron Laws on brevity and no-flattery (this rule extends to no-trivial-questions)
+- [`non-destructive-by-default`](non-destructive-by-default.md) —
+  universal safety floor; never overridden by autonomy
+- [`scope-control`](scope-control.md) — git-ops permission gate
+  (push/merge/branch/PR/tag stays explicit)
+- [`ask-when-uncertain`](ask-when-uncertain.md) — vague-request
+  triggers that always require asking
+- [`no-cheap-questions`](no-cheap-questions.md) — mode-independent
+  floor against context-derived, sequencing-only, and
+  Iron-Law-violating asks (applies in `off` and pre-opt-in `auto` too)
+- [`direct-answers`](direct-answers.md) — Iron Laws on brevity and
+  no-flattery (this rule extends to no-trivial-questions)
 - [`/commit-in-chunks`](../commands/commit-in-chunks.md) — auto-split and commit without confirmation
 - [`/commit`](../commands/commit.md) — split and commit with confirmation

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

@@ -82,7 +82,7 @@ Body: 1-paragraph **pattern** (not anecdote) + 1 concrete example.
 A learning file is the input to `learning-to-rule-or-skill`, which
 produces a proposal draft under `agents/proposals/`. The proposal is
 then gated by `scripts/check_proposal.py`; see
-[`self-improvement-pipeline`](../guidelines/agent-infra/self-improvement-pipeline.md).
+[`self-improvement-pipeline`](../../docs/guidelines/agent-infra/self-improvement-pipeline.md).
 
 The `agents/learnings/` and `agents/proposals/` directories are
 consumer-owned — the package ships templates and schemas, never the

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

@@ -0,0 +1,109 @@
+---
+type: "auto"
+description: "Appending to .agent-chat-history — cadence boundaries (per_turn/per_phase/per_tool), turn-check ownership refusal handling, never writing the file directly; cadence is the trigger, not reply length"
+alwaysApply: false
+source: package
+---
+
+<!-- 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: "auto"
+description: "First turn or reference to .agent-chat-history — detects ownership (match/returning/foreign/missing) and HOOK/ENGINE/CHECKPOINT/MANUAL path classification with numbered-options prompt"
+alwaysApply: false
+source: package
+---
+
+<!-- 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: "auto"
+description: "Emitting the chat-history heartbeat marker — paste subprocess stdout verbatim or nothing, never type from memory, hybrid mode prints on drift only, slip handling per language-and-tone"
+alwaysApply: false
+source: package
+---
+
+<!-- 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 → command-suggestion-policy.md}

@@ -1,7 +1,7 @@
 ---
-type: "always"
-description: "Surface matching slash commands as numbered options when user intent matches a command's purpose — never auto-executes; user always picks (read-only suggestion layer)."
-alwaysApply: true
+type: "auto"
+description: "User prompt without /command but matching an eligible slash command — surface matches as numbered options with as-is escape hatch; never auto-executes, user always picks"
+alwaysApply: false
 source: package
 ---
 
@@ -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
@@ -24,7 +25,7 @@ SUGGEST. NEVER INVOKE. THE USER PICKS, ALWAYS.
 ```
 
 A suggestion block emits options. It does **not** start a command
-flow. The user picking option N triggers `slash-commands` on the
+flow. The user picking option N triggers `slash-command-routing-policy` on the
 **next** turn — with all the command's own halts intact.
 
 ## When to fire
@@ -32,7 +33,7 @@ flow. The user picking option N triggers `slash-commands` on the
 On a user turn that matches **all** of the following:
 
 1. The message does **not** start with an explicit `/command` (those
-   bypass suggestion entirely — see `slash-commands`).
+   bypass suggestion entirely — see `slash-command-routing-policy`).
 2. `commands.suggestion.enabled` is `true` (default).
 3. The user has not issued `/command-suggestion-off` in this conversation.
 4. No clarification is owed for the same turn (per
@@ -109,7 +110,7 @@ prompt runs exactly as it would without this rule.
 
 ## What this rule does NOT do
 
-- Invoke any command. Picking option N is what triggers `slash-commands`.
+- Invoke any command. Picking option N is what triggers `slash-command-routing-policy`.
 - Stack with other questions. One numbered-options block per turn.
 - Re-trigger on its own output. Command names emitted in the
   suggestion block are excluded from the next-turn matcher input.
@@ -125,7 +126,7 @@ available — degrade silently, never crash the turn.
 
 ## Interactions
 
-- [`slash-commands`](slash-commands.md) — explicit `/command` skips suggestion entirely.
+- [`slash-command-routing-policy`](slash-command-routing-policy.md) — explicit `/command` skips suggestion entirely.
 - [`user-interaction`](user-interaction.md) — numbered-options Iron Law and single-source recommendation.
 - [`ask-when-uncertain`](ask-when-uncertain.md) — clarification wins on conflict.
 - [`scope-control`](scope-control.md) — git-op gates outrank suggestion.