@event4u/agent-config 1.12.0 → 1.13.0

package/.agent-src/rules/user-interaction.md

@@ -25,30 +25,76 @@ The user should be able to reply with just a number (e.g., `1`) instead of typin
 - **Every question with choices** must use numbered options — no exceptions.
 - **Keep options short** — one line each, with a brief explanation after the dash.
 - **Always include a "skip" or "no change" option** when applicable.
-- **Default/recommended option** can be marked: `1. Do X (recommended)`.
+- **Always state a recommendation** — see iron law below.
 - **Use the user's language** for the question and options.
 - **Accept both** the number and a natural language answer (e.g., "1" or "the first one").
 
+### Iron Law — ALWAYS recommend
+
+```
+EVERY numbered-option question MUST state which option the agent recommends and WHY.
+"Egal, was bevorzugst Du?" / "no preference" is NEVER an acceptable agent stance.
+```
+
+The user is asking the agent because the agent has read the code, the
+contracts, the trade-offs. Refusing to take a position dumps that work
+back on the user. Take the position; be wrong out loud if needed.
+
+**Format:**
+
+- Mark the recommended option inline: `1. Do X — short explanation (recommended)`.
+- After the option block, state **WHY** in 1–3 sentences: the trade-off
+  that tips the balance, plus the **caveat** that would flip it.
+- If the agent genuinely cannot pick (rare — true 50/50 with missing
+  data), say what data would break the tie and ask for that instead.
+
+**Example:**
+
+```
+> 1. Hybrid contract — keys + query (recommended)
+> 2. Key-based — extend the package
+> 3. Semantic — change all call sites
+
+I recommend 1: solves the acute consult-flow without a cross-repo PR,
+and the file-fallback stays trivial. Caveat — if hit-rate on the
+concat-shim turns out poor in practice, escalate to 2.
+```
+
+**What does NOT count as a recommendation:**
+
+- "Both work" / "either is fine" / "depends on what you prefer"
+- Listing pros and cons without picking
+- "I'd lean towards X" without a reason
+- Hiding behind "you know the project better" (the agent just researched it)
+
 ### Examples
 
-**Binary choice:**
+**Binary choice (with recommendation):**
 ```
-> 1. Interactive — ask before each comment
+> 1. Interactive — ask before each comment (recommended)
 > 2. Automatic — handle all independently
+
+I recommend 1: the comments touch security-sensitive code, so a wrong
+auto-fix is more expensive than the friction of approving each one.
+Switch to 2 if the comments turn out to be pure formatting.
 ```
 
-**Multiple choice with skip:**
+**Multiple choice with skip (with recommendation):**
 ```
-> 1. Fix the code
+> 1. Fix the code (recommended)
 > 2. Fix the test
 > 3. Skip
+
+I recommend 1: the test is asserting the documented behavior; the
+production code drifted from the contract. Pick 2 only if the contract
+itself is wrong.
 ```
 
-**Confirmation with context:**
+**Confirmation with context (recommendation implicit in framing):**
 ```
 > Found PR #1399 on branch `chore/refactor-agent-setup-2`.
 >
-> 1. Yes, that's the right PR
+> 1. Yes, that's the right PR (recommended — branch matches)
 > 2. No, different PR — I'll provide the URL
 ```
 

package/.agent-src/scripts/update_roadmap_progress.py

@@ -19,6 +19,12 @@ Percentage = done / (done + open). Deferred and cancelled do not count towards
 Invocation (from project root):
   python3 .augment/scripts/update_roadmap_progress.py              # rewrite
   python3 .augment/scripts/update_roadmap_progress.py --check      # CI: exit 1 if stale
