@event4u/agent-config 1.13.0 → 1.15.0

package/scripts/agent-config

@@ -49,6 +49,26 @@ Commands:
   hooks:install              Install the pre-commit roadmap-progress hook
                              (use --print to dump it, --force to overwrite an existing hook)
   first-run                  Guided first-run setup — cost profile, settings, tooling
+  implement-ticket           Drive the work_engine Python engine on a ticket envelope
+                             (Option-A loop; called by the /implement-ticket command)
+  work                       Drive the work_engine Python engine on a free-form prompt
+                             (Option-A loop; called by the /work command)
+  migrate-state              Migrate a legacy .implement-ticket-state.json file
+                             to the v1 .work-state.json schema (preserves .bak)
+  memory:lookup              Retrieve memory entries (text or JSON envelope)
+  memory:signal              Append a provisional intake signal (memory proposal)
+  memory:hash                Hash a memory entry (YAML or JSON stdin)
+  memory:check               Validate memory YAML schema + staleness
+  memory:check-proposal      Run the admission gate on a memory proposal
+  proposal:check             Validate a learning/skill/rule proposal markdown
+  refine-ticket:detect       Run the deterministic refine-ticket detection helper
+  chat-history:hook          Platform hook entry point (read JSON from stdin)
+                             Usage: chat-history:hook --platform <claude|augment|cursor|cline|windsurf|gemini>
+  chat-history:checkpoint    Append a phase-boundary entry to .agent-chat-history
+                             (CHECKPOINT fallback for platforms without native hooks)
+  telemetry:record           Append one artefact-engagement event (default-off)
+  telemetry:status           Print artefact-engagement telemetry status (read-only)
+  telemetry:report           Aggregate the engagement log into a quartile report
   help                       Show this help
   --version, -V              Print package version
 
@@ -59,6 +79,17 @@ Examples:
   ./agent-config roadmap:progress
   ./agent-config hooks:install
   ./agent-config first-run
+  ./agent-config implement-ticket --state-file .work-state.json
+  ./agent-config work --state-file .work-state.json --prompt-file prompt.txt
+  ./agent-config migrate-state
+  ./agent-config memory:lookup --types domain-invariants --key billing
+  ./agent-config memory:signal --type architecture-decision --path src/Foo.php --body "…"
+  ./agent-config memory:check --path agents/memory
+  ./agent-config refine-ticket:detect ticket-body.txt
+  ./agent-config telemetry:status
+  ./agent-config telemetry:status --format json
+  ./agent-config telemetry:report --since 30d --top 20
+  ./agent-config telemetry:report --since 7d --format json --top 0
 
 All commands operate on the CURRENT DIRECTORY (your project root).
 The CLI is strictly consumer-facing. Maintainer tasks live in Taskfile.yml.
@@ -101,6 +132,32 @@ resolve_script() {
   return 1
 }
 
