@event4u/agent-config 1.13.0 → 1.15.0

package/scripts/sync_agent_settings.py

@@ -47,29 +47,48 @@ DEFAULT_PROFILE_DIR = Path(__file__).resolve().parent.parent / "config" / "profi
 
 
 def _flatten(data: dict, prefix: str = "") -> dict[str, object]:
-    """Flatten nested dicts to dotted keys — one level of nesting supported."""
+    """Flatten nested dicts to dotted keys — recurses to all leaves.
+
+    Lists, scalars, and ``None`` are leaves. Dicts are walked and their
+    keys folded into the dotted path.
+    """
     out: dict[str, object] = {}
     for key, value in data.items():
         path = f"{prefix}{key}"
         if isinstance(value, dict):
-            for sub_key, sub_val in value.items():
-                out[f"{path}.{sub_key}"] = sub_val
+            out.update(_flatten(value, prefix=f"{path}."))
         else:
             out[path] = value
     return out
 
 
-def _as_scalar_text(value: object) -> str:
-    """Normalize a parsed YAML value to the raw string form expected by
-    `install._replace_template_value` — which re-quotes via `_yaml_scalar`
-    internally, so we must pass the *unquoted* payload here."""
+def _as_yaml_value(value: object) -> str | None:
+    """Format *value* as an inline-YAML literal.
+
+    Returns ``None`` when the value cannot be safely represented as a
+    scalar / flow-style sequence (e.g. unsupported types). Callers
+    must skip those keys so the template default sticks instead of
+    producing malformed YAML.
+    """
     if isinstance(value, bool):
         return "true" if value else "false"
     if isinstance(value, int):
         return str(value)
+    if isinstance(value, float):
+        return repr(value)
     if value is None:
-        return ""
-    return str(value)
+        return "~"
+    if isinstance(value, list):
+        items: list[str] = []
+        for item in value:
+            rendered = _as_yaml_value(item)
+            if rendered is None:
+                return None
+            items.append(rendered)
+        return "[" + ", ".join(items) + "]"
+    if isinstance(value, str):
+        return _install._yaml_scalar(value)
+    return None
 
 
 def _template_keys(template_body: str) -> set[str]:
@@ -81,10 +100,18 @@ def _template_keys(template_body: str) -> set[str]:
 
 
 def _apply_user_values(template_body: str, user_flat: dict[str, object]) -> str:
-    """Overlay every known user value on the rendered template body."""
+    """Overlay every known user value on the rendered template body.
+
+    Keys whose value cannot be rendered inline (see :func:`_as_yaml_value`)
+    are skipped so the template default survives instead of corrupting
+    the file.
+    """
     body = template_body
     for dotted, value in user_flat.items():
-        body = _install._replace_template_value(body, dotted, _as_scalar_text(value))
+        rendered = _as_yaml_value(value)
+        if rendered is None:
+            continue
+        body = _install._replace_template_value_raw(body, dotted, rendered)
     return body
 
 
@@ -100,7 +127,10 @@ def _append_unknown(body: str, user_flat: dict[str, object], known: set[str]) ->
         "_user:",
     ]
     for key in unknown:
-        lines.append(f"  {key}: {_install._yaml_scalar(_as_scalar_text(user_flat[key]))}")
+        rendered = _as_yaml_value(user_flat[key])
+        if rendered is None:
+            continue
+        lines.append(f"  {key}: {rendered}")
     suffix = "\n".join(lines) + "\n"
     return body + (suffix if body.endswith("\n") else "\n" + suffix)
 

package/scripts/update_counts.py

@@ -72,6 +72,16 @@ TARGETS: list[tuple[str, list[tuple[str, str]]]] = [
             (r"(Browse all )(\d+)( commands\])", "commands"),
         ],
     ),
