@event4u/agent-config 1.19.0 → 1.20.0

package/scripts/lint_hook_manifest.py

@@ -57,7 +57,8 @@ EVENT_VOCABULARY: set[str] = {
 # Known platform identifiers. New platforms MUST be added here as they
 # land — the linter is the gate that proves no orphan slot escapes.
 KNOWN_PLATFORMS: set[str] = {
-    "augment", "claude", "cursor", "cline", "windsurf", "gemini", "copilot",
+    "augment", "claude", "cowork",
+    "cursor", "cline", "windsurf", "gemini", "copilot",
 }
 
 

package/scripts/redact_hook_capture.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""Redact captured hook payloads for the verified-platforms roadmap.
+
+Reads JSON capture files written by ``dispatch_hook.py`` (when
+``AGENT_HOOK_CAPTURE_DIR`` is set) and produces a redacted version
+suitable for pasting into
+``agents/roadmaps/road-to-verified-chat-history-platforms.md``.
+
+Redaction policy (per the roadmap's Capture-and-redact protocol):
+
+- Replace string values at known user-content paths with
+  ``<REDACTED>``. Default field allowlist mirrors the fallback list
+  in ``scripts/chat_history.py::_extract_hook_text`` plus Augment's
+  nested ``conversation.*`` shape.
+- Preserve envelope keys (``hook_event_name``, ``session_id``,
+  ``platform``, ``event``, ``cwd``, ``workspace_roots``,
+  ``transcript_path``, ``model``, ``cursor_version``, …) so the
+  schema is reviewable.
+- ``--strict`` redacts any string longer than ``--max-len`` (default
+  120) chars regardless of key, as a safety net for unknown fields.
+
+Usage:
+
+    python3 scripts/redact_hook_capture.py <input> [--out <path>] [--strict]
+
+Input may be a single JSON file or a directory; with a directory,
+every ``*.json`` is redacted and written next to the original with
+the suffix ``.redacted.json``.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+REDACTED = "<REDACTED>"
+
+# Field names that carry user / agent content (from
+# scripts/chat_history.py::_extract_hook_text fallback list +
+# nested Augment shape). Matched case-insensitively against the
+# leaf key.
+_USER_CONTENT_KEYS = {
+    "prompt", "user_prompt", "userprompt", "first_user_msg",
+    "firstusermsg", "usermessage", "user_message", "text",
+    "response", "message", "content",
+    # Augment Code with includeConversationData
+    "agenttextresponse", "agent_text_response",
+    "agentcoderesponse", "agent_code_response",
+    # Cursor / generic
+    "submitted_prompt", "submittedprompt",
+    # Free-form transcript bodies (path stays — content is in another file)
+    "transcript", "transcript_text",
+}
+
+# Keys whose value is a structural / schema marker — keep as-is even
+# when --strict would otherwise redact long values.
+_ENVELOPE_KEYS_KEEP = {
+    "hook_event_name", "session_id", "transcript_path", "transcriptpath",
+    "platform", "event", "native_event", "captured_at", "cwd",
+    "workspace_roots", "model", "cursor_version", "user_email",
+    "conversation_id", "generation_id", "agent", "type",
+    "schema_version", "started_at", "completed_at", "_raw_text",
+    "path", "changetype", "change_type",
+}
+
+
+def _redact_value(val: Any, *, key: str | None, strict: bool,
+                  max_len: int) -> Any:
+    """Recursively redact a value."""
+    norm_key = (key or "").lower().replace("-", "_")
+    if isinstance(val, dict):
+        return {k: _redact_value(v, key=k, strict=strict, max_len=max_len)
+                for k, v in val.items()}
+    if isinstance(val, list):
+        return [_redact_value(item, key=key, strict=strict, max_len=max_len)
+                for item in val]
+    if isinstance(val, str):
+        if norm_key in _ENVELOPE_KEYS_KEEP:
+            return val
+        if norm_key in _USER_CONTENT_KEYS:
+            return REDACTED
+        if strict and len(val) > max_len:
+            return REDACTED
+        return val
+    return val
+
+
+def redact(record: dict, *, strict: bool = False, max_len: int = 120) -> dict:
+    """Redact a single capture record. Top-level envelope is preserved."""
+    out: dict = {}
+    for k, v in record.items():
+        if k == "raw_payload":
+            out[k] = _redact_value(v, key=None, strict=strict,
+                                   max_len=max_len)
+        else:
+            out[k] = _redact_value(v, key=k, strict=strict,
+                                   max_len=max_len)
+    return out
+
+
+def _process_file(path: Path, *, out: Path | None, strict: bool,
+                  max_len: int) -> Path:
+    record = json.loads(path.read_text(encoding="utf-8"))
+    redacted = redact(record, strict=strict, max_len=max_len)
+    target = out or path.with_suffix(".redacted.json")
+    target.write_text(json.dumps(redacted, indent=2) + "\n",
+                      encoding="utf-8")
+    return target
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("input", help="capture file or directory")
+    parser.add_argument("--out", default=None,
+                        help="output path (single-file mode only)")
+    parser.add_argument("--strict", action="store_true",
+                        help="redact any string longer than --max-len")
+    parser.add_argument("--max-len", type=int, default=120,
+                        help="strict-mode length threshold (default 120)")
+    args = parser.parse_args(argv)
+
+    src = Path(args.input).expanduser()
+    if not src.exists():
+        sys.stderr.write(f"redact: input not found: {src}\n")
+        return 2
+
+    if src.is_dir():
+        if args.out:
+            sys.stderr.write("redact: --out is single-file only\n")
+            return 2
+        files = sorted(p for p in src.glob("*.json")
+                       if not p.name.endswith(".redacted.json"))
+        for path in files:
+            target = _process_file(path, out=None, strict=args.strict,
+                                   max_len=args.max_len)
+            print(f"redacted: {target}")
+        return 0
+
+    target = _process_file(src, out=Path(args.out) if args.out else None,
+                           strict=args.strict, max_len=args.max_len)
+    print(f"redacted: {target}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/schemas/skill.schema.json

@@ -37,6 +37,11 @@
         "pattern": "^[a-z][a-z0-9-]*$"
       }
     },
+    "tier": {
+      "type": "string",
+      "enum": ["senior"],
+      "description": "Optional tier marker. `senior` opts the skill into the Senior-Tier Required Structure check (Context-First lead, Related Skills, Proactive Triggers, Output Artifacts) per .agent-src.uncompressed/rules/skill-quality.md."
+    },
     "execution": {
       "type": "object",
       "additionalProperties": false,

package/scripts/skill_linter.py

@@ -99,6 +99,17 @@ TYPE_PATTERN = re.compile(r'^type:\s*"?(always|auto)"?\s*$', re.MULTILINE)
 SOURCE_PATTERN = re.compile(r'^source:\s*"?(package|project)"?\s*$', re.MULTILINE)
 STATUS_PATTERN = re.compile(r'^status:\s*"?(active|deprecated|superseded)"?\s*$', re.MULTILINE)
 REPLACED_BY_PATTERN = re.compile(r'^replaced_by:\s*"?([\w-]+)"?\s*$', re.MULTILINE)
+TIER_PATTERN = re.compile(r'^tier:\s*"?([\w-]+)"?\s*$', re.MULTILINE)
+
+# --- Senior-tier required-block patterns (skill-quality.md § Senior-Tier Required Structure) ---
+# Heading-only checks; detail-shape lives in skill-quality-mechanics.md.
+SENIOR_RELATED_SKILLS_PATTERN = re.compile(r"^##\s+Related Skills\s*$", re.MULTILINE)
+SENIOR_RELATED_WHEN_PATTERN = re.compile(r"\*\*WHEN to use this\*\*", re.IGNORECASE)
+SENIOR_RELATED_WHEN_NOT_PATTERN = re.compile(r"\*\*WHEN NOT to use this\*\*", re.IGNORECASE)
+SENIOR_PROACTIVE_PATTERN = re.compile(
+    r"^##\s+When the agent should load this\s*$", re.MULTILINE
+)
+SENIOR_OUTPUT_PATTERN = re.compile(r"^##\s+Output\s*$", re.MULTILINE)
 H1_PATTERN = re.compile(r"^# .+", re.MULTILINE)
 DOUBLE_BLANK_PATTERN = re.compile(r"\n{3,}")
 
@@ -415,6 +426,11 @@ def lint_skill(path: Path, text: str) -> LintResult:
         if execution is not None:
             issues.extend(lint_execution_metadata(execution))
 
+        # --- Senior-tier required-block check (skill-quality.md § Senior-Tier Required Structure) ---
+        tier_match = TIER_PATTERN.search(frontmatter)
+        if tier_match and tier_match.group(1) == "senior":
+            issues.extend(lint_senior_tier_blocks(text))
+
     procedure_block = find_procedure_block(text)
     if procedure_block is not None:
         if not procedure_block:
@@ -603,6 +619,57 @@ def parse_execution_block(frontmatter: str) -> Optional[dict]:
     return result
 
 
+def lint_senior_tier_blocks(text: str) -> List[Issue]:
+    """Validate the four required blocks for `tier: senior` skills.
+
+    Per .agent-src.uncompressed/rules/skill-quality.md § Senior-Tier
+    Required Structure: Context-First lead (description), Related Skills
+    (with WHEN / WHEN NOT lists), Proactive Triggers, Output Artifacts.
+
+    The Context-First lead is checked structurally via description length
+    + content; here we enforce the three section blocks and the WHEN /
+    WHEN NOT two-list pattern inside Related Skills.
+    """
+    issues: List[Issue] = []
+
+    if not SENIOR_RELATED_SKILLS_PATTERN.search(text):
+        issues.append(Issue(
+            "error",
+            "missing_senior_related_skills",
+            "Senior-tier skill missing `## Related Skills` block (skill-quality.md § Senior-Tier Required Structure)",
+        ))
+    else:
+        related_block = extract_section_block(text, "Related Skills") or ""
+        if not SENIOR_RELATED_WHEN_PATTERN.search(related_block):
+            issues.append(Issue(
+                "error",
+                "missing_senior_related_when",
+                "Senior-tier `## Related Skills` block missing `**WHEN to use this**` list",
+            ))
+        if not SENIOR_RELATED_WHEN_NOT_PATTERN.search(related_block):
+            issues.append(Issue(
+                "error",
+                "missing_senior_related_when_not",
+                "Senior-tier `## Related Skills` block missing `**WHEN NOT to use this**` list",
+            ))
+
+    if not SENIOR_PROACTIVE_PATTERN.search(text):
+        issues.append(Issue(
+            "error",
+            "missing_senior_proactive_triggers",
+            "Senior-tier skill missing `## When the agent should load this` block",
+        ))
+
+    if not SENIOR_OUTPUT_PATTERN.search(text):
+        issues.append(Issue(
+            "error",
+            "missing_senior_output_artifacts",
+            "Senior-tier skill missing `## Output` block declaring artifact name + shape",
+        ))
+
+    return issues
+
+
 def lint_execution_metadata(execution: dict) -> List[Issue]:
     """Validate the execution block of a skill."""
     issues: List[Issue] = []
@@ -1656,6 +1723,70 @@ def lint_governance(path: Path, text: str, artifact_type: str, repo_root: Path |
     return issues
 
 
+# --- Structural malice check (see road-to-suite-closure Phase 5) ---
+#
+# Five regex patterns scan skill / rule / command bodies for **structural**
+# (not semantic) malice. Findings surface as ``Issue("error",
+# "malice:<pattern>", "<line>:<matched>")`` so ``compute_exit_code`` can
+# emit exit code 3 (security-failure), distinct from 2 (build-failure).
+# Semantic checks (PII leakage, prompt injection) are deferred to v2.
+
+# (a) credential exfil — curl|wget piping ${TOKEN}/${KEY}/${SECRET}/...
+#     env vars or hitting ~/.aws/ ~/.ssh/ secrets.
+_MALICE_CRED_EXFIL = re.compile(
+    r"\b(?:curl|wget)\b[^\n]*"
+    r"(?:\$\{?[A-Z_]*(?:TOKEN|KEY|SECRET|PASSWORD|CREDENTIAL|API)[A-Z_]*\}?"
+    r"|~/\.(?:aws|ssh)/)"
+)
+# (b) arbitrary execution — eval/exec over a network-fetched payload, or
+#     `bash <(curl ...)` / `sh <(wget ...)` style remote-execution.
+_MALICE_REMOTE_EXEC = re.compile(
+    r"(?:\b(?:eval|exec)\s*\([^)]*(?:curl|wget|requests\.get|urllib)"
+    r"|\b(?:bash|sh|zsh)\s*<\s*\(\s*(?:curl|wget))"
+)
+# (c) force-push to a protected ref.
+_MALICE_FORCE_PUSH = re.compile(
+    r"\bgit\s+push\b[^\n]*--force(?:-with-lease)?\b[^\n]*"
+    r"\b(?:main|master|prod|production|release)\b"
+)
+# (d) world-readable secrets — chmod 0?[4567]xx on .pem/.key/.env files.
+_MALICE_CHMOD_SECRETS = re.compile(
+    r"\bchmod\s+0?[4567]\d{2}\s+[^\n]*\.(?:pem|key|env)\b"
+)
+# (e) unbounded subprocess shell injection — shell=True interpolating ${VAR}.
+_MALICE_SHELL_INJECT = re.compile(
+    r"\bsubprocess\.[A-Za-z_]+\s*\([^)]*shell\s*=\s*True[^)]*\$\{"
+)
+
+_MALICE_PATTERNS: list[tuple[str, re.Pattern[str]]] = [
+    ("cred_exfil", _MALICE_CRED_EXFIL),
+    ("remote_exec", _MALICE_REMOTE_EXEC),
+    ("force_push_protected", _MALICE_FORCE_PUSH),
+    ("chmod_secrets", _MALICE_CHMOD_SECRETS),
+    ("shell_injection", _MALICE_SHELL_INJECT),
+]
+
+
+def check_structural_malice(text: str) -> List[Issue]:
+    """Return one Issue per malice match. Empty list when clean.
+
+    Issue shape: ``Issue("error", f"malice:{name}", f"{line}:{matched}")``.
+    The ``format_text`` renderer special-cases the ``malice:`` code prefix
+    to emit ``<path>:<line>:malice:<pattern>:<matched>`` per Phase 5.2.
+    """
+    issues: List[Issue] = []
+    for lineno, raw in enumerate(text.splitlines(), start=1):
+        for name, pattern in _MALICE_PATTERNS:
+            match = pattern.search(raw)
+            if match:
+                issues.append(Issue(
+                    severity="error",
+                    code=f"malice:{name}",
+                    message=f"{lineno}:{match.group(0).strip()}",
+                ))
+    return issues
+
+
 # --- Output-schema check (see road-to-trigger-evals Phase 3.5) ---
 #
 # Skills that freeze an output shape (`refine-ticket`, `estimate-ticket`)
@@ -1865,11 +1996,36 @@ def lint_file(path: Path, repo_root: Path | None = None) -> LintResult:
             result.issues.extend(schema_issues)
             result.status = classify_status(result.issues)
 
+    # Post-processing: structural malice scan (errors). Skills, rules,
+    # and commands carry executable patterns; guidelines/personas are
+    # prose-only and skipped to keep noise low.
+    if artifact_type in ("skill", "rule", "command"):
+        malice_issues = check_structural_malice(text)
+        if malice_issues:
+            result.issues.extend(malice_issues)
+            result.status = classify_status(result.issues)
+
     return result
 
 
 def format_text(results: list[LintResult]) -> str:
     lines: list[str] = []
+    # Phase 5.2: malice findings render in the spec shape
+    # ``<path>:<line>:malice:<pattern>:<matched>`` ahead of the badge
+    # block so security-failures are grep-able from the top.
+    malice_total = 0
+    for result in results:
+        for issue in result.issues:
+            if issue.code.startswith("malice:"):
+                pattern_name = issue.code.split(":", 1)[1]
+                lineno, _, matched = issue.message.partition(":")
+                lines.append(
+                    f"{result.file}:{lineno}:malice:{pattern_name}:{matched}"
+                )
+                malice_total += 1
+    if malice_total:
+        lines.append("")
+
     for result in results:
         badge = {"pass": "[PASS]", "pass_with_warnings": "[WARN]", "fail": "[FAIL]"}[result.status]
         lines.append(f"{badge} {result.file} ({result.artifact_type})")
@@ -1888,7 +2044,8 @@ def format_text(results: list[LintResult]) -> str:
     fails = sum(1 for r in results if r.status == "fail")
     warns = sum(1 for r in results if r.status == "pass_with_warnings")
     passes = sum(1 for r in results if r.status == "pass")
-    lines.append(f"Summary: {passes} pass, {warns} warn, {fails} fail, {total} total")
+    suffix = f", {malice_total} malice" if malice_total else ""
+    lines.append(f"Summary: {passes} pass, {warns} warn, {fails} fail, {total} total{suffix}")
     return "\n".join(lines)
 
 
@@ -2087,6 +2244,11 @@ def check_duplication(root: Path) -> list[LintResult]:
 
 
 def compute_exit_code(results: list[LintResult], strict_warnings: bool) -> int:
+    # Phase 5.2: structural-malice findings emit exit code 3 (security-
+    # failure), distinct from 2 (build-failure) so CI surfaces can split.
+    for r in results:
+        if any(issue.code.startswith("malice:") for issue in r.issues):
+            return 3
     if any(r.status == "fail" for r in results):
         return 2
     if any(r.status == "pass_with_warnings" for r in results) and strict_warnings:

package/scripts/update_prices.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Refresh `.agent-prices.md` from the LiteLLM model-prices feed.
+"""Refresh `agents/.agent-prices.md` from the LiteLLM model-prices feed.
 
 Source: https://raw.githubusercontent.com/BerriAI/litellm/main/
         model_prices_and_context_window.json
@@ -9,7 +9,7 @@ Network failure or invalid response → fall back to
 always written. Stdlib only; no extra dependency.
 
 Usage:
-    python3 scripts/update_prices.py            # writes .agent-prices.md
+    python3 scripts/update_prices.py            # writes agents/.agent-prices.md
     python3 scripts/update_prices.py --check    # exit 1 if file is stale
 """
 
@@ -81,7 +81,7 @@ def _to_rows_from_litellm(payload: dict[str, dict[str, object]]) -> list[tuple[s
 
 
 def refresh(path: Path = PRICES_FILE) -> str:
-    """Write a fresh `.agent-prices.md`. Returns the source label used."""
+    """Write a fresh `agents/.agent-prices.md`. Returns the source label used."""
     payload = _fetch_litellm()
     if payload is not None:
         rows = _to_rows_from_litellm(payload)

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

@@ -1,126 +0,0 @@
----
-name: chat-history:checkpoint
-cluster: chat-history
-sub: checkpoint
-description: Append a phase-boundary entry to .agent-chat-history — CHECKPOINT fallback for platforms without a native hook (Augment IDE, Cursor pre-1.7, Cline non-Mac/Linux). ~1s.
-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

@@ -1,103 +0,0 @@
----
-name: chat-history:clear
-cluster: chat-history
-sub: 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),
-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`](../../docs/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-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
-- [`scripts/chat_history.py`](../../../scripts/chat_history.py) — helper API