@event4u/agent-config 1.14.0 → 1.16.0

package/.agent-src/rules/security-sensitive-stop.md

@@ -1,7 +1,7 @@
 ---
 type: "auto"
 alwaysApply: false
-description: "Security-sensitive code paths — authentication, authorization, billing, tenant boundaries, secrets, file uploads, external integrations, webhooks, public endpoints — stop and run threat analysis BEFORE editing"
+description: "Security-sensitive paths — auth, billing, tenant boundaries, secrets, file uploads, external integrations, webhooks, public endpoints — stop and run threat analysis BEFORE editing"
 source: package
 ---
 
@@ -42,7 +42,7 @@ STOP writing code. Run the matching analysis skill first:
 | Wide refactor of security-sensitive code | `blast-radius-analyzer` |
 
 **Before the analysis, consult memory for prior incidents** on this
-surface. Via [`memory-access`](../guidelines/agent-infra/memory-access.md):
+surface. Via [`memory-access`](../../docs/guidelines/agent-infra/memory-access.md):
 
 ```python
 from scripts.memory_lookup import retrieve

package/.agent-src/rules/size-enforcement.md

@@ -22,6 +22,7 @@ source: package
   - Rules and system instructions should stay well below 200 lines
   - Smaller (≈60 lines) is strongly preferred
 
-→ Size limits and details: `.augment/guidelines/agent-infra/size-and-scope.md`
+→ Size limits and details: `../../docs/guidelines/agent-infra/size-and-scope.md`
 
-→ Frontmatter contract: schemas live in `scripts/schemas/` and are enforced by `python3 scripts/validate_frontmatter.py`.
+→ Frontmatter contract: schemas live in `scripts/schemas/` and are enforced by
+`python3 scripts/validate_frontmatter.py`.

package/.agent-src/rules/think-before-action.md

@@ -1,7 +1,7 @@
 ---
-type: "always"
-description: "Always analyze before acting. Prefer targeted inspection, tests, and real verification over guessing or trial-and-error."
-alwaysApply: true
+type: "auto"
+description: "Before coding, modifying, or debugging — analyze first, verify with real tools, never guess or trial-and-error"
+alwaysApply: false
 source: package
 ---
 
@@ -16,7 +16,7 @@ source: package
 - If requirements are unclear, ask a precise clarification question instead of making hidden assumptions
 - Refactors must preserve behavior, validation, examples, and anti-failure guidance unless there is an explicit reason to change them
 - Do NOT modify code you do not fully understand — read it first, trace the flow, then change it
-- Multiple valid frameworks/patterns already in the codebase (Tailwind + Flux, multiple form libs, competing state stores) → do NOT pick one silently, ask. See [`no blind implementation`](../guidelines/agent-infra/agent-interaction-and-decision-quality.md#2-no-blind-implementation)
+- Multiple valid frameworks/patterns already in the codebase (Tailwind + Flux, multiple form libs, competing state stores) → do NOT pick one silently, ask. See [`no blind implementation`](../../docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md#2-no-blind-implementation)
 
 ## The Developer Workflow
 
@@ -33,7 +33,7 @@ Skipping steps 1-3 = #1 cause of wrong implementations and wasted retries.
 ## Consult memory before editing
 
 Before writing code for the touched paths, call
-[`memory-access`](../guidelines/agent-infra/memory-access.md):
+[`memory-access`](../../docs/guidelines/agent-infra/memory-access.md):
 
 ```python
 from scripts.memory_lookup import retrieve

package/.agent-src/rules/token-efficiency.md

@@ -1,7 +1,7 @@
 ---
-type: "always"
-description: "Token efficiency — redirect output, minimize tool calls, keep responses concise"
-alwaysApply: true
+type: "auto"
+description: "When running CLI tools, fetching logs, or producing replies — redirect verbose output, minimize tool calls, keep replies concise"
+alwaysApply: false
 source: package
 ---
 
@@ -96,4 +96,4 @@ When `personal.minimal_output: true`:
 - Debugging: OK to read more context around one error.
 - User explicitly asks for full output: show it.
 
-→ Detailed patterns: `guidelines/agent-infra/output-patterns.md`
+→ Detailed patterns: `docs/guidelines/agent-infra/output-patterns.md`

