@event4u/agent-config 1.12.0 → 1.14.0

package/scripts/skill_linter.py

@@ -772,6 +772,70 @@ def lint_rule(path: Path, text: str) -> LintResult:
     )
 
 
+def _lint_command_suggestion_block(text: str) -> List[Issue]:
+    """Validate the suggestion frontmatter block (road-to-context-aware-command-suggestion).
+
+    Schema-shape is enforced upstream by validate_frontmatter; this function adds the
+    *conditional* content rules that JSON Schema (Draft-07 subset used here) cannot
+    express: trigger fields must be non-empty when eligible, rationale must be
+    non-empty when ineligible.
+    """
+    issues: List[Issue] = []
+    data, _offset = parse_frontmatter_for_schema(text)
+    if data is None:
+        return issues
+    suggestion = data.get("suggestion")
+    if suggestion is None:
+        issues.append(Issue(
+            "warning", "missing_suggestion_block",
+            "Command frontmatter is missing the 'suggestion' block — required by "
+            "road-to-context-aware-command-suggestion Phase 2.",
+        ))
+        return issues
+    if not isinstance(suggestion, dict):
+        issues.append(Issue("error", "invalid_suggestion_block", "'suggestion' must be a mapping"))
+        return issues
+    eligible = suggestion.get("eligible")
+    if eligible is True:
+        td = (suggestion.get("trigger_description") or "").strip()
+        tc = (suggestion.get("trigger_context") or "").strip()
+        if not td:
+            issues.append(Issue(
+                "error", "missing_trigger_description",
+                "suggestion.eligible=true requires a non-empty 'trigger_description'.",
+            ))
+        elif len(td) < 10:
+            issues.append(Issue(
+                "warning", "trigger_description_too_short",
+                "suggestion.trigger_description is suspiciously short (<10 chars); "
+                "linter rejects empty or overly generic patterns.",
+            ))
+        if not tc:
+            issues.append(Issue(
+                "error", "missing_trigger_context",
+                "suggestion.eligible=true requires a non-empty 'trigger_context'.",
+            ))
+        elif len(tc) < 10:
+            issues.append(Issue(
+                "warning", "trigger_context_too_short",
+                "suggestion.trigger_context is suspiciously short (<10 chars); "
+                "linter rejects empty or overly generic patterns.",
+            ))
+    elif eligible is False:
+        rationale = (suggestion.get("rationale") or "").strip()
+        if not rationale:
+            issues.append(Issue(
+                "error", "missing_suggestion_rationale",
+                "suggestion.eligible=false requires a non-empty 'rationale'.",
+            ))
+    else:
+        issues.append(Issue(
+            "error", "invalid_suggestion_eligible",
+            "suggestion.eligible must be true or false.",
+        ))
+    return issues
+
+
 def lint_command(path: Path, text: str) -> LintResult:
     issues: List[Issue] = []
     suggestions: List[str] = []
@@ -800,6 +864,9 @@ def lint_command(path: Path, text: str) -> LintResult:
         if not description:
             issues.append(Issue("warning", "missing_description", "Frontmatter description is missing"))
 
+        # suggestion block (road-to-context-aware-command-suggestion Phase 2)
+        issues.extend(_lint_command_suggestion_block(text))
+
     # --- Structure checks ---
     if not H1_PATTERN.search(text):
         issues.append(Issue("error", "missing_h1", "Command is missing an H1 heading (# Title)"))

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/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/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"]

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

