@event4u/agent-config 14.23.0 → 15.0.0

package/dist/agent-src/guidelines/agent-infra/output-patterns.md

@@ -0,0 +1,117 @@
+# Output Patterns
+
+Reference patterns for token-efficient command execution and output handling.
+Referenced by the `token-efficiency` rule.
+
+## Pattern: Redirect, Summarize, Target
+
+Every command that MAY produce more than ~30 lines of output:
+
+### Step 1: Redirect to file
+
+```bash
+docker compose exec -T <service> <command> 2>&1 > /tmp/<tool>-output.txt
+echo "EXIT=$?"
+```
+
+### Step 2: Read ONLY the summary
+
+```bash
+tail -5 /tmp/<tool>-output.txt
+```
+
+### Step 3: If errors exist, read ONLY what you need to fix
+
+```bash
+# Read specific error lines
+grep "ERROR\|error\|✏️" /tmp/<tool>-output.txt | head -20
+
+# Read a specific file's errors
+grep "app/Services/MyService.php" /tmp/<tool>-output.txt
+```
+
+**NEVER** do:
+
+- `cat /tmp/<tool>-output.txt` (loads everything)
+- Read the full output of a passing command (waste)
+- Read diffs you don't plan to act on
+
+---
+
+## Targeted Operations
+
+Minimize scope. Never fetch more than you need.
+
+### Queries and lookups
+
+- **Single item over list**: query directly, don't fetch list to find one entry.
+- **Filtered queries**: always filter when listing unavoidable. `--filter=ClassName` not `--all`.
+- **Specific fields**: request only needed fields.
+- **JSON + jq**: use JSON output + `jq` to extract exactly what you need.
+
+### Testing
+
+- **During work**: ONLY the specific test affected (`--filter=ClassName`).
+- **Broader scope**: only if change could affect other tests.
+- **Full suite**: only at the very end.
+- **Decision tree**:
+  1. Changed one method → run that method's test
+  2. Changed a class → run that class's test file
+  3. Changed a shared service → run tests for all consumers
+  4. Changed config/infrastructure → full suite
+
+### API calls
+
+- Targeted endpoints over list endpoints
+- Small page sizes, stop after finding what you need
+- Don't re-fetch what you just received
+
+---
+
+## Tool-First, Script-Last
+
+**Prefer skills with CLI tools over custom scripts.**
+
+### Hierarchy
+
+1. **Existing skill** — use directly
+2. **Skill + CLI tool** (jq, grep, awk, sed) — compose
+3. **Python/Bash script** — only when no skill/tool combination exists
+
+### Scripts allowed only when
+
+- No skill covers the workflow
+- No CLI tool achieves the goal
+- Operation needs programmatic logic
+- Script is reusable
+
+### Scripts NOT allowed when
+
+- Skill exists for this workflow
+- `jq` can extract what you need
+- `grep` + `head` can filter output
+
+### Learning trigger
+
+When you write a script because no skill exists → capture learning → propose skill.
+
+---
+
+## General Rules
+
+For tool-specific commands → see the `quality-tools` skill.
+
+1. **ECS and Rector are trusted tools** — run with `--fix`, don't read diffs. Trust the config.
+   Verification: PHPStan + tests afterwards.
+
+2. **Both ECS and Rector always run with `--fix`** — dry-run diffs waste tokens.
+
+3. **Exit code first**: Check `$?` before reading ANY output. If 0, you're done.
+
+4. **Summary line**: Most tools print a summary as the last few lines. That's all you need.
+
+5. **Targeted grep**: `grep` for the specific file or error type. Never read full output "just in case".
+
+6. **Don't re-read**: Once read and acted on, don't re-load into context.
+
+7. **Iterative fixing**: Fix one error, re-run, check exit code. Output becomes stale after each fix.

package/dist/agent-src/guidelines/agent-infra/recurring-criticism-mechanics.md