package/.agent-src/rules/{ui-audit-before-build.md → ui-audit-gate.md}

@@ -1,7 +1,7 @@
 ---
-type: "always"
-description: "UI work — never write a component, screen, or partial without existing-ui-audit findings populated in state.ui_audit; the audit is the gate, not a suggestion"
-alwaysApply: true
+type: "auto"
+description: "Writing or editing UI — components, screens, partials, layouts, design tokens — require existing-ui-audit findings in state.ui_audit before non-trivial UI change; gate, not suggestion"
+alwaysApply: false
 source: package
 ---
 

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

@@ -1,7 +1,7 @@
 ---
-type: "always"
-description: "User interaction — numbered options, progress indicators, summaries"
-alwaysApply: true
+type: "auto"
+description: "Asking the user a question, presenting options, or summarizing progress — numbered-options Iron Law, single-recommendation rule, progress indicators"
+alwaysApply: false
 source: package
 ---
 
@@ -18,6 +18,7 @@ EXACTLY ONE LINE NAMES THE RECOMMENDED NUMBER. NO INLINE TAG. NO SECOND PROSE NU
 THE OPTION BLOCK STAYS NEUTRAL. THE RECOMMENDATION LINE IS THE ONLY SOURCE OF TRUTH.
 DRIFT BETWEEN OPTION-BLOCK AND PROSE IS STRUCTURALLY IMPOSSIBLE WHEN THE TAG DOES NOT EXIST.
 MISSING RECOMMENDATION = RULE VIOLATION, NOT A SLIP.
+POSITION-AGNOSTIC. END-OF-TURN MENUS COUNT. NEXT-STEP LISTS COUNT. NO EXCEPTIONS.
 ```
 
 The agent has read the code, the contracts, the trade-offs. Refusing
@@ -25,6 +26,16 @@ to take a position dumps that work back on the user. Take the
 position; be wrong out loud if needed. "Egal, was bevorzugst Du?" /
 "no preference" is NEVER acceptable.
 
+**Position-agnostic — closes the most common slip:** End-of-turn
+"Wie weiter?" / "What next?" / "How to proceed?" / "How should we
+continue?" blocks with numbered options are **numbered-options
+blocks**. Same Iron Law applies — exactly one `Empfehlung: N` /
+`Recommendation: N` line, every time. There is no "these are just
+follow-up suggestions" exception, no "the user knows better here"
+exception, no "I genuinely don't have a preference" exception. If
+the agent prints `1. … 2. … 3. …` anywhere in the reply, the
+recommendation line is mandatory.
+
 **Format — non-negotiable:**
 
 - Options block stays NEUTRAL — no `(recommended)`, no `(rec)`, no `←`, no bold, no checkmark.
@@ -58,16 +69,28 @@ SKIPPING IT IS A RULE VIOLATION, NOT A SLIP.
 ```
 
 Before emitting any reply that contains numbered options, scan the
-drafted text:
+**entire drafted reply** — top to bottom, including end-of-turn
+"Wie weiter?" / "What next?" continuation menus, follow-up
+suggestion blocks, and any list of `1. … 2. … 3. …` regardless of
+its position or framing:
 
 1. Count occurrences of `(recommended)` / `(rec)` / `(empfohlen)` inline next to a numbered option → MUST be **zero**. Found one → rewrite, drop the tag.
-2. Count distinct `Recommendation:\s*N` / `Empfehlung:\s*N` lines (case-insensitive) → MUST be **exactly one**. Zero → add one. Two or more distinct numbers → rewrite, pick one.
-3. The number on the recommendation line MUST exist in the option block.
+2. Count `1\.\s` / `2\.\s` / `3\.\s` patterns inside blockquotes or top-level prose → if **any** numbered-option block exists anywhere in the reply, the recommendation line is mandatory.
+3. Count distinct `Recommendation:\s*N` / `Empfehlung:\s*N` lines (case-insensitive) → MUST be **exactly one per options block**. Zero → add one. Two or more distinct numbers → rewrite, pick one.
+4. The number on the recommendation line MUST exist in the option block it follows.
+5. If the reply has multiple options blocks (e.g. a clarification block AND an end-of-turn menu), each block gets its own `Recommendation: N` line directly underneath.
 
 Mechanical backstop: `python3 scripts/check_reply_consistency.py --stdin < draft.md`
 (non-zero exit on any rule above). Self-scan is the primary gate; the
 script is the deterministic safety net for ambiguous cases.
 
