@event4u/agent-config 1.14.0 → 1.16.0

package/.agent-src/contexts/execution/autonomy-examples.md

@@ -0,0 +1,90 @@
+# Autonomy Examples — Anchors, Trivial Cases, Failure Modes
+
+Loaded by the [`autonomous-execution`](../../rules/autonomous-execution.md)
+rule when concrete examples sharpen a decision. The detection algorithm
+lives in [`autonomy-detection.md`](autonomy-detection.md); the setting
+semantics live in [`autonomy-mechanics.md`](autonomy-mechanics.md).
+
+## Opt-in anchors — flip `auto` → `on`
+
+Multilingual phrases that, when spoken **as a meta-instruction to the
+agent** (per the speech-act check in [`autonomy-detection.md`](autonomy-detection.md)),
+flip standing autonomy on:
+
+- DE: "arbeite selbstständig" · "frag nicht jedes Mal" · "tue es einfach"
+- EN: "work autonomously" · "don't ask" · "just do it"
+
+Illustrative, not exhaustive — recognition is intent-based, not
+substring-based.
+
+## Opt-out anchors — flip back to `off`
+
+Reverse-trigger phrases (same speech-act check applies):
+
+- DE: "frag mich wieder" · "frag mich erst" · "stop autonomous mode"
+- EN: "ask me first" · "ask me again" · "stop being autonomous"
+
+## Speech-act check — patterns that DO NOT flip
+
+The same words can appear in many forms. None of these flip standing
+autonomy:
+
+- **Content / copy** — "Put the slogan 'just do it' on the landing page."
+- **Quote / reference** — "Nike's tagline is 'just do it' — write a blog post about it."
+- **Subject of a request** — "Write docs about the 'work autonomously' modes."
+- **Code / data** — string literals, test fixtures, translations, JSON.
+- **About a third party** — "My colleague works autonomously."
+- **A question or hypothetical** — "Should I set `don't ask` as the default?"
+
+Counter-examples — meta-questions, self-descriptions, or one-shot
+delegations also do **not** flip:
+
+- "Why don't you ask that yourself?"
+- "I'm working autonomously right now."
+- "Can you decide that yourself?"
+
+## Trivial — JUST ACT (in `on` or `auto`-after-opt-in)
+
+Eight worked cases. In `personal.autonomy: off`, ask these. In `on`
+or `auto`-after-opt-in, act on them.
+
+- "Should I start with Step 2 or Step 3?" — pick the obvious next step
+  on the roadmap and proceed; if blocked, name the blocker, otherwise go.
+- "Should we commit now or after the next change?" — answered by the
+  commit-default in [`commit-policy`](../../rules/commit-policy.md), no need to ask.
+- "How should I split the commits?" — never asked; either you are
+  invoked via `/commit-in-chunks` (split and commit) or you are not
+  (don't commit at all).
+- "Should I run the linter / tests now or after the change?" — run
+  what [`verify-before-complete`](../../rules/verify-before-complete.md)
+  requires; don't ask.
+- "I found 3 follow-up issues — fix all or stop?" — if they are within
+  the stated task scope and minimal-safe-diff allows, fix them; if they
+  expand scope, stop and surface them as a list.
+- "Filename should be `X.md` or `Y.md`?" when one matches the
+  surrounding convention — pick the convention-matching one.
+- "Do you want a verification table or paragraph?" — pick whichever
+  fits the conversation style; format is not a decision worth a turn.
+- "Show me a diff before regenerating output from a tracked source?"
+  — compression, code-gen, formatter passes, lock-file rebuilds — run
+  it and report the result. Reversibility comes from the source, not
+  from per-file confirmation. See [`non-destructive-by-default`](../../rules/non-destructive-by-default.md#not-in-scope--deterministic-regeneration)
+  § Not in scope.
+
+## Failure modes — autonomy side
+
+Wrong-behavior patterns this rule prevents:
+
+- Asking "Step 2 or Step 3?" when the roadmap orders them.
+- "Should I run the CI checks?" — `verify-before-complete` decides; act.
+- "Do we want to commit this?" — no, by default. Don't ask.
+- Numbered-options block whose only choice differences are sequencing
+  ("do A then B" vs "do B then A") with no real trade-off.
+- Asking after the user already issued a standing autonomy directive
+  earlier in the conversation (cache the opt-in for `auto`).
+
+For Hard-Floor failure modes (treating autonomy as cover for a
+floor-crossing action, reading a roadmap step as deploy authorization,
+refusing task-aligned WIP deletions, committing bulk-deletion / infra
+diffs without surfacing them) see
+[`non-destructive-by-default`](../../rules/non-destructive-by-default.md#failure-modes).

package/.agent-src/contexts/execution/autonomy-mechanics.md

@@ -0,0 +1,29 @@
+# Autonomy Mechanics — Settings and Platform Behavior
+
+Loaded by the [`autonomous-execution`](../../rules/autonomous-execution.md)
+rule when settings semantics or platform-specific defaults are
+relevant. Detection logic lives in [`autonomy-detection.md`](autonomy-detection.md).
+
+## `personal.autonomy` setting
+
+| Value | Behavior |
+|---|---|
+| `on` | Suppress trivial questions. Act on the obvious next step. Still ask on blocking / critical decisions, and ALWAYS ask on Hard-Floor triggers. |
+| `off` | Ask trivial questions too. Use this if you want the agent to check in on each workflow step. |
+| `auto` (default) | Same as `off` by default. Flips to `on` for the rest of the conversation as soon as the user expresses the intent "stop asking, just work". See [detection logic](autonomy-detection.md) — match by **intent**, not exact string. The flip never lifts the Hard Floor. |
+
+The value is read once on the first turn (per
+[`layered-settings`](../../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules))
+and cached. Missing key → treat as `on`.
+
+## Cloud platforms — settings degrade to `on`
+
+Setting reads degrade gracefully on cloud platforms (no
+`.agent-settings.yml` available). Treat as `personal.autonomy: on` —
+the user had to deliberately ship a custom skill bundle to a cloud
+agent and is unlikely to want trivial-question friction.
+
+The Hard Floor still applies on every surface, including cloud. There
+is no "cloud override" for production-branch merges, deploys, pushes,
+prod data/infra, or whimsical bulk deletions — see
+[`non-destructive-by-default`](../../rules/non-destructive-by-default.md#cloud-behavior).

package/.agent-src/contexts/execution/verification-mechanics.md

@@ -0,0 +1,80 @@
+# Verification Mechanics
+
+Loaded by [`verify-before-complete`](../../rules/verify-before-complete.md).
+Holds the decision logic and lookup tables behind the Iron Law: when
+to run which verification command, the per-task-type evidence table,
+confidence gating, and the break-glass reduction during live
+incidents.
+
+**Size budget:** ≤ 4,000 chars. Tracked under Phase 6 of
+`road-to-pr-34-followups`.
+
+## 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
+
+## 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.
+
+Completion wording: _"hotfix applied, full verification deferred per
+break-glass"_ — never _"done"_ or _"verified"_. The normal gate resumes
+on the follow-up PR.

package/.agent-src/personas/README.md

@@ -99,5 +99,5 @@ cast (usually Core-6 for review skills, empty for others).
 
 ## Related
 
-- [`../guidelines/agent-infra/role-contracts.md`](../guidelines/agent-infra/role-contracts.md) — workflow modes personas compose with
+- [`../../docs/guidelines/agent-infra/role-contracts.md`](../../docs/guidelines/agent-infra/role-contracts.md) — workflow modes personas compose with
 - [`../rules/artifact-drafting-protocol.md`](../rules/artifact-drafting-protocol.md) — mandatory per new persona

package/.agent-src/rules/agent-authority.md

@@ -0,0 +1,24 @@
+---
+type: "always"
+description: "Priority Index for the four authority rules — Hard Floor → Permission Gate → Commit Default → Trivial-vs-Blocking; read first, route to canonical rule"
+alwaysApply: true
+source: package
+---
+
+# Agent Authority — Priority Index
+
+Four rules answer **"may the agent do this autonomously?"** Check bands in order; higher band wins.
+
+| Band | Trigger | Canonical rule |
+|---|---|---|
+| **1. Hard Floor** | Prod-trunk merge · deploy · push · prod data/infra · whimsical bulk deletion · bulk-deletion or infra commit | [`non-destructive-by-default`](non-destructive-by-default.md) |
+| **2. Permission Gate** | Git op · branch / PR / tag · architectural or library change · scope expansion | [`scope-control`](scope-control.md) |
+| **3. Commit Default** | About to commit — never, unless one of four exceptions fires | [`commit-policy`](commit-policy.md) |
+| **4. Trivial-vs-Blocking** | Routine workflow question — act or ask | [`autonomous-execution`](autonomous-execution.md) |
+
+## Index rules
+
+- **Hard Floor wins, always.** No autonomy setting, roadmap step, or standing instruction lifts it.
+- **Higher band wins on conflict.** Commit exception ≠ Hard Floor override; scope permission ≠ commit override.
+- **Index never restates an Iron Law.** Iron Laws live verbatim in canonical files; this router only points.
+- **Unsure → ask.** [`ask-when-uncertain`](ask-when-uncertain.md) is the universal escape hatch.

package/.agent-src/rules/architecture.md

@@ -10,7 +10,7 @@ source: package
 ## General Principles
 
 - **Controllers are thin** — no business logic, delegate to services.
-- **Only Single Action Controllers** — every new controller MUST use `__invoke()`. No multi-action / resource controllers. See `.augment/guidelines/php/controllers.md` for naming conventions.
+- **Only Single Action Controllers** — every new controller MUST use `__invoke()`. No multi-action / resource controllers. See `../../docs/guidelines/php/controllers.md` for naming conventions.
 - **Every controller needs a FormRequest** — never validate inline with `$request->validate()`. Use a dedicated `FormRequest` subclass.
 - **Services contain business logic** — calculations, orchestration, validation.
 - **Models have no business logic** — only relationships, scopes, accessors/mutators.

package/.agent-src/rules/artifact-drafting-protocol.md

@@ -1,7 +1,7 @@
 ---
 type: "auto"
 alwaysApply: false
-description: "Use when the user asks to create a new skill, rule, command, or guideline, or to significantly rewrite an existing one — even if they don't explicitly say 'new artifact' or 'drafting protocol'. Runs a mandatory Understand → Research → Draft sequence before anything is written."
+description: "Creating a new skill, rule, command, or guideline, or significantly rewriting one — runs a mandatory Understand → Research → Draft sequence before any artifact content is written."
 source: package
 ---
 

package/.agent-src/rules/artifact-engagement-recording.md

@@ -1,7 +1,7 @@
 ---
 type: "auto"
 alwaysApply: false
-description: "After completing a /implement-ticket or /work phase-step (refine, memory, analyze, plan, implement, test, verify, report) or full task — emit one telemetry:record call with consulted+applied artefact ids when telemetry.artifact_engagement.enabled is true"
+description: "After a /implement-ticket or /work phase-step (refine/memory/analyze/plan/implement/test/verify/report) or full task — emit one telemetry:record call with consulted+applied ids when enabled"
 source: package
 ---
 
@@ -127,7 +127,7 @@ log — that is a real bug, not a swallowed error.
 ## See also
 
 - [`road-to-artifact-engagement-telemetry`](../../../agents/roadmaps/road-to-artifact-engagement-telemetry.md) — phase contract
-- [`agents/contexts/artifact-engagement-flow.md`](../../../agents/contexts/artifact-engagement-flow.md) — recording contract details
+- [`docs/contracts/artifact-engagement-flow.md`](../../docs/contracts/artifact-engagement-flow.md) — recording contract details
 - [`/implement-ticket`](../commands/implement-ticket.md) and [`/work`](../commands/work.md) — boundary points where this rule fires
 - [`scripts/telemetry/`](../../../scripts/telemetry/) — engine source
 - [`agent-settings`](../templates/agent-settings.md) — `telemetry.artifact_engagement.*` reference

package/.agent-src/rules/ask-when-uncertain.md

@@ -94,7 +94,7 @@ are related".
 - **Session handoff** (`/agent-handoff`, fresh-chat proposal): ask LAST,
   after all domain / clarifying questions — so the user's answers can be
   folded into the handoff prompt. Full rationale in
-  [`agent-interaction-and-decision-quality`](../guidelines/agent-infra/agent-interaction-and-decision-quality.md#handoff--model-switch-questions).
+  [`agent-interaction-and-decision-quality`](../../docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md#handoff--model-switch-questions).
 - **Model switch**: different phase — [`model-recommendation`](model-recommendation.md)
   triggers at task start with its own STOP-AND-WAIT gate, standalone, not
   appended to a Q&A block. Do not conflate the two.

package/.agent-src/rules/augment-portability.md

@@ -6,38 +6,47 @@ source: package
 
 # Package Portability
 
-Everything shipped with `event4u/agent-config` MUST be **project-agnostic**:
+Everything that ships with the `event4u/agent-config` package MUST be
+**project-agnostic**. That includes:
 
-- `.augment/` (skills, rules, commands, guidelines, templates, contexts)
-- Package root `AGENTS.md`
-- Package `.github/copilot-instructions.md`
+- Everything inside `.augment/` (skills, rules, commands, guidelines,
+  templates, contexts)
+- The package repo's own root `AGENTS.md`
+- The package repo's own `.github/copilot-instructions.md`
 
 All three are either installed into consumer projects (`.augment/` via
-`install.sh`) or read by AI tools working on the package itself. Leaking
-consumer-specific content pollutes downstream or misleads agents.
+`install.sh`) or read by AI tools when working on the package itself
+(`AGENTS.md`, `copilot-instructions.md`). Leaking consumer-specific
+content into any of them pollutes downstream projects or misleads agents.
 
 ## Rules
 
-- NEVER reference a specific consumer project, repo, domain, or tech
-  stack. The package repo itself (`event4u/agent-config`) MAY appear
-  in its own root `AGENTS.md` / `copilot-instructions.md` — meta about
-  the package, not a leak.
+- NEVER reference a specific consumer project, repo name, domain, or tech
+  stack directly. The package repo itself (`event4u/agent-config`) MAY be
+  named inside its own root `AGENTS.md` and `copilot-instructions.md` —
+  that is meta about the package, not a leak.
 - NEVER hardcode consumer-project paths, class names, or conventions.
-- Write content so it works as a reusable package across any project.
-- Project-specific behavior belongs in the **consumer's**
-  `.agent-settings.yml`, `AGENTS.md`, or `agents/` — never here.
-- If a skill/rule needs project-specific input: read from
-  `.agent-settings.yml` or accept as parameter.
-- Always ask when editing package files: "Would this still make sense
-  in a completely different project?"
+- Write content so it works as a **reusable package** across any project.
+- Project-specific behavior belongs in the **consumer's** `.agent-settings.yml`,
+  `AGENTS.md`, or `agents/` — never in files shipped by this package.
+- If a skill or rule needs project-specific input, read it from
+  `.agent-settings.yml` or accept it as a parameter.
+- When reviewing or editing package files, always ask: "Would this still
+  make sense in a completely different project?"
 
 ## Runtime invocations — no `task` commands
 
-Skills, rules, commands, guidelines, personas, contexts shipped by this
-package run in **consumer projects** that may not have Task installed.
-NEVER reference a `task <name>` invocation inside any artefact file
-under `.agent-src.uncompressed/{skills,rules,commands,guidelines,personas,contexts}/`
-(or the compressed mirror under `.agent-src/`). Use the direct script:
+Skills, rules, commands, guidelines, personas, and context docs
+shipped by this package run in **consumer projects**. Consumer
+projects may not have [Task](https://taskfile.dev) installed —
+they might use npm scripts, Composer scripts, Make, or nothing at
+all. A skill that instructs an agent to run `task <something>`
+silently breaks in every project without a `Taskfile.yml`.
+
+**Rule:** Never reference a `task <something>` invocation inside any
+artefact file under `.agent-src.uncompressed/{skills,rules,commands,guidelines,personas,contexts}/`
+(and therefore also not in the compressed mirror under `.agent-src/`).
+Use the direct script invocation instead:
 
 | ❌ Forbidden | ✅ Portable |
 |---|---|
@@ -54,19 +63,29 @@ under `.agent-src.uncompressed/{skills,rules,commands,guidelines,personas,contex
 | `task validate-schema` | `python3 scripts/validate_frontmatter.py` |
 | `task counts-check` | `python3 scripts/update_counts.py --check` |
 | `task roadmap-progress` | `./agent-config roadmap:progress` |
-| `task ci` | run each underlying script directly |
+| `task ci` | run each underlying script directly (no single portable equivalent) |
+
+Task remains a convenience shortcut for maintainers working on the
+package repo itself — `task ci` is the recommended local gate before
+a PR and lives in `Taskfile.yml`, `AGENTS.md`, and the package README.
+Those maintainer-facing surfaces are outside the scope of this rule.
+Artefact files must assume Task is absent.
 
-Task stays a convenience for package maintainers (`Taskfile.yml`,
-`AGENTS.md`, README). Artefact files must assume Task is absent.
+The detection pattern *"if the consumer has a `Makefile` / build
+script, prefer its targets over raw commands"* is still allowed when
+the skill adapts to the **consumer's own** tooling (e.g.
+`tests-execute` detecting `php artisan test` vs `vendor/bin/pest`).
+It is not allowed to reference `task <name>` as the detected target —
+every direct invocation must resolve to a real script path.
 
 ## Consumer CLI — `./agent-config`
 
-A subset of scripts is exposed through a project-local CLI wrapper
-`./agent-config` (written into the project root by the installer,
-gitignored). Artefacts MUST prefer the CLI over raw `python3 scripts/…`
-paths for every command it covers — raw paths only resolve inside the
-package repo, in consumer projects the scripts live under
-`node_modules/` or `vendor/`.
+A subset of package scripts is exposed through a project-local CLI
+wrapper `./agent-config` (written into the project root by the
+installer, gitignored). Artefacts MUST prefer the CLI over raw
+`python3 scripts/…` paths for every command the CLI already covers,
+because the raw paths only resolve inside the package repo — in a
+consumer project the scripts live under `node_modules/` or `vendor/`.
 
 | ❌ Forbidden in artefacts | ✅ Portable |
 |---|---|
@@ -85,13 +104,13 @@ package repo, in consumer projects the scripts live under
 | `python3 scripts/refine_ticket_detect.py` | `./agent-config refine-ticket:detect` |
 
 Commands not covered by the CLI stay as direct script invocations
-(e.g. `bash scripts/compress.sh --sync`) — maintainer-only, not
-reachable from a consumer project anyway.
+(e.g. `bash scripts/compress.sh --sync`) — those are maintainer-only
+and not reachable from a consumer project anyway.
 
 ## Enforcement
 
 `scripts/check_portability.py` scans `.augment/`, `.agent-src.uncompressed/`,
-and the package root `AGENTS.md` + `.github/copilot-instructions.md` for
-forbidden identifiers, for any `task <name>` invocation, and for direct
-script invocations that bypass the `./agent-config` CLI. Runs in CI —
-must pass before any PR.
+and the package repo's root `AGENTS.md` + `.github/copilot-instructions.md`
+for forbidden identifiers, for any `task <name>` invocation inside
+artefact files, and for direct script invocations that bypass the
+`./agent-config` CLI. It runs in CI and must pass before any PR.