@@ -0,0 +1,96 @@
+# Recurring-criticism mechanics
+
+> Depth for the `recurring-criticism` rule — the past-disposition store list, the mechanism-is-the-defect classification, the hardening floor, and the failure-mode catalog.
+
+_No YAML frontmatter, deliberately: every other guideline under `docs/guidelines/`
+is frontmatter-less, and a `name:` key here makes the two MCP resource loaders
+derive different URIs for the same file — one from the key
+(`guideline://recurring-criticism-mechanics`), one from the path
+(`guideline://agent-infra/recurring-criticism-mechanics`). That is a
+`mcp_parity_smoke` drift, and it only surfaces once `dist/cli/agent-config.js`
+is built, so the local suite passes and CI does not._
+
+Depth for [`recurring-criticism`](../../rules/recurring-criticism.md). The
+rule carries the obligation; this carries the lookup addresses and the reasoning
+that would otherwise be paid in every session — that rule is phrase-triggered, and
+a phrase-triggered rule is unconditionally loaded on Claude (the emitter writes no
+`paths:` when any non-path trigger is present), so every line in it is a line every
+session pays for. This file is read on demand.
+
+## Look it up before re-deriving it
+
+Without a mechanism that forces a reference to the earlier disposition, every
+recurrence becomes a fresh investigation even where the answer already exists
+<!-- harvest:forced-lookup-of-past-root-causes -->. The stores are fragmented and
+only partly queryable, so **name which one you checked**:
+
+| Store | Path | Queryable? |
+|---|---|---|
+| ADRs + index | `docs/decisions/` + `INDEX.md`, via `adr_cite_check <ADR-NNN>` | yes — status, `review_trigger` state, successors |
+| Estate / activation / low-impact dispositions | `agents/decisions/*.yml`, `agents/decisions/low-impact-decisions.md` | yes, closed vocabularies |
+| Roadmap dispositions | `agents/roadmaps/{archive,skipped,later}/` | `later/` only; `skipped/` carries its reason as header prose |
+| Curated memory | `agents/memory/*.yml` | yes |
+| Analysis documents | `agents/evidence/analysis/` | grep only |
+| Harvest / borrow ledgers | `provenance/*.jsonl` | yes, but `adopt`/`adapt` only |
+
+**Rejections are the weak spot, and by design.** `provenance/README.md` states that
+a `reject` verdict lives in the analysis document rather than a ledger, because
+nothing in the tree cites it. So "I found nothing" here means *unstructured prose
+was grepped*, never *nothing was decided*. Say which of the two you mean — the
+difference decides whether the recurrence is new information or a lookup failure.
+
+## The mechanism is the candidate defect, not the item
+
+Classify what was missing before choosing an artefact — the taxonomy in
+[`skill-improvement-pipeline`](../../skills/skill-improvement-pipeline/SKILL.md)
+§ Classify the missing component (instruction · source-of-truth · tool · validator ·
+permission · sandbox · evaluation · recovery-path) is the one to use, because "add
+another rule" is the answer that feels right and is usually wrong.
+
+Then land the learning where it **constrains** the next run, per
+[`learning-to-rule-or-skill`](../../skills/learning-to-rule-or-skill/SKILL.md).
+A lesson that does not narrow the next attempt produces thrashing rather than
+convergence <!-- harvest:unconstraining-lesson-thrashes -->; a learning that lives
+only in a reply is not a learning, it is a note.
+
+**Third recurrence of the same class escalates to structure** —
+[`decision-review`](../../skills/decision-review/SKILL.md) § Escalation owns
+the threshold, and its point is worth restating: a louder restatement of a rule the
+agent keeps missing is the one response already known not to work. At that point
+the choice is a deterministic gate or deletion, not more prose.
+
+## The hardening floor
+
+Self-improvement loops can regress the artefact they improve
+<!-- harvest:self-improvement-can-self-regress -->. Two consequences:
+
+- A hardening change carries the **same evidence bar** as any other change. "We
+  learned something" is not a licence, and a mechanism proposed in response to a
+  recurrence still needs a measured false-positive rate before it becomes CI.
+- It never arrives as a **weakened** gate, a widened allowlist, a lifted Hard
+  Floor, or a loosened ratchet. If the only available hardening lowers a floor, the
+  recurrence escalates to the owner instead — that transition is owner-reserved per
+  [`decision-revisit-gate`](../../rules/decision-revisit-gate.md) § Who
+  decides.
+
+## Failure modes
+
+- **Resolving on the count.** "You have said it three times, so you are right" is
+  the sycophancy failure with a procedure attached. The count opens the question.
+- **Resolving on the count, inverted.** "It is only the second time, so the old
+  call stands" — the repetition still shifted the burden of proof.
+- **Naming no outcome.** A resolution that does not say which of the three applies
+  (decision wrong · never recorded · unreachable) has not resolved anything.
+- **Grepping prose and reporting absence.** See the rejection note above.
+- **Treating a resemblance as a recurrence.** Mechanism-match runs first; a new
+  complaint that tests a different mechanism is a new finding.
+- **Hardening the item instead of the mechanism.** Fixing the one instance leaves
+  the surface that dismissed it intact, which is what produces the fourth
+  recurrence.
+- **Writing the learning into the reply.** It has to land in an artefact.
+
+## See also
+
+- [`recurring-criticism`](../../rules/recurring-criticism.md) — the obligation.
+- [`decision-revisit-gate`](../../rules/decision-revisit-gate.md) — the other entrance (a lock blocking a change), the five steps, the owner-reserved table.
+- [`self-repair-loop`](../../rules/self-repair-loop.md) — the single-occurrence intake and the `occurrences` counter this rule consumes.