@@ -1,134 +0,0 @@
-"""Linear step dispatcher for ``/implement-ticket``.
-
-The dispatcher holds no business logic. It walks the fixed eight-step
-order declared in ``agents/contexts/implement-ticket-flow.md``, hands
-each step a live ``DeliveryState``, and honours the three terminal
-outcomes:
-
-- ``SUCCESS`` — record and advance.
-- ``BLOCKED`` — record, copy questions onto the state, halt.
-- ``PARTIAL`` — record, copy questions onto the state, halt.
-
-Resumption semantics (Option A, flow contract §agent-directives):
-steps whose name is already marked ``success`` in
-``state.outcomes`` are **skipped**. This lets a caller re-invoke the
-dispatcher after executing an agent-directive (the ``implement``,
-``test``, ``verify`` steps cannot run from pure Python), update the
-relevant slice of ``DeliveryState``, record ``success`` on the
-resumed step, and continue without replaying earlier work.
-
-Step handlers are injected by the caller rather than discovered at
-import time. Phase 1 shipped the dispatcher with mock handlers;
-Phase 2 wires the real ones under ``steps/``. Keeping injection
-explicit means the dispatcher is trivially testable and never
-depends on handler import order.
-"""
-from __future__ import annotations
-
-from collections.abc import Mapping
-
-from .delivery_state import DeliveryState, Outcome, Step, StepResult
-
-STEP_ORDER: tuple[str, ...] = (
-    "refine",
-    "memory",
-    "analyze",
-    "plan",
-    "implement",
-    "test",
-    "verify",
-    "report",
-)
-"""Canonical execution order. Eight steps, fixed, no branching.
-
-Changing this order is a roadmap-level decision — not a PR rider — per
-the surface-growth guardrails in
-``agents/roadmaps/road-to-implement-ticket.md``.
-"""
-
-
-def dispatch(
-    state: DeliveryState,
-    steps: Mapping[str, Step],
-) -> tuple[Outcome, str | None]:
-    """Run the eight steps linearly against ``state``.
-
-    Returns a ``(final_outcome, halting_step)`` tuple. ``halting_step``
-    is ``None`` when every step succeeded; otherwise it carries the
-    name of the step whose result halted the flow.
-
-    Parameters
-    ----------
-    state:
-        Live ``DeliveryState``. Mutated in place: each step's outcome
-        is recorded in ``state.outcomes`` under the step name, and
-        any surfaced questions land on ``state.questions``.
-    steps:
-        Mapping from step name to handler. Every entry in
-        :data:`STEP_ORDER` must be present; missing entries raise
-        ``KeyError`` at dispatch time rather than silently skipping,
-        so incomplete wiring surfaces as a hard failure.
-
-    Raises
-    ------
-    KeyError
-        If ``steps`` does not cover every entry in
-        :data:`STEP_ORDER`.
-    """
-    _assert_all_steps_present(steps)
-
-    # Clear stale questions from a previous halt before we resume so
-    # the caller never mistakes old options for fresh ones.
-    state.questions = []
-
-    for name in STEP_ORDER:
-        if state.outcomes.get(name) == Outcome.SUCCESS.value:
-            # Already completed on an earlier invocation — skip per the
-            # resume contract. The caller is responsible for keeping
-            # ``state.outcomes`` and the matching slice in sync.
-            continue
-
-        handler = steps[name]
-        result = handler(state)
-        _validate_step_result(name, result)
-
-        state.outcomes[name] = result.outcome.value
-
-        if result.outcome is Outcome.BLOCKED:
-            state.questions = list(result.questions)
-            return Outcome.BLOCKED, name
-
-        if result.outcome is Outcome.PARTIAL:
-            state.questions = list(result.questions)
-            return Outcome.PARTIAL, name
-
-    return Outcome.SUCCESS, None
-
-
-def _assert_all_steps_present(steps: Mapping[str, Step]) -> None:
-    """Reject an incomplete step mapping up front.
-
-    We deliberately fail loudly here: a missing step would otherwise
-    raise deep inside the dispatch loop after partial state mutation,
-    which makes debugging the wiring harder than it needs to be.
-    """
-    missing = [name for name in STEP_ORDER if name not in steps]
-    if missing:
-        raise KeyError(
-            "Step mapping is missing handlers for: " + ", ".join(missing),
-        )
-
-
-def _validate_step_result(name: str, result: StepResult) -> None:
-    """Enforce the blocked/partial invariant: questions must be set.
-
-    A step that blocks without surfacing a question is a bug — there
-    is nothing for the user to answer. We raise ``ValueError`` instead
-    of silently recording the outcome so the defect is visible at the
-    earliest possible point.
-    """
-    if result.outcome in (Outcome.BLOCKED, Outcome.PARTIAL) and not result.questions:
-        raise ValueError(
-            f"Step {name!r} returned {result.outcome.value} with no questions; "
-            "blocked and partial outcomes must surface at least one numbered option.",
-        )

package/.agent-src/templates/scripts/implement_ticket/steps/__init__.py

@@ -1,49 +0,0 @@
-"""Step handlers for the ``/implement-ticket`` dispatcher.
-
-Each module exposes a single ``run`` callable that matches the
-``Step`` protocol defined in ``..delivery_state``. The dispatcher
-wires them into the ``STEP_ORDER`` mapping at call time; nothing in
-this package imports handlers eagerly, so a partial wiring during
-development is caught by the dispatcher's missing-step check rather
-than by an import-time failure.
-
-Phase 2 ships all eight step handlers. The deterministic gates
-(``refine``, ``memory``, ``analyze``) validate upstream state; the
-delegation gates (``plan``, ``implement``, ``test``, ``verify``)
-halt with ``@agent-directive:`` markers so the orchestrator can
-invoke the matching skill and resume. ``report`` renders the
-delivery Markdown once everything else has succeeded. See
-``agents/roadmaps/road-to-implement-ticket.md`` for the shipping
-order and ``agents/contexts/implement-ticket-flow.md`` for the
-slice contracts each handler writes to.
-"""
-from __future__ import annotations
-
-from . import analyze, implement, memory, plan, refine, report, test, verify
-
-_STEPS = (refine, memory, analyze, plan, implement, test, verify, report)
-
-
-def all_ambiguities() -> dict[str, tuple[dict[str, str], ...]]:
-    """Return `{step_name: AMBIGUITIES}` for every step in flow order.
-
-    Used by documentation generators and the ``test_ambiguity_coverage``
-    suite to prove every step explicitly declares what can surface a
-    ``BLOCKED`` outcome. Steps that always succeed (``memory``,
-    ``report``) return an empty tuple — declared intent, not an
-    omission.
-    """
-    return {step.__name__.rsplit(".", 1)[-1]: step.AMBIGUITIES for step in _STEPS}
-
-
-__all__ = [
-    "all_ambiguities",
-    "analyze",
-    "implement",
-    "memory",
-    "plan",
-    "refine",
-    "report",
-    "test",
-    "verify",
-]