+### Common failure modes — known, named, no excuses
+
+- **End-of-turn menu skipped.** Reply answers the question fine, then ends with `> 1. Foo > 2. Bar > 3. Stop` and no `Empfehlung:`. Iron Law 1 was violated — these are numbered options, position is irrelevant.
+- **"Genuinely no preference" hedge.** Pick anyway. The agent has more context than the user on the trade-off; refusing to pick dumps the work back. Pick the safest option, name the flip-condition.
+- **"User knows the project better" hedge.** Same failure mode, different costume. The user asked for an opinion by virtue of accepting the options block; deliver it.
+- **Multi-block reply with one recommendation.** Two options blocks but only one `Empfehlung:` line — the second block is unguarded. Rule 5 above closes this.
+
 ## Numbered Options — Always
 
 When asking the user a question with predefined choices, **always
@@ -87,9 +110,10 @@ just a number (e.g., `1`) instead of typing a sentence.
 ### Rules
 
 - **Every question with choices** must use numbered options — no exceptions.
+- **Every numbered list with `1. … 2. … 3. …`** is a numbered-options block, regardless of position. End-of-turn "Wie weiter?" / "What next?" / "How to proceed?" menus, mid-reply continuation prompts, and clarification blocks all count.
 - **Keep options short** — one line each, with a brief explanation after the dash.
 - **Always include a "skip" or "no change" option** when applicable.
-- **Always state a recommendation** — Iron Law 1 above.
+- **Always state a recommendation** — Iron Law 1 above. Per options block, every time, position-agnostic.
 - **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").
 

package/.agent-src/rules/verify-before-complete.md

@@ -3,6 +3,8 @@ type: "always"
 description: "Verify before completion — run tests and quality tools before claiming done"
 alwaysApply: true
 source: package
+load_context:
+  - .agent-src.uncompressed/contexts/execution/verification-mechanics.md
 ---
 
 # Verify Before Completion
@@ -15,25 +17,6 @@ NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
 
 If you haven't run the verification command **in this message**, you cannot claim it passes.
 
-## When to run what — timing matters
-
-**Quality tools (PHPStan, Rector, ECS) run ONCE at the very end** — not after every edit.
-Do NOT run quality checks between tasks if you have more work to do.
-Only run the full quality pipeline when you are about to finish all work in the current conversation.
-
-**Tests: as targeted as possible, as little as necessary.**
-- During work: run ONLY the specific test class or test case affected by the change.
-  Use `--filter=ClassName` or `--filter=test_name` — NEVER the full suite mid-work.
-- Only run tests when you genuinely need to verify behavior (not "just to be safe").
-- Full test suite: ONCE at the very end, before quality tools.
-
-**The sequence at the end:**
-1. All code changes are done
-2. Run tests — targeted first (`--filter`), full suite only if targeted passes
-3. Run quality pipeline (PHPStan → Rector → ECS → PHPStan)
-4. Fix any issues from step 2-3
-5. ONLY THEN claim completion or suggest commit/push/PR
-
 ## The Gate
 
 Before claiming ANY work is complete:
@@ -67,54 +50,16 @@ Skip any step = the claim is unverified.
 For specific commands → see the `quality-tools` skill.
 
 For the detailed evidence-gate playbook (claim→command mapping, output
-inspection, end-of-work sequence) → see the `verify-before-complete`
+inspection, end-of-work sequence) → see the `verify-completion-evidence`
 skill.
 
