@event4u/agent-config 1.9.1

package/.agent-src/guidelines/agent-infra/agent-interaction-and-decision-quality.md

@@ -0,0 +1,110 @@
+# agent-interaction-and-decision-quality
+
+Improves how the agent asks questions, handles uncertainty, learns from feedback,
+and integrates quality rules into CI.
+
+## Core principles
+
+- Do not guess when clarification is cheap
+- Do not overwhelm the user with too many complex questions at once
+- Prefer structured decision-making over assumptions
+- Learn from negative feedback and turn it into system improvements
+- Integrate recurring improvements into rules, skills, or CI
+
+## 1. Question strategy
+
+### Simple decisions
+
+If questions are simple binary or small choices — ask multiple at once, numbered clearly:
+
+```
+1. Use Tailwind or existing styles?
+2. Add tests? (yes/no)
+3. Extend existing component or create new one?
+```
+
+### Complex questions
+
+If questions require thinking, context-create, or explanation:
+
+- Ask ONE question at a time
+- Wait for answer before continuing
+- Do not bundle multiple complex topics together
+
+### Handoff / model-switch questions
+
+If a handoff (e.g. model change, deeper analysis) is required:
+
+1. First ask all necessary domain questions (step-by-step if complex)
+2. Then ask the handoff question LAST
+
+Reason: answers must be available before switching context — avoids incomplete downstream instructions.
+
+## 2. No blind implementation
+
+Before implementing, analyze what already exists:
+
+- Identify used frameworks, libraries, patterns
+- If multiple UI systems exist (e.g. Tailwind, shadcn, custom): ask which one to use
+- Do NOT pick one arbitrarily or start implementation without alignment
+
+## 3. Handling unclear requirements
+
+If instructions are incomplete:
+
+- Do NOT assume missing behavior
+- Do NOT silently decide critical aspects
+- Ask precise clarification questions or output a structured clarification request
+
+## 4. Learning from negative feedback
+
+If the user complains, says something is wrong, or shows frustration:
+
+1. Do NOT ignore or defend blindly
+2. Extract the underlying failure pattern
+3. Convert it into one of:
+   - Rule (constraint to prevent recurrence)
+   - Skill improvement (better workflow step)
+   - Guideline addition (reference convention)
+   - Linter check (if recurring and automatable)
+
+> Every mistake should improve the system.
+
+## 5. CI integration mindset
+
+When introducing new quality patterns, consider whether they should be enforced automatically.
+
+If unsure, ask:
+- "Should this be enforced via CI?"
+- "Should this be part of the linter?"
+
+Prefer consistent enforcement over manual discipline.
+
+## 6. Decision transparency
+
+When making decisions:
+
+- State what you assumed
+- State what alternatives exist
+- State why a decision was made
+- If the decision is important: confirm with the user before proceeding
+
+## 7. Efficiency in interaction
+
+- Avoid long back-and-forth caused by poor initial questions
+- Avoid rework caused by wrong assumptions
+- Prefer: short clarification early → correct implementation once
+
+## Anti-patterns
+
+- Asking 5 complex questions at once
+- Mixing clarification and implementation in the same step
+- Doing handoff before collecting required context
+- Blindly choosing frameworks/tools without checking existing usage
+- Ignoring user frustration instead of learning from it
+- Introducing new quality rules without considering CI enforcement
+- Making important decisions silently without stating reasoning
+
+## Final principle
+
+> Ask better → decide better → build once → improve system continuously

package/.agent-src/guidelines/agent-infra/break-glass-usage.md