+# Resolve a script that ships under templates/scripts/. Tries (in order):
+#   1. CONSUMER_ROOT/scripts/<name>                       — local copy / customization
+#   2. CONSUMER_ROOT/.augment/templates/scripts/<name>    — installer-shipped
+#   3. PACKAGE_ROOT/.agent-src/templates/scripts/<name>   — package-internal fallback
+# Consumer customization wins so projects can patch behavior locally
+# without losing the upstream default.
+resolve_template_script() {
+  local name="$1"
+  local p
+  for p in \
+    "$CONSUMER_ROOT/scripts/$name" \
+    "$CONSUMER_ROOT/.augment/templates/scripts/$name" \
+    "$PACKAGE_ROOT/.agent-src/templates/scripts/$name"; do
+    if [[ -f "$p" ]]; then
+      printf '%s' "$p"
+      return 0
+    fi
+  done
+  echo "❌  agent-config: template script not found: $name" >&2
+  echo "    Searched:" >&2
+  echo "      - $CONSUMER_ROOT/scripts/$name" >&2
+  echo "      - $CONSUMER_ROOT/.augment/templates/scripts/$name" >&2
+  echo "      - $PACKAGE_ROOT/.agent-src/templates/scripts/$name" >&2
+  return 1
+}
+
 cmd_mcp_render() {
   require_python3
   local script
@@ -135,6 +192,133 @@ cmd_first_run() {
   exec bash "$script" "$@"
 }
 
+cmd_implement_ticket() {
+  require_python3
+  local engine_root="$PACKAGE_ROOT/.agent-src/templates/scripts"
+  if [[ ! -d "$engine_root/work_engine" ]]; then
+    echo "❌  agent-config: work_engine module not found at $engine_root/work_engine" >&2
+    echo "    Reinstall the package and retry." >&2
+    return 1
+  fi
+  exec env PYTHONPATH="$engine_root" python3 -m work_engine "$@"
+}
+
+cmd_work() {
+  # /work shares the engine with /implement-ticket — only the input
+  # envelope differs (kind=prompt vs kind=ticket). Keeping a separate
+  # subcommand makes the user-facing distinction explicit and lets the
+  # two flows diverge later without churn at the wrapper layer.
+  require_python3
+  local engine_root="$PACKAGE_ROOT/.agent-src/templates/scripts"
+  if [[ ! -d "$engine_root/work_engine" ]]; then
+    echo "❌  agent-config: work_engine module not found at $engine_root/work_engine" >&2
+    echo "    Reinstall the package and retry." >&2
+    return 1
+  fi
+  exec env PYTHONPATH="$engine_root" python3 -m work_engine "$@"
+}
+
+cmd_migrate_state() {
+  require_python3
+  local engine_root="$PACKAGE_ROOT/.agent-src/templates/scripts"
+  if [[ ! -d "$engine_root/work_engine/migration" ]]; then
+    echo "❌  agent-config: work_engine.migration module not found at $engine_root/work_engine/migration" >&2
+    echo "    Reinstall the package and retry." >&2
+    return 1
+  fi
+  # -W ignore::RuntimeWarning suppresses the known sys.modules notice from
+  # `python3 -m pkg.subpkg.module` when the parent package eagerly imports
+  # the submodule via its CLI module. The migration is non-invasive and
+  # the warning is cosmetic; suppressing here avoids touching the engine.
+  exec env PYTHONPATH="$engine_root" python3 -W ignore::RuntimeWarning -m work_engine.migration.v0_to_v1 "$@"
+}
+
+cmd_memory_lookup() {
+  require_python3
+  local script
+  script="$(resolve_template_script "memory_lookup.py")" || return 1
+  exec python3 "$script" "$@"
+}
+
+cmd_memory_signal() {
+  require_python3
+  local script
+  script="$(resolve_template_script "memory_signal.py")" || return 1
+  exec python3 "$script" "$@"
+}
+
+cmd_memory_hash() {
+  require_python3
+  local script
+  script="$(resolve_template_script "memory_hash.py")" || return 1
+  exec python3 "$script" "$@"
+}
+
+cmd_telemetry_record() {
+  require_python3
+  local script
+  script="$(resolve_template_script "telemetry_record.py")" || return 1
+  exec python3 "$script" "$@"
+}
+
+cmd_telemetry_status() {
+  require_python3
+  local script
+  script="$(resolve_template_script "telemetry_status.py")" || return 1
+  exec python3 "$script" "$@"
+}
+
+cmd_telemetry_report() {
+  require_python3
+  local script
+  script="$(resolve_template_script "telemetry_report.py")" || return 1
+  exec python3 "$script" "$@"
+}
+
+cmd_memory_check() {
+  require_python3
+  local script
+  script="$(resolve_template_script "check_memory.py")" || return 1
+  exec python3 "$script" "$@"
+}
+
+cmd_memory_check_proposal() {
+  require_python3
+  local script
+  script="$(resolve_template_script "check_memory_proposal.py")" || return 1
+  exec python3 "$script" "$@"
+}
+
+cmd_proposal_check() {
+  require_python3
+  local script
+  script="$(resolve_script "scripts/check_proposal.py")" || return 1
+  exec python3 "$script" "$@"
+}
+
+cmd_refine_ticket_detect() {
+  require_python3
+  local script
+  script="$(resolve_script "scripts/refine_ticket_detect.py")" || return 1
+  exec python3 "$script" "$@"
+}
+
+cmd_chat_history_hook() {
+  require_python3
+  local script
+  script="$(resolve_script "scripts/chat_history.py")" || return 1
+  exec python3 "$script" hook-dispatch "$@"
+}
+
+cmd_chat_history_checkpoint() {
+  require_python3
+  local script
+  script="$(resolve_script "scripts/chat_history.py")" || return 1
+  # Default cadence-bearing event when a user/agent invokes /chat-history-checkpoint:
+  # "phase" — explicit phase boundary, lands under per_phase / per_turn cadences.
+  exec python3 "$script" hook-append --event phase "$@"
+}
+
 cmd_hooks_install() {
   local force=false
   local print_only=false
@@ -217,6 +401,21 @@ main() {
     roadmap:progress-check)  cmd_roadmap_progress_check "$@" ;;
     hooks:install)           cmd_hooks_install "$@" ;;
     first-run)               cmd_first_run "$@" ;;
