@event4u/agent-config 1.12.0 → 1.14.0

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

@@ -5,6 +5,8 @@ alwaysApply: true
 source: package
 ---
 
+<!-- cloud_safe: noop -->
+
 # Chat History
 
 Persists the conversation to `.agent-chat-history` (JSONL, project root,
@@ -12,160 +14,187 @@ git-ignored) so a crashed or switched agent session can be resumed. File
 I/O is owned by [`scripts/chat_history.py`](../../../scripts/chat_history.py)
 — this rule says **when** to call it, not how the file is structured.
 
-## Activation
+## Two paths — platform decides which Iron Law applies
 
-Read `chat_history.*` from `.agent-settings.yml` **once per conversation**
-(first turn). Cache the values.
+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).
 
-- `chat_history.enabled: false` **or** section missing → rule is a **no-op**
-  for the whole conversation. Do not read, write, or mention the file.
-- `chat_history.enabled: true` → cache `frequency`, `max_size_kb`,
-  `on_overflow` and proceed to the first-turn handshake.
+| 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 — the three gates below are mandatory |
+| **MANUAL** | Cloud surfaces (Claude.ai Web, Skills API) | Rule is inert — see Cloud Behavior | None |
 
-## First-turn handshake — four states
+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`).
 
-Before executing the user's request, run:
+## Iron Law (CHECKPOINT path) — three gates, skipping any one is a rule violation
 
-```bash
-scripts/chat_history.py state --first-user-msg "<msg>"
+```
+1. turn-check    — first tool call of every session
+2. append        — at every cadence boundary, with --first-user-msg
+3. heartbeat     — last line of every reply, from current subprocess
+                   stdout (NEVER from memory)
 ```
 
-It prints exactly one of `match` | `returning` | `foreign` | `missing`.
-Branch:
+**Overrides** token-efficiency, conversation momentum, "the turn was
+trivial". Three enforcement layers: **turn-check** non-zero on
+`missing`/`foreign`/`returning`, **append refusal** (exit `3` on
+ownership mismatch), **script-generated heartbeat** (silent skip
+becomes immediately visible).
 
-- `missing` → `init --first-user-msg "<msg>" --freq <frequency>`. Proceed
-  silently.
-- `match` → this chat already owns the file. Continue appending as cached.
-- `foreign` → a different session's file. Show **Foreign-Prompt** below.
-- `returning` → this chat once owned the file but another session took
-  over. Show **Returning-Prompt** below.
+On the HOOK and ENGINE paths the platform / engine performs gates 1 + 2
+structurally; the agent **must not** also call `turn-check` or `append`
+(double-write risk). Engine-driven turns inherit the structural guarantee
+for the duration of the dispatch cycle — once the engine returns control,
+free-form prose around the engine output falls back to whatever path the
+platform supplies. Heartbeat (gate 3) stays useful for visibility on
+every path — see below.
 
-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.
+### Turn-start gate — MANDATORY first tool call
 
-## Foreign-Prompt — new chat finds existing history
-
-Trigger: `state == foreign` **and** `status.entries >= 1`.
-
-```
-> 📒 Found chat history from an unknown session.
->
-> Header fingerprint: <short-hash-A>
-> Current session:    <short-hash-B>
-> Entries on file:    <N>   Age: <age>
->
-> 1. Resume — adopt this file, load entries as context, keep appending here
-> 2. New start — archive to .agent-chat-history.bak, init fresh
-> 3. Ignore — leave the file untouched, disable logging for this session
+```bash
+scripts/chat_history.py turn-check --first-user-msg "<first-user-msg>"
 ```
 
-- `1` → `adopt --first-user-msg "<msg>"` (the old fp lands in
-  `former_fps` automatically). Read entries into context, then append
-  normally.
-- `2` → rename to `.agent-chat-history.bak`, then
-  `init --first-user-msg "<msg>" --freq <frequency>`.
-- `3` → logging disabled for this conversation; do not touch the file,
-  do not edit settings.
+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 also writes a one-line
+`ACTION REQUIRED:` hint to stderr on non-zero exits.
 
-Free-text replies ("weiter", "skip it") count as `3`.
+### Append cadence — MANDATORY at boundaries
 
-## Returning-Prompt — old chat comes back
+Cadence comes from `chat_history.frequency`:
 
-Trigger: `state == returning`. The file exists, its current owner is a
-different session, but this chat's fingerprint is in `former_fps`. The
-agent still has its own in-memory history of the turns it logged before
-the hand-off.
+- `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.
 
