@event4u/agent-config 1.19.0 → 1.21.0

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

@@ -1,124 +0,0 @@
----
-type: "auto"
-tier: "1"
-description: "First turn or reference to .agent-chat-history — detects ownership (match/returning/foreign/missing) and HOOK/ENGINE/CHECKPOINT/MANUAL path classification with numbered-options prompt"
-alwaysApply: false
-source: package
----
-
-<!-- cloud_safe: noop -->
-
-# Chat History — Ownership
-
-Owns gate 1 of the chat-history Iron Law: the first-turn handshake
-that decides whose `.agent-chat-history` file the current session is
-talking to. Cadence (gate 2) lives in [`chat-history-cadence`](chat-history-cadence.md);
-visibility (gate 3) lives in [`chat-history-visibility`](chat-history-visibility.md).
-File I/O is owned by [`scripts/chat_history.py`](../../../scripts/chat_history.py)
-— this rule says **when** to handshake, not how the file is structured.
-
-## Two paths — platform decides which Iron Law applies
-
-Population of `.agent-chat-history` is **structural** (platform-driven)
-on platforms with native lifecycle hooks, and **cooperative**
-(agent-driven) on platforms without. Both paths converge on the same
-JSONL schema; only the trigger differs. Per-platform classification
-lives in
-[`agents/contexts/chat-history-platform-hooks.md`](../../../agents/contexts/chat-history-platform-hooks.md).
-
-| Path | Platforms / Surfaces | Trigger | Agent's role |
-|---|---|---|---|
-| **HOOK** | Claude Code, Augment CLI, Cursor 1.7+, Cline non-Windows, Windsurf, Gemini CLI | Platform fires native lifecycle hooks → `./agent-config chat-history:hook --platform <name>` | Read-only — observe, do not duplicate appends |
-| **ENGINE** | `/implement-ticket`, `/work`, any flow driven by `scripts/work_engine/cli.py` | `work_engine` fires `turn-check` (before-dispatch), `append --type phase` (per successful step), `--type decision` (on-halt), `heartbeat` (after-dispatch) via the hook layer | Read-only during engine-driven turns — do not duplicate appends. See [`agents/contexts/work-engine-hooks.md`](../../../agents/contexts/work-engine-hooks.md) |
-| **CHECKPOINT** | Augment IDE plugin, Cursor < 1.7, Cline on Windows | Agent invokes `/chat-history-checkpoint` at phase boundaries | Cooperative — gates 1 + 2 + 3 are mandatory |
-| **MANUAL** | Cloud surfaces (Claude.ai Web, Skills API) | Rule is inert — see Cloud Behavior | None |
-
-Detect the path on first turn: read `chat_history.platform` from
-`.agent-settings.yml` if set, else fall back to `chat_history.path`
-(`hook` / `checkpoint` / `manual`). Missing both → assume CHECKPOINT
-(safest cooperative default; HOOK platforms install the platform
-config explicitly via `scripts/install.py`).
-
-## Iron Law — gate 1 (turn-check is the first tool call)
-
-```
-ON CHECKPOINT, turn-check IS THE FIRST TOOL CALL OF EVERY SESSION.
-ON HOOK, THE PLATFORM FIRES turn-check STRUCTURALLY — DO NOT DUPLICATE.
-ON ENGINE, work_engine FIRES turn-check BEFORE DISPATCH — DO NOT DUPLICATE.
-```
-
-CHECKPOINT path — run silently before any other tool call:
-
-```bash
-scripts/chat_history.py turn-check --first-user-msg "<first-user-msg>"
-```
-
-Exit codes: `0` = `ok`/`disabled` (proceed), `10` = `missing`
-(run `init --first-user-msg "..." --freq <freq>`), `11` = `foreign`
-(render Foreign-Prompt + stop), `12` = `returning` (render
-Returning-Prompt + stop). The script writes a one-line
-`ACTION REQUIRED:` hint to stderr on non-zero exits.
-
-## Activation & handshake
-
-Read `chat_history.*` from `.agent-settings.yml` **once per conversation**
-(first turn) and cache. `enabled: false` or section missing → all three
-chat-history rules are a **no-op** (do not read, write, or mention the
-file). Otherwise cache `frequency`, `max_size_kb`, `on_overflow`, and
-the **path** (HOOK / CHECKPOINT / MANUAL — see the table above).
-
-**HOOK path** — skip `turn-check` entirely. The platform's
-`SessionStart` hook already initialized the file; the agent's job is to
-read `status` once for context awareness (header preview, entry count)
-and otherwise leave I/O to the hook dispatcher. Foreign / Returning
-prompts still apply because hooks call into the same ownership state
-machine — when the dispatcher reports `foreign` or `returning` via
-exit code or stderr, render the corresponding prompt.
-
-**CHECKPOINT path** — run `turn-check` as the first tool call. State
-token branches to one of: `missing` → `init`, `ok` → continue,
-`foreign` → Foreign-Prompt, `returning` → Returning-Prompt.
-`/chat-history-checkpoint` is the recommended way to satisfy gate 2
-at phase boundaries (see [`chat-history-cadence`](chat-history-cadence.md)).
-
-In `foreign` and `returning`, **always read the file's current contents
-into the agent's working context before any write** — the user chose to
-log history for a reason; losing it silently is never acceptable. The
-legacy `state` subcommand still works for shell scripts; agents prefer
-`turn-check` (folds in `enabled` + distinct exit codes).
-
-## Foreign / Returning prompts — full mechanics
-
-When `turn-check` exits `11` (foreign) or `12` (returning), render the
-matching numbered-options block from
-[`agents/contexts/chat-history-handshake.md`](../../../agents/contexts/chat-history-handshake.md).
-That doc holds the prompt bodies, the option → script-call mapping
-(`adopt` / `init` / `prepend` / `reset`), the in-memory entries-list
-shape, free-text fallbacks, and the overflow handling per
-`on_overflow` (`rotate` / `compress`). Read it once on first foreign
-or returning event; cache the chosen option for the rest of the
-conversation.
-
-## What this rule does NOT do
-
-Display/reload/clear (`/chat-history*` commands). Auto-flip `enabled` or
-`on_overflow`. Run when `enabled: false`. Decide ownership
-heuristically — only `turn-check` / `state` does that. Double-write on
-HOOK platforms — when hooks fire structurally, the agent does **not**
-also call `turn-check`. Cadence (gate 2) and heartbeat (gate 3) are
-covered in their sibling rules.
-
-## Cloud Behavior
-
-On cloud surfaces (Claude.ai Web, Skills API) the rule is **fully inert** —
-no `.agent-chat-history`, no `scripts/`, no Iron Law gates, no foreign/returning
-prompts. Treat `chat_history.enabled` as `false`; persistence is a
-local-agent concern.
-
-## Interactions & references
-
-- Sibling rules: [`chat-history-cadence`](chat-history-cadence.md) (gate 2 — append timing) · [`chat-history-visibility`](chat-history-visibility.md) (gate 3 — heartbeat marker).
-- `ask-when-uncertain` + `user-interaction` — foreign/returning prompts use numbered options, one question per turn.
-- `language-and-tone` — prompt translated at runtime; `.md` stays English.
-- `onboarding-gate` — runs first; this rule activates only after it clears.
-- API: [`scripts/chat_history.py`](../../../scripts/chat_history.py). Commands: [`/chat-history`](../commands/chat-history.md), [`/chat-history-resume`](../commands/chat-history-resume.md), [`/chat-history-clear`](../commands/chat-history-clear.md), [`/chat-history-checkpoint`](../commands/chat-history-checkpoint.md). Settings: [`agent-settings`](../templates/agent-settings.md). Platform classification: [`agents/contexts/chat-history-platform-hooks.md`](../../../agents/contexts/chat-history-platform-hooks.md). Types: [`rule-type-governance`](rule-type-governance.md).

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