package/dist/agent-src/guidelines/agent-infra/reuse-verdict-mechanics.md

@@ -0,0 +1,71 @@
+# Reuse-verdict mechanics — the verdict set, the cheap question, and the routing that was refused
+
+> The detail behind § 8b of
+> [`agent-interaction-and-decision-quality`](agent-interaction-and-decision-quality.md),
+> which [`improve-before-implement`](../../rules/improve-before-implement.md)
+> routes to. It lives here rather than inline because that guideline sits at the
+> 16,000-char depth ceiling `check_depth_budget` holds as a growth ratchet, and
+> the gate states plainly that raising its baseline is a defect rather than a fix.
+
+## 8b-verdict. The verdict set, and what `new` owes
+
+The ladder's answer is a **named verdict, never a yes/no**:
+
+| verdict | meaning |
+|---|---|
+| `reuse` | the existing thing carries the requirement as-is |
+| `extract` | it carries it once a shared part is pulled out |
+| `refactor` | it carries it once reshaped, same responsibility |
+| `extend` | it carries it with an added, non-distorting case |
+| `migrate` | it should carry it, and the move is the work |
+| `new` | nothing carries it, and the search that establishes that is the evidence |
+
+**`new` owes negative evidence** — the closest existing candidate **by name and
+path**, and why it does not carry the requirement. *"Nothing similar exists"*
+naming no candidate is an unrun search, not an answer, and it is the shape this
+verdict set exists to make visible.
+
+Two clauses hold the set honest, and both cut against reading it as a ranking:
+
+- **The order is a thinking preference, not a ranking.** A `new` after a real
+  search beats an `extend` that bends a helper out of shape. Preferring reuse is
+  not preferring reuse *at any cost*.
+- **Textual similarity alone is never grounds for an abstraction.** Two blocks
+  that read alike and change for different reasons are two blocks — the
+  per-class bars are in [`abstraction-thresholds`](../abstraction-thresholds.md).
+
+**Reach the verdict with the engine, not a fresh grep protocol.** `agent-config
+code-graph query` and `code-graph affected`;
+[`external-code-graph-interop`](../../rules/external-code-graph-interop.md)
+already mandates query-before-grep and names grep the fallback, so a second
+search specification here would contradict it rather than add to it.
+
+## 8b-cheap. Why the exclusions buy the checks and never the question
+
+The rule excludes bug fixes, config changes, user-fenced tasks and trivial
+changes from the **three heavy checks**. The one cheap question — *does this
+already exist in the tree* — fires on all four rows anyway.
+
+The reason is empirical rather than tidy: **bug fixes and renames re-add an
+existing helper more often than features do**, because the author is inside one
+file and reaching for something small. Switching the reuse rung off there
+switches it off where it pays most.
+
+Cheap means cheap, on the [`ui-audit-gate`](../../rules/ui-audit-gate.md)
+precedent: one `code-graph query`, one named verdict, no interview.
+
+**The skip is decidable from the diff alone** — ≤ 1 file, ≤ 5 changed lines, no
+new symbol, no new dependency. A typo satisfies all four with no state to
+consult; an added symbol never does.
+
+## 8b-routing. Why this is not routed through the TDD cluster
+
+Two source proposals put the existence question in `/tdd`'s design mode, as the
+one point every behavior passes through. **It cannot live there, and the reason
+is delivery rather than design:**
+`src/domains/engineering-base/tdd/command.md` carries `visibility: internal` and
+`disable-model-invocation: true`, so **a consumer cannot reach it.** The routing
+is undeliverable, not merely unwanted.
+
+Recorded here so the next author does not re-derive the proposal and re-propose
+it.