-```
-> 📒 Welcome back. This chat once owned the history file; another
-> session has written to it since.
->
-> On-file entries:    <N>   Size: <X> KB   (now includes <M> foreign entries)
->
-> (All three options read the on-disk entries into context first.)
->
-> 1. Merge — my in-memory history first, the foreign entries after,
->    overwrite the file with the combined body
-> 2. Replace — wipe the foreign entries, rewrite the file with my
->    in-memory history only
-> 3. Continue — leave the file as-is; only new entries from now on
+Every append goes through
+
+```bash
+scripts/chat_history.py append --first-user-msg "<msg>" \
+  --type <user|agent|tool|decision|phase> --json '<obj>'
 ```
 
-- `1` (Merge) → build the in-memory entries list (see below), call
-  `prepend --entries-json '<list>'`, then `adopt --first-user-msg "<msg>"`.
-- `2` (Replace) → build the in-memory list,
-  `reset --first-user-msg "<msg>" --freq <frequency> --entries-json '<list>'`.
-- `3` (Continue) → `adopt --first-user-msg "<msg>"`, then append normally.
+Never write the file directly. Prefer `phase` over `agent` for boundaries.
+Exit `3` (`OWNERSHIP_REFUSED`) means turn-start was skipped or the file
+was hijacked — surface it, do not swallow it. Cadence is the trigger, not
+reply length; do not batch missed turns (crashes happen between turns).
 
-Free-text replies count as `3`.
+### Heartbeat marker — visibility gated by `chat_history.heartbeat`
 
-## Building the in-memory entries list (Merge / Replace)
+Run silently before emitting the final reply:
 
-The agent reconstructs its own conversation as a JSON array, one entry
-per turn boundary. Keep it compact:
+```bash
+scripts/chat_history.py heartbeat --first-user-msg "<first-user-msg>"
+```
 
-- One `{"t":"user","text":"<preview>","ts":"<iso>"}` per user message.
-- One `{"t":"agent","text":"<preview>","ts":"<iso>"}` per agent reply.
-- `text` is a preview — flatten whitespace, cap at ~200 characters. This
-  is context, not a transcript.
-- Timestamps in ISO-8601 UTC. If the agent does not have exact times,
-  use the current time for all entries; order is what matters.
-- Do **not** include tool-call payloads, file contents, or secrets.
+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.
 
-If the list is large (>30 KB), pass it via stdin:
-`reset ... --entries-stdin <<< '<list>'`.
+**Visibility modes** — `chat_history.heartbeat`:
 
-## Append cadence — from `frequency`
+| 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 |
 
-Every append goes through `scripts/chat_history.py append --type <t>
---json '<obj>'`. Never write the file directly.
+`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.
 
-- `per_turn` — one entry at the end of every agent turn.
-- `per_phase` — at phase boundaries (user question, agent answer,
-  decision, completion of a task-list item).
-- `per_tool` — after each tool-call sequence.
+### Memory-typing the marker — rule violation, not a slip
 
-Entry types: `user`, `agent`, `tool`, `decision`, `phase`. Prefer `phase`
-over `agent` when the entry marks a boundary.
+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.
 
-## Overflow — from `on_overflow`
+**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.
 
-When the helper reports file size > `max_size_kb`:
+**Slip handling.** Stale marker called out → acknowledge once in the
+user's language; run `status`; on CHECKPOINT `append` missed phase-
+boundaries; 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).
 
-- `rotate` → `rotate --mode rotate --max-kb <n>`. Drops oldest entries;
-  silent and cheap.
-- `compress` → `rotate --mode compress --max-kb <n>`. Marks the file for
-  summarization; the **next** turn writes the summary for the dropped
-  range. Do not block the current turn on this.
+## Activation & handshake
 
-After Merge or Replace rewrites, run the overflow check once — the new
-body may exceed the budget.
+Read `chat_history.*` from `.agent-settings.yml` **once per conversation**
+(first turn) and cache. `enabled: false` or section missing → rule is 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. Cooperative
+gates 1 + 2 + 3 are mandatory; `/chat-history-checkpoint` is the
+recommended way to satisfy gate 2 at phase boundaries.
 