@@ -1,97 +0,0 @@
----
-type: "auto"
-tier: "mechanical-already"
-description: "Emitting the chat-history heartbeat marker — paste subprocess stdout verbatim or nothing, never type from memory, hybrid mode prints on drift only, slip handling per language-and-tone"
-alwaysApply: false
-source: package
----
-
-<!-- cloud_safe: noop -->
-
-# Chat History — Visibility
-
-Owns gate 3 of the chat-history Iron Law: the heartbeat marker that
-makes append-cadence drift visible. Ownership (gate 1) lives in
-[`chat-history-ownership`](chat-history-ownership.md); cadence (gate 2)
-lives in [`chat-history-cadence`](chat-history-cadence.md). File I/O is
-owned by [`scripts/chat_history.py`](../../../scripts/chat_history.py).
-
-## Iron Law — gate 3 (heartbeat is subprocess stdout, not memory)
-
-```
-HEARTBEAT IS THE SCRIPT OUTPUT OF THE CURRENT TURN, VERBATIM, OR NOTHING.
-NEVER TYPE THE LINE FROM MEMORY. NEVER REUSE THE PRIOR TURN'S MARKER.
-EMPTY STDOUT → NO MARKER LINE.
-```
-
-Run silently before emitting the final reply:
-
-```bash
-scripts/chat_history.py heartbeat --first-user-msg "<first-user-msg>"
-```
-
-Stdout is **at most** one line, e.g.
-`📒 chat-history: ok · 9 entries · per_phase · last 30s ago`. Non-empty →
-paste **verbatim** as the last line of the reply. Empty → emit nothing.
-Always exits 0 — observability, not a gate.
-
-## Visibility modes — `chat_history.heartbeat`
-
-| Mode | When marker prints | Token cost |
-|---|---|---|
-| `on` | every reply (legacy) | ~20 tokens / reply |
-| `off` | never — full silence | 0 |
-| `hybrid` *(default)* | drift states only (`missing`/`foreign`/`returning`) | 0 in normal flow, ~20 on drift |
-
-`hybrid` ships zero tokens when healthy, loud on ownership drift. YAML 1.1
-booleanizes bare `on`/`off`; the reader coerces both back, so
-`heartbeat: on` works unquoted.
-
-## Memory-typing the marker — rule violation, not a slip
-
-Format is memorizable; counts and timestamps are not. A typed-from-
-memory line shows stale entries and a healthy-looking `ok` while the
-file is silently behind — observability collapses, invisible until
-`status` is checked. Heartbeat is the script output of the **current
-turn**, verbatim, or nothing.
-
-**Self-check before send — MANDATORY.** (1) Did `heartbeat` run on
-this turn? (2) Is the line byte-identical to that subprocess stdout?
-(3) Empty stdout → no marker line. Any "no" → drop it.
-
-**Slip handling.** Stale marker called out → acknowledge once in the
-user's language; run `status`; on CHECKPOINT call `append` for
-missed phase-boundaries (see [`chat-history-cadence`](chat-history-cadence.md));
-run a real `heartbeat`; paste stdout verbatim or nothing. Don't promise
-"from now on" — only behaviour proves compliance (mirrors
-`language-and-tone` § slip handling).
-
-## Path-specific behavior
-
-Heartbeat (gate 3) stays useful for visibility on **every** path —
-HOOK, ENGINE, CHECKPOINT — because the marker reports the file's
-state, not the agent's intent. On HOOK and ENGINE paths the agent
-still emits the marker even though it didn't fire `turn-check` or
-`append` itself: the marker is read-only observability over whatever
-the platform / engine wrote.
-
-## What this rule does NOT do
-
-Manage ownership decisions — those live in [`chat-history-ownership`](chat-history-ownership.md).
-Manage append timing — that lives in [`chat-history-cadence`](chat-history-cadence.md).
-Auto-decide visibility mode — `chat_history.heartbeat` is the only
-trigger. Insert decoration: the marker is functional output per
-[`direct-answers`](direct-answers.md) emoji whitelist, not a status
-badge.
-
-## Cloud Behavior
-
-On cloud surfaces (Claude.ai Web, Skills API) heartbeat is **inert** —
-no marker line, no `scripts/`. Treat `chat_history.enabled` as `false`.
-
-## Interactions & references
-
-- Sibling rules: [`chat-history-ownership`](chat-history-ownership.md) (gate 1 — turn-check) · [`chat-history-cadence`](chat-history-cadence.md) (gate 2 — append).
-- `direct-answers` — emoji whitelist permits the `📒` marker as functional output, not decoration.
-- `language-and-tone` § slip handling — stale-marker acknowledgement.
-- API: [`scripts/chat_history.py`](../../../scripts/chat_history.py) `heartbeat` and `status` subcommands. Settings: [`agent-settings`](../templates/agent-settings.md) `chat_history.heartbeat`.