package/dist/agent-src/guidelines/agent-infra/review-routing-data-format.md

@@ -0,0 +1,143 @@
+# Review Routing Data Format
+
+Schema and conventions for the two project-local YAML files that feed the
+[`reviewer-awareness`](../../rules/reviewer-awareness.md) rule
+and the [`review-routing`](../../skills/review-routing/SKILL.md) skill.
+
+Both files are **optional** and live in the consumer repository — never
+in package-shipped artifacts. Absence is handled gracefully: routing
+falls back to generic role-based reviewer suggestions.
+
+## File locations
+
+Primary (checked first):
+
+- `.github/ownership-map.yml`
+- `.github/historical-bug-patterns.yml`
+
+Fallback (checked if the `.github/` file does not exist):
+
+- `agents/ownership-map.yml`
+- `agents/historical-bug-patterns.yml`
+
+Choose one location per project and stick with it. Having both is not an
+error, but tools read only the first match.
+
+## ownership-map.yml
+
+Maps glob patterns → roles + optional focus + optional risk hint.
+
+```yaml
+# Required: the version field — breaks loudly if future schema changes.
+version: 1
+
+# Optional: last-reviewed timestamp. If > 6 months old, routing
+# flags the map as stale in its report.
+updated: 2026-02-01
+
+# Optional: defaults applied when no entry matches. If omitted,
+# unmatched paths fall through to reviewer-awareness defaults.
+defaults:
+  roles: [backend]
+
+# Required: list of entries, first match wins per file.
+entries:
+  - paths:
+      - "app/Billing/**"
+      - "app/Services/Payment*.php"
+    roles: [finance-engineering, security]
+    focus: "tax calculation + idempotency"
+    risk: "monetary correctness — regressions bill real customers"
+
+  - paths:
+      - "**/Tenant*.php"
+      - "app/Http/Middleware/TenantScope.php"
+    roles: [platform, security]
+    focus: "cross-tenant isolation"
+    risk: "data leak across customers"
+
+  - paths:
+      - "resources/views/**"
+      - "**/*.blade.php"
+    roles: [frontend]
+    focus: "a11y + responsive layout"
+```
+
+Field semantics:
+
+- **paths** (required, list) — fnmatch globs, same syntax as
+  `pr-risk-config.yml`. First match wins; later entries are ignored for
+  that path.
+- **roles** (required, list) — role identifiers from the common
+  vocabulary in [`reviewer-awareness`](../../rules/reviewer-awareness.md)
+  or project-custom roles.
+- **focus** (optional, string) — one-line description of what reviewers
+  should look at. Surfaced in the PR comment verbatim.
+- **risk** (optional, string) — one-line description of what goes wrong
+  when this area breaks. Used by routing to annotate high-risk matches.
+
+## historical-bug-patterns.yml
+
+Registry of recurring failure modes. Each pattern names a class of bug
+the project has paid for before, with the minimum control or test
+expected for similar new work.
+
+```yaml
+version: 1
+updated: 2026-02-01
+
+patterns:
+  - id: n-plus-one-tenant-listing
+    label: "N+1 on tenant-scoped listings"
+    severity: medium
+    paths:
+      - "app/Http/Controllers/**Listing*.php"
+      - "app/Services/**Query*.php"
+    required_test: "assert query count ≤ N for a multi-row fixture"
+    references:
+      - "PR #842 — production slowdown 2024-09"
+
+  - id: missing-policy-on-admin-route
+    label: "Admin-only route without Gate::allows"
+    severity: high
+    paths:
+      - "app/Http/Controllers/Admin/**"
+      - "routes/admin.php"
+    required_test: "negative test: non-admin gets 403"
+
+  - id: queue-job-not-idempotent
+    label: "Queue job without idempotency key"
+    severity: high
+    paths:
+      - "app/Jobs/**"
+    required_test: "asserting a retried job does not double-write"
+```
+
+Field semantics:
+
+- **id** (required, unique string) — stable slug; used in PR comments
+  and tests as a label.
+- **label** (required, string) — human-readable name.
+- **severity** (required, `low` | `medium` | `high`) — matched patterns
+  contribute this severity to overall PR routing.
+- **paths** (required, list) — fnmatch globs. A pattern matches the
+  diff when **any** changed file matches any glob.
+- **required_test** (required, string) — the specific assertion or
+  regression test the pattern demands. Feeds
+  [`verify-before-complete`](../../rules/verify-before-complete.md) and
+  [`judge-test-coverage`](../../skills/judge-test-coverage/SKILL.md).
+- **references** (optional, list) — links to prior PRs, incidents, or
+  postmortems. Agents quote these verbatim when warning about a match.
+
+## Maintenance
+
+- Both files are code. Review changes to them like code — PR + review.
+- Stale is worse than absent. Update the `updated` field or delete the
+  file when ownership or patterns have drifted.
+- Never auto-generate entries from agent sessions. Entries are curated,
+  not inferred.
+
+## See also
+
+- [`reviewer-awareness`](../../rules/reviewer-awareness.md)
+- [`review-routing`](../../skills/review-routing/SKILL.md)