-The setting is stable for the session; never mix modes.
+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, or clear the log — that is `/chat-history`,
-  `/chat-history-resume`, `/chat-history-clear`.
-- Auto-flip `enabled` or `on_overflow` in settings.
-- Run when `enabled: false`. No silent logging. No telemetry.
-- Decide ownership heuristically. Only the `state` helper does that.
+Display/reload/clear (`/chat-history*` commands). Auto-flip `enabled` or
+`on_overflow`. Run when `enabled: false` (no silent logging, no
+telemetry). Decide ownership heuristically — only `state` does that.
+Double-write on HOOK platforms — when hooks fire structurally, the
+agent does **not** also call `append`.
 
-## Interactions
+## Cloud Behavior
 
-- `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.
-- `token-efficiency` — never load the full log into context from this
-  rule; use `status` for metadata, `read --last N` for a tail.
+On cloud surfaces (Claude.ai Web, Skills API) the rule is **fully inert** —
+no `.agent-chat-history`, no `scripts/`, no Iron Law gates, no heartbeat,
+no foreign/returning prompts, no overflow warning. Treat
+`chat_history.enabled` as `false`; persistence is a local-agent concern.
 
-## See also
+## Interactions & references
 
-- [`scripts/chat_history.py`](../../../scripts/chat_history.py) — file API
-- [`/chat-history`](../commands/chat-history.md) — status inspection
-- [`/chat-history-resume`](../commands/chat-history-resume.md) — adopt + load
-- [`/chat-history-clear`](../commands/chat-history-clear.md) — wipe
-- [`agent-settings` template](../templates/agent-settings.md) — `chat_history.*` reference
-- [`rule-type-governance`](rule-type-governance.md) — why this is `always`
+- `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.
+- `token-efficiency` — never load the full log; use `status` / `read --last N`.
+- 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/cli-output-handling.md

@@ -1,7 +1,7 @@
 ---
 type: "auto"
 alwaysApply: false
-description: "Running CLI commands that produce verbose output — git, tests, linters, docker, build tools, artisan, npm, composer"
+description: "Running CLI commands that produce verbose output — git, tests, linters, docker, build tools, artisan, npm, composer. Wrap with rtk when installed; tail/grep is fallback."
 source: package
 ---
 
@@ -10,6 +10,28 @@ source: package
 Loaded when actively working with code, tests, quality tools, CLI, or analysis.
 For communication and response style rules → see the always-loaded `token-efficiency` rule.
 
+## Iron Law — rtk first, tail/grep fallback
+
+```
+IF `rtk` IS INSTALLED, WRAP VERBOSE COMMANDS WITH rtk.
+USE tail / grep / cat ONLY AS FALLBACK WHEN rtk HAS NO MATCHING SUBCOMMAND.
+NEVER PIPE A STILL-RUNNING LONG COMMAND THROUGH tail — IT BUFFERS TO EOF.
+```
+
+Detection: `rtk_installed: true` in `.agent-settings.yml`, or `which rtk`
+exits 0. Caching the result for the session is fine.
+
+| Verbose command | Use | Fallback (no rtk) |
+|---|---|---|
+| CI-style suites, full test runs | `rtk err <cmd>` — only errors/warnings | redirect → tail → grep |
+| Unit tests | `rtk test <cmd>` — only failures | redirect → tail → grep |
+| `git status`/`log`/`diff` | `rtk git <subcmd>` | plain |
+| `gh pr list`, `gh run view` | `rtk gh <subcmd>` | plain |
+| Generic noisy command | `rtk summary <cmd>` or `rtk err <cmd>` | redirect → tail |
+
+For the full rtk subcommand catalog and project-local filter setup → see
+the `rtk-output-filtering` skill.
+
 ## Codebase Navigation
 
 ### Use what you already have
@@ -38,9 +60,10 @@ For communication and response style rules → see the always-loaded `token-effi
 - **`view_range`** when you know the exact lines.
 - **One `codebase-retrieval` call** with all symbols — batch, not 5 separate calls.
 
-## Pattern: Redirect, Summarize, Target
+## Fallback Pattern: Redirect, Summarize, Target
 
-Every command that MAY produce more than ~30 lines of output:
+When `rtk` has no matching subcommand for the tool at hand, fall back to
+this pattern. Every command that MAY produce more than ~30 lines of output:
 
 ### Step 1: Redirect to file
 ```bash

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

