@event4u/agent-config 1.18.0 → 1.19.0

package/.agent-src/rules/improve-before-implement.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2b"
 description: "Before implementing features or architectural changes — validate the request against existing code, challenge weak requirements, and suggest improvements"
 alwaysApply: false
 source: package

package/.agent-src/rules/language-and-tone.md

@@ -1,5 +1,6 @@
 ---
 type: "always"
+tier: "3"
 description: "Language and tone — informal German Du, English code comments, .md files always English"
 alwaysApply: true
 source: package

package/.agent-src/rules/laravel-translations.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2a"
 alwaysApply: false
 description: "Laravel language files, translations, i18n, lang/de, lang/en, __() helper, localization, multilingual text"
 source: package

package/.agent-src/rules/markdown-safe-codeblocks.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2b"
 description: "Generating markdown output that contains code blocks — prevent broken nesting"
 alwaysApply: false
 source: package

package/.agent-src/rules/minimal-safe-diff.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2a"
 alwaysApply: false
 description: "When writing or reviewing a diff — the smallest change that solves the stated problem; no drive-by edits, no opportunistic refactors, no reformatting of untouched code"
 source: package

package/.agent-src/rules/missing-tool-handling.md

@@ -1,5 +1,6 @@
 ---
 type: auto
+tier: "2a"
 source: package
 description: "When a CLI tool needed for the task is not installed — ask before working around it; do NOT install silently"
 ---

package/.agent-src/rules/model-recommendation.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2a"
 description: "Starting a new task, switching task type, or invoking a command — detect task complexity and recommend the optimal model (Opus/Sonnet/GPT) before any work"
 alwaysApply: false
 source: package

package/.agent-src/rules/no-cheap-questions.md

@@ -1,5 +1,6 @@
 ---
 type: "always"
+tier: "3"
 description: "No cheap questions — never ask what context answers, never offer Iron-Law-violating options, never stage no-trade-off choices; mode-independent (off / auto / on)"
 alwaysApply: true
 source: package

package/.agent-src/rules/no-roadmap-references.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "mechanical-already"
 description: "Adding a link to a specific file in agents/roadmaps/ from any stable artifact (rule, skill, command, context, guideline) — roadmaps are transient; promote durable findings to agents/contexts/ instead"
 alwaysApply: false
 source: package

package/.agent-src/rules/non-destructive-by-default.md

@@ -1,5 +1,6 @@
 ---
 type: "always"
+tier: "safety-floor"
 description: "Agent is never destructive — Hard Floor always asks for prod-trunk merges, deploys, pushes, prod data/infra, bulk deletions, and bulk-deletion/infra commits; no autonomy or roadmap bypass"
 alwaysApply: true
 source: package

package/.agent-src/rules/onboarding-gate.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "1"
 description: "First turn of a conversation on a project — check onboarding.onboarded in .agent-settings.yml; when false, prompt the user to run /onboard before executing any other request"
 alwaysApply: false
 source: package
@@ -92,6 +93,31 @@ gate. This protects projects that were set up before this rule shipped.
 - `scope-control` — option `2` writes exactly one key; no side effects.
 - `role-mode-adherence` — gate runs BEFORE the mode marker is emitted.
 