+
+`--check` mode also fails when a roadmap reaches `count_open == 0` but is
+still under `agents/roadmaps/` instead of `agents/roadmaps/archive/` —
+backstopping the `roadmap-progress-sync` rule's "completion = archival,
+same response" requirement. The write path emits the same finding as a
+warning on stderr and still regenerates the dashboard.
 """
 
 from __future__ import annotations
@@ -176,6 +182,15 @@ def collect(roadmap_root: Path) -> list[RoadmapStats]:
     return results
 
 
+def unarchived_complete(roadmaps: list[RoadmapStats]) -> list[RoadmapStats]:
+    # A roadmap is complete when every active checkbox is done and at least
+    # one active checkbox exists. The `roadmap-progress-sync` rule mandates
+    # that such a roadmap be moved to `agents/roadmaps/archive/` in the
+    # same response that closes its last open item; `collect()` already
+    # excludes that directory, so anything left here is unarchived.
+    return [r for r in roadmaps if r.total_active > 0 and r.open_ == 0]
+
+
 def render(roadmaps: list[RoadmapStats]) -> str:
     total_done = sum(r.done for r in roadmaps)
     total_active = sum(r.total_active for r in roadmaps)
@@ -241,12 +256,22 @@ def main() -> int:
     roadmaps = collect(roadmap_root)
     new_text = render(roadmaps)
     current = target.read_text(encoding="utf-8") if target.exists() else ""
+    complete = unarchived_complete(roadmaps)
     if args.check:
-        if current != new_text:
+        stale = current != new_text
+        if stale:
             print(f"❌  {target.relative_to(args.repo_root)} is stale. "
                   f"Run `python3 .augment/scripts/update_roadmap_progress.py` "
                   f"to regenerate (or `task roadmap-progress` in Taskfile "
                   f"projects).", file=sys.stderr)
+        if complete:
+            print("❌  Completed roadmaps are still in `agents/roadmaps/` — "
+                  "move them to `agents/roadmaps/archive/` (per the "
+                  "`roadmap-progress-sync` rule):", file=sys.stderr)
+            for r in complete:
+                print(f"      - {r.rel}  ({r.done}/{r.total_active} done)",
+                      file=sys.stderr)
+        if stale or complete:
             return 1
         print(f"✅  {target.relative_to(args.repo_root)} is up to date.")
         return 0
@@ -254,6 +279,11 @@ def main() -> int:
     print(f"✅  Wrote {target.relative_to(args.repo_root)} · "
           f"{len(roadmaps)} roadmap(s) · "
           f"{sum(r.done for r in roadmaps)}/{sum(r.total_active for r in roadmaps)} steps done.")
+    if complete:
+        print("⚠️   Completed roadmaps not yet archived — move to "
+              "`agents/roadmaps/archive/`:", file=sys.stderr)
+        for r in complete:
+            print(f"      - {r.rel}", file=sys.stderr)
     return 0
 
 

package/.agent-src/templates/github-workflows/roadmap-progress-check.yml

@@ -0,0 +1,63 @@
+# Roadmap Progress Check — template shipped by agent-config
+#
+# Copy this file to `.github/workflows/roadmap-progress-check.yml` in the
+# consumer project. It fails CI when `agents/roadmaps-progress.md` is
+# stale relative to the source roadmaps under `agents/roadmaps/`.
+#
+# This is the last-line defence behind the `roadmap-progress-sync` rule
+# and the optional pre-commit hook (see `./agent-config hooks:install`).
+# A green check here proves the dashboard reflects reality on every PR
+# that touches roadmaps.
+#
+# Prerequisites:
+#   - `.augment/scripts/update_roadmap_progress.py` installed by
+#     `task install` (or `./agent-config install`).
+#   - At least one file exists under `agents/roadmaps/` — absence
+#     short-circuits the check with a passing exit (consumer projects
+#     that haven't adopted roadmaps stay green).
+#
+# This workflow is intentionally narrow: it only runs when relevant
+# files change, so it adds zero overhead to unrelated PRs.
+
+name: Roadmap Progress Check
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "agents/roadmaps/**"
+      - "agents/roadmaps-progress.md"
+      - ".augment/scripts/update_roadmap_progress.py"
+  pull_request:
+    paths:
+      - "agents/roadmaps/**"
+      - "agents/roadmaps-progress.md"
+      - ".augment/scripts/update_roadmap_progress.py"
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: Verify roadmaps-progress.md is fresh
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Run roadmap progress check
+        run: python3 .augment/scripts/update_roadmap_progress.py --check
+
+      - name: Remediation hint on failure
+        if: failure()
+        run: |
+          echo "::error::roadmaps-progress.md is stale."
+          echo "Regenerate locally with one of:"
+          echo "  ./agent-config roadmap:progress"
+          echo "  task roadmap-progress"
+          echo "  python3 .augment/scripts/update_roadmap_progress.py"
+          echo "Then commit and push the updated agents/roadmaps-progress.md."

package/.agent-src/templates/hooks/pre-commit-roadmap-progress

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# Pre-commit hook: roadmap progress dashboard sync (event4u/agent-config)
+#
+# Installed by `./agent-config hooks:install`. Aborts the commit if
+# `agents/roadmaps-progress.md` is out of date relative to staged
+# changes under `agents/roadmaps/`. Exits silently when no roadmap
+# files are staged — zero overhead on unrelated commits.
+#
+# To run manually:
+#   ./agent-config roadmap:progress-check
+#
+# To uninstall:
+#   rm .git/hooks/pre-commit
+set -e
+
+# Only act on commits that touch roadmap content.
+staged="$(git diff --cached --name-only --diff-filter=ACMR 2>/dev/null || true)"
+case "$staged" in
+  *agents/roadmaps/*.md*|*agents/roadmaps-progress.md*|*.augment/scripts/update_roadmap_progress.py*)
+    : ;;
+  *)
+    exit 0 ;;
+esac
+
+# Resolve the script — prefer the consumer-shipped path, fall back to
+# the source-of-truth copy when run from inside the package itself.
+script=""
+for cand in \
+  ".augment/scripts/update_roadmap_progress.py" \
+  ".agent-src/scripts/update_roadmap_progress.py" \
+  ".agent-src.uncompressed/scripts/update_roadmap_progress.py"; do
+  if [ -f "$cand" ]; then
+    script="$cand"
+    break
+  fi
+done
+
+if [ -z "$script" ]; then
+  echo "⚠️  pre-commit-roadmap-progress: update_roadmap_progress.py not found." >&2
+  echo "    Run \`task install\` (or \`./agent-config install\`) and retry." >&2
+  echo "    Skipping check — letting commit through." >&2
+  exit 0
+fi
+
+if ! python3 "$script" --check >/dev/null 2>&1; then
+  echo "❌  agents/roadmaps-progress.md is stale relative to your staged changes." >&2
+  echo "" >&2
+  echo "    Regenerate the dashboard with one of:" >&2
+  echo "      ./agent-config roadmap:progress" >&2
+  echo "      task roadmap-progress" >&2
+  echo "      python3 $script" >&2
+  echo "" >&2
+  echo "    Then \`git add agents/roadmaps-progress.md\` and retry the commit." >&2
+  echo "" >&2
+  echo "    To bypass once (NOT recommended):" >&2
+  echo "      git commit --no-verify" >&2
+  exit 1
+fi
+
+exit 0