package/dist/agent-src/guidelines/agent-infra/roadmap-deferred-resolution-provenance.md

@@ -0,0 +1,54 @@
+---
+title: Roadmap deferred-item resolution — provenance
+description: Why the preservation test routes a preserving disposition to the council and a dropping one to the owner, what it deliberately does not fix, and the two council decisions behind it.
+type: guideline
+---
+
+# Roadmap deferred-item resolution — provenance
+
+Migrated from [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md)
+§ *Who resolves it — the preservation test* under the P4 pattern
+(`road-to-standing-payload-diet` step 1.3). The rule keeps the Iron Law, the
+route table, the fail-closed clause and the recorded-or-it-did-not-happen
+clause — everything an agent must act on. What moved here is the provenance and
+the argument: read once, not on every session.
+
+It lives in its own file rather than in
+[`roadmap-progress-mechanics`](roadmap-progress-mechanics.md), which is the
+topical home, for a mechanical reason worth stating so the next migration does
+not repeat the attempt: that file sits ~134 characters under the 16,000-char
+`check_depth_budget` ceiling, so appending this block — or even a stub pointing
+at it — turns a green ratchet red. The ceiling is a growth ratchet rather than a
+measured quality threshold, and the fix it asks for is a smaller destination,
+not a raised baseline.
+
+## The residual hole, stated not papered over
+
+Both authoring seats named it in their own strongest counter: a carried
+follow-up can still become an indefinite deferral, so the preservation test
+bounds *who decides*, not *whether the work happens*. Only fix-now discharges
+it. A carried item untouched at the next task boundary is raised again per
+[`active-remediation`](../../rules/active-remediation.md).
+
+## Why the routing changed
+
+Adopted 2026-08-19, unanimous 2/2 council (blind peer review). The prior text —
+*"Wait for the user"* — handed back a fully analysed choice carrying four costed
+options, which is the low-value interruption
+[`no-cheap-questions`](../../rules/no-cheap-questions.md) forbids. The
+gate exists to protect the item, not the maintainer's attention; routing a
+preserving disposition to the council keeps the protection and drops the
+interruption.
+
+## `deferred_policy` provenance
+
+The declared-contract branch that removes the options round without moving the
+route is `decision 2026-08-20`, AI council 2/2. It is reversible by
+construction: `wait` is the default, so removing the field restores always-wait.
+A declared field never moves a row from owner to council — it changes only
+*when* the round happens.
+
+## See also
+
+- [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md) — the live obligation, Iron Law 3 and the route table.
+- [`roadmap-progress-mechanics`](roadmap-progress-mechanics.md) — glyph semantics, regen cadence, the deferred-resolution menu.