+    implement-ticket)        cmd_implement_ticket "$@" ;;
+    work)                    cmd_work "$@" ;;
+    migrate-state)           cmd_migrate_state "$@" ;;
+    memory:lookup)           cmd_memory_lookup "$@" ;;
+    memory:signal)           cmd_memory_signal "$@" ;;
+    memory:hash)             cmd_memory_hash "$@" ;;
+    memory:check)            cmd_memory_check "$@" ;;
+    memory:check-proposal)   cmd_memory_check_proposal "$@" ;;
+    proposal:check)          cmd_proposal_check "$@" ;;
+    refine-ticket:detect)    cmd_refine_ticket_detect "$@" ;;
+    chat-history:hook)       cmd_chat_history_hook "$@" ;;
+    chat-history:checkpoint) cmd_chat_history_checkpoint "$@" ;;
+    telemetry:record)        cmd_telemetry_record "$@" ;;
+    telemetry:status)        cmd_telemetry_status "$@" ;;
+    telemetry:report)        cmd_telemetry_report "$@" ;;
     help|--help|-h|"")        usage ;;
     --version|-V)            print_version ;;
     *)

package/scripts/audit_cloud_compatibility.py

@@ -0,0 +1,288 @@
+#!/usr/bin/env python3
+"""audit_cloud_compatibility.py — tier each artefact for cloud distribution.
+
+Classifies every .md under .agent-src.uncompressed/{skills,rules,commands,
+guidelines} into a tier:
+
+  T1  Universal       no script / no FS / pure guidance
+  T2  Local-Agent     references repo paths or FS work, no script
+  T3-S Script-soft    mentions a script as one option (manual fallback exists)
+  T3-H Script-hard    artefact's core procedure REQUIRES a script
+
+Cloud-safe markers (HTML comment on its own line, anywhere in body):
+
+  <!-- cloud_safe: noop -->     artefact is inert on cloud → tier = T1
+  <!-- cloud_safe: degrade -->  prose fallback is provided → tier = T3-S
+
+The marker downgrades the audit tier so build_cloud_bundle.py can emit a
+cloud-aware variant. Source still ships its full local content; the
+marker plus a "## Cloud Behavior" section is what the cloud agent reads.
+
+Output: JSON summary on stdout + per-artefact list on --details.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from collections import Counter
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SOURCE = ROOT / ".agent-src.uncompressed"
+SCAN_DIRS = ["skills", "rules", "commands", "guidelines"]
+
+# patterns
+SCRIPT_RE = re.compile(
+    r"(?:scripts/[a-z_]+\.(?:py|sh)|python3\s+scripts/|bash\s+scripts/|\./scripts/)"
+)
+TASK_RE = re.compile(r"`task\s+[a-z][a-z0-9-]+`")
+HARD_RE = re.compile(
+    r"(?:MUST\s+(?:run|invoke|call)|"
+    r"^\s*[*-]?\s*(?:Run|Invoke|Call)\s+`?(?:python3\s+)?scripts/|"
+    r"first\s+tool\s+call.*scripts/|"
+    r"runs?\s+silently\s+before|"
+    r"automatically\s+(?:invokes?|runs?)\s+`?scripts/)",
+    re.IGNORECASE | re.MULTILINE,
+)
+FS_RE = re.compile(
+    r"(?:\.agent-src(?:\.uncompressed)?/|"
+    r"\.augment/|\.claude/|\.cursor/|\.clinerules/|"
+    r"agents/|\.agent-settings\.yml|\.agent-chat-history)"
+)
+CLOUD_MARKER_RE = re.compile(
+    r"<!--\s*cloud_safe:\s*(noop|degrade)\s*-->",
+    re.IGNORECASE,
+)
+
+# Cloud-action heuristics — Phase 4 Step 1, narrow second pass.
+#
+# Goal: flag only artefacts whose PROSE imperatives the cloud agent
+# cannot execute. False positives from a broad first pass (inline
+# backtick CLI, ```bash example blocks, "write a test" coding
+# instructions) are explicitly excluded — the bundle builder's
+# SANDBOX_NOTE preamble already neutralises CLI-as-guidance.
+#
+# Two signals that DO matter on cloud:
+#
+# 1. AGENT_EDIT_RE — procedure imperatively tells the AGENT to write
+#    or edit a specific local path the user owns (`.agent-settings.yml`,
+#    `.gitignore`, `.augmentignore`, `composer.json`, etc.). Plain
+#    "create a file" / "write a class" is coding work, fine on cloud.
+# 2. AGENT_RUN_RE — procedure imperatively tells the AGENT to invoke
+#    a local command as ITS OWN action ("first tool call is …",
+#    "MUST run `task ci`", "automatically invokes scripts/x.py").
+#    Backtick CLI in mid-sentence ("with `composer install`") is
+#    guidance for the user and does NOT match.
+AGENT_EDIT_RE = re.compile(
+    r"(?:"
+    r"\b(?:edit|write|update|modify|patch|append\s+to|set)\s+"
+    r"(?:the\s+|a\s+|this\s+|that\s+|your\s+)?"
+    r"`?\.(?:agent-settings\.yml|gitignore|augmentignore|"
+    r"agent-chat-history|env|claude/|cursor/|clinerules|windsurfrules)"
+    r"|"
+    r"\b(?:str-replace-editor|save-file|remove-files)\b"
+    r")",
+    re.IGNORECASE,
+)
+AGENT_RUN_RE = re.compile(
+    r"(?:"
+    r"MUST\s+(?:run|invoke|call|execute)\s+`?(?:task|python3|bash|"
+    r"scripts/|\.augment/scripts/|\.augment/scripts)"
+    r"|"
+    r"first\s+tool\s+call\s+(?:is|must\s+be)\b"
+    r"|"
+    r"automatically\s+(?:invokes?|runs?)\s+`?(?:task|scripts/|"
+    r"\.augment/scripts/)"
+    r"|"
+    r"runs?\s+silently\s+before"
+    r"|"
+    r"^\s*[*-]\s*(?:Run|Invoke|Call|Execute)\s+`(?:task|python3|"
+    r"bash\s+scripts|scripts/|\.augment/scripts/)"
+    r")",
+    re.IGNORECASE | re.MULTILINE,
+)
+# READ_RE retained for completeness — but it's mostly informational
+# (read-only ops are universally cloud-safe; we don't rewrite them).
+AGENT_READ_RE = re.compile(
+    r"\b(?:MUST\s+read|first\s+(?:reads?|inspects?))\s+"
+    r"(?:the\s+|a\s+)?(?:file|frontmatter|`\.)",
+    re.IGNORECASE,
+)
+
+
+def detect_cloud_marker(text: str) -> str | None:
+    """Return 'noop', 'degrade', or None for the cloud-safe marker."""
+    m = CLOUD_MARKER_RE.search(text)
+    return m.group(1).lower() if m else None
+
+
+def classify_cloud_action(text: str) -> str:
+    """Tag T2/T3-S artefact with cloud-action category.
+
+    Returns one of: 'reads-only', 'edits', 'runs-task', 'mixed', 'none'.
+    Narrow heuristic — only matches imperatives directed at the agent
+    itself. CLI examples shown to the user (backtick or ```bash) do
+    not match — the bundle builder's SANDBOX_NOTE handles those.
+    """
+    has_edit = bool(AGENT_EDIT_RE.search(text))
+    has_run = bool(AGENT_RUN_RE.search(text))
+    has_read = bool(AGENT_READ_RE.search(text))
+
+    active = sum([has_edit, has_run, has_read])
+    if active == 0:
+        return "none"
+    if active >= 2:
+        return "mixed"
+    if has_edit:
+        return "edits"
+    if has_run:
+        return "runs-task"
+    return "reads-only"
+
+
+def classify(text: str) -> tuple[str, dict]:
+    scripts = sorted(set(SCRIPT_RE.findall(text)))
+    tasks = sorted(set(m.strip("`") for m in TASK_RE.findall(text)))
+    fs_refs = sorted(set(FS_RE.findall(text)))
+    has_hard = bool(HARD_RE.search(text))
+    cloud_marker = detect_cloud_marker(text)
+
+    has_script = bool(scripts) or bool(tasks)
+    has_fs = bool(fs_refs)
+
+    if has_script and has_hard:
+        raw_tier = "T3-H"
+    elif has_script:
+        raw_tier = "T3-S"
+    elif has_fs:
+        raw_tier = "T2"
+    else:
+        raw_tier = "T1"
+
+    # Cloud marker downgrades the served tier — local behavior unchanged.
+    if cloud_marker == "noop":
+        tier = "T1"
+    elif cloud_marker == "degrade":
+        tier = "T3-S" if raw_tier == "T3-H" else raw_tier
+    else:
+        tier = raw_tier
+
+    # Cloud-action category is meaningful for tiers that *might* run on
+    # cloud (T1 / T2 / T3-S). For T3-H the answer is always "blocked".
+    if tier in ("T1", "T2", "T3-S"):
+        cloud_action = classify_cloud_action(text)
+    else:
+        cloud_action = "blocked"
+
+    return tier, {
+        "scripts": scripts,
+        "tasks": tasks,
+        "fs_refs_sample": fs_refs[:3],
+        "has_hard_dep_marker": has_hard,
+        "raw_tier": raw_tier,
+        "cloud_marker": cloud_marker,
+        "cloud_action": cloud_action,
+    }
+
+
+def scan() -> list[dict]:
+    rows: list[dict] = []
+    for sub in SCAN_DIRS:
+        base = SOURCE / sub
+        if not base.is_dir():
+            continue
+        for md in sorted(base.rglob("*.md")):
+            if md.name.lower() == "readme.md":
+                continue
+            text = md.read_text(encoding="utf-8")
+            tier, evidence = classify(text)
+            rows.append({
+                "path": str(md.relative_to(ROOT)),
+                "kind": sub,
+                "tier": tier,
+                **evidence,
+            })
+    return rows
+
+
+def summarize(rows: list[dict]) -> dict:
+    by_tier = Counter(r["tier"] for r in rows)
+    by_kind_tier: dict[str, Counter] = {}
+    for r in rows:
+        by_kind_tier.setdefault(r["kind"], Counter())[r["tier"]] += 1
+    script_freq = Counter()
+    task_freq = Counter()
+    cloud_action_freq = Counter()
+    cloud_action_by_tier: dict[str, Counter] = {}
+    for r in rows:
+        for s in r["scripts"]:
+            script_freq[s] += 1
+        for t in r["tasks"]:
+            task_freq[t] += 1
+        ca = r.get("cloud_action")
+        if ca:
+            cloud_action_freq[ca] += 1
+            cloud_action_by_tier.setdefault(r["tier"], Counter())[ca] += 1
+    return {
+        "total": len(rows),
+        "by_tier": dict(by_tier.most_common()),
+        "by_kind_tier": {k: dict(v) for k, v in by_kind_tier.items()},
+        "by_cloud_action": dict(cloud_action_freq.most_common()),
+        "cloud_action_by_tier": {
+            k: dict(v) for k, v in cloud_action_by_tier.items()
+        },
+        "top_scripts": script_freq.most_common(15),
+        "top_tasks": task_freq.most_common(10),
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description=__doc__.split("\n", 1)[0])
+    p.add_argument("--details", action="store_true",
+                   help="emit per-artefact rows, not just summary")
+    p.add_argument("--tier", choices=["T1", "T2", "T3-S", "T3-H"],
+                   help="filter --details to one tier")
+    p.add_argument(
+        "--cloud-action",
+        choices=["reads-only", "edits", "runs-task", "mixed", "none",
+                 "blocked"],
+        help="filter --details to one cloud-action category",
+    )
+    p.add_argument("--format", choices=["json", "md"], default="json")
+    args = p.parse_args(argv)
+
+    rows = scan()
+    summary = summarize(rows)
+
+    if args.details:
+        filtered = [
+            r for r in rows
+            if (not args.tier or r["tier"] == args.tier)
+            and (not args.cloud_action
+                 or r.get("cloud_action") == args.cloud_action)
+        ]
+        if args.format == "json":
+            print(json.dumps({"summary": summary, "rows": filtered}, indent=2))
+        else:
+            print(f"# Cloud-compat audit — tier filter: {args.tier or 'all'}"
+                  f" · cloud-action: {args.cloud_action or 'all'}\n")
+            print(f"Total in scope: {len(filtered)}\n")
+            for r in filtered:
+                marker = " 🔴" if r["has_hard_dep_marker"] else ""
+                action = r.get("cloud_action", "—")
+                print(f"- `{r['path']}` — **{r['tier']}** · "
+                      f"action: `{action}`{marker}")
+                if r["scripts"]:
+                    print(f"  - scripts: `{'`, `'.join(r['scripts'])}`")
+                if r["tasks"]:
+                    print(f"  - tasks: `{'`, `'.join(r['tasks'])}`")
+        return 0
+
+    print(json.dumps(summary, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())