@event4u/agent-config 1.13.0 → 1.15.0

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 |
 |---|---|
@@ -75,15 +94,23 @@ package repo, in consumer projects the scripts live under
 | `python3 .augment/scripts/update_roadmap_progress.py` | `./agent-config roadmap:progress` |
 | `python3 .augment/scripts/update_roadmap_progress.py --check` | `./agent-config roadmap:progress-check` |
 | `bash scripts/first-run.sh` | `./agent-config first-run` |
+| `PYTHONPATH=… python3 -m implement_ticket` | `./agent-config implement-ticket` |
+| `python3 scripts/memory_lookup.py` | `./agent-config memory:lookup` |
+| `python3 scripts/memory_signal.py` | `./agent-config memory:signal` |
+| `python3 scripts/memory_hash.py` | `./agent-config memory:hash` |
+| `python3 scripts/check_memory.py` | `./agent-config memory:check` |
+| `python3 scripts/check_memory_proposal.py` | `./agent-config memory:check-proposal` |
+| `python3 scripts/check_proposal.py` | `./agent-config proposal:check` |
+| `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/autonomous-execution.md

@@ -0,0 +1,158 @@
+---
+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
+source: package
+---
+
+# 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).
+
+## Hard Floor — see [`non-destructive-by-default`](non-destructive-by-default.md)
+
+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.
+
+## 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`.
+
+## 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`:
+
+- 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.
+
+## 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.
+
+## Blocking — STILL ASK regardless of `personal.autonomy`
+
+Beyond the Hard Floor, 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).
+- **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.
+
+## Commit policy — see [`commit-policy`](commit-policy.md)
+
+Committing is governed by [`commit-policy`](commit-policy.md), 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.
+
+Push, merge, rebase, branch creation, PR ops, tags remain
+permission-gated per [`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
+[`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)
+- [`/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/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`.