package/.agent-src/templates/scripts/work_engine/hooks/builtin/chat_history_heartbeat.py

@@ -1,50 +0,0 @@
-"""``ChatHistoryHeartbeatHook`` — visibility marker before save.
-
-Fires on ``before_save``. Runs ``chat_history.py heartbeat`` and,
-if the script emits a marker line, threads it onto ``state.report``
-so the agent's reply naturally carries the heartbeat without manual
-copy/paste.
-
-Why ``before_save`` and not ``after_dispatch``: the marker must land
-in the report that gets persisted. ``cli._sync_back`` runs between
-``after_dispatch`` and ``before_save`` and reassigns
-``work.report = delivery.report`` — a marker written on
-``after_dispatch`` would be overwritten before ``_save``. Firing on
-``before_save`` runs after the sync, so the marker survives.
-"""
-from __future__ import annotations
-
-from ..context import HookContext
-from ..events import HookEvent
-from ..exceptions import HookError
-from ..registry import HookRegistry
-from ._chat_history_base import EXIT_OK, _ChatHistoryHookBase
-
-
-class ChatHistoryHeartbeatHook(_ChatHistoryHookBase):
-    """Run heartbeat before save; thread marker into ``state.report``."""
-
-    def register(self, registry: HookRegistry) -> None:
-        registry.register(HookEvent.BEFORE_SAVE, self._on_before_save)
-
-    def _on_before_save(self, ctx: HookContext) -> None:
-        msg = self._resolve_msg(ctx)
-        proc = self._invoke("heartbeat", "--first-user-msg", msg)
-        if proc.returncode != EXIT_OK:
-            raise HookError(
-                f"chat-history heartbeat failed (exit {proc.returncode})"
-            )
-        marker = (proc.stdout or "").strip()
-        if not marker or ctx.work is None:
-            return
-        existing = getattr(ctx.work, "report", "") or ""
-        if marker in existing:
-            return
-        sep = "\n\n" if existing else ""
-        try:
-            ctx.work.report = f"{existing}{sep}{marker}"
-        except AttributeError:
-            raise HookError("chat-history heartbeat: state.report not writable")
-
-
-__all__ = ["ChatHistoryHeartbeatHook"]