+    (
+        "docs/architecture.md",
+        [
+            # "What's inside" table: | **Skills** | NNN | … |
+            (r"(\| \*\*Skills\*\* \| )(\d+)( \|)", "skills"),
+            (r"(\| \*\*Rules\*\* \| )(\d+)( \|)", "rules"),
+            (r"(\| \*\*Commands\*\* \| )(\d+)( \|)", "commands"),
+            (r"(\| \*\*Guidelines\*\* \| )(\d+)( \|)", "guidelines"),
+        ],
+    ),
     # Note: ``agents/roadmaps/road-to-stronger-skills.md`` was previously
     # tracked here with a living ``baseline N as of`` pattern. The roadmap
     # was moved to ``skipped/`` on 2026-04-23 (Q35 superseded), so its

package/templates/consumer-settings/augment-cli-hooks.json

@@ -0,0 +1,54 @@
+{
+  "// Instructions": "OPTIONAL: merge this into ~/.augment/settings.json (user-scope, NOT project-scope) to wire chat-history hooks for the Augment CLI.",
+  "// Why user-scope": "The Augment CLI reads hooks from ~/.augment/settings.json (per https://docs.augmentcode.com/cli/hooks.md). Project-scoped .augment/settings.json belongs to the IDE plugin, which has no documented hook surface as of 2026-04-30.",
+  "// IDE plugin": "Use the /chat-history-checkpoint command at phase boundaries instead — see rules/chat-history.md.",
+  "// Wrapper": "The command assumes the project-root ./agent-config wrapper is on PATH or invoked with a project-relative cwd. Adjust to absolute paths if your shell does not chdir into the project.",
+
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./agent-config chat-history:hook --platform augment",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./agent-config chat-history:hook --platform augment",
+            "timeout": 3000
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./agent-config chat-history:hook --platform augment",
+            "timeout": 3000
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./agent-config chat-history:hook --platform augment",
+            "timeout": 3000
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/consumer-settings/claude-settings.json

@@ -1,9 +1,63 @@
 {
-  "// Instructions": "Copy this into your project's .claude/settings.json to auto-enable the agent-config plugin.",
+  "// Instructions": "Copy this into your project's .claude/settings.json to auto-enable the agent-config plugin and chat-history hooks.",
   "// After setup": "Claude Code will load the plugin when the marketplace is installed.",
   "// Install marketplace": "Run: claude plugin marketplace add event4u-app/agent-config",
+  "// Hooks": "Hooks call ./agent-config (the wrapper installed at the project root) which dispatches to scripts/chat_history.py hook-dispatch. They are no-ops when chat_history.enabled is false in .agent-settings.yml.",
 
   "enabledPlugins": {
     "agent-conf@event4u": true
+  },
+
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./agent-config chat-history:hook --platform claude"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./agent-config chat-history:hook --platform claude"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./agent-config chat-history:hook --platform claude"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./agent-config chat-history:hook --platform claude"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./agent-config chat-history:hook --platform claude"
+          }
+        ]
+      }
+    ]
   }
 }

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

