@event4u/agent-config 1.13.0 → 1.15.0

package/.agent-src/commands/agent-handoff.md

@@ -3,6 +3,9 @@ name: agent-handoff
 skills: [agent-docs-writing]
 description: Generate a context summary for continuing work in a fresh chat. Replaces the session system.
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Explicit fresh-chat handoff — must be deliberate, never inferred from prose."
 ---
 
 # /agent-handoff
@@ -70,7 +73,7 @@ Show the handoff prompt in a fenced code block and say:
   and without any persistent file.
 - [`/chat-history-resume`](chat-history-resume.md) is **pull-based**: the
   new chat reads `.agent-chat-history` from disk (written by the
-  [`chat-history`](../rules/chat-history.md) rule). Works only on the
+  [`chat-history`](../rules/chat-history-ownership.md) rule). Works only on the
   same machine and same repo, but captures more detail (every phase /
   tool call / decision the prior session logged).
 

package/.agent-src/commands/agent-status.md

@@ -3,6 +3,9 @@ name: agent-status
 skills: [agent-docs-writing]
 description: Show current conversation stats — message count, token costs, task progress, next freshness check.
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Pure status display; no natural-language trigger distinct from idle small-talk."
 ---
 
 # /agent-status

package/.agent-src/commands/agents-audit.md

@@ -3,6 +3,10 @@ name: agents-audit
 description: Audits agents/ and module agents/ directories — finds outdated docs, structural issues, duplicates, orphaned overrides, and creates an improvement roadmap.
 skills: [agents-audit, agent-docs-writing, override-management, module-management]
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "audit my agent docs, check the state of the agents/ directory"
+  trigger_context: "stale files under agents/ or recent edits to .augment/ without doc updates"
 ---
 
 # /agents-audit

package/.agent-src/commands/agents-cleanup.md

@@ -3,6 +3,9 @@ name: agents-cleanup
 skills: [agent-docs-writing]
 description: Execute cleanup actions from an agents-audit — move, merge, delete, and update agent docs
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Consumes prior audit output; only meaningful right after /agents-audit."
 ---
 
 # agents-cleanup
@@ -18,10 +21,12 @@ disable-model-invocation: true
 ```
 ⚠️  No audit roadmap found.
 
-1. 🔍 Run /agents-audit first (recommended)
+1. 🔍 Run /agents-audit first
 2. 💬 I know what to do — start directly
 ```
 
+**Recommendation: 1 — Run /agents-audit first** — without an audit roadmap, the cleanup is shooting in the dark. Caveat: pick 2 only if you already know exactly which docs to touch.
+
 If option 2, ask what to clean up.
 
 ### 2. Show action plan

package/.agent-src/commands/agents-prepare.md

@@ -3,6 +3,9 @@ name: agents-prepare
 skills: [agent-docs-writing]
 description: Scaffold the agents/ directory structure with all required subdirectories and .gitkeep files
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "One-shot project scaffolding; only run during initial setup."
 ---
 
 # agents-prepare

package/.agent-src/commands/analyze-reference-repo.md

@@ -3,6 +3,10 @@ name: analyze-reference-repo
 skills: [project-analyzer, learning-to-rule-or-skill]
 description: Analyze an external reference repository (competitor, inspiration, peer) and produce a structured comparison + adoption plan for this project.
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "look at how X does this, compare with that other repo, study this competitor's approach"
+  trigger_context: "external repo URL or path mentioned in the prompt"
 ---
 
 # analyze-reference-repo

package/.agent-src/commands/bug-fix.md

@@ -3,6 +3,10 @@ name: bug-fix
 skills: [bug-analyzer, pest-testing]
 description: Plan and implement a bug fix — based on investigation, with quality checks and test verification
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "fix this bug, patch the issue, resolve this error"
+  trigger_context: "branch name matches fix/* or bug/*"
 ---
 
 # bug-fix
@@ -71,8 +75,8 @@ RISIKO-CHECK:
 For each change:
 
 1. **Read the file** before modifying.
-2. **Make the change** using `str-replace-editor`.
-3. **Check for downstream effects** — use `codebase-retrieval` to find callers.
+2. **Make the change** with the file-edit tool available to the agent.
+3. **Check for downstream effects** — search the codebase for callers.
 4. **Update related code** if signatures or behavior changed.
 
 ### 4. Quality checks