+## Copilot fallback
+
+GitHub Copilot has no `SessionStart` hook surface, so
+`scripts/onboarding_gate_hook.py` cannot run structurally and
+`agents/state/onboarding-gate.json` is not refreshed for the agent.
+On the first turn of a Copilot conversation:
+
+1. Read `onboarding.onboarded` from `.agent-settings.yml` directly
+   (one read per conversation, then cache as the prose above
+   describes).
+2. Optionally refresh the state file manually so other tooling sees
+   the same value the hook would have written:
+
+   ```bash
+   python3 scripts/onboarding_gate_hook.py < /dev/null
+   ```
+
+   The script reads `.agent-settings.yml`, atomically writes
+   `agents/state/onboarding-gate.json`, and exits 0 — same payload
+   the Augment / Claude / Cursor / Cline / Windsurf / Gemini hook
+   would have produced.
+3. Apply the gate behavior from "Gate behavior when `onboarded:
+   false`" above. The cooperative path is the spec; the hook is the
+   cache.
+
 ## See also
 
 - [`/onboard`](../commands/onboard.md) — the command this gate invokes

package/.agent-src/rules/package-ci-checks.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "mechanical-already"
 alwaysApply: false
 description: "Before pushing to remote or creating a PR in the agent-config package — run all CI checks locally first"
 source: package

package/.agent-src/rules/php-coding.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "3"
 description: "Writing or reviewing PHP code — strict types, naming, comparisons, early returns, Eloquent conventions"
 alwaysApply: false
 source: package

package/.agent-src/rules/preservation-guard.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2b"
 alwaysApply: false
 description: "When merging, refactoring, compressing, or restructuring skills, rules, commands, or guidelines — prevent quality loss"
 source: package

package/.agent-src/rules/review-routing-awareness.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2a"
 description: "When routing reviewers or flagging risk hotspots — consult ownership-map and historical-bug-patterns before suggesting reviewers or claiming a change is safe"
 source: package
 load_context:

package/.agent-src/rules/reviewer-awareness.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2a"
 description: "When suggesting reviewers for a change — anchor the choice in paths and risk, never prestige or seniority; require primary + secondary role for medium/high risk"
 source: package
 ---

package/.agent-src/rules/roadmap-progress-sync.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "1"
 description: "Any touch to agents/roadmaps/ — create/rename/delete/move, edit checkboxes ([x]/[~]/[-]), add/rename/remove phases — must regenerate dashboard and archive if 0 open items, same response"
 alwaysApply: false
 source: package
@@ -156,3 +157,24 @@ the mandatory pre-send self-check, the failure-mode catalog, and the
 [`contexts/communication/rules-auto/roadmap-progress-sync-mechanics.md`](../contexts/communication/rules-auto/roadmap-progress-sync-mechanics.md).
 Pull it whenever a trigger fires — the rule above is the obligation
 surface; the mechanics file is the lookup material.
+
+## Copilot fallback
+
+GitHub Copilot has no `PostToolUse` hook surface, so
+`scripts/roadmap_progress_hook.py` cannot detect roadmap-file writes
+structurally. The dashboard at `agents/roadmaps-progress.md` will
+not regenerate on its own.
+
+The cooperative path: every time a roadmap touch fires (per the
+trigger list in the mechanics context above), the agent regenerates
+the dashboard in the same response — which is the same Iron Law the
+hook enforces, just executed manually:
+
+```bash
+./agent-config roadmap:progress
+```
+
+The hook implementation is the specification; on Copilot the agent
+runs the regenerator itself after the same triggers fire. Skipping
+it is a rule violation, not a hook gap — the Iron Law on dashboard
+sync survives the missing hook surface.

package/.agent-src/rules/role-mode-adherence.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2a"
 description: "When roles.active_role is set in .agent-settings.yml — closing outputs must match the mode's contract and emit the structured mode marker"
 alwaysApply: false
 source: package
@@ -12,8 +13,7 @@ one of the six modes defined in
 [`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md):
 `developer`, `reviewer`, `tester`, `po`, `incident`, `planner`.
 
-Read `roles.active_role` from `.agent-settings.yml` at session start.
-Empty or missing → rule is inert. Do NOT guess a mode.
+Read `roles.active_role` from `.agent-settings.yml` at session start. Empty / missing → rule is inert; do NOT guess a mode.
 
 When active, every closing output MUST:
 

package/.agent-src/rules/rule-type-governance.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2a"
 description: "Creating or editing rules, or auditing rule types — decides when a rule should be always vs auto"
 alwaysApply: false
 source: package

package/.agent-src/rules/runtime-safety.md

@@ -1,5 +1,6 @@
 ---
 type: auto
+tier: "2b"
 source: package
 description: "When a skill declares execution metadata — enforce safety constraints for assisted and automated execution types"
 ---

package/.agent-src/rules/scope-control.md

@@ -1,5 +1,6 @@
 ---
 type: "always"
+tier: "safety-floor"
 description: "Scope control — no unsolicited architectural changes, refactors, or library replacements"
 alwaysApply: true
 source: package

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

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2a"
 alwaysApply: false
 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

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

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "mechanical-already"
 description: "Creating or editing rules, skills, commands, guidelines, AGENTS.md, or copilot-instructions.md — enforce size and scope limits"
 alwaysApply: false
 source: package

package/.agent-src/rules/skill-improvement-trigger.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2a"
 description: "After completing a meaningful task — trigger post-task learning capture if pipelines.skill_improvement is enabled"
 alwaysApply: false
 source: package

package/.agent-src/rules/skill-quality.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "mechanical-already"
 description: "Creating, editing, or reviewing skills — minimum quality standard, every skill must be executable, validated, and self-contained"
 alwaysApply: false
 source: package

package/.agent-src/rules/slash-command-routing-policy.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "1"
 description: "When user types a slash command like /create-pr, /commit, or pastes command file content"
 alwaysApply: false
 source: package