@@ -1,171 +0,0 @@
----
-type: "always"
-description: "Persist the conversation to .agent-chat-history for crash recovery — read on first turn, detect match/returning/foreign/missing, append on progress, honor per-profile frequency and overflow settings"
-alwaysApply: true
-source: package
----
-
-# Chat History
-
-Persists the conversation to `.agent-chat-history` (JSONL, project root,
-git-ignored) so a crashed or switched agent session can be resumed. File
-I/O is owned by [`scripts/chat_history.py`](../../../scripts/chat_history.py)
-— this rule says **when** to call it, not how the file is structured.
-
-## Activation
-
-Read `chat_history.*` from `.agent-settings.yml` **once per conversation**
-(first turn). Cache the values.
-
-- `chat_history.enabled: false` **or** section missing → rule is a **no-op**
-  for the whole conversation. Do not read, write, or mention the file.
-- `chat_history.enabled: true` → cache `frequency`, `max_size_kb`,
-  `on_overflow` and proceed to the first-turn handshake.
-
-## First-turn handshake — four states
-
-Before executing the user's request, run:
-
-```bash
-scripts/chat_history.py state --first-user-msg "<msg>"
-```
-
-It prints exactly one of `match` | `returning` | `foreign` | `missing`.
-Branch:
-
-- `missing` → `init --first-user-msg "<msg>" --freq <frequency>`. Proceed
-  silently.
-- `match` → this chat already owns the file. Continue appending as cached.
-- `foreign` → a different session's file. Show **Foreign-Prompt** below.
-- `returning` → this chat once owned the file but another session took
-  over. Show **Returning-Prompt** below.
-
-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.
-
-## Foreign-Prompt — new chat finds existing history
-
-Trigger: `state == foreign` **and** `status.entries >= 1`.
-
-```
-> 📒 Found chat history from an unknown session.
->
-> Header fingerprint: <short-hash-A>
-> Current session:    <short-hash-B>
-> Entries on file:    <N>   Age: <age>
->
-> 1. Resume — adopt this file, load entries as context, keep appending here
-> 2. New start — archive to .agent-chat-history.bak, init fresh
-> 3. Ignore — leave the file untouched, disable logging for this session
-```
-
-- `1` → `adopt --first-user-msg "<msg>"` (the old fp lands in
-  `former_fps` automatically). Read entries into context, then append
-  normally.
-- `2` → rename to `.agent-chat-history.bak`, then
-  `init --first-user-msg "<msg>" --freq <frequency>`.
-- `3` → logging disabled for this conversation; do not touch the file,
-  do not edit settings.
-
-Free-text replies ("weiter", "skip it") count as `3`.
-
-## Returning-Prompt — old chat comes back
-
-Trigger: `state == returning`. The file exists, its current owner is a
-different session, but this chat's fingerprint is in `former_fps`. The
-agent still has its own in-memory history of the turns it logged before
-the hand-off.
-
-```
-> 📒 Welcome back. This chat once owned the history file; another
-> session has written to it since.
->
-> On-file entries:    <N>   Size: <X> KB   (now includes <M> foreign entries)
->
-> (All three options read the on-disk entries into context first.)
->
-> 1. Merge — my in-memory history first, the foreign entries after,
->    overwrite the file with the combined body
-> 2. Replace — wipe the foreign entries, rewrite the file with my
->    in-memory history only
-> 3. Continue — leave the file as-is; only new entries from now on
-```
-
-- `1` (Merge) → build the in-memory entries list (see below), call
-  `prepend --entries-json '<list>'`, then `adopt --first-user-msg "<msg>"`.
-- `2` (Replace) → build the in-memory list,
-  `reset --first-user-msg "<msg>" --freq <frequency> --entries-json '<list>'`.
-- `3` (Continue) → `adopt --first-user-msg "<msg>"`, then append normally.
-
-Free-text replies count as `3`.
-
-## Building the in-memory entries list (Merge / Replace)
-
-The agent reconstructs its own conversation as a JSON array, one entry
-per turn boundary. Keep it compact:
-
-- One `{"t":"user","text":"<preview>","ts":"<iso>"}` per user message.
-- One `{"t":"agent","text":"<preview>","ts":"<iso>"}` per agent reply.
-- `text` is a preview — flatten whitespace, cap at ~200 characters. This
-  is context, not a transcript.
-- Timestamps in ISO-8601 UTC. If the agent does not have exact times,
-  use the current time for all entries; order is what matters.
-- Do **not** include tool-call payloads, file contents, or secrets.
-
-If the list is large (>30 KB), pass it via stdin:
-`reset ... --entries-stdin <<< '<list>'`.
-
-## Append cadence — from `frequency`
-
-Every append goes through `scripts/chat_history.py append --type <t>
---json '<obj>'`. Never write the file directly.
-
-- `per_turn` — one entry at the end of every agent turn.
-- `per_phase` — at phase boundaries (user question, agent answer,
-  decision, completion of a task-list item).
-- `per_tool` — after each tool-call sequence.
-
-Entry types: `user`, `agent`, `tool`, `decision`, `phase`. Prefer `phase`
-over `agent` when the entry marks a boundary.
-
-## Overflow — from `on_overflow`
-
-When the helper reports file size > `max_size_kb`:
-
-- `rotate` → `rotate --mode rotate --max-kb <n>`. Drops oldest entries;
-  silent and cheap.
-- `compress` → `rotate --mode compress --max-kb <n>`. Marks the file for
-  summarization; the **next** turn writes the summary for the dropped
-  range. Do not block the current turn on this.
-
-After Merge or Replace rewrites, run the overflow check once — the new
-body may exceed the budget.
-
-The setting is stable for the session; never mix modes.
-
-## What this rule does NOT do
-
-- Display, reload, or clear the log — that is `/chat-history`,
-  `/chat-history-resume`, `/chat-history-clear`.
-- Auto-flip `enabled` or `on_overflow` in settings.
-- Run when `enabled: false`. No silent logging. No telemetry.
-- Decide ownership heuristically. Only the `state` helper does that.
-
-## Interactions
-
-- `ask-when-uncertain` + `user-interaction` — foreign/returning prompts
-  use numbered options, one question per turn.
-- `language-and-tone` — prompt translated at runtime; `.md` stays English.
-- `onboarding-gate` — runs first; this rule activates only after it clears.
-- `token-efficiency` — never load the full log into context from this
-  rule; use `status` for metadata, `read --last N` for a tail.
-
-## See also
-
-- [`scripts/chat_history.py`](../../../scripts/chat_history.py) — file API
-- [`/chat-history`](../commands/chat-history.md) — status inspection
-- [`/chat-history-resume`](../commands/chat-history-resume.md) — adopt + load
-- [`/chat-history-clear`](../commands/chat-history-clear.md) — wipe
-- [`agent-settings` template](../templates/agent-settings.md) — `chat_history.*` reference
-- [`rule-type-governance`](rule-type-governance.md) — why this is `always`