package/.agent-src/templates/scripts/work_engine/hooks/builtin/chat_history_turn_check.py

@@ -1,49 +0,0 @@
-"""``ChatHistoryTurnCheckHook`` — guards engine-driven turns.
-
-Fires on ``before_dispatch``; classifies the chat-history file via
-``scripts/chat_history.py turn-check``:
-
-- exit 0 (``ok``)        → continue
-- exit 10 (``missing``)  → continue (auto-init handled by chat_history.py)
-- exit 11 (``foreign``)  → raise :class:`HookHalt` so CLI exits 2
-- exit 12 (``returning``)→ raise :class:`HookHalt` so CLI exits 2
-- any other exit         → raise :class:`HookError` (warn, continue)
-"""
-from __future__ import annotations
-
-from ..context import HookContext
-from ..events import HookEvent
-from ..exceptions import HookError, HookHalt
-from ..registry import HookRegistry
-from ._chat_history_base import (
-    EXIT_FOREIGN,
-    EXIT_MISSING,
-    EXIT_OK,
-    EXIT_RETURNING,
-    _ChatHistoryHookBase,
-)
-
-
-class ChatHistoryTurnCheckHook(_ChatHistoryHookBase):
-    """Run ``turn-check`` at the start of dispatch; halt on drift."""
-
-    def register(self, registry: HookRegistry) -> None:
-        registry.register(HookEvent.BEFORE_DISPATCH, self._on_before_dispatch)
-
-    def _on_before_dispatch(self, ctx: HookContext) -> None:
-        msg = self._resolve_msg(ctx)
-        result = self._invoke("turn-check", "--first-user-msg", msg)
-        code = result.returncode
-        if code in (EXIT_OK, EXIT_MISSING):
-            return
-        if code in (EXIT_FOREIGN, EXIT_RETURNING):
-            text = (result.stderr or result.stdout or "").strip()
-            reason = "foreign" if code == EXIT_FOREIGN else "returning"
-            surface = [line for line in text.splitlines() if line] or [
-                f"chat-history turn-check: {reason}",
-            ]
-            raise HookHalt(f"chat_history_turn_check_{reason}", surface=surface)
-        raise HookError(f"chat-history turn-check failed (exit {code})")
-
-
-__all__ = ["ChatHistoryTurnCheckHook"]

package/scripts/check_phase_coupling.py

