@event4u/agent-config 1.9.1 → 1.12.0

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

@@ -62,3 +62,18 @@ Show the handoff prompt in a fenced code block and say:
 - **Open tasks are critical** — the new chat needs to know what's left.
 - **Decisions are important** — prevents the new chat from re-asking settled questions.
 - **File list is optional** — only include if the new chat will need to edit specific files.
+
+## When to use this vs. `/chat-history-resume`
+
+- `/agent-handoff` is **push-based**: you copy a short summary into the
+  new chat. Works across tools (Augment → Claude Code), across machines,
+  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
+  same machine and same repo, but captures more detail (every phase /
+  tool call / decision the prior session logged).
+
+Prefer `/agent-handoff` for planned context switches; prefer
+`/chat-history-resume` after a crash or after switching tools within the
+same workspace.

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

@@ -0,0 +1,98 @@
+---
+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
+---
+
+# /chat-history-clear
+
+Wipes `.agent-chat-history`. Use when the log is stale (wrong session),
+bloated beyond usefulness, or contains information you do not want
+persisted on disk.
+
+This command is **destructive** — always asks for confirmation before
+touching the file, unless the file does not exist in the first place.
+
+## When NOT to use
+
+- Inspect before deleting → [`/chat-history`](chat-history.md).
+- Keep the entries but re-point the header → [`/chat-history-resume`](chat-history-resume.md).
+- Disable logging entirely → set `chat_history.enabled: false` in
+  `.agent-settings.yml`; see
+  [`layered-settings`](../guidelines/agent-infra/layered-settings.md#section-aware-merge-rules).
+  Disabling does not delete the existing file; run this command
+  afterwards if you also want it gone.
+
+## Steps
+
+### 1. Check current state
+
+Run `scripts/chat_history.py status`. If `exists: false`, tell the user
+and stop:
+
+```
+> 📒 No .agent-chat-history to clear.
+```
+
+### 2. Show what is about to be deleted
+
+Render a short preview so the user sees what they are wiping:
+
+```
+> 📒 About to clear .agent-chat-history
+>
+> Size:       {size_kb} KB
+> Entries:    {entries}
+> Session:    {short_fp}  (started {created_at_relative})
+>
+> 1. Archive — rename to .agent-chat-history.{YYYYMMDD-HHMMSS}.bak, then start fresh
+> 2. Delete — permanent, no backup
+> 3. Cancel — keep the file as-is
+```
+
+### 3. Act on the choice
+
+- `1` (Archive) → `mv .agent-chat-history
+  .agent-chat-history.{timestamp}.bak`. The rule will create a fresh
+  file on the next append.
+- `2` (Delete) → run `scripts/chat_history.py clear`. Permanent.
+- `3` (Cancel) → stop. Make no changes.
+
+Free-text replies ("abbrechen", "keep it", "nevermind") count as `3`.
+An unrecognized reply also counts as `3` — never delete on ambiguous
+input.
+
+### 4. Confirm
+
+After a successful archive or delete, print a one-line confirmation:
+
+```
+> 📒 Archived to .agent-chat-history.{timestamp}.bak
+```
+
+or
+
+```
+> 📒 .agent-chat-history deleted.
+```
+
+Do **not** re-enable logging or change `.agent-settings.yml` as a side
+effect — this command is scoped to the file on disk only.
+
+## Gotchas
+
+- `.agent-chat-history.*.bak` files are also git-ignored by the
+  installer's `.gitignore` block. They accumulate if archived often —
+  users can delete them manually.
+- If `chat_history.enabled: false`, the file will **not** be recreated
+  after clearing. That is usually fine, but mention it so the user
+  knows the log is now silent.
+- Deletion cannot be undone. When in doubt, prefer option `1` (Archive).
+
+## See also
+
+- [`chat-history`](../rules/chat-history.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
+- [`scripts/chat_history.py`](../../../scripts/chat_history.py) — helper API

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

@@ -0,0 +1,178 @@
+---
+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
+---
+
+# /chat-history-resume
+
+Reconnects the current conversation with an existing `.agent-chat-history`
+file. Depending on the 4-state ownership check, it routes to the right
+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
+"resume".
+
+## When NOT to use
+
+- Just inspect metadata → [`/chat-history`](chat-history.md).
+- Start fresh instead of resuming → [`/chat-history-clear`](chat-history-clear.md)
+  or pick "New start" in the foreign prompt.
+- Logging is disabled (`chat_history.enabled: false`) → enable it in
+  `.agent-settings.yml` first; this command refuses to run otherwise.
+
+## Preconditions
+
+- `.agent-settings.yml` exists and `chat_history.enabled: true`.
+- `.agent-chat-history` exists at the project root.
+
+If either is missing, tell the user and stop — do not create files here.
+
+## Steps
+
+### 1. Load status
+
+Run `scripts/chat_history.py status`. If `exists: false` or
+`entries: 0`, tell the user there is nothing to resume and stop.
+
+### 2. Determine ownership state
+
+Run `scripts/chat_history.py state --first-user-msg "<current first user
+message>"`. Branch on the result:
+
+- `match` → step 3a (already owner)
+- `returning` → step 3b (pick Merge / Replace / Continue)
+- `foreign` → step 3c (pick Resume / New start / Ignore)
+- `missing` → header corrupt; tell the user and suggest
+  `/chat-history-clear` to start fresh. Stop.
+
+### 3a. `match` — already owner
+
+Nothing to adopt. Skip to step 4 (summarize) for the user's benefit.
+
+### 3b. `returning` — this chat once owned the file
+
+Another session took over. Present the Returning-Prompt from the rule
+and wait for a number:
+
+```
+> 📒 Welcome back. This chat once owned the history file; another
+> session has written to it since.
+>
+> On-file entries: {N}   Size: {X} KB
+>
+> 1. Merge — my in-memory history first, the foreign entries after
+> 2. Replace — wipe the foreign entries, keep only my history
+> 3. Continue — leave the file as-is; only new entries from now on
+```
+
+- **1 (Merge)** — build the in-memory entries list (see below), then:
+  ```bash
+  scripts/chat_history.py prepend --entries-json '<list>'
+  scripts/chat_history.py adopt --first-user-msg "<msg>"
+  ```
+- **2 (Replace)** — build the in-memory entries list, then:
+  ```bash
+  scripts/chat_history.py reset --first-user-msg "<msg>" \
+    --freq <frequency> --entries-json '<list>'
+  ```
+- **3 (Continue)** —
+  ```bash
+  scripts/chat_history.py adopt --first-user-msg "<msg>"
+  ```
+
+### 3c. `foreign` — new chat finds an unknown session's file
+
+Present the Foreign-Prompt from the rule and wait for a number:
+
+```
+> 📒 Found chat history from an unknown session.
+>
+> Entries on file: {N}   Size: {X} KB
+>
+> 1. Resume — adopt this file, load entries as context, keep appending
+> 2. New start — archive to .agent-chat-history.bak, init fresh
+> 3. Ignore — leave the file untouched, disable logging for this session
+```
+
+- **1 (Resume)** — `adopt --first-user-msg "<msg>"`.
+- **2 (New start)** — rename file to `.agent-chat-history.bak`, run
+  `init --first-user-msg "<msg>" --freq <frequency>`. Skip summary.
+- **3 (Ignore)** — do nothing. Report that logging is off for this
+  conversation. Stop.
+
+### 3d. Building the in-memory entries list (Merge / Replace)
+
+Reconstruct the agent's prior turns as a JSON array:
+
+- one `{"t":"user","text":"<preview>","ts":"<iso>"}` per user message
+- one `{"t":"agent","text":"<preview>","ts":"<iso>"}` per agent reply
+- `text` previews capped at ~200 chars (whitespace flattened)
+- timestamps in ISO-8601 UTC (current time is acceptable if exact times
+  are unknown; order is what matters)
+- no tool-call payloads, no file contents, no secrets
+
+If the list is large (>30 KB), stream it via stdin:
+`prepend --entries-stdin` or `reset --entries-stdin`.
+
+### 4. Overflow check
+
+After any Merge or Replace, run
+`scripts/chat_history.py rotate --max-kb <max_size_kb>
+--mode <on_overflow>` so the combined body stays within the user's
+budget.
+
+### 5. Summarize into conversation context
+
+Read the entries via the helper (`read --all` or `read --last N` for
+bounded). Produce a short, structured summary — **not** a verbatim dump:
+
+```
+> 📒 Resumed chat-history ({entries} entries, {age})
+>
+> ## What was done
+> - {1–3 bullets from agent/decision entries}
+>
+> ## Open threads
+> - {1–3 bullets from the most recent entries and any pending questions}
+>
+> ## Key decisions
+> - {decisions captured during the prior session}
+>
+> Ready to continue. What would you like to do?
+```
+
+Keep the summary under ~25 lines. Rationale: this is input into the new
+turn, not a display artifact (see
+[`token-efficiency`](../rules/token-efficiency.md)).
+
+### 6. Hand control back to the user
+
+After presenting the summary, stop and wait. Do not auto-resume work —
+the user decides what to do next.
+
+## Gotchas
+
+- **Iron law — one question at a time.** Even if the log contains
+  several open threads, ask about one at a time after the summary
+  (see [`ask-when-uncertain`](../rules/ask-when-uncertain.md)).
+- `adopt` rewrites the header in place and pushes the previous fp into
+  `former_fps` (capped at 10). No backup is created — use
+  `/chat-history-clear` first if you want a clean slate.
+- `reset` discards whatever was on disk. Only use it when the user
+  explicitly picks "Replace".
+- The summary is derived from the agent's reading of the JSONL. Old
+  entries may be incomplete (especially under `per_turn` with
+  previews only). Flag gaps explicitly.
+
+## See also
+
+- [`chat-history`](../rules/chat-history.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
+- [`/agent-handoff`](agent-handoff.md) — complementary: generates a
+  paste-into-new-chat prompt (no disk file)
+- [`scripts/chat_history.py`](../../../scripts/chat_history.py) — helper API

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

@@ -0,0 +1,102 @@
+---
+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
+---
+
+# /chat-history
+
+Inspect `.agent-chat-history` — the JSONL log maintained by the
+[`chat-history`](../rules/chat-history.md) rule for crash recovery.
+
+Shows:
+
+- Whether the file exists and whether logging is currently enabled
+- File size vs `max_size_kb`
+- Header metadata: fingerprint preview, created-at, `frequency`
+- Entry count and age of the oldest/newest entry
+- A peek at the last 3–5 entries so the user can see what was captured
+
+Read-only — this command never writes to the file.
+
+## When NOT to use
+
+- Load the log back into the conversation for context →
+  [`/chat-history-resume`](chat-history-resume.md).
+- Wipe the file → [`/chat-history-clear`](chat-history-clear.md).
+- Configure logging behavior → edit `.agent-settings.yml` directly
+  (`chat_history.*`); see
+  [`layered-settings`](../guidelines/agent-infra/layered-settings.md#section-aware-merge-rules).
+
+## 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).
+> Set it to true in .agent-settings.yml to start logging.
+```
+
+### 2. Read status via helper
+
+Run `scripts/chat_history.py status`. The helper returns a JSON object
+with `exists`, `size_bytes`, `size_kb`, `entries`, `header`, and `path`.
+
+If `exists: false`, tell the user the file has not been created yet —
+it will be created on the next agent turn that writes an entry.
+
+### 3. Read last N entries
+
+Run `scripts/chat_history.py read --last 5` (or equivalent — see the
+helper's CLI). Capture timestamps and entry types without loading the
+full file.
+
+### 4. Present the summary
+
+Render a concise report:
+
+```
+> 📒 chat-history status
+>
+> File:       .agent-chat-history  ({size_kb} KB / {max_size_kb} KB)
+> Entries:    {entries}
+> Fingerprint:{short_fp}  (session started {created_at_relative})
+> Frequency:  {frequency}
+> Overflow:   {on_overflow}
+>
+> Last entries:
+>   {ts_1}  {type_1}  {preview_1}
+>   {ts_2}  {type_2}  {preview_2}
+>   ...
+```
+
+Keep previews short (≤ 60 chars). Do not render the full entry text
+unless the user asks (avoids flooding the conversation with old log
+data, see [`token-efficiency`](../rules/token-efficiency.md)).
+
+### 5. Offer follow-ups (optional)
+
+If the file exists and the fingerprint does **not** match the current
+session, suggest `/chat-history-resume` to adopt it.
+
+If the file is close to `max_size_kb` (> 80 %), mention it — the next
+append may trigger overflow handling.
+
+## Gotchas
+
+- `.agent-chat-history` is git-ignored. This command never commits.
+- The helper is the only way to read the file — do not cat or parse
+  the JSONL directly; entry shape is owned by `scripts/chat_history.py`.
+- If `exists: false` but the rule says logging is enabled, the file is
+  created lazily on the first append. That is expected — not an error.
+
+## See also
+
+- [`chat-history`](../rules/chat-history.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
+- [`scripts/chat_history.py`](../../../scripts/chat_history.py) — helper API

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

@@ -16,7 +16,7 @@ Only changed files need recompression — saving tokens and time.
 ## Step 1: Sync non-.md files
 
 ```bash
-task sync
+bash scripts/compress.sh --sync
 ```
 
 This copies non-`.md` files (`.php`, etc.), deletes stale files, and shows the count of
@@ -25,13 +25,13 @@ changed `.md` files that need compression.
 ## Step 2: Get changed files
 
 ```bash
-task sync-changed
+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: `task sync-list`.
+If you need to see ALL files regardless of change status: `bash scripts/compress.sh --list`.
 
 ## Step 3: Compress each changed .md file
 
@@ -97,7 +97,7 @@ Common errors and how to fix them:
 **Do NOT call `mark-done` until this file has zero 🔴 errors.**
 
 8. Show word count: `{original} → {compressed} words ({saved}% saved)`
-9. **Mark as done:** `task sync-mark-done -- {path}`
+9. **Mark as done:** `bash scripts/compress.sh --mark-done {path}`
 
 ### Batch processing
 
@@ -113,7 +113,7 @@ Batch 1/5 complete: 10 files, avg 42% saved
 Run BOTH checks. Both must pass before finishing.
 
 ```bash
-task sync-check
+bash scripts/compress.sh --check
 ```
 
 Must show ✅ (hashes in sync).
@@ -132,9 +132,9 @@ Show a summary table with per-category stats (files compressed, avg savings).
 ## Hash management
 
 - Hashes are stored in `.augment/.compression-hashes.json` (committed to Git).
-- `task sync` automatically cleans up hashes for deleted source files.
-- `task sync-mark-all-done` marks ALL current `.md` files as compressed (useful after an
-  initial full compression or when bootstrapping the hash file).
+- `bash scripts/compress.sh --sync` automatically cleans up hashes for deleted source files.
+- `bash scripts/compress.sh --mark-all-done` marks ALL current `.md` files as compressed
+  (useful after an initial full compression or when bootstrapping the hash file).
 - A file with no stored hash is always treated as "changed".
 
 ## Compression quality checklist
@@ -174,4 +174,4 @@ Unsafe (DO NOT do this):
 - **Only write to `.augment/`** — the compressed output directory.
 - **Preserve ALL technical content** — only compress natural language prose.
 - **YAML frontmatter** in command/skill files must be preserved exactly.
-- **Always run `task sync-mark-done`** after writing each compressed file.
+- **Always run `bash scripts/compress.sh --mark-done {path}`** after writing each compressed file.

package/.agent-src/commands/copilot-agents-init.md

@@ -134,7 +134,7 @@ Next steps:
 ### 7. Follow-ups
 
 If `agents/` directory does not exist, suggest running `/agents-prepare`.
-If `.agent-settings.yml` does not exist, suggest running `/config-agent-settings`.
+If `.agent-settings.yml` does not exist, suggest running `scripts/install` (then `/onboard` for first-run setup).
 
 ## Rules
 

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

@@ -71,7 +71,7 @@ Present a summary:
 
 ### 5. Apply fixes
 
-Edit files in `.agent-src.uncompressed/`, then run `task sync` to regenerate `.agent-src/` and `.augment/`.
+Edit files in `.agent-src.uncompressed/`, then run `bash scripts/compress.sh --sync` to regenerate `.agent-src/` and `.augment/`.
 
 After all fixes, re-run:
 
@@ -90,7 +90,7 @@ python3 scripts/compress.py --mark-done "{relative_path}"
 ## Rules
 
 - **Always fix in `.agent-src.uncompressed/`** — never edit `.agent-src/` or `.augment/` directly.
-- **Run `task sync`** after fixing to regenerate `.agent-src/` and `.augment/`.
+- **Run `bash scripts/compress.sh --sync`** after fixing to regenerate `.agent-src/` and `.augment/`.
 - **Do NOT commit or push.**
 - **`agents/` directory is allowed** to have project-specific references — skip it.
 - **Do NOT fix references in code blocks** unless the code block is clearly a template.

package/.agent-src/commands/fix-pr-bot-comments.md

@@ -127,7 +127,7 @@ Process all comments without asking. For each comment:
 
 ### Bot icon prefix
 
-Read `project.pr_comment_bot_icon` from `.agent-settings.yml`. If `true` (default),
+Read `personal.pr_comment_bot_icon` from `.agent-settings.yml`. If `true` (default),
 prefix every reply with `🤖 ` so reviewers can see at a glance that the reply was
 bot-authored.
 

package/.agent-src/commands/fix-pr-developer-comments.md

@@ -133,7 +133,7 @@ Process all comments without asking. For each comment:
 
 ### Bot icon prefix
 
-Read `project.pr_comment_bot_icon` from `.agent-settings.yml`. If `true` (default),
+Read `personal.pr_comment_bot_icon` from `.agent-settings.yml`. If `true` (default),
 prefix every reply with `🤖 ` so reviewers can see at a glance that the reply was
 bot-authored.
 

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

@@ -66,7 +66,7 @@ Present a summary before applying:
 
 ### 5. Apply fixes
 
-Edit files in `.agent-src.uncompressed/` (source of truth). Regenerate `.agent-src/` and `.augment/` via `task sync`.
+Edit files in `.agent-src.uncompressed/` (source of truth). Regenerate `.agent-src/` and `.augment/` via `bash scripts/compress.sh --sync`.
 
 After all fixes:
 
@@ -87,7 +87,7 @@ python3 scripts/compress.py --mark-done "{relative_path}"
 ## Rules
 
 - **Always fix in `.agent-src.uncompressed/`** — never edit `.agent-src/` or `.augment/` directly.
-- **Run `task sync`** after fixing to regenerate `.agent-src/` and `.augment/`.
+- **Run `bash scripts/compress.sh --sync`** after fixing to regenerate `.agent-src/` and `.augment/`.
 - **Do NOT commit or push** — the user decides.
 - **Do NOT fix references in code blocks** — they are examples, not live refs.
 - **Do NOT auto-fix without showing the summary first.**

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

@@ -41,7 +41,7 @@ If `<name>` is not in that set, refuse and print the valid list.
 ### 3. Read settings
 
 Read `.agent-settings.yml`. If missing, tell the user to run
-`/config-agent-settings` first and stop — do not create the file here.
+`scripts/install` first and stop — do not create the file here.
 
 Extract `roles.default_role` and `roles.active_role`.
 
@@ -58,9 +58,9 @@ exactly what the contract demands.
 
 ### 5. Write the active role
 
-Update `roles.active_role` in `.agent-settings.yml` using the same
-section-aware merge rules as `/config-agent-settings` (preserve comments,
-preserve key order, touch only the changed field).
+Update `roles.active_role` in `.agent-settings.yml` using the
+[section-aware merge rules](../guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
+(preserve comments, preserve key order, touch only the changed field).
 
 For `/mode none`: set `active_role: ""`.
 
@@ -117,5 +117,5 @@ For `/mode` (status only):
 
 - [`role-contracts`](../guidelines/agent-infra/role-contracts.md) — the six modes
 - [`role-mode-adherence`](../rules/role-mode-adherence.md) — closing-output gate
-- [`config-agent-settings`](config-agent-settings.md) — baseline settings writer
+- [`layered-settings`](../guidelines/agent-infra/layered-settings.md) — merge rules for settings edits
 - [`ask-when-uncertain`](../rules/ask-when-uncertain.md) — never invent modes