package/.agent-src/templates/scripts/implement_ticket/cli.py

@@ -1,171 +0,0 @@
-"""Command-line entry point for ``/implement-ticket``.
-
-Minimal Option-A transport: the script loads a persisted
-``DeliveryState`` (or builds one from a ticket file), runs the
-dispatcher once, writes the updated state back, and prints either
-the delivery report (on SUCCESS) or the halt surface — directive
-plus numbered questions — on BLOCKED/PARTIAL.
-
-The script never edits code, runs tests, or opens pull requests.
-All of that is delegated to the agent via ``@agent-directive:``
-markers per
-``agents/contexts/implement-ticket-flow.md#agent-directives``. The
-agent executes the directive, writes the resulting slice back to
-the state file, and re-invokes this script to resume.
-
-Exit codes:
-
-- ``0`` — flow reached SUCCESS; ``state.report`` printed.
-- ``1`` — flow halted BLOCKED; halt surface printed on stdout, the
-  state file carries the updated ``outcomes`` and ``questions`` so
-  the agent can resume.
-- ``2`` — argument or I/O error (ticket file missing, JSON parse
-  failure, etc.). The state file is *not* written in this case.
-"""
-from __future__ import annotations
-
-import argparse
-import json
-import sys
-from dataclasses import asdict
-from pathlib import Path
-from typing import Sequence
-
-from .delivery_state import DeliveryState, Outcome
-from .dispatcher import dispatch
-from .steps import analyze, implement, memory, plan, refine, report, verify
-from .steps import test as test_step
-
-DEFAULT_STATE_FILE = Path(".implement-ticket-state.json")
-"""State file used when ``--state-file`` is not passed."""
-
-_STEPS = {
-    "refine": refine.run,
-    "memory": memory.run,
-    "analyze": analyze.run,
-    "plan": plan.run,
-    "implement": implement.run,
-    "test": test_step.run,
-    "verify": verify.run,
-    "report": report.run,
-}
-
-
-def main(argv: Sequence[str] | None = None) -> int:
-    """Run one dispatch cycle against the persisted state.
-
-    ``argv`` is taken as-is; pass ``None`` to fall back to
-    ``sys.argv[1:]`` (the usual entry-point contract).
-    """
-    parser = _build_parser()
-    args = parser.parse_args(argv)
-    state_file: Path = args.state_file
-
-    try:
-        state = _load_or_build(state_file, args)
-    except _CLIError as exc:
-        print(f"error: {exc}", file=sys.stderr)
-        return 2
-
-    final, halting = dispatch(state, _STEPS)
-    _save(state_file, state)
-    _emit(state, final, halting)
-    return 0 if final is Outcome.SUCCESS else 1
-
-
-def _build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(
-        prog="implement-ticket",
-        description="Run one dispatch cycle of the /implement-ticket flow.",
-    )
-    parser.add_argument(
-        "--state-file",
-        type=Path,
-        default=DEFAULT_STATE_FILE,
-        help=f"Path to persisted state JSON (default: {DEFAULT_STATE_FILE}).",
-    )
-    parser.add_argument(
-        "--ticket-file",
-        type=Path,
-        default=None,
-        help="JSON file carrying the ticket payload; used only when the "
-        "state file does not exist yet.",
-    )
-    parser.add_argument(
-        "--persona",
-        type=str,
-        default=None,
-        help="Persona name (senior-engineer | qa | advisory). Only honoured "
-        "when the state file does not exist yet; ignored on resume so a "
-        "mid-flight persona switch cannot silently change behaviour.",
-    )
-    return parser
-
-
-def _load_or_build(state_file: Path, args: argparse.Namespace) -> DeliveryState:
-    """Return the state to dispatch against — either loaded or freshly built."""
-    if state_file.exists():
-        return _load(state_file)
-    if args.ticket_file is None:
-        raise _CLIError(
-            f"No state file at {state_file} and no --ticket-file given; "
-            "cannot build an initial DeliveryState.",
-        )
-    ticket = _read_json(args.ticket_file)
-    if not isinstance(ticket, dict):
-        raise _CLIError(
-            f"--ticket-file must carry a JSON object; got {type(ticket).__name__}.",
-        )
-    kwargs: dict = {"ticket": ticket}
-    if args.persona:
-        kwargs["persona"] = args.persona
-    return DeliveryState(**kwargs)
-
-
-def _load(state_file: Path) -> DeliveryState:
-    data = _read_json(state_file)
-    if not isinstance(data, dict):
-        raise _CLIError(
-            f"State file {state_file} must carry a JSON object; "
-            f"got {type(data).__name__}.",
-        )
-    try:
-        return DeliveryState(**data)
-    except TypeError as exc:
-        raise _CLIError(f"State file shape is invalid: {exc}") from exc
-
-
-def _save(state_file: Path, state: DeliveryState) -> None:
-    """Persist ``state`` as pretty JSON for diffing + human inspection."""
-    state_file.parent.mkdir(parents=True, exist_ok=True)
-    state_file.write_text(
-        json.dumps(asdict(state), indent=2, ensure_ascii=False) + "\n",
-        encoding="utf-8",
-    )
-
-
-def _read_json(path: Path):
-    try:
-        raw = path.read_text(encoding="utf-8")
-    except OSError as exc:
-        raise _CLIError(f"Cannot read {path}: {exc}") from exc
-    try:
-        return json.loads(raw)
-    except json.JSONDecodeError as exc:
-        raise _CLIError(f"Invalid JSON in {path}: {exc}") from exc
-
-
-def _emit(state: DeliveryState, final: Outcome, halting: str | None) -> None:
-    if final is Outcome.SUCCESS:
-        print(state.report)
-        return
-    print(f"[halt] outcome={final.value} step={halting or '(none)'}")
-    for line in state.questions:
-        print(line)
-
-
-class _CLIError(Exception):
-    """Raised on configuration or I/O problems. Converted to exit code 2."""
-
-
-__all__ = ["DEFAULT_STATE_FILE", "main"]