@@ -0,0 +1,113 @@
+# Break-Glass Usage
+
+Guideline for operating the agent under a controlled emergency state —
+when a production incident requires faster stabilization than normal
+verification allows.
+
+Break-glass is **a narrowing, not a bypass**. The rules still apply; the
+gate is just smaller. Never decide to "break glass" unilaterally.
+
+## When break-glass is justified
+
+All of the following must hold:
+
+- **Active customer-impacting incident** — data loss, outage, security
+  exposure, billing regression. Not "we have a deadline".
+- **Explicit user invocation** — the user says "break-glass" or
+  "hotfix, skip the full suite". Ambiguous wording is not enough; ask.
+- **No viable rollback path** that would be faster than the forward fix.
+
+Not a break-glass situation:
+
+- Friday afternoon and you want to ship a feature.
+- CI is slow and you want to skip tests.
+- You can't reproduce a flaky test locally.
+- A reviewer is asleep and you want to self-approve.
+
+## How to invoke
+
+The user sets one of:
+
+1. **Conversation flag** — says "break-glass: true" or "this is a hotfix".
+2. **PR label** — `break-glass` on the PR (optional; the agent still
+   requires explicit invocation in the current turn).
+3. **Commit trailer** — `Break-Glass: <incident-id>` in the commit
+   message of the hotfix.
+
+The agent confirms: "Entering break-glass — narrowing verification to
+targeted test + smoke check. Follow-up PR required within 24h. Confirm?"
+If the user agrees, proceed. If not, stay in the normal gate.
+
+## What narrows
+
+| Layer | Normal gate | Break-glass |
+|---|---|---|
+| Tests | Targeted + full suite | Targeted only — covering the regression |
+| Quality tools | PHPStan + Rector + ECS | Deferred to follow-up PR |
+| Migrations review | Full dry-run + rollback check | Dry-run only, rollback note mandatory |
+| Code review | ≥ 1 reviewer from required roles | 1 reviewer, can be post-merge |
+| Changelog | Required | Deferred to follow-up PR |
+
+Zero tests is **never** acceptable. If the incident fix genuinely cannot
+be tested in the available time, document that explicitly and attach a
+reproducer to the follow-up ticket.
+
+## What does NOT narrow
+
+These rules stay fully in force, break-glass or not:
+
+- [`minimal-safe-diff`](../../rules/minimal-safe-diff.md) — the hotfix is
+  still the **smallest** change that stops the bleeding. No drive-by
+  cleanups.
+- [`security-sensitive-stop`](../../rules/security-sensitive-stop.md) — a
+  security-relevant change still needs the threat-model pass.
+- [`scope-control`](../../rules/scope-control.md) — never mix the
+  hotfix with unrelated refactors from another branch.
+- [`ask-when-uncertain`](../../rules/ask-when-uncertain.md) — more
+  asking, not less, when the blast radius is live.
+
+## Required artifacts
+
+The hotfix PR must include, in the description:
+
+1. **Incident link** — ticket, Sentry issue, or Statuspage entry.
+2. **Skipped validations** — bullet list of what was deferred (e.g.
+   "full PHPUnit suite", "PHPStan", "Rector").
+3. **Evidence attached in-PR** — targeted test output, smoke-check log or
+   curl response, migration dry-run if applicable.
+4. **Follow-up commitment** — link to the follow-up ticket or PR that
+   will run the full gate. Due within 24h.
+
+## After the incident
+
+Within 24 hours:
+
+1. Open the **follow-up PR** — runs the full verification gate against
+   the same branch or a rebase onto main.
+2. Write a short **incident note** (2–5 lines) — what failed, what the
+   hotfix did, what was deferred. Store in the project's postmortem
+   location.
+3. If the incident exposed a recurring failure mode, add an entry to
+   `historical-bug-patterns.yml` (see
+   [`review-routing-data-format`](review-routing-data-format.md)).
+
+## Anti-patterns — reject them
+
+- "Break-glass" used as a label for every urgent task — the word stops
+  meaning anything.
+- Shipping the hotfix **and** a refactor in the same commit "since the
+  file was open".
+- Skipping the follow-up PR because "the hotfix was fine". The gate
+  runs once, not zero times.
+- Logging the incident as "false alarm" when the hotfix actually
+  changed behavior. If behavior changed, write the note.
+
+## See also
+
+- [`minimal-safe-diff`](../../rules/minimal-safe-diff.md) — break-glass
+  exception section.
+- [`verify-before-complete`](../../rules/verify-before-complete.md) —
+  break-glass reduction section.
+- [`security-sensitive-stop`](../../rules/security-sensitive-stop.md).
+- [`review-routing-data-format`](review-routing-data-format.md) —
+  where to register newly-discovered failure modes.