-## Minimum verification per task type
-
-| Task | Required evidence |
-|---|---|
-| Code change | Tests + PHPStan |
-| New feature | Tests + PHPStan + smoke test |
-| Bug fix | Regression test + full suite |
-| Refactoring | Full suite + PHPStan + Rector |
-| Config/migration | Relevant tests or command output |
-| API endpoint | curl/HTTP response output |
-| Documentation only | No verification needed |
-
-**Never accept** as proof: "should work", "looks correct", "logic is sound".
-No captured output = not verified.
-
-## Confidence gating
-
-State confidence explicitly before claiming completion on non-trivial work.
-
-- **High** — runtime path read end-to-end, relevant tests inspected or run,
-  no hidden side-effects (queues/events/observers) unaccounted for.
-- **Medium** — main path verified but one gap remains; list the gap in the
-  completion message.
-- **Low** — broad implementation NOT allowed; switch to analysis, narrow
-  the scope, or ask the user before proceeding.
-
-For high-risk areas (auth, tenancy, migrations, queues, dependencies,
-external APIs, data exposure), "high" requires tests AND a cross-layer
-read — not inference from a single file.
-
-## Break-glass reduction
-
-During a live production incident the verification gate is **narrowed**,
-never skipped. Break-glass requires explicit user invocation (e.g.
-`break-glass: true`, "this is a hotfix"). Never enter it unilaterally.
-
-Minimum evidence:
-
-- **Targeted test(s)** covering the exact regression — zero tests is not
-  acceptable.
-- **Smoke check** of the fixed path (curl, manual trigger, log tail) with
-  output captured in the message.
-- **Explicit list of skipped validations** and a **follow-up commitment**
-  (ticket or PR line) to run them within 24h.
+## Mechanics — when to run what, per-task evidence, confidence, break-glass
 
-Completion wording: _"hotfix applied, full verification deferred per
-break-glass"_ — never _"done"_ or _"verified"_. The normal gate resumes
-on the follow-up PR.
+The decision logic for **when** to run quality tools vs. tests, the
+per-task-type minimum-evidence table, confidence gating (High /
+Medium / Low), and the break-glass reduction during live incidents
+all live in
+[`verification-mechanics`](../contexts/execution/verification-mechanics.md).
+The Iron Law and the Gate above are the obligation surface; the
+mechanics context is the lookup material the agent pulls when the
+gate fires.

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

@@ -16,6 +16,13 @@ Checkbox states:
 Percentage = done / (done + open). Deferred and cancelled do not count towards
 "open" (they are explicit decisions).
 
+Roadmap visibility is binary:
+
+  - No `status:` frontmatter (or `status: ready`) → executable, listed.
+  - `status: draft` → hidden from the dashboard entirely (not counted,
+    not listed). Drafts become visible the moment the frontmatter flag
+    is removed or flipped to `ready`.
+
 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
@@ -37,17 +44,21 @@ from pathlib import Path
 
 CHECKBOX_RE = re.compile(r"^\s*[-*]\s+\[([ xX~\-])\]\s", re.MULTILINE)
 # H2 or H3 heading starting with "Phase <id>"; separator (colon, em-dash,
-# hyphen, or whitespace) and name are optional. The id supports three
+# hyphen, or whitespace) and name are optional. The id supports four
 # project-level conventions:
 #   - numeric        `Phase 0`, `Phase 10`
+#   - numeric+sub    `Phase 2a`, `Phase 10c` (digit run + single
+#                    lowercase letter for sub-phases)
 #   - roman I..XXXIX `Phase I`, `Phase III`
 #   - letter track   `Phase A`, `Phase B1` (single uppercase letter,
 #                    optional trailing digits for sub-track IDs)
 # Roman is capped at [IVX]+ (up to XXXIX) on purpose: the broader
 # [IVXLCDM]+ would also match all-caps words like `Phase LIVE`. Letter
 # is [A-Z] not [A-Za-z] so `## Phase overview` stays a non-phase anchor.
+# The numeric+sub branch keeps the lowercase-letter restriction so
+# `Phase abc` (no digits) still falls through to the rejection branch.
 PHASE_RE = re.compile(
-    r"^(#{2,3})\s+Phase\s+(\d+|[IVX]+|[A-Z](?:\d+)?)"
+    r"^(#{2,3})\s+Phase\s+(\d+[a-z]?|[IVX]+|[A-Z](?:\d+)?)"
     r"(?:[\s:\u2014\-]+(.*?))?\s*$",
     re.MULTILINE,
 )