@@ -1,148 +0,0 @@
-#!/usr/bin/env python3
-"""Phase 6 → Phase 2B coupling guard (Phase 0.3.3).
-
-Re-runs the audit recorded in `agents/roadmaps/phase6-2b-coupling.md`
-on every CI run. Fails the build if any of the 13 Phase-2B target
-rules introduces a reference to one of the three Phase-6-owned rules
-(`chat-history-cadence`, `chat-history-ownership`,
-`chat-history-visibility`) — by rule name, `load_context:` entry, or
-body link / cite.
-
-Excluded from the coupling probe (separate infrastructure, not
-reshaped by Phase 6):
-
-- The CLI dispatcher subcommand `./agent-config chat-history:hook`
-  and any other `chat-history:*` colon-suffix command surface.
-
-Exit codes: 0 = decoupling intact, 1 = coupling detected,
-3 = internal error (target rule missing, unreadable file).
-"""
-
-from __future__ import annotations
-
-import argparse
-import re
-import sys
-from pathlib import Path
-
-REPO_ROOT = Path(__file__).resolve().parents[1]
-SRC_RULES = REPO_ROOT / ".agent-src.uncompressed" / "rules"
-COMP_RULES = REPO_ROOT / ".agent-src" / "rules"
-
-# Phase 2B priority list — see road-to-structural-optimization.md § Phase 2 → 2B.
-TARGET_RULES: tuple[str, ...] = (
-    "roadmap-progress-sync",
-    "user-interaction",
-    "augment-source-of-truth",
-    "command-suggestion-policy",
-    "artifact-engagement-recording",
-    "review-routing-awareness",
-    "autonomous-execution",
-    "docs-sync",
-    "cli-output-handling",
-    "augment-portability",
-    "ui-audit-gate",
-    "skill-quality",
-    "package-ci-checks",
-)
-
-# Phase 6 owns these three rule names. Match must be a *rule reference*,
-# not a *dispatcher reference* (chat-history:hook etc).
-PHASE6_RULES: tuple[str, ...] = (
-    "chat-history-cadence",
-    "chat-history-ownership",
-    "chat-history-visibility",
-)
-
-# Rule-reference pattern: rule name not immediately followed by `:` (which
-# would mark it as a CLI subcommand like `chat-history:hook`). Allows
-# trailing word-boundary characters typical of Markdown / YAML contexts.
-_RULE_REF_RE = re.compile(
-    r"\bchat-history-(?:cadence|ownership|visibility)\b(?!:)"
-)
-
-
-def _scan(file: Path) -> list[tuple[int, str]]:
-    """Return [(line_no, line)] of rule-reference matches in `file`."""
-    if not file.is_file():
-        return []
-    hits: list[tuple[int, str]] = []
-    for i, line in enumerate(file.read_text(encoding="utf-8").splitlines(), 1):
-        if _RULE_REF_RE.search(line):
-            hits.append((i, line.strip()))
-    return hits
-
-
-def _check_surface(label: str, base: Path) -> tuple[int, list[str]]:
-    """Scan `base` for all 13 Phase-2B targets; return (#hits, formatted lines)."""
-    if not base.is_dir():
-        return 0, [f"❌  {label} dir missing: {base}"]
-    out: list[str] = []
-    total = 0
-    for rule in TARGET_RULES:
-        path = base / f"{rule}.md"
-        if not path.is_file():
-            return 0, [f"❌  target rule missing: {path}"]
-        hits = _scan(path)
-        if not hits:
-            continue
-        total += len(hits)
-        for line_no, line in hits:
-            out.append(f"  {label}/{rule}.md:{line_no}  {line}")
-    return total, out
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument(
-        "--quiet",
-        action="store_true",
-        help="suppress the per-rule breakdown when no coupling found",
-    )
-    args = parser.parse_args()
-
-    hits_src, lines_src = _check_surface("uncompressed", SRC_RULES)
-    if any(line.startswith("❌") for line in lines_src):
-        for line in lines_src:
-            print(line, file=sys.stderr)
-        return 3
-    hits_comp, lines_comp = _check_surface("compressed", COMP_RULES)
-    if any(line.startswith("❌") for line in lines_comp):
-        for line in lines_comp:
-            print(line, file=sys.stderr)
-        return 3
-
-    total = hits_src + hits_comp
-
-    if total == 0:
-        if not args.quiet:
-            print(
-                f"✅  Phase 6 → 2B decoupling intact: 0 rule-references "
-                f"across {len(TARGET_RULES)} Phase-2B targets "
-                f"(uncompressed + compressed surfaces)."
-            )
-            print(
-                "      probe: rule names, load_context: entries, body "
-                "link/cite — dispatcher subcommand chat-history:hook "
-                "excluded by design."
-            )
-        return 0
-
-    print(
-        f"❌  Phase 6 → 2B coupling detected: {total} rule-reference(s) "
-        f"across Phase-2B targets:"
-    )
-    for line in lines_src + lines_comp:
-        print(line)
-    print(
-        "\n      Action: see agents/roadmaps/phase6-2b-coupling.md. "
-        "Either drop the new reference, migrate it to the dispatcher "
-        "(chat-history:hook), or trigger the >0-hits branch in 0.3.2 "
-        "(Phase 6 ships call-signature contract before Phase 2B "
-        "touches the coupled rule)."
-    )
-    return 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())