package/.agent-src/guidelines/agent-infra/developer-judgment.md

@@ -0,0 +1,82 @@
+# Developer Judgment Guideline
+
+When the agent should challenge, when it should ask, and when it should just execute.
+
+## Decision table
+
+| Situation | Agent behavior | Max delay |
+|---|---|---|
+| Clear, well-defined request | Execute immediately | 0 |
+| Minor ambiguity | Ask ONE clarifying question | 10s |
+| Request overlaps existing code | Point out existing solution | 15s |
+| Request contradicts architecture | Challenge with evidence, propose alternative | 30s |
+| Request is technically harmful | Warn, propose safe alternative | 30s |
+| User insists after challenge | Execute immediately | 0 |
+| Simple task (config, typo, docs) | Never challenge | 0 |
+
+## What makes a good challenge
+
+✅ **Good challenge:**
+- References specific files or code
+- Offers a concrete alternative
+- Fits in 2-3 sentences
+- Ends with numbered options
+
+❌ **Bad challenge:**
+- Vague ("this might be problematic")
+- No alternative offered
+- Long explanation before the point
+- Blocks work without clear reason
+
+## Examples
+
+### Good: Existing functionality
+
+```
+> ⚠️ `UserService::deactivate()` (app/Services/UserService.php:45) already handles
+> account deactivation with email notification.
+>
+> 1. Extend existing method with the new parameter
+> 2. Create separate method — I'll document the overlap
+```
+
+### Good: Architecture concern
+
+```
+> ⚠️ This would create a direct dependency from Module A to Module B's internals.
+> The current pattern uses events for cross-module communication.
+>
+> 1. Use an event instead (follows existing pattern)
+> 2. Add direct dependency (I'll add a note about the coupling)
+```
+
+### Bad: Vague concern
+
+```
+> I'm not sure this is the best approach. There might be issues with this design.
+> Should I look into alternatives?
+```
+
+→ This wastes the user's time. Either have a specific concern or don't raise one.
+
+## Integration with rules and skills
+
+| Component | Role |
+|---|---|
+| `improve-before-implement` rule | Triggers validation on feature/architecture tasks |
+| `validate-feature-fit` skill | Deep analysis when rule detects potential misfit |
+| `ask-when-uncertain` rule | General uncertainty handling (complementary) |
+| `think-before-action` rule | Analysis-first workflow (complementary) |
+
+## The spectrum of judgment
+
+```
+Silent ────────────────── Challenging ──────────────── Blocking
+  ↑                           ↑                          ↑
+  Bug fixes                   Features                   NEVER
+  Config                      Architecture
+  Docs                        New patterns
+```
+
+The agent NEVER reaches "Blocking". The right side of the spectrum is
+"Challenge and let the user decide", never "refuse to implement".

package/.agent-src/guidelines/agent-infra/engineering-memory-data-format.md

@@ -0,0 +1,117 @@
+# Engineering Memory Data Format
+
+Schema and conventions for the four project-local YAML files that
+extend the memory layer beyond `ownership-map` and
+`historical-bug-patterns` (those are covered in
+[`review-routing-data-format`](review-routing-data-format.md)).
+
+All four files are **optional** and live in the consumer repository —
+never in package-shipped artifacts. Absence is handled gracefully:
+consulting skills fall through to their generic behaviour.
+
+This guideline replaces the *"one guideline per schema"* plan from
+`road-to-engineering-memory.md` with a single consolidated reference,
+matching the existing pattern established by `review-routing-data-format`.
+
+## File locations
+
+Each schema lives under `agents/memory/<type>/<hash>.yml` (content-addressed,
+merge-safe — see [`road-to-memory-merge-safety.md`](../../../agents/roadmaps/road-to-memory-merge-safety.md))
+**or** in a single `agents/memory/<type>.yml` file for projects that prefer
+one file per type.
+
+| Type | Single-file path | Sharded path |
+|---|---|---|
+| Domain invariants | `agents/memory/domain-invariants.yml` | `agents/memory/domain-invariants/<hash>.yml` |
+| Architecture decisions | `agents/memory/architecture-decisions.yml` | `agents/memory/architecture-decisions/<hash>.yml` |
+| Incident learnings | `agents/memory/incident-learnings.yml` | `agents/memory/incident-learnings/<hash>.yml` |
+| Product rules | `agents/memory/product-rules.yml` | `agents/memory/product-rules/<hash>.yml` |
+
+Choose one layout per type and stick with it. `scripts/check_memory.py`
+warns if both exist for the same type.
+
+## Shared frontmatter fields
+
+Every entry across all four types MUST carry these keys. The gate
+rejects entries missing any required field.
+
+| Key | Required | Type | Notes |
+|---|---|---|---|
+| `id` | yes | kebab-case slug | unique within the type |
+| `status` | yes | `active` \| `deprecated` \| `archived` | lifecycle |
+| `confidence` | yes | `low` \| `medium` \| `high` | reader weights accordingly |
+| `source` | yes | list of URLs / ADR refs | ≥1 entry |
+| `owner` | yes | team slug | who keeps this entry fresh |
+| `last_validated` | yes | ISO date | stale check per type |
+| `review_after_days` | yes | integer | triggers staleness warning |
+
+## Type-specific required fields
+
+Each file also carries the template-specific body. See the example
+templates for the full shape:
+
+- [`domain-invariants.example.yml`](../../templates/agents/memory/domain-invariants.example.yml)
+  adds `rule`, `boundary`, `scope.paths`, `violation_contract`.
+- [`architecture-decisions.example.yml`](../../templates/agents/memory/architecture-decisions.example.yml)
+  adds `title`, `context`, `decision`, `alternatives_rejected`,
+  `trade_offs`, `paths`, `superseded_by`.
+- [`incident-learnings.example.yml`](../../templates/agents/memory/incident-learnings.example.yml)
+  adds `pattern`, `trigger_conditions`, `consequence`, `guardrail`,
+  `enforcement`, `severity`.
+- [`product-rules.example.yml`](../../templates/agents/memory/product-rules.example.yml)
+  adds `rule`, `applies_to`, `enforcement`, `error_contract`, `version`.
+
+## Ownership (who writes, who reads)
+
+| Type | Writer | Reader (skill/role) | Expiry |
+|---|---|---|---|
+| Domain invariants | senior engineer / architect | `developer-like-execution`, `php-coder`, `laravel` | reviewed at major version bump |
+| Architecture decisions | decision author at ADR time | `feature-plan`, `api-design`, `blast-radius-analyzer` | `deprecated` on reversal; never deleted |
+| Incident learnings | incident commander post-resolution | `Incident` role, `bug-investigate`, `bug-analyzer` | archived when guardrail lands + verified in prod |
+| Product rules | PO or tech lead post-decision | `PO` role, `validate-feature-fit`, `laravel-validation` | version-stamped; old versions archived |
+
+## Redaction rules (hard)
+
+Enforced by `scripts/check_memory.py`. Reject on match:
+
+- **No secrets.** API keys, tokens, credentials, private URLs with
+  credentials, internal hostnames that expose infrastructure.
+- **No customer names.** ACME Corp, specific account IDs, domain
+  names of real customers. Rephrase to the pattern.
+- **No PII.** Names, emails, phone numbers, IP addresses tied to
+  real users. Incident-learnings is tempting here — resist.
+- **No ticket IDs that identify the incident** in
+  `incident-learnings.yml`. Link the guardrail PR instead.
+
+## Reader contract
+
+Consuming skills read an entry and expose its `status` + `confidence`
+to the agent. A `confidence: low` domain invariant informs, it does not
+dictate. A `confidence: high` incident learning blocks the generation
+path if the guardrail is absent.
+
+## Staleness
+
+`check_memory.py` runs weekly (not per-PR). It reports entries where
+`(today - last_validated) > review_after_days`. Stale entries stay
+active — the report is informational, not a gate.
+
+## Anti-patterns
+
+- **Do NOT** merge `ownership-map.yml` semantics into these files.
+  Ownership is a separate concern; mixing them doubles the staleness
+  surface.
+- **Do NOT** generate entries via LLM in bulk. Curated is the point.
+  The point of a `confidence: high` entry is human-verified claim,
+  not high-volume output.
+- **Do NOT** delete `deprecated` or `archived` entries. History is
+  the value of memory; deletion is amnesia.
+- **Do NOT** ship this file pre-populated. Each consumer starts
+  empty and fills as decisions and incidents accumulate.
+
+## See also
+
+- [`road-to-engineering-memory.md`](../../../agents/roadmaps/road-to-engineering-memory.md) — roadmap this guideline implements
+- [`road-to-memory-merge-safety.md`](../../../agents/roadmaps/road-to-memory-merge-safety.md) — why content-addressed files
+- [`review-routing-data-format.md`](review-routing-data-format.md) — sibling format for ownership + bug patterns
+- [`road-to-role-modes.md`](../../../agents/roadmaps/road-to-role-modes.md) — role modes that consume these files

package/.agent-src/guidelines/agent-infra/layered-settings.md

@@ -0,0 +1,158 @@
+# Layered Settings
+
+Two-file settings model: **team defaults** (committed) and
+**developer overrides** (git-ignored). Lets a project pin decisions
+without forcing every developer to work the same way.
+
+Referenced by `road-to-project-memory.md` Phase 0. Consumed by the
+`config-agent-settings` command and the settings loader.
+
+## The two files
+
+| File | Git | Scope | Owner | Example values |
+|---|---|---|---|---|
+| `.agent-project-settings.yml` | **committed** | team / repo | lead maintainer | `project.stack`, `quality.php.tools`, `memory.dogfood` |
+| `.agent-settings.yml` | **gitignored** | developer workstation | individual | `personal.ide`, `personal.user_name`, `subagents.max_parallel` |
+
+Both are YAML. Schema is documented in
+[`agent-settings.md`](../../templates/agent-settings.md) (dev layer)
+and [`agent-project-settings.example.yml`](../../templates/agents/agent-project-settings.example.yml)
+(team layer).
+
+## Merge order
+
+Lowest priority → highest priority:
+
+```
+1. Package defaults       (shipped by event4u/agent-config)
+2. .agent-project-settings.yml   (team file, committed)
+3. .agent-settings.yml           (developer file, gitignored)
+```
+
+Keys from higher layers win unless the lower layer marks them
+`locked`. Locked keys cannot be shadowed by a higher layer.
+
+## Lock semantics
+
+`.agent-project-settings.yml` has a top-level `locked_keys` list.
+Any key listed there cannot be overridden from `.agent-settings.yml`:
+
+```yaml
+# .agent-project-settings.yml
+quality:
+  php:
+    tools: [phpstan, rector, ecs]
+
+locked_keys:
+  - quality.php.tools
+```
+
+Even if a developer's `.agent-settings.yml` sets
+`quality.php.tools: [pint]`, the resolved value stays
+`[phpstan, rector, ecs]`. The loader emits a one-line warning
+when it ignores a locked override.
+
+### When to lock
+
+- **Correctness** — test framework, database driver, seeder ordering.
+- **Compliance** — code style enforced by CI.
+- **Team-wide rituals** — mandatory pre-commit checks.
+
+### When NOT to lock
+
+- Personal preferences — IDE, output verbosity, name.
+- Performance knobs the developer should tune to their hardware.
+- Anything that slows down onboarding without a correctness payoff.
+
+Err on the side of **not** locking. Every locked key reduces
+autonomy. Unlock by removing the entry from `locked_keys` — no
+migration needed.
+
+## Migration from a single file
+
+Repos that currently ship only `.agent-settings.yml` (often
+mistakenly committed) migrate by:
+
+1. Create `.agent-project-settings.yml` from the example template.
+2. Move team-wide keys (`project.*`, `quality.*`, `memory.*`,
+   `review_routing.*`, `roles.*`) into the new file.
+3. Leave personal keys (`personal.*`, `subagents.*`, `github.*`)
+   in `.agent-settings.yml`.
+4. Commit `.agent-project-settings.yml`.
+5. Confirm `.agent-settings.yml` is in `.gitignore`; add it if not.
+6. Remove any previously-committed `.agent-settings.yml` from the
+   repo history only if it leaked personal tokens. Otherwise leave
+   it — future commits supersede.
+
+The `config-agent-settings` command performs steps 1–3 and 5
+automatically when it detects a one-file setup.
+
+## .gitignore expectations
+
+```
+# .gitignore
+.agent-settings.yml              # developer-local, NEVER committed
+.agent-settings.backup.*         # migration backups
+!.agent-project-settings.yml     # explicitly NOT ignored
+```
+
+The final negated entry protects the team file if a broader
+pattern (e.g. `*.yml` in a nested folder) would otherwise match.
+
+## Consumption
+
+- **Skills** read settings via the loader, never by parsing YAML
+  directly. The loader returns the merged view already.
+- **Commands** that mutate settings must state which layer they
+  write to. Writing to the wrong layer is a spec bug.
+- **`config-agent-settings`** is the single writer for both files.
+  Other commands MUST delegate — no ad-hoc YAML edits.
+
+## Persona-list merge semantics
+
+Persona configuration does **not** follow the simple "higher layer
+wins" rule — lists merge with explicit override and ignore hooks.
+
+| Key | Layer | Role |
+|---|---|---|
+| `personas.default` | project | Team default cast (list of ids) |
+| `personas.specialists.auto_include` | project | Specialists auto-added on every multi-lens run |
+| `personas.override` | developer | Full replacement of `personas.default` for this developer (empty = inherit) |
+| `personas.ignore` | developer | Ids dropped from the effective cast |
+| `.augmentignore` | workstation | Persona files physically hidden from the agent |
+
+**Resolution order** for the effective cast of a multi-lens skill:
+
+1. Start with `personas.default` from the project file.
+2. If `personas.override` is non-empty, **replace** the list (not merge).
+3. Add every id from `personas.specialists.auto_include`.
+4. Remove every id from `personas.ignore`.
+5. Remove every id whose file is matched by `.augmentignore`.
+6. If the skill's own frontmatter pins `personas: [...]`, that wins
+   over all of the above — the skill is the authority for its own
+   cast.
+
+An id removed in step 4 or 5 stays **invokable** via explicit
+`--personas=<id>` on the skill invocation. Ignore hides the id from
+the default cast; it does not blacklist it.
+
+If the project locks `personas.default` via `locked_keys`, steps 2
+and 4 are ignored with a one-line warning — the developer cannot
+narrow a team-locked cast.
+
+## Anti-patterns
+
+- **Do NOT** commit `.agent-settings.yml`. It contains developer
+  identity and potentially secrets.
+- **Do NOT** put personal preferences in `.agent-project-settings.yml`.
+  The team file is not a place to publish your IDE choice.
+- **Do NOT** lock every key "just to be safe". Locking is an
+  intervention, not a default.
+- **Do NOT** merge settings in skill code. The loader owns the
+  merge; duplicating it creates drift.
+
+## See also
+
+- [`agent-settings.md`](../../templates/agent-settings.md) — dev-layer schema
+- [`agent-project-settings.example.yml`](../../templates/agents/agent-project-settings.example.yml) — team-layer template
+- [`road-to-project-memory.md`](../../../agents/roadmaps/road-to-project-memory.md) — roadmap this guideline implements