@@ -142,7 +146,7 @@ If the root cause is a recognizable pattern (not a one-off typo),
 drop a `historical-patterns` signal so future work benefits:
 
 ```bash
-python3 scripts/memory_signal.py \
+./agent-config memory:signal \
     --type historical-patterns \
     --path "<primary affected file>" \
     --body "<root cause → fix, one sentence>" \

package/.agent-src/commands/bug-investigate.md

@@ -3,6 +3,10 @@ name: bug-investigate
 skills: [bug-analyzer, sentry-integration]
 description: Investigate a bug — auto-detect ticket from branch, gather Jira/Sentry/description context, trace root cause
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "why is this broken, investigate this error, trace the root cause"
+  trigger_context: "Sentry URL, Jira bug ticket key, or stack trace pasted in the prompt"
 ---
 
 # bug-investigate

package/.agent-src/commands/chat-history-checkpoint.md

@@ -0,0 +1,126 @@
+---
+name: chat-history-checkpoint
+description: Append a phase-boundary entry to .agent-chat-history — the CHECKPOINT fallback for platforms without a native hook surface (Augment Code IDE plugin, Cursor non-1.7+, Cline non-Mac/Linux). Cooperative gate, ~1 second to run.
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "User wants to flush a chat-history phase boundary on a CHECKPOINT-class platform (Augment IDE, Cursor < 1.7, Cline on Windows) — phrases like 'checkpoint chat history', 'log a phase boundary', 'manual chat-history append'."
+  trigger_context: "chat_history.path == checkpoint AND a phase-shaped boundary just completed (decision recorded, multi-tool sequence finished, task-list item closed)."
+---
+
+<!-- cloud_safe: noop -->
+
+# /chat-history-checkpoint
+
+Force-append a `phase`-typed entry to `.agent-chat-history`. CHECKPOINT
+fallback for platforms without native hooks — see
+[`agents/contexts/chat-history-platform-hooks.md`](../../../agents/contexts/chat-history-platform-hooks.md)
+for the per-platform classification.
+
+Use this at decision points, end of phase, or after a meaningful tool
+sequence on a CHECKPOINT/MANUAL platform. On HOOK platforms (Claude
+Code, Augment CLI, Cursor 1.7+, Cline non-Windows, Windsurf, Gemini
+CLI), the platform fires hooks automatically — manual use is allowed
+but rarely needed.
+
+## When to use
+
+- IDE plugin without hooks (Augment Code IDE plugin as of 2026-04-30).
+- Long-running tool sequence on any platform that did not flush.
+- Explicit phase-boundary marker after a multi-tool refactor.
+- Crash-recovery rehearsal — verifies the append path works before a
+  real outage.
+
+## When NOT to use
+
+- HOOK platform mid-session — the platform already records turn-level
+  cadence; an extra checkpoint just adds noise.
+- After every line of agent output — that's `per_turn` cadence and is
+  configured in `.agent-settings.yml`, not via this command.
+- To inspect the log → [`/chat-history`](chat-history.md).
+- To wipe the log → [`/chat-history-clear`](chat-history-clear.md).
+- To reload the log into context → [`/chat-history-resume`](chat-history-resume.md).
+
+## Steps
+
+### 1. Check if enabled
+
+Read `chat_history.enabled` from `.agent-settings.yml`. If `false` or
+the section is missing, say so and stop:
+
+```
+> 📒 chat-history is disabled (chat_history.enabled = false).
+> Nothing to checkpoint. Enable in .agent-settings.yml first.
+```
+
+### 2. Determine the phase label
+
+Pick a short label (2–6 words) that names what just happened:
+
+- "phase-1-done", "refactor-extracted", "tests-green",
+  "review-comments-fixed", "merge-ready".
+
+If the user invoked the command without context, ask once with
+numbered options per [`user-interaction`](../rules/user-interaction.md):
+
+```
+> 1. Use a free-text label — type 2–6 words for the checkpoint
+> 2. Use a generic "manual-checkpoint" label
+> 3. Skip — close without writing
+```
+
+### 3. Append the checkpoint
+
+Invoke the master CLI:
+
+```
+./agent-config chat-history:checkpoint \
+  --first-user-msg "<the conversation's first user message>" \
+  --payload '{"phase": "<label>"}'
+```
+
+The wrapper delegates to `scripts/chat_history.py hook-append --event phase`,
+which performs cadence filtering and ownership checks. Cadence is read
+from `chat_history.frequency` in `.agent-settings.yml` — `per_turn` /
+`per_phase` / `per_tool`. `per_tool` cadence drops the `phase` event;
+say so explicitly if that is the active mode.
+
+### 4. Confirm
+
+Render a one-line confirmation, mirroring the user's language:
+
+```
+> 📒 Checkpoint logged: <label>  (entries: N → N+1)
+```
+
+If the helper returned `skipped_cadence`, surface it:
+
+```
+> 📒 Checkpoint skipped — current cadence is per_tool, phase events are dropped.
+> Switch chat_history.frequency to per_phase or per_turn to capture phase boundaries.
+```
+
+## Gotchas
+
+- The command writes through the same ownership-state machine as
+  hooks — a `foreign` log triggers the
+  [`chat-history`](../rules/chat-history-ownership.md) Foreign-Prompt before any
+  append. This is intentional; the checkpoint must not silently
+  hijack another session's log.
+- The `phase` payload key is required. Other keys are accepted but
+  ignored by the JSONL schema (forward-compat — they may be promoted
+  to first-class fields later).
+- On HOOK platforms, hook entries and checkpoint entries coexist
+  cleanly. The schema does not deduplicate; if you checkpoint
+  immediately after a hook fires, expect two adjacent entries with
+  different `source` values.
+
+## See also
+
+- [`chat-history`](../rules/chat-history-ownership.md) — the rule defining the
+  conditional Iron Law (HOOK platforms vs CHECKPOINT/MANUAL platforms)
+- [`/chat-history`](chat-history.md) — read-only status display
+- [`/chat-history-resume`](chat-history-resume.md) — adopt + load
+- [`/chat-history-clear`](chat-history-clear.md) — wipe
+- [`agents/contexts/chat-history-platform-hooks.md`](../../../agents/contexts/chat-history-platform-hooks.md) — per-platform strategy table
+- [`scripts/chat_history.py`](../../../scripts/chat_history.py) — `hook-append` API

package/.agent-src/commands/chat-history-clear.md

@@ -2,8 +2,13 @@
 name: chat-history-clear
 description: Manually delete the persistent chat-history log — asks for confirmation, optionally archives to a timestamped backup before wiping
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Destructive log wipe — must be deliberate."
 ---
 
+<!-- cloud_safe: noop -->
+
 # /chat-history-clear
 
 Wipes `.agent-chat-history`. Use when the log is stale (wrong session),
@@ -91,7 +96,7 @@ effect — this command is scoped to the file on disk only.
 
 ## See also
 
-- [`chat-history`](../rules/chat-history.md) — the rule that writes the file
+- [`chat-history`](../rules/chat-history-ownership.md) — the rule that writes the file
 - [`/chat-history`](chat-history.md) — status inspection
 - [`/chat-history-resume`](chat-history-resume.md) — load + adopt instead of wipe
 - [`agent-settings` template](../templates/agent-settings.md) — `chat_history.*` reference

package/.agent-src/commands/chat-history-resume.md

@@ -2,8 +2,13 @@
 name: chat-history-resume
 description: Load the persistent chat-history log into the current conversation — picks match/returning/foreign flow and supports resume, merge, replace, or continue
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Explicit resume mechanic with foreign/returning state machine."
 ---
 
+<!-- cloud_safe: noop -->
+
 # /chat-history-resume
 
 Reconnects the current conversation with an existing `.agent-chat-history`
@@ -12,7 +17,7 @@ flow: silent summarize, adopt, merge, or replace.
 
 Use after a crashed chat, after switching tools (Augment → Claude Code),
 or when the agent showed the foreign- or returning-session prompt from
-the [`chat-history`](../rules/chat-history.md) rule and the user picked
+the [`chat-history`](../rules/chat-history-ownership.md) rule and the user picked
 "resume".
 
 ## When NOT to use
@@ -169,7 +174,7 @@ the user decides what to do next.
 
 ## See also
 
-- [`chat-history`](../rules/chat-history.md) — the rule that triggers
+- [`chat-history`](../rules/chat-history-ownership.md) — the rule that triggers
   this command via the foreign- and returning-session prompts
 - [`/chat-history`](chat-history.md) — status inspection without adopting
 - [`/chat-history-clear`](chat-history-clear.md) — wipe instead of adopt

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

@@ -2,12 +2,17 @@
 name: chat-history
 description: Show the status of the persistent chat-history log — file size, entry count, header fingerprint, age, and the last few entries
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Status display only; no NL trigger distinct from 'show status'."
 ---
 
+<!-- cloud_safe: noop -->
+
 # /chat-history
 
 Inspect `.agent-chat-history` — the JSONL log maintained by the
-[`chat-history`](../rules/chat-history.md) rule for crash recovery.
+[`chat-history`](../rules/chat-history-ownership.md) rule for crash recovery.
 
 Shows:
 
@@ -95,7 +100,7 @@ append may trigger overflow handling.
 
 ## See also
 
-- [`chat-history`](../rules/chat-history.md) — the rule that writes the file
+- [`chat-history`](../rules/chat-history-ownership.md) — the rule that writes the file
 - [`/chat-history-resume`](chat-history-resume.md) — adopt + load
 - [`/chat-history-clear`](chat-history-clear.md) — wipe
 - [`agent-settings` template](../templates/agent-settings.md) — `chat_history.*` reference

package/.agent-src/commands/check-current-md.md

@@ -0,0 +1,137 @@
+---
+name: check-current-md
+description: Check the currently open .md file (or a path you pass) for German content outside DE:/EN: anchor blocks — umlauts, German function words, untranslated quoted phrases. Reports findings and offers fixes.
+disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Package-internal — only the event4u/agent-config repo runs this."
+---
+
+# check-current-md
+
+Manual runner for the [`md-language-check`](../skills/md-language-check/SKILL.md)
+skill. Use to spot-check an `.md` file the agent did not just edit, or to
+audit a file before opening a PR.
+
+## Instructions
+
+### 1. Resolve target paths
+
+If the user passed one or more paths, use those. Otherwise, default to
+the file currently open in the editor (per `personal.ide` open-file
+context). If no file is open and no path was passed:
+
+```
+> ❌  No target file. Pass a path: /check-current-md path/to/file.md
+```
+
+Stop here.
+
+### 2. Run the checker
+
+```bash
+python3 scripts/check_md_language.py <path> [<path> …] --format json
+```
+
+Exit codes:
+
+- `0` → no findings; report and stop
+- `1` → findings present; continue to step 3
+- `3` → internal error; surface stderr and stop
+
+### 3. Display findings
+
+```
+═══════════════════════════════════════════════
+  📒 .md LANGUAGE CHECK
+═══════════════════════════════════════════════
+
+  Found: {count} violation(s) across {files} file(s)
+```
+
+For each violation:
+
+```
+  {file}:{line} — kind: {umlaut|de_word} — match: `{matched_text}`
+    │ {context_line}
+```
+
+Group by file when multiple files are scanned.
+
+### 4. Classify and propose fixes
+
+For each violation, propose one of:
+
+| Cause | Proposed fix |
+|---|---|
+| German sentence in body prose | Translate the line to English |
+| Quoted German token used as example | Move into a labeled `DE: … · EN: …` block |
+| Meta-documentation that documents trigger words | Append `<!-- md-language-check: ignore -->` to the line |
+| Line is intentionally bilingual but unlabeled | Reformat as labeled anchor block |
+
+Present a summary:
+
+```
+  Proposed fixes:
+  1. {file}:{line} — {strategy}
+  2. {file}:{line} — {strategy}
+
+> 1. Apply all fixes
+> 2. Apply interactively
+> 3. Skip — report only
+```
+
+Recommendation: **2 — Apply interactively** when ≥3 findings, **1 —
+Apply all fixes** for ≤2 findings or when all are pure translations.
+
+### 5. Apply fixes
+
+Edit only the source-of-truth file:
+
+- Path under `.agent-src.uncompressed/` → edit there directly
+- Path under `.agent-src/` → edit the matching
+  `.agent-src.uncompressed/` file instead, then run
+  `bash scripts/compress.sh --sync`
+- Path under `.augment/` → same as `.agent-src/` (it's a projection)
+- Path under `agents/` → edit directly (no compression layer)
+
+After all fixes, re-run:
+
+```bash
+python3 scripts/check_md_language.py <path> [<path> …]
+```
+
+### 6. Mark hashes (only if `.agent-src.uncompressed/` was edited)
+
+For each modified source file:
+
+```bash
+python3 scripts/compress.py --mark-done "{relative_path}"
+```
+
+This keeps `.compression-hashes.json` consistent with the new content.
+
+## Rules
+
+- **Never edit `.augment/` directly** — it's a generated projection.
+  Per [`augment-source-of-truth`](../rules/augment-source-of-truth.md),
+  the source is `.agent-src.uncompressed/`.
+- **Per-line ignore marker is reserved** for meta-documentation that
+  must quote German tokens; do NOT use it as a generic mute.
+- **Frontmatter is exempt** — the checker skips YAML frontmatter at
+  the head of the file; do not try to "fix" frontmatter.
+- **Do NOT commit or push** — finishing the check leaves the working
+  tree to the user.
+
+## When NOT to use
+
+- Project content outside `.agent-src*/`, `.augment/`, or `agents/`
+  follows a different language policy — do not enforce English there.
+- During autonomous edits, the [`md-language-check`](../skills/md-language-check/SKILL.md)
+  skill already gates saves; this command is for **manual** spot-checks.
+
+## See also
+
+- [`md-language-check`](../skills/md-language-check/SKILL.md) — the gate skill this command wraps
+- [`language-and-tone`](../rules/language-and-tone.md) — the rule that defines the policy
+- [`augment-source-of-truth`](../rules/augment-source-of-truth.md) — where to apply fixes

package/.agent-src/commands/commit-in-chunks.md

@@ -0,0 +1,118 @@
+---
+name: commit-in-chunks
+skills: [git-workflow]
+description: Stage and commit all uncommitted changes in logical chunks WITHOUT confirmation — sibling of /commit for autonomous flows
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "commit everything autonomously, split and commit without confirmation"
+  trigger_context: "autonomous mode active and uncommitted changes present"
+---
+
+# commit-in-chunks
+
+Auto-split and commit all local changes in one go. Use this when you
+want commits made without being asked to confirm each batch. Sibling
+of [`/commit`](commit.md), which presents the plan and waits for
+approval. This command skips the approval step.
+
+Per [`autonomous-execution`](../rules/autonomous-execution.md), the
+agent does **not** commit on its own initiative — invoking this
+command is the user's explicit consent to commit.
+
+## Instructions
+
+### 1. Detect uncommitted changes
+
+```bash
+git status --short
+git diff --stat
+git diff --cached --stat
+```
+
+If there are no uncommitted changes (staged or unstaged), report
+"Nothing to commit." and stop.
+
+### 2. Determine the ticket number
+
+- Extract the ticket ID from the current branch name (e.g. `feat/DEV-1234/...`
+  → `DEV-1234`).
+- If no ticket ID is found, omit the scope from the messages — write
+  `chore: ...` not `chore(): ...`. Do **not** ask the user for one.
+
+### 3. Analyze and split
+
+Group changed files into logical units following [`/commit`](commit.md)
+step 3 grouping rules:
+
+- Same feature / fix → one commit.
+- Migration + corresponding model/seeder → one commit.
+- Test + the class under test → one commit.
+- Style-only changes (ECS/Rector/formatter) → separate `style:` /
+  `chore:` commit when mixed with logic changes.
+- Truly unrelated change → its own commit.
+
+Splitting rules:
+- **Do NOT split arbitrarily** — only when the changes are logically
+  independent.
+- **Prefer fewer, coherent commits** over many tiny ones.
+- **Tests go with the code they test** unless test-only changes are
+  large and noisy.
+
+Generate commit messages per [`commit-conventions`](../rules/commit-conventions.md).
+
+### 4. Commit immediately
+
+For each planned commit in order:
+
+```bash
+git add {files...}
+git commit -m "{message}"
+```
+
+No "looks good?" prompt. No confirmation step. The user invoked this
+command knowing the plan would be executed.
+
+### 5. Report
+
+Show a summary:
+
+```
+Created N commits:
+1. {sha1}  feat(DEV-1234): {summary}
+2. {sha2}  test(DEV-1234): {summary}
+3. {sha3}  chore: {summary}
+```
+
+Include `git log --oneline -N` output for verification.
+
+## Rules
+
+- **Never push** — pushing remains explicit per [`scope-control`](../rules/scope-control.md#git-operations--permission-gated).
+- **Never modify files** — only stage and commit existing changes.
+- **Do NOT add untracked files** unless they are clearly part of the
+  change (check with `git status` first).
+- **Follow commit conventions** as defined in [`commit-conventions`](../rules/commit-conventions.md).
+- **Stop on first failure** — if `git commit` fails (hook rejection,
+  pre-commit lint error), stop, report the error, and do not continue
+  with the remaining planned commits. Leave staged files for the user
+  to inspect.
+- **No interactive prompts** — fail fast over hanging waiting for
+  input.
+
+## When NOT to use
+
+- The user has not seen the diff yet and would benefit from review →
+  use [`/commit`](commit.md) instead.
+- The diff includes large unrelated changes the user might want to
+  reorganise → use [`/commit`](commit.md).
+- The repo has a pre-commit hook that requires manual response → fix
+  the hook or use `/commit`.
+
+## See also
+
+- [`/commit`](commit.md) — split + present plan + wait for approval
+- [`autonomous-execution`](../rules/autonomous-execution.md) — the
+  rule that defines the no-ask commit default this command opts out of
+- [`commit-conventions`](../rules/commit-conventions.md) — message
+  format

package/.agent-src/commands/commit.md

@@ -3,6 +3,10 @@ name: commit
 skills: [git-workflow]
 description: Stage and commit all uncommitted changes — splits into logical commits following Conventional Commits
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "commit my changes, save this to git, create commits for these changes"
+  trigger_context: "git status shows uncommitted changes"
 ---
 
 # commit

package/.agent-src/commands/compress.md

@@ -3,6 +3,9 @@ name: compress
 skills: []
 description: Compress .md files from .agent-src.uncompressed/ into caveman format and write to .agent-src/
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Package-internal tooling; only the event4u/agent-config repo runs this."
 ---
 
 # compress
@@ -31,7 +34,8 @@ bash scripts/compress.sh --changed
 This lists only `.md` files whose source has changed since the last compression (based on
 stored SHA-256 hashes). If no files changed → you're done.
 
-If you need to see ALL files regardless of change status: `bash scripts/compress.sh --list`.
+If you need to see ALL files regardless of change status:
+`bash scripts/compress.sh --list`.
 
 ## Step 3: Compress each changed .md file
 
@@ -68,6 +72,7 @@ For each changed `.md` file:
    - Concrete validation checks
    - Gotchas based on real failure patterns
    - Anti-patterns that prevent recurring failures
+   - **Iron Law sections** — see "Iron Laws — do not touch" below
 5. **Enrich (SKILL.md files only):** During compression, also improve agent-effectiveness:
    - **Validation steps:** If a Procedure ends with a vague validation ("check if it works"),
      replace with concrete checks (expected output, commands to verify, specific conditions)
@@ -137,9 +142,39 @@ Show a summary table with per-category stats (files compressed, avg savings).
   (useful after an initial full compression or when bootstrapping the hash file).
 - A file with no stored hash is always treated as "changed".
 
+## Iron Laws — do not touch
+
+Sections under headings matching `Iron Law`, `Iron Laws`, or `The Iron Law` (any
+heading level, numbered variants like `Iron Law 1` included) are **load-bearing
+behavioral rules**. Compression rules above do **not** apply to them.
+
+For every Iron Law section in a source file:
+
+- **Copy the heading verbatim**, exact text, exact `#` level. NEVER downgrade
+  `## Iron Law` to `### Iron Law` or to inline `**Iron Law:**`.
+- **Copy the fenced code block byte-for-byte**, including capitalization, line
+  breaks, and trailing punctuation.
+- **Copy the negation clauses verbatim** — `NO X`, `NEVER Y`, `NOT Z`. These
+  are the law's exception denials; stripping them weakens the rule.
+- **Caveman the prose, keep every passage** — every paragraph, every list
+  item, and every fenced code block from the source must appear in the
+  compressed output, in order. Drop articles, shorten phrasing, primitive
+  grammar, terse cave-speak — all encouraged. What's forbidden is dropping
+  whole sentences, merging two paragraphs into one, or skipping a bullet.
+  One paragraph → one paragraph; one bullet → one bullet.
+- **No word-count budget** — compress the prose as hard as caveman style
+  allows. The check is structural (passage count), not quantitative.
+
+`scripts/check_compression.py` enforces these mechanically — `iron_law_missing`,
+`iron_law_passage_dropped`, and `iron_law_heading_downgrade` are `error`-level
+and block CI.
+
+If an Iron Law section genuinely contains filler (rare): edit the SOURCE in
+`.agent-src.uncompressed/`, not the compressed copy. Source is the truth.
+
 ## Compression quality checklist
 
-**Also apply the `preservation-guard` rule** — strongest validation, example, anti-pattern, and decision hints must survive compression.
+**Also apply the `preservation-guard` rule** — strongest validation, example, anti-pattern, and decision hints must survive compression. Iron Laws are non-negotiable.
 
 After compressing each file, verify: