@event4u/agent-config 1.9.1

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

@@ -0,0 +1,125 @@
+---
+type: "auto"
+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
+---
+
+# Review Routing Awareness
+
+Before suggesting reviewers or declaring a change safe, the agent consults
+two project-local data sources — if they exist — to ground the routing in
+the consumer's actual organizational memory:
+
+1. **Ownership map** — which roles/teams own which paths, with per-path
+   risk notes.
+2. **Historical bug patterns** — recurring failure modes or technical debt
+   the project has paid for before.
+
+Both live in the consumer repository (never in package-shipped files) and
+are optional. Absence is not an error — the agent falls back to
+generic, role-based suggestions from [`reviewer-awareness`](reviewer-awareness.md).
+
+## When this rule applies
+
+- The agent is classifying PR risk, suggesting reviewers, writing a PR
+  description, or producing a review plan.
+- The agent is reviewing its own diff before asking for human review.
+- The change modifies more than a trivial amount of code (≥ 1 file
+  outside docs).
+
+## Required behavior
+
+### 1. Check for project data
+
+Look, in order, for:
+
+- `.github/ownership-map.yml` (or `agents/ownership-map.yml`)
+- `.github/historical-bug-patterns.yml` (or
+  `agents/historical-bug-patterns.yml`)
+
+If neither exists, fall back to engineering-memory via
+[`memory-access`](../guidelines/agent-infra/memory-access.md):
+
+```python
+from scripts.memory_lookup import retrieve
+extra = retrieve(
+    types=["ownership", "historical-patterns"],
+    keys=<changed file paths>,
+    limit=5,
+)
+```
+
+Curated memory (`agents/memory/ownership.yml`,
+`agents/memory/historical-patterns.yml`) shares the schema with the
+project-local YAMLs and is merged into the routing output. If both
+memory and project YAMLs are absent, skip this rule and rely on
+[`reviewer-awareness`](reviewer-awareness.md) defaults. **Do not invent
+owners or patterns** from context.
+
+### 2. Match the diff
+
+For every changed file, collect:
+
+- **Matching ownership entries** — each yields a role, optional focus
+  note, and optional risk hint.
+- **Matching historical patterns** — each yields a named prior failure
+  mode and the minimum control or test the project expects.
+
+Matching uses glob patterns (see
+[`review-routing-data-format`](../guidelines/review-routing-data-format.md)
+for the schema).
+
+### 3. Surface findings
+
+When producing a review plan, include:
+
+- **Owner-mapped roles** — explicitly preferred over generic roles. If
+  the ownership map says `app/Billing/**` is owned by `finance-engineering
+  + security`, use those, not "backend + security".
+- **Historical-pattern warnings** — list every matched pattern with a
+  short label and the required control, e.g. _"Pattern: N+1 on tenant
+  listings → add an eager-load regression test"_.
+- **Confidence note** — if the ownership map is stale (last updated > 6
+  months ago per the `updated` field), say so. Ownership maps rot.
+
+### 4. Do NOT overreach
+
+- **Never rename paths** or add ownership entries as a side effect of a
+  code change. Ownership map edits are a separate, explicit task.
+- **Never mark a change safe** only because no pattern matched. Pattern
+  absence means "no known hit", not "no risk".
+- **Never copy historical-pattern names into the diff** as code comments
+  or commit messages — they are routing metadata, not commentary.
+
+## Interaction with other rules
+
+- Feeds [`reviewer-awareness`](reviewer-awareness.md) — this rule
+  **resolves** owners; reviewer-awareness **formats** them.
+- Extends [`verify-before-complete`](verify-before-complete.md) — if a
+  historical pattern demands a regression test, the verification gate
+  requires that test before completion is claimed.
+- Does not override [`minimal-safe-diff`](minimal-safe-diff.md) — a
+  matched pattern is a reason to **add a test**, never a reason to
+  expand scope into unrelated refactors.
+
+## Anti-patterns — reject them
+
+- Suggesting owners "because this looks like billing code" without
+  consulting the ownership map when one exists.
+- Inventing historical patterns from general knowledge — patterns must
+  come from the project's own registry.
+- Downgrading a matched high-severity pattern because "the author said
+  it's fine" — the pattern was registered because it bit before.
+- Treating an out-of-date map as absent. Flag staleness; do not silently
+  skip.
+
+## See also
+
+- [`reviewer-awareness`](reviewer-awareness.md) — formatting reviewer
+  suggestions.
+- [`review-routing-data-format`](../guidelines/review-routing-data-format.md)
+  — YAML schemas for ownership-map and historical-bug-patterns.
+- [`review-routing`](../skills/review-routing/SKILL.md) — the skill
+  that produces the merged routing report.
+- [`judge-test-coverage`](../skills/judge-test-coverage/SKILL.md) —
+  consumes the "required test" output from historical patterns.

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

@@ -0,0 +1,92 @@
+---
+type: "auto"
+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
+---
+
+# Reviewer Awareness
+
+When a change is medium- or high-risk, the agent suggests reviewer **roles**
+(not individuals) based on what the diff actually touches — not who is
+loudest, most senior, or who "usually reviews this kind of thing".
+
+## When this rule applies
+
+- The agent is asked to suggest reviewers, draft a PR description, or
+  consolidate a review plan.
+- The change is classified medium or high risk by
+  [`review-routing`](../skills/review-routing/SKILL.md), the
+  `pr_risk_review.py` script, or explicit user judgment.
+- For **low-risk** changes, reviewer suggestions are optional and may be
+  omitted.
+
+## Required behavior
+
+1. **Anchor every suggestion in the diff.** Name the path or change that
+   triggered the role — "backend because `app/Services/PaymentGateway.php`
+   changed", not "backend because it's a code change".
+2. **Two roles minimum for medium/high risk** — one **primary** (the
+   domain most at risk) and one **secondary** (cross-cutting sanity:
+   security, infra, domain owner).
+3. **Explain the focus area** for each reviewer — what they should look
+   at, not just that they should look. "security: confirm the new
+   authorization boundary actually denies cross-tenant reads".
+4. **Prefer ownership-mapped owners** when an ownership map exists
+   (see [`review-routing-awareness`](review-routing-awareness.md)). Fall
+   back to generic roles only when no mapping matches.
+5. **Never name individual reviewers** in package-shipped artifacts.
+   The consumer repo's CODEOWNERS or ownership map does the mapping
+   role → person.
+
+## Reviewer roles
+
+The reference set — extend per project, but keep these as the common
+vocabulary:
+
+| Role | Typical focus |
+|---|---|
+| `backend` | business logic, validation, side effects, data integrity |
+| `frontend` | UX, accessibility, client-side state, rendering |
+| `security` | authz, secrets, trust boundaries, data exposure |
+| `infra` / `ops` | rollout, migration safety, observability, retries |
+| `database` | schema changes, indexes, query plans, rollback realism |
+| `domain owner` | business invariants, policy intent, edge-case correctness |
+| `qa` | test coverage, regression scenarios, flake risk |
+
+## Anti-patterns — reject them
+
+- "Reviewers: @alice, @bob" inside a shared package artifact — individuals
+  live in the consumer's CODEOWNERS, not in package output.
+- "Any senior engineer" — prestige is not a review strategy.
+- "Whoever reviewed this last time" — selection by habit, not by
+  current risk.
+- One role for a 🔴 high-risk change — single-reviewer risk, especially
+  when the change crosses an authorization or tenancy boundary.
+- Suggesting reviewers without naming what they should look at — a
+  rubber-stamp invitation.
+
+## Format
+
+When the agent proposes reviewers, use this block:
+
+```
+Suggested reviewers (role-based):
+  • primary:   <role> — focus: <one line, anchored in diff>
+  • secondary: <role> — focus: <one line, anchored in diff>
+  (optional) additional: <role> — focus: …
+```
+
+## Rationale
+
+The right reviewer reduces blind spots more than the loudest reviewer.
+Blind-spot reduction comes from role diversity (different angles on the
+same diff), not from seniority.
+
+## See also
+
+- [`review-routing-awareness`](review-routing-awareness.md) — how
+  ownership maps and historical patterns feed reviewer selection.
+- [`review-routing`](../skills/review-routing/SKILL.md) — the skill that
+  produces the reviewer block.
+- [`requesting-code-review`](../skills/requesting-code-review/SKILL.md) —
+  PR preparation and self-review before asking for reviewers.

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

@@ -0,0 +1,56 @@
+---
+type: "auto"
+description: "Editing checkboxes in agents/roadmaps/*.md — [x], [~], [-], or add/rename/remove phases — must run task roadmap-progress in the SAME response; a roadmap that hits 0 open items must also be archived in the SAME response"
+alwaysApply: false
+source: package
+---
+
+# Roadmap Progress Sync
+
+## Rule
+
+**CRITICAL — ZERO TOLERANCE:** Whenever you change checkbox state in a
+roadmap file (`agents/roadmaps/*.md`, module or package equivalents)
+you MUST run `task roadmap-progress` **in the same response** — not
+later, not batched across sessions, not "at the end of the roadmap".
+
+`agents/roadmaps-progress.md` is the read-only dashboard. Every
+unsynced edit makes it lie to the next reader.
+
+**Completion = archival, same response.** When the edit takes a
+roadmap to `count_open == 0` (every item is `[x]`, `[~]`, or `[-]`),
+`git mv` it into `agents/roadmaps/archive/` (or `skipped/` if no
+`[x]` at all) **before** regenerating. A 100%-complete roadmap left
+in `agents/roadmaps/` is a rule violation. See `roadmap-management`
+for the archive vs skipped decision table.
+
+## Triggers
+
+| Edit | Must run, same response |
+|---|---|
+| Mark step `[x]`, `[~]`, `[-]`, or unmark back to `[ ]` | `task roadmap-progress` |
+| Add, rename, or remove a phase | `task roadmap-progress` |
+| Create a new roadmap file | `task roadmap-progress` |
+| **Last `[ ]` flips** — roadmap reaches `count_open == 0` | `git mv` → `archive/` (or `skipped/`) **then** `task roadmap-progress` |
+| Move roadmap between `roadmaps/` ↔ `archive/` ↔ `skipped/` | `task roadmap-progress` |
+
+**Batching:** multiple checkbox edits in one response → a **single**
+`task roadmap-progress` call at the end is enough. If one closes a
+roadmap, archive it first, then run the single regen. But the
+response must not end without it.
+
+## Why a rule, not just a skill tip
+
+The `roadmap-management` skill documents the command in several
+places, but skill body text is easy to miss under procedure pressure.
+A rule collapses the constraint into one line the model cannot skip:
+"checkbox edit → `task roadmap-progress` — same response".
+
+## Do NOT
+
+- Do NOT edit `agents/roadmaps-progress.md` by hand — always regenerate.
+- Do NOT defer regen to "next commit" or "before push" — same response.
+- Do NOT rely on `task ci` / `task roadmap-progress-check` as first line of defence — CI is last-line, not real-time.
+- Do NOT skip regen because "only one checkbox changed" — the dashboard aggregates counts and phase percentages that shift on single edits.
+- Do NOT leave a 100%-complete roadmap in `agents/roadmaps/` "for review" — archive same response, ask the user afterwards if needed, not before.
+- Do NOT regenerate the dashboard before the `git mv` when a roadmap closes — otherwise it reappears in "Open roadmaps".

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

@@ -0,0 +1,54 @@
+---
+type: "auto"
+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
+---
+
+# Role Mode Adherence
+
+Auto-activates when `.agent-settings.yml` sets `roles.active_role` to
+one of the six modes defined in
+[`role-contracts`](../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.
+
+When active, every closing output MUST:
+
+1. Use the contract fields in the declared order. No invented fields.
+   Missing evidence → single question (per `ask-when-uncertain`), never
+   a fabricated value.
+2. End with the structured mode marker:
+
+   ```
+   <!-- role-mode: <active_role> | contract: <kebab-case-fields> -->
+   ```
+
+3. Refuse work the contract forbids:
+   - `reviewer` — NEVER ships implementation; verdict + blockers only.
+   - `developer` — NEVER writes a review verdict on own change.
+   - `incident` — NEVER expands scope beyond the stated symptom.
+
+   Forbidden work → numbered prompt (per `user-interaction`): switch
+   mode, narrow scope, or clear mode.
+
+## Interactions
+
+- `scope-control` — adherence is stricter (mode may forbid work
+  scope-control would allow).
+- `verify-before-complete` — gate runs BEFORE the mode marker.
+
+## What this rule does NOT do
+
+Infer the mode (Phase-3 router does that). Modify `.agent-settings.yml`
+(only `/mode` writes). Change the contracts (guideline is source of truth).
+
+## See also
+
+- [`role-contracts`](../guidelines/agent-infra/role-contracts.md)
+- [`/mode`](../commands/mode.md)
+- [`ask-when-uncertain`](ask-when-uncertain.md)
+- [`scope-control`](scope-control.md)
+- [`verify-before-complete`](verify-before-complete.md)

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

@@ -0,0 +1,46 @@
+---
+type: "auto"
+description: "Creating or editing rules, or auditing rule types — decides when a rule should be always vs auto"
+alwaysApply: false
+source: package
+---
+
+# rule-type-governance
+
+## `always` = loaded every conversation
+
+Use ONLY when the rule applies to virtually every interaction:
+
+- Universal agent behavior (language, tone, interaction style)
+- Safety constraints (scope control, verification before completion)
+- Token/efficiency constraints
+- First-message checks that cannot wait for auto-trigger
+
+## `auto` = loaded on demand by description match
+
+Use for everything else:
+
+- Language-specific rules (PHP, JS, SQL)
+- Tool-specific rules (Docker, Git, quality tools)
+- Workflow-specific rules (commands, skill creation, E2E testing)
+- Domain-specific rules (translations, architecture)
+
+## Decision test
+
+> "Does this rule need to be active when the user asks a simple question, reviews a PR, or discusses architecture?"
+
+- Yes → `always`
+- No → `auto` with a clear trigger description
+
+## Auto description quality
+
+The `description` field IS the trigger. It must describe **when** the rule applies, not **what** it contains.
+
+- ❌  `"PHP coding standards"` — too vague, won't match reliably
+- ✅  `"Writing or reviewing PHP code — strict types, naming, Eloquent conventions"`
+
+## Hard constraint
+
+- Default to `auto`. Justify `always`.
+- If >50% of conversations don't need a rule → it must be `auto`.
+- `optimize-agents` command checks this and suggests changes.

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

@@ -0,0 +1,42 @@
+---
+type: auto
+source: package
+description: "When a skill declares execution metadata — enforce safety constraints for assisted and automated execution types"
+---
+
+# Runtime Safety
+
+## Core principle
+
+Execution is an extension of skills, not a replacement for reasoning or review.
+
+## Constraints
+
+- Default execution type is `manual` — skills without an execution block are instructional only
+- `assisted` execution must produce a proposal, never execute silently
+- `automated` execution requires:
+  - `handler` ≠ `none`
+  - `safety_mode: strict`
+  - Explicit `allowed_tools` declaration (can be empty `[]`)
+  - A verification step defined in the skill's steps
+- No arbitrary code execution — handlers are allowlisted values only
+- No bypass of rules, linter, or reviewer standards
+- No execution without declared intent in frontmatter
+
+## Allowed handler values
+
+`none`, `shell`, `php`, `node`, `internal`
+
+Any other value is a linter error.
+
+## Escalation
+
+If a skill's execution type or handler is unclear:
+1. Default to `manual`
+2. Ask the user before assuming `assisted` or `automated`
+
+## What this rule does NOT cover
+
+- Tool registry and permissions (see tool-integration roadmap)
+- Runtime hooks and error handling (see runtime hooks PR)
+- Async execution (not in scope for this phase)

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

@@ -0,0 +1,40 @@
+---
+type: "always"
+description: "Scope control — no unsolicited architectural changes, refactors, or library replacements"
+alwaysApply: true
+source: package
+---
+
+# Scope Control
+
+- Do NOT introduce architectural changes unless explicitly requested.
+- Do NOT replace existing patterns with alternatives.
+- Do NOT refactor existing code solely to comply with current rules.
+- Do NOT suggest new libraries unless explicitly requested.
+- Existing code should only be modified if directly related to the current change, required for bug fixes, security, or explicitly requested.
+- New or newly modified code MUST follow all coding rules.
+- Stay within the established project structure and conventions.
+- When unsure about the scope, ask the user.
+
+## Git operations — permission-gated
+
+The user decides the git shape of the work.
+
+- 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 push a tag or create a release without explicit user permission.
+- 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.

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

@@ -0,0 +1,77 @@
+---
+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"
+source: package
+---
+
+# Security-Sensitive Stop Rule
+
+Before editing any file that matches a security-sensitive surface, **stop and
+run a threat analysis first**. Shipping a security-sensitive change without a
+prior threat pass is the #1 driver of authorization and data-exposure bugs.
+
+## What counts as security-sensitive
+
+A file or planned change is security-sensitive when **any** of the following
+is true:
+
+| Surface | Examples |
+|---|---|
+| Authentication | login, session, token issuance, password reset, 2FA, SSO |
+| Authorization | policies, gates, voters, middleware that gates actions, admin checks |
+| Tenancy | tenant scope / `tenant_id` / row-level security / per-tenant keys |
+| Billing / money | charge, refund, subscription, invoice, balance, credit |
+| Secrets | API keys, tokens, signing keys, `.env`, vault, KMS, OAuth client secrets |
+| File uploads | any endpoint that accepts user files or URLs for files |
+| External integrations | outbound HTTP to third parties, webhooks, queue consumers from external sources |
+| Public endpoints | any route with no auth gate (including health/status) |
+| Data exposure | API resources, serializers, exception renderers, log channels, admin panels |
+
+If the change touches any of these, the rule fires.
+
+## What to do when it fires
+
+STOP writing code. Run the matching analysis skill first:
+
+| Change type | Analysis skill |
+|---|---|
+| New or modified permission / tenant check | `authz-review` |
+| New feature touching any surface above | `threat-modeling` |
+| Data flows to logs / API / external | `data-flow-mapper` |
+| 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):
+
+```python
+from scripts.memory_lookup import retrieve
+priors = retrieve(
+    types=["incident-learnings", "historical-patterns"],
+    keys=<touched file paths>,
+    limit=3,
+)
+```
+
+A prior security incident on the same path is the cheapest input to a
+threat pass — cite any matching `id` so the required control or
+regression test ships with the fix.
+
+Capture the analysis output (abuse cases, missing controls, required
+negative tests) — implement against that list, not your first instinct.
+Never silently fall back to editing without the analysis; if blocked,
+ask the user.
+
+## When NOT to fire
+
+Typo/comment-only edits · test-only edits without behavior change · automated
+tooling output (lockfile, generated code) the user explicitly requested.
+These still deserve review, but do not require a full threat pass.
+
+## Rationale
+
+Authorization and tenancy bugs are often invisible in logs and fire silently
+until an auditor or attacker finds them. The cheapest moment to catch them
+is before the first edit — this rule makes that the default path.
+
+See also: `threat-modeling` · `authz-review` · `data-flow-mapper` · `minimal-safe-diff` · `think-before-action`.

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

@@ -0,0 +1,29 @@
+---
+type: "auto"
+description: "Creating or editing rules, skills, commands, guidelines, AGENTS.md, or copilot-instructions.md — enforce size and scope limits"
+alwaysApply: false
+source: package
+---
+
+# size-enforcement
+
+- Split by responsibility, not by length.
+
+- Rules must stay short, constraint-only, and easy to scan.
+- Skills must remain executable with clear workflow and validation.
+- Commands must orchestrate, not implement detailed workflows.
+- Guidelines must not replace skill execution.
+- AGENTS.md must stay high-level and not contain workflows.
+- copilot-instructions.md must stay short and behavioral.
+
+- If a component grows too large, mixes responsibilities, or becomes hard to scan → split or refactor.
+
+- Prefer small files:
+  - 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`
+
+→ Frontmatter contract (required/optional keys per type):
+[`agents/docs/frontmatter-contract.md`](../../../agents/docs/frontmatter-contract.md).
+Schemas live in `scripts/schemas/` and are enforced by `task validate-schema`.

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

@@ -0,0 +1,58 @@
+---
+type: "auto"
+description: "After completing a meaningful task — trigger post-task learning capture if pipelines.skill_improvement is enabled"
+alwaysApply: false
+source: package
+---
+
+# Skill Improvement Trigger
+
+## When to activate
+
+Read `pipelines.skill_improvement` from `.agent-settings.yml`.
+
+- **If `false` or missing** → do nothing. Stop here.
+- **If `true`** → continue.
+
+## What counts as "meaningful task"
+
+Trigger after completing tasks that involve:
+- Debugging a non-trivial bug (root cause wasn't obvious)
+- Implementing a feature that required learning something new
+- A pattern that worked well and should be remembered
+- A mistake that cost >5 minutes to diagnose
+- A workaround for a tool limitation
+
+## What does NOT trigger
+
+- Config changes, typos, docs-only edits
+- Routine tasks with no surprises
+- Tasks where the agent is just following instructions step by step
+- Tasks shorter than 3 messages
+
+## Trigger behavior
+
+After completing a qualifying task, do a **quick mental check** (not a full workflow):
+
+1. Was there a concrete, actionable learning?
+2. Is it generalizable (not project-specific one-off)?
+3. Is it NOT already covered by an existing rule or skill?
+
+If all 3 are YES → propose to the user:
+
+```
+> 💡 Learning detected: "{one-sentence summary}"
+>
+> 1. Capture & improve — run the improvement pipeline
+> 2. Skip — not worth capturing
+```
+
+If user picks 1 → invoke the `skill-improvement-pipeline` skill.
+If user picks 2 → stop, do not ask again for this task.
+
+## Important
+
+- **Never auto-run the pipeline** — always ask first.
+- **Max 1 trigger per task** — don't ask repeatedly.
+- **Be honest** — if the learning is vague ("be more careful"), skip it silently.
+- **Do not interrupt the user's flow** — only trigger AFTER the task is done.