@@ -31,3 +32,41 @@ This is **irrelevant** for command detection.
 - If command file content appears in the context alongside an open file, the **command invocation takes priority**.
 - Do NOT confuse "file is open" with "user wants to discuss this file".
 - The user's typed message determines intent — not editor state.
+
+## Read the whole prompt — command is the operator, prose is the target
+
+```
+/<command> IS THE OPERATOR.
+THE REST OF THE USER MESSAGE NAMES THE TARGET.
+NEVER ASSUME THE COMMAND NAME IS THE TARGET.
+```
+
+Slash token = **what to do**; surrounding prose = **what to do it on**.
+
+- `/council and analyse chat-history` → target is `chat-history`,
+  not `council`. Council is the *tool*, prose names the *artefact*.
+- `/work the memory bug from PROJ-123` → target is "the memory bug
+  from PROJ-123".
+- `/fix ci and then open a PR` → target is "CI failure"; trailing
+  "open a PR" is a follow-up needing separate permission (per
+  `scope-control`).
+
+### Pre-flight before expensive operations
+
+Before any operation costing real time or money — external API call,
+large codebase analysis, multi-file refactor, council run, generated
+test suite — run silently:
+
+1. Re-read the **whole** user message, not just slash + first token.
+2. Identify the target the prose actually names.
+3. Target unambiguous → execute, no question.
+4. Target **genuinely** ambiguous after re-reading (prose names *two*
+   artefacts, can't tell which is the operand) → ask ONE
+   disambiguating numbered-options question per
+   [`ask-when-uncertain`](ask-when-uncertain.md), then proceed.
+
+**Not** a license to re-introduce cheap questions (`no-cheap-questions`
+still binds). Threshold: *"would this guess waste the user's tokens,
+money, or trust?"* — not *"I'd feel safer asking"*. Single failure
+mode to avoid: spending API spend on the wrong artefact because the
+agent fixated on the command name.

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

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2b"
 description: "Before coding, modifying, or debugging — analyze first, verify with real tools, never guess or trial-and-error"
 alwaysApply: false
 source: package

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

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2a"
 description: "When running CLI tools, fetching logs, or producing replies — redirect verbose output, minimize tool calls, keep replies concise"
 alwaysApply: false
 source: package

package/.agent-src/rules/tool-safety.md

@@ -1,5 +1,6 @@
 ---
 type: auto
+tier: "2b"
 source: package
 description: "When a skill uses external tools — enforce allowlist, deny-by-default, and no hidden credential patterns"
 ---

package/.agent-src/rules/ui-audit-gate.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2b"
 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/upstream-proposal.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2a"
 description: "After creating or significantly improving a skill, rule, guideline, or command — ask if it should be contributed upstream to the shared package"
 alwaysApply: false
 source: package

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

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "3"
 description: "Asking the user a question, presenting options, or summarizing progress — numbered-options Iron Law, single-recommendation rule, progress indicators"
 alwaysApply: false
 source: package

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

@@ -1,5 +1,6 @@
 ---
 type: "always"
+tier: "2a"
 description: "Verify before completion — run tests and quality tools before claiming done"
 alwaysApply: true
 source: package

package/.agent-src/skills/roadmap-management/SKILL.md

@@ -117,11 +117,28 @@ Every roadmap follows this structure:
 
 ### Quality gates
 
-Every roadmap implicitly includes these gates (run after each step that changes code):
+Every roadmap implicitly includes the project's quality pipeline
+(static analysis, autofixes, tests). What's configurable is **when**
+the pipeline runs during `/roadmap execute`, controlled by
+`roadmap.quality_cadence` in `.agent-settings.yml`:
 
-- PHPStan must pass (detect command: artisan vs composer, see `rules/docker-commands.md`)
-- Rector: run with fix flag, verify no new PHPStan errors
-- Tests: run affected tests
+| Cadence | Pipeline runs | Trade-off |
+|---|---|---|
+| `end_of_roadmap` (default) | Once before archiving | Fastest, fewest tokens; errors compound across phases |
+| `per_phase` | After every completed phase + final | Balanced; catches drift at phase boundaries |
+| `per_step` | After every completed step + final | Legacy verbose; highest token cost |
+
+The default is `end_of_roadmap` because most steps are checkbox-only
+content edits and a final pipeline run is the cheapest way to satisfy
+`verify-before-complete`. Switch to `per_phase` for risky migrations or
+unfamiliar codebases.
+
+**Always-on, regardless of cadence:**
+
+- Step checkboxes flip `[ ] → [x]` and the dashboard regenerates **same
+  response** (enforced by `roadmap-progress-sync`).
+- Before any "roadmap complete" claim or archival, the pipeline runs
+  fresh (enforced by `verify-before-complete`).
 
 ### Step granularity
 
@@ -149,6 +166,14 @@ Every roadmap implicitly includes these gates (run after each step that changes
    the roadmap text. If the user declines, do **not** re-propose during
    `roadmap-execute`. Decline = silence. See [`scope-control`](../../rules/scope-control.md#decline--silence--no-re-asking-on-the-same-task).
 5. Save with a kebab-case filename (e.g. `optimize-webhook-jobs.md`).
+   **Before writing**, scan the entire roadmap namespace for a
+   collision — active, `archive/`, `skipped/`, and nested subdirs —
+   with `find agents/roadmaps -type f -iname "<name>.md"`. If any
+   hit comes back, stop and ask the user to rename, open the
+   existing file, or abort. Never silently overwrite an archived
+   or skipped roadmap. Detailed prompt in
+   [`commands/roadmap/create.md`](../../commands/roadmap/create.md)
+   step 6.
 6. Regenerate the dashboard so the new roadmap is included.
 
 ### Executing a roadmap

package/.agent-src/skills/verify-completion-evidence/SKILL.md

@@ -128,7 +128,12 @@ When reporting completion to the user:
 3. **Result** — numeric breakdown (tests passed/failed/skipped, errors,
    warnings)
 4. **Caveats** — anything the output flagged but you chose to accept
-5. **Next step** — e.g. "Ready for `/commit`" or "Awaiting review"
+5. **Untracked files** — if `git status --short` shows any untracked
+   files in the working tree, list them verbatim in the report. This
+   prevents silently-shipped artefacts (logs, scratch scripts, ad-hoc
+   notes) from disappearing into a future commit. Empty list means
+   omit the section.
+6. **Next step** — e.g. "Ready for `/commit`" or "Awaiting review"
 
 ## Gotchas
 
@@ -188,3 +193,5 @@ Before sending a completion message:
 * [ ] No warnings or skips are hidden
 * [ ] Targeted tests green → full suite green → quality pipeline clean
 * [ ] `git status` reflects only the intended change set
+* [ ] If `git status --short` shows untracked files, the report lists
+      them verbatim under "Untracked files"

package/.agent-src/templates/agent-settings.md

@@ -217,6 +217,21 @@ pipelines:
   # Included by every cost_profile except `custom`.
   skill_improvement: true
 
+# --- Roadmap execution ---
+#
+# Controls when /roadmap execute runs the project's quality pipeline.
+# Step checkboxes and the dashboard are ALWAYS updated in the same
+# response — that cadence is governed by `roadmap-progress-sync` and
+# is non-negotiable. This setting only governs *quality tool runs*.
+roadmap:
+  # When to run quality tools during /roadmap execute.
+  #   end_of_roadmap = once, before archiving (default — fastest, fewest tokens)
+  #   per_phase      = once after every completed phase
+  #   per_step       = after every completed step (legacy; highest token cost)
+  # Iron Law `verify-before-complete` still applies — fresh output is
+  # mandatory before any "roadmap complete" claim, regardless of cadence.
+  quality_cadence: end_of_roadmap
+
 # --- Subagent orchestration ---
 subagents:
   # Model for implementer subagents (empty = same tier as the session model)
@@ -362,6 +377,7 @@ lives under `personal:` in YAML.
 | `hooks.chat_history.enabled` | `true`, `false` | `true` | Register the four chat-history hooks (turn-check, append, halt-append, heartbeat). Gated by **both** this flag AND `chat_history.enabled`; either off → no chat-history hook registers. |
 | `hooks.chat_history.script` | path | `scripts/chat_history.py` | Override path to the chat-history CLI. Set only when the script lives outside the standard location. |
 | `pipelines.skill_improvement` | `true`, `false` | `true` | When `true`: propose learning capture after meaningful tasks. When `false`: silent. Included in every profile except `custom`. |
+| `roadmap.quality_cadence` | `end_of_roadmap`, `per_phase`, `per_step` | `end_of_roadmap` | When `/roadmap execute` runs the project's quality pipeline. Default skips per-step / per-phase runs and gates only the final archival. `per_phase` runs once after every phase; `per_step` is the legacy verbose mode. Step checkboxes and the dashboard are always updated regardless. `verify-before-complete` still requires fresh output before any "roadmap complete" claim. |
 | `subagents.implementer_model` | model alias or empty | _(empty)_ | Model for implementer subagents. Empty = same tier as session model. See [subagent-configuration](../contexts/subagent-configuration.md). |
 | `subagents.judge_model` | model alias or empty | _(empty)_ | Model for judge subagents. Empty = one tier above implementer (opus if sonnet, sonnet if haiku). |
 | `subagents.max_parallel` | integer | `3` | Maximum parallel subagent invocations. `1` serializes. |

package/.agent-src/templates/roadmaps.md

@@ -39,11 +39,16 @@ Templates for roadmap files stored in `agents/roadmaps/` or `app/Modules/{Module
 
 ---
 
-## Quality Gates (always apply)
+## Quality Gates (always apply at completion)
 
-Every roadmap must pass these before it is considered done:
+Every roadmap must pass the project's quality pipeline before it is
+considered done. **When** the pipeline runs during `/roadmap execute` is
+governed by `roadmap.quality_cadence` in `.agent-settings.yml`
+(`end_of_roadmap` default → once before archival; `per_phase` → after
+every phase; `per_step` → after every step). Either way, a final fresh
+run is mandatory before "complete" per `verify-before-complete`.
 
-Run the project's quality pipeline and test suite. Common commands:
+Common commands:
 
 ```bash
 # PHP projects (inside Docker container if applicable)

package/.agent-src/templates/scripts/work_engine/hook_bootstrap.py

@@ -19,8 +19,10 @@ from .hooks.builtin import (
     ChatHistoryHaltAppendHook,
     ChatHistoryHeartbeatHook,
     ChatHistoryTurnCheckHook,
+    DecisionTraceHook,
     DirectiveSetGuardHook,
     HaltSurfaceAuditHook,
+    MemoryVisibilityHook,
     StateShapeValidationHook,
     TraceHook,
 )
@@ -56,6 +58,13 @@ def _build_hook_registry(args: argparse.Namespace) -> HookRegistry:
         StateShapeValidationHook().register(registry)
     if settings.directive_set_guard:
         DirectiveSetGuardHook().register(registry)
+    if settings.decision_trace:
+        DecisionTraceHook().register(registry)
+    if settings.memory_visibility:
+        MemoryVisibilityHook(
+            cost_profile=settings.cost_profile,
+            visibility_off=settings.memory_visibility_off,
+        ).register(registry)
     if settings.chat_history_enabled:
         _register_chat_history_hooks(registry, settings)
 

package/.agent-src/templates/scripts/work_engine/hooks/__init__.py

@@ -24,8 +24,10 @@ from .builtin import (
     ChatHistoryHaltAppendHook,
     ChatHistoryHeartbeatHook,
     ChatHistoryTurnCheckHook,
+    DecisionTraceHook,
     DirectiveSetGuardHook,
     HaltSurfaceAuditHook,
+    MemoryVisibilityHook,
     StateShapeValidationHook,
     TraceHook,
 )
@@ -40,6 +42,7 @@ __all__ = [
     "ChatHistoryHaltAppendHook",
     "ChatHistoryHeartbeatHook",
     "ChatHistoryTurnCheckHook",
+    "DecisionTraceHook",
     "DirectiveSetGuardHook",
     "HaltSurfaceAuditHook",
     "HookCallback",
@@ -49,6 +52,7 @@ __all__ = [
     "HookHalt",
     "HookRegistry",
     "HookRunner",
+    "MemoryVisibilityHook",
     "StateShapeValidationHook",
     "TraceHook",
 ]

package/.agent-src/templates/scripts/work_engine/hooks/builtin/__init__.py

@@ -15,8 +15,10 @@ from .chat_history_append import ChatHistoryAppendHook
 from .chat_history_halt_append import ChatHistoryHaltAppendHook
 from .chat_history_heartbeat import ChatHistoryHeartbeatHook
 from .chat_history_turn_check import ChatHistoryTurnCheckHook
+from .decision_trace import DecisionTraceHook
 from .directive_set_guard import DirectiveSetGuardHook
 from .halt_surface_audit import HaltSurfaceAuditHook
+from .memory_visibility import MemoryVisibilityHook
 from .state_shape_validation import StateShapeValidationHook
 from .trace import TraceHook
 
@@ -25,8 +27,10 @@ __all__ = [
     "ChatHistoryHaltAppendHook",
     "ChatHistoryHeartbeatHook",
     "ChatHistoryTurnCheckHook",
+    "DecisionTraceHook",
     "DirectiveSetGuardHook",
     "HaltSurfaceAuditHook",
+    "MemoryVisibilityHook",
     "StateShapeValidationHook",
     "TraceHook",
 ]