@@ -56,12 +67,20 @@ EXCLUDE_NAMES = {"template.md", "README.md", "progress.md", "roadmaps-progress.m
 EXCLUDE_PREFIXES = ("open-questions",)
 EXCLUDE_DIRS = {"archive", "skipped"}
 
+# Frontmatter — minimal YAML block at the top of a roadmap. Used to hide
+# drafts (`status: draft`) from the dashboard. Anything else (no
+# frontmatter, `status: ready`, unknown values) counts as a normal
+# executable roadmap.
+FRONTMATTER_RE = re.compile(r"\A---\n(.*?)\n---\s*\n", re.DOTALL)
+DRAFT_VALUES = frozenset({"draft"})
+
 
 @dataclass
 class PhaseStats:
     # Phase identifier as it appears in the heading: numeric ("0"),
-    # roman ("III"), or letter-track ("A", "B1"). Kept as a string so
-    # non-numeric conventions survive round-tripping through render().
+    # numeric+sub ("2a"), roman ("III"), or letter-track ("A", "B1").
+    # Kept as a string so non-numeric conventions survive round-tripping
+    # through render().
     id: str
     name: str
     done: int = 0
@@ -130,6 +149,37 @@ class RoadmapStats:
         return round(self.done * 100 / self.total_active) if self.total_active else 0
 
 
+def parse_frontmatter(text: str) -> dict[str, str]:
+    """Parse a leading YAML frontmatter block. String scalars only.
+
+    Returns an empty dict if no frontmatter is present. Handles quoted and
+    unquoted values; ignores blank lines and comments. Nested keys, lists,
+    and multiline scalars are out of scope — the dashboard only needs flat
+    string flags (`status`, `mode`).
+    """
+    m = FRONTMATTER_RE.match(text)
+    if not m:
+        return {}
+    fm: dict[str, str] = {}
+    for line in m.group(1).splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#") or ":" not in line:
+            continue
+        key, _, value = line.partition(":")
+        fm[key.strip()] = value.strip().strip('"').strip("'")
+    return fm
+
+
+def is_draft(fm: dict[str, str]) -> bool:
+    """Return True when frontmatter declares the roadmap as draft.
+
+    `status: draft` is the single supported way to hide a roadmap from
+    the dashboard. Everything else (no frontmatter, `status: ready`,
+    unknown values) counts as an executable roadmap.
+    """
+    return fm.get("status", "").lower() in DRAFT_VALUES
+
+
 def is_roadmap_candidate(path: Path) -> bool:
     if path.name in EXCLUDE_NAMES:
         return False
@@ -180,10 +230,14 @@ def bar(pct: int, width: int = 10) -> str:
 
 
 def collect(roadmap_root: Path) -> list[RoadmapStats]:
+    """Collect executable roadmaps. Drafts are excluded."""
     results: list[RoadmapStats] = []
     for path in sorted(roadmap_root.rglob("*.md")):
         if not path.is_file() or not is_roadmap_candidate(path):
             continue
+        text = path.read_text(encoding="utf-8")
+        if is_draft(parse_frontmatter(text)):
+            continue
         stats = parse_roadmap(path, roadmap_root)
         if stats:
             results.append(stats)
@@ -205,14 +259,17 @@ def render(roadmaps: list[RoadmapStats]) -> str:
     overall_pct = round(total_done * 100 / total_active) if total_active else 0
     lines: list[str] = []
     lines.append("# Roadmap Progress\n")
+    header_meta = (
+        f"> {len(roadmaps)} open roadmap"
+        f"{'s' if len(roadmaps) != 1 else ''}"
+        " · [roadmaps/](roadmaps/) · [archive/](roadmaps/archive/) · "
+        "[skipped/](roadmaps/skipped/)\n"
+    )
     lines.append(
         "> Auto-generated by `.augment/scripts/update_roadmap_progress.py`. "
         "Do not edit — regenerated on every roadmap-create, -execute, or "
         "completion change (last-modified timestamp lives in git history).\n>\n"
-        f"> {len(roadmaps)} open roadmap"
-        f"{'s' if len(roadmaps) != 1 else ''} · "
-        "[roadmaps/](roadmaps/) · [archive/](roadmaps/archive/) · "
-        "[skipped/](roadmaps/skipped/)\n"
+        + header_meta
     )
     lines.append("## Overall\n")
     lines.append(f"**{total_done} / {total_active} steps done · {overall_pct}%**\n")