@event4u/agent-config 1.15.0 → 1.16.0

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

@@ -3,6 +3,8 @@ type: "always"
 description: "Scope control — no unsolicited architectural changes, refactors, or library replacements"
 alwaysApply: true
 source: package
+load_context:
+  - .agent-src.uncompressed/contexts/authority/scope-mechanics.md
 ---
 
 # Scope Control
@@ -20,62 +22,79 @@ source: package
 
 The user decides the git shape of the work. Never improvise.
 
-> **Commit specifics:** see [`commit-policy`](commit-policy.md) — narrower
-> than the general "no git ops without permission" below (never-ask
-> default + roadmap-authorized exception).
+> **Commit specifics:** see the canonical [`commit-policy`](commit-policy.md)
+> rule — narrower than the general "no git ops without permission"
+> below (covers the never-ask-about-committing default and the
+> roadmap-authorized exception).
 
 - NEVER commit, push, merge, rebase, or force-push without explicit user permission.
-- NEVER create, switch, or delete a branch without explicit user permission.
-  Includes spike, scratch, throwaway, worktree branches.
-- NEVER create, close, reopen, or retarget a pull request without explicit
-  user permission.
+- NEVER create a new branch, switch to a different branch, or delete a
+  branch without explicit user permission. This includes spike, scratch,
+  throwaway, and worktree branches.
+- NEVER create, close, reopen, or change the target of a pull request
+  without explicit user permission.
 - NEVER push a tag or create a release without explicit user permission.
-- NEVER include version numbers, releases, deprecation dates,
-  release-tied milestones, or git tags in roadmaps, plans, tickets, or
-  any planning artifact. Roadmaps plan **work**; releases are a
-  separate user decision. Never surface "which release" as a numbered
-  option, ADR field, or roadmap entry. If user wants a release pinned
-  to a milestone, they say so explicitly.
+- NEVER include version numbers, target releases, deprecation dates,
+  release-tied milestones, or git tags inside roadmaps, plans, tickets,
+  or any other planning artifact. Roadmaps plan **work**; releases and
+  tags are a separate decision the user makes outside the roadmap.
+  Never surface "which release should this ship in?" as an option in
+  numbered choices, ADRs, or roadmap text. If the user wants a release
+  pinned to a milestone, they will say so explicitly.
 - If a task seems to need a separate branch or PR, STOP and **brief
-  first, ask second**. The brief MUST cover, in order:
-  1. **Why** — what the new branch solves that the current one cannot.
-  2. **What** — files touched, experiments run, expected duration.
-  3. **How it continues** — merge back, cherry-pick, throwaway, PR
-     target, how the current branch is protected meanwhile.
-  Then present numbered options with "stay on current branch" as
-  default. User decides. Do NOT branch first and explain later.
-
-"Explicit permission" = the user said so this turn or gave a standing
-instruction they have not revoked. Earlier permission for another op
-does not carry over.
+  the user before asking** — see
+  [`scope-mechanics`](../contexts/authority/scope-mechanics.md)
+  § Brief-before-asking for the required Why / What / How sequence.
+
+"Explicit permission" means the user said so **in this turn or in a
+standing instruction they have not revoked**. Earlier permission for a
+different operation does not carry over.
 
 ## Production, infrastructure, bulk-destructive — Hard Floor
 
-Subset of the above is **never** autonomous and never auto-permitted
-by a standing autonomy directive. Canonical rule:
-[`non-destructive-by-default`](non-destructive-by-default.md).
-Restated so this file remains the single read for git/scope concerns:
+A subset of the operations above is **never** autonomous and never
+auto-permitted by a standing autonomy directive. Canonical rule:
+[`non-destructive-by-default`](non-destructive-by-default.md). The
+trigger list (production-branch merges, deploys / releases, prod
+data / infra, bulk-destructive ops) and the
+"authorization is this turn, not earlier" clarification live in
+[`scope-mechanics`](../contexts/authority/scope-mechanics.md)
+§ Production, infrastructure, bulk-destructive.
 
-- **Production-branch merges** — `main`, `master`, `prod`, `production`, `release/*`, or any deployment-trunk branch. Always ask, even when the roadmap step says "merge".
-- **Deploys / releases** — `terraform apply` / `kubectl apply` on prod, deploy scripts, release commands, tag pushes that trigger CI deployment. Always ask.
-- **Production data / infrastructure** — prod DB writes / migrations, prod config edits, secrets rotation, IAM / role / policy, DNS, anything in a `prod`-scoped path or pipeline. Always ask.
-- **Bulk-destructive ops** — wildcard or directory deletion (`rm -rf <dir>`, `git rm -r`), `DROP TABLE`, `TRUNCATE`, `git reset --hard` past unpushed work, mass class / module / migration deletion. Always ask.
+## Decline = silence — no re-asking on the same task
 
-A roadmap step or earlier turn does **not** count as authorization for
-these. Authorization is "the user said so on this turn".
+After the user **declines** a proposal (branch switch, PR creation,
+tag/release entry, separate worktree, version pinning in a roadmap),
+do **not** raise the same proposal again on the same task. The decline
+stands until the user reopens the topic themselves.
 
-## Decline = silence — no re-asking on the same task
+Timing and "is this worth asking?" guidance lives in
+[`scope-mechanics`](../contexts/authority/scope-mechanics.md)
+§ Decline = silence — context.
+
+## Fenced step — user-set review gates
+
+When the user explicitly fences off the next step — *"don't implement
+yet"*, *"plan only"*, *"just write the roadmap, I'll review"*,
+*"review first"*, *"erst Roadmap, ich schau drüber"*, *"nichts
+implementieren"*, *"nur planen"*, *"erstmal nur X, dann ich"* — the
+agent's reply is **the deliverable plus a handoff**, never the
+deliverable plus *"shall we start?"*.
 
-After a declined proposal (branch switch, PR, tag/release entry,
-worktree, version pinning in a roadmap), do **not** raise it again on
-the same task. Decline stands until user reopens it.
+```
+USER FENCED OFF EXECUTION → DELIVER + HAND BACK.
+NO NUMBERED OPTION OFFERING TO BEGIN WORK.
+NO "READY TO IMPLEMENT?" RE-ASK.
+NO "STARTEN WIR MIT PHASE 1?" PIVOT.
+```
 
-Right moment to ask — at most **once**, only when genuinely useful —
-is **before** work starts (writing roadmap, opening ticket), not
-mid-execution. During roadmap execution the branch question is
-settled; do not resurface it step by step.
+The fence stands until the user reopens the topic themselves, exactly
+like `Decline = silence` above. Permitted follow-up questions on the
+same turn cover **the deliverable** (adjust scope, fix wording, add a
+section), never **its execution**.
 
-A proposal that "might be sensible" is not enough reason to ask.
-Default: stay on current branch, no release language. Only ask with
-concrete evidence-based reason (e.g. risky migration → spike branch).
-If in doubt, do not ask.
+For the failure-mode catalog (Option 1 = "start now", re-asking after
+delivery, hand-off-to-execution drift, inferring acceptance from a
+thumbs-up) and the explicit bypass phrases that lift the fence, see
+[`scope-mechanics`](../contexts/authority/scope-mechanics.md)
+§ Fenced step.

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,7 +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`.

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
 ---
 

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

@@ -44,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,
 )
@@ -74,8 +78,9 @@ 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