@@ -0,0 +1,133 @@
+---
+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
+source: package
+---
+
+# Command Suggestion
+
+When the user's prompt matches an eligible slash command, surface it
+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:
+[`agents/contexts/command-suggestion-eligibility.md`](../../agents/contexts/command-suggestion-eligibility.md).
+Design:
+[`road-to-context-aware-command-suggestion`](../../agents/roadmaps/road-to-context-aware-command-suggestion.md).
+
+## Iron Law — never auto-execute
+
+```
+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
+**next** turn — with all the command's own halts intact.
+
+## When to fire
+
+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`).
+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
+   `ask-when-uncertain` — clarification wins; suggestion can fire next turn).
+5. No active engine flow is mid-halt (e.g. an `/implement-ticket`
+   step waiting on the user — the active flow has the floor).
+6. The matcher returns at least one match above the effective
+   `confidence_floor` after rank + cooldown + anti-noise.
+
+When all six hold, the suggestion block is the **first and only**
+thing the agent emits that turn. No tools, no edits, no other prose.
+
+## What to emit
+
+Render exactly one numbered-options block conforming to
+`user-interaction`:
+
+```
+> 💡 Your request matches a command. Pick one or run the prompt as-is:
+>
+> 1. /implement-ticket — drive ticket end-to-end through refine → plan → implement → test
+> 2. /refine-ticket — tighten the AC and risks on a ticket before planning
+> 3. Just run the prompt as-is, no command
+
+**Recommendation: 1 — /implement-ticket** — the request matches its trigger description (`setze ticket abc-123 um`). Pick the last option to skip the command and run the prompt as written.
+```
+
+Rules — non-negotiable:
+
+- The "run as-is" option is **always present**, **always last**, never removed.
+- At most `commands.suggestion.max_options` command suggestions
+  precede the as-is option (default 4 → 5 total).
+- Exactly **one** `Recommendation:` line follows the block, naming
+  the highest-scoring command — or no recommendation when the top
+  two scores are within 0.05 of each other (single-source-of-truth
+  Iron Law from `user-interaction`).
+- Free-text replies count as the as-is option unless they
+  unambiguously name one of the listed commands.
+
+## Subordination — when to stay silent
+
+The suggestion rule is **junior** to:
+
+- `scope-control` — never surfaces a git-op command behind a
+  permission gate the user already declined this turn.
+- `ask-when-uncertain` — if a clarification is owed, the
+  clarification is the only question; suggestion suppresses for
+  that turn.
+- `verify-before-complete` — suggestion does not interrupt an
+  evidence-gate verification that's already running.
+- Any active role-mode contract (`role-mode-adherence`).
+- Any active engine halt (`/implement-ticket`, `/work`, etc.).
+
+On any conflict → suggestion stays silent. Zero output. The user's
+prompt is processed as it would be without this rule.
+
+## Anti-noise — silent when uncertain
+
+The engine's `rank.py` already drops:
+
+- Matches below the `confidence_floor` (default 0.6, per-command
+  override in frontmatter).
+- Single matches scoring `< floor + 0.1` with no structural bonus
+  (high uncertainty isn't worth interrupting for).
+- Short prompts (< 6 words) hitting > 2 commands with no structural
+  bonus (ticket key, file path) — too vague to disambiguate.
+- Pure-continuation messages (`ok`, `weiter`, `mach weiter`, `go on`,
+  …) — no new intent signal, no structural bonus → silent.
+- Suggestions that fired for the same `(command, evidence)` pair
+  within the cooldown window (default 10m, per-command override).
+
+If the engine returns an empty list → emit nothing. The user's
+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`.
+- 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.
+- Override `enabled: false`, blocklist entries, or per-conversation opt-out.
+- Suggest commands that are not in the locked eligibility table.
+
+## Cloud Behavior
+
+On cloud surfaces (Claude.ai Web, Skills API) the rule is **inert**
+unless the suggester package is shipped in the bundle. Treat
+`commands.suggestion.enabled` as `false` when the engine is not
+available — degrade silently, never crash the turn.
+
+## Interactions
+
+- [`slash-commands`](slash-commands.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.
+- [`role-mode-adherence`](role-mode-adherence.md) — active mode contract outranks suggestion.
+- [`agents/contexts/command-suggestion-eligibility.md`](../../agents/contexts/command-suggestion-eligibility.md) — locked eligibility table.

package/.agent-src/rules/commit-policy.md

@@ -0,0 +1,99 @@
+---
+type: "always"
+description: "Commit policy — never commit and never ask about committing unless the user said so this turn, the roadmap authorizes it, or a commit command is invoked"
+alwaysApply: true
+source: package
+---
+
+# Commit Policy
+
+Local commits don't change remote state, but committing prematurely
+makes review harder. **Canonical** rule, referenced by
+[`autonomous-execution`](autonomous-execution.md),
+[`scope-control`](scope-control.md), and roadmap commands.
+
+## The Iron Law
+
+```
+NEVER COMMIT. NEVER ASK ABOUT COMMITTING.
+EXCEPTIONS ARE EXPLICIT, NOT INFERRED.
+```
+
+Applies regardless of `personal.autonomy`, conversation momentum, or
+"clean stopping point". Default is **no commit, no question**.
+
+## Exceptions — when committing IS allowed
+
+Four ways only:
+
+1. **User says so this turn** — explicit phrase like "commit this now",
+   "go ahead and commit". This commit only, not standing.
+2. **Standing instruction not yet revoked** — earlier "commit after
+   every phase" or similar, not yet revoked. Cache and honor.
+3. **Commit command invoked** — `/commit` (with confirmation) or
+   `/commit-in-chunks` (auto-split, no confirmation).
+4. **Roadmap authorization** — roadmap lists explicit commit steps
+   and user invoked execution. See [Roadmap-authorized commits](#roadmap-authorized-commits).
+
+Anything else → no commit.
+
+## Hard Floor still applies — bulk deletions and infra changes
+
+Even when one of the four exceptions above authorizes a commit, the
+[`non-destructive-by-default`](non-destructive-by-default.md) Hard
+Floor still fires when the diff:
+
+- Removes a directory
+- Deletes ≥5 unrelated files
+- Touches Terraform / Pulumi / k8s manifests / Ansible / cloud-config
+
+In those cases, **surface the diff** (paths + counts) and confirm
+this turn before committing — even under `/commit-in-chunks`,
+roadmap pre-scan authorization, or an explicit "commit this now". The
+four exceptions cover *whether* commits happen; the Hard Floor covers
+*which diffs* still need a separate confirmation.
+
+## NEVER ask about committing
+
+Asking "should I commit this?", "do we want to commit?", or any
+variant is **forbidden**. User invokes a command or says so
+explicitly. Don't surface a commit option in numbered-options unless
+the rest of the message would be incomplete without it.
+
+Speech-act check from [`autonomous-execution`](autonomous-execution.md#speech-act-check--the-phrase-must-be-a-meta-instruction-to-the-agent)
+applies in reverse: an explicit commit phrase inside a quote, code
+block, or content (e.g. a copy-paste of a chat log) is **not** a
+permission grant.
+
+## NEVER write commit steps into roadmaps unsolicited
+
+When **creating** a roadmap (`/roadmap-create`, `/feature-roadmap`,
+or any roadmap-producing flow), do **not** include commit steps
+unless the user explicitly requested them. Commits are a delivery
+decision; roadmaps plan **work**.
+
+If the user explicitly wants commit steps, write them clearly
+(e.g. "Commit phase X: chore: …").
+
+## Roadmap-authorized commits
+
+When **executing** a roadmap that contains commit steps:
+
+- **Non-autonomous** (`autonomy: off`, or `auto` before opt-in) —
+  agent may ask before each commit step. User retains step-level
+  control.
+- **Autonomous** (`autonomy: on`, or `auto` after opt-in) — agent
+  pre-scans the roadmap **before starting execution**. Commit steps
+  found → ask **once** upfront: "Roadmap contains N commit steps —
+  should they be executed?". Cache the answer; honor or skip for
+  the rest of the run. No re-asking per step.
+
+The pre-scan ask is the **only** permitted commit-related question
+in autonomous mode.
+
+## See also
+
+- [`autonomous-execution`](autonomous-execution.md) — trivial-question suppression survives this rule.
+- [`scope-control`](scope-control.md) — push/merge/branch/PR/tag stay permission-gated.
+- [`/commit`](../commands/commit.md) — split + commit with confirmation.
+- [`/commit-in-chunks`](../commands/commit-in-chunks.md) — auto-split + commit without confirmation.