@event4u/agent-config 1.14.0 → 1.16.0

package/.agent-src/skills/ai-council/SKILL.md

@@ -0,0 +1,333 @@
+---
+name: ai-council
+description: "Use when polling external AIs (OpenAI, Anthropic) outside the host session for a neutral second opinion on a roadmap, diff, prompt, or file set — or 'cross-check with another model'."
+source: package
+---
+
+# ai-council
+
+## When to use
+
+* The host agent has drafted a roadmap, plan, or design and wants an
+  **external** critique that is not biased by its own framing.
+* The user asks "what would Claude / GPT say about this?" or invokes
+  `/council`.
+* A PR diff or commit range needs a second-opinion review beyond the
+  internal four-judge pass.
+* A free-form proposal benefits from being challenged by an outside
+  reviewer before it calcifies into work.
+
+Do NOT use when:
+
+* The decision is internal-only and budget matters more than diversity
+  of opinion → use `subagent-orchestration` (in-session, no network,
+  no money).
+* The artefact contains secrets that cannot be redacted with the
+  bundler's pattern set → ask the user before sending.
+* The user has not configured any council member → state that and stop;
+  do not silently fall back to anything.
+
+## Goal
+
+Bring in **independent** external models to critique a project
+artefact. Independent means: the council members never see the host
+agent's reasoning, internal state, or framing language — only the
+artefact (roadmap, diff, prompt, file set) plus a neutral system
+prompt that asks them to think on their own merits.
+
+## Neutrality guidelines (Iron Law)
+
+```
+THE COUNCIL DOES NOT SEE THE HOST AGENT'S ANALYSIS.
+THE COUNCIL DOES NOT SEE PRIOR REPLIES.
+THE COUNCIL SEES THE ARTEFACT + THE NEUTRAL SYSTEM PROMPT. NOTHING ELSE.
+```
+
+If you find yourself wanting to "frame" the artefact for the council,
+stop. Framing is exactly what kills the second-opinion value. Use the
+unbiased system prompts in `scripts/ai_council/prompts.py`; do not
+roll your own.
+
+### Neutrality — context-handoff
+
+External reviewers do better critique when they know **what the
+project is**, not just what the artefact looks like. The council
+ships a neutral **handoff preamble** (modelled on `/agent-handoff`)
+in front of every member's system prompt, assembled by
+`prompts.handoff_preamble(project, original_ask)`:
+
+| Carried | Forbidden |
+|---|---|
+| Project name (from `composer.json` / `package.json` / repo dir) | Host-agent identity (Augment, Claude Code, Cursor, Cline, Windsurf, Copilot agent) — stripped line-by-line before send |
+| Stack one-liner inferred from manifest files | Host-agent reasoning, prior turns, internal analysis |
+| One paragraph of repo purpose from `README.md` (max 400 chars) | Host-agent framing language ("I think this looks weak", "the user probably wants…") |
+| The user's **original ask** verbatim (the free-form sentence that triggered `/council`) | Anything the host agent generated about the artefact |
+
+`detect_project_context()` in `scripts/ai_council/project_context.py`
+reads only the manifest files + root README; missing fields collapse
+to `None` and the preamble silently omits the line. With both
+`project=None` and `original_ask=""`, the preamble degrades to the
+bare `NEUTRALITY_PREAMBLE` (v1 shape — back-compat for callers that
+have not migrated yet).
+
+## Execution modes
+
+A council member can run in one of three transports. The neutrality
+preamble is identical across all of them — only the path the bytes
+travel changes.
+
+| Mode | Client | Billable | Transport | Status |
+|---|---|---|---|---|
+| `api` | `AnthropicClient` / `OpenAIClient` | yes | provider SDK + key from `~/.config/agent-config/<provider>.key` | shipped |
+| `manual` | `ManualClient` | no | `stdout` (prompt block) + `stdin` (user pastes the web-UI reply, terminated by a line containing only `END`) | shipped (Phase 2b) |
+| `playwright` | `PlaywrightClient` | no | persistent-profile browser at the provider's chat URL via DOM adapter | reserved (Phase 2c — capture-only) |
+
+Resolution lives in `scripts/ai_council/modes.py`:
+`resolve_mode(name, invocation_mode, member_settings, global_mode)`
+with precedence **invocation flag > per-member setting > global
+setting > default (`api`)**. Whitespace-and-case insensitive; empty
+strings fall through; unknown values raise `InvalidModeError` with
+the offending settings path (`ai_council.mode`,
+`ai_council.members.<name>.mode`, or `/council mode=`).
+
+### Manual-mode UX
+
+`ManualClient` is the user-as-transport variant: the agent prints
+one Markdown block per member (system prompt + handoff preamble +
+artefact between two `═` rules), the user pastes it into a web
+chat (Claude.ai, ChatGPT, Gemini), then pastes the reply back
+ending with a line containing only `END`. After each reply, a 1/2/3
+menu surfaces:
+
+1. More feedback for this member (continue this thread)
+2. Done with this member, move to the next
+3. Abort the council run
+
+`1` re-emits a follow-up block addressed to the **same chat
+thread** (no system prompt repetition). `2` records the round and
+moves to the next member. `3` returns `error="manual_aborted"` for
+that member and the orchestrator stops the fan-out.
+
+### Cost-gate bypass for non-billable members
+
+`ExternalAIClient.billable` is the contract. Clients with
+`billable=False` (today: `ManualClient`; future: `PlaywrightClient`)
+bypass the cost gate entirely — the orchestrator skips the
+projection check, the `on_overrun` callback, and the USD-budget
+short-circuit for that member, but still records the response's
+token counts (from the manual-paste length heuristic or the
+provider's reply, when available) for observability. Mixed runs
+(one manual + one api) gate only the api members.
+
+## Procedure
+
+1. **Resolve target.** Identify the artefact mode (`prompt`, `roadmap`,
+   `diff`, `files`) and locate the source. Refuse to proceed if the
+   target is ambiguous.
+2. **Bundle + redact.** Call `scripts/ai_council/bundler.py` to produce
+   a redacted artefact bundle. If `BundleTooLarge` fires, surface the
+   size and ask the user to narrow scope — do NOT truncate silently.
+3. **Confirm spend.** Before any network call, surface members + cost
+   ceiling and require an explicit user `1` to proceed. Autonomy
+   settings do not override this gate.
+4. **Fan out.** Dispatch the bundle to each enabled council member via
+   `scripts/ai_council/orchestrator.py`. Each member receives the
+   neutrality preamble from `prompts.py` plus the artefact — nothing
+   from the host agent's prior reasoning.
+5. **Render results.** Stack each member's response under its own
+   provider-attributed heading. Never merge or paraphrase responses
+   into the host agent's voice.
+6. **Summarise.** Write a `Convergence / Divergence` block listing
+   agreements, disagreements, and unique insights — provider-attributed.
+7. **Translate to options.** Convert actionable council suggestions
+   into concrete numbered options for the user. The user decides;
+   the council advises.
+
+## Output format
+
+Every council reply MUST contain, in this order:
+
+1. **Header line** with mode, member count, and total token cost.
+2. **One section per member**, titled `### <provider> · <model>`,
+   containing the member's verbatim output.
+3. **Convergence / Divergence summary** — bullet list, every claim
+   attributed by provider name.
+4. **User-facing options** — numbered block per `user-interaction`,
+   with "discard council input" always present as an option.
+
+The host agent NEVER ships council output as its own reasoning.
+Provider attribution stays visible in every render.
+
+## Do NOT
+
+- Do NOT paraphrase council output into the host agent's voice — strip
+  attribution and you've stripped the value.
+- Do NOT pre-warm the council with the host agent's analysis or
+  identity — that primes the reviewer and collapses diversity.
+- Do NOT silently truncate a too-large bundle — surface the size and
+  ask for narrower scope.
+- Do NOT auto-spend tokens under `personal.autonomy: on` — the cost
+  gate fires every time, no exceptions.
+- Do NOT reuse SDK clients across invocations — re-load keys via
+  `load_*_key()` each call.
+
+## Gotchas
+
+Real failure modes seen in the wild:
+
+- **Bias-by-framing:** agent pastes "I think X is the right answer,
+  what do you think?" → council rubber-stamps. Symptom: 100%
+  convergence, zero unique insight. Fix: send artefact only, neutral
+  preamble, no host reasoning.
+- **Silent budget overrun:** `cost_budget_exceeded` mid-fan-out, agent
+  retries one member to "complete" the council. Result: skewed sample,
+  hidden spend. Fix: surface partial result, stop, ask user.
+- **Identity leak:** roadmap text contains "the agent decided…" —
+  reviewer infers host model and mirrors it. Fix: redact host-agent
+  identity strings before bundling.
+
+| Anti-pattern | Why it's wrong | Correct approach |
+|---|---|---|
+| "Pre-warm" the council with the agent's own analysis. | Bias attack — collapses the reviewer to a yes-man. | Send the artefact text only. |
+| Paste the host-agent identity ("I am Augment / Claude Code…") | Identity primes the reviewer's model. | Neutrality preamble in `prompts.py` already handles this. |
+| Silently truncate a too-large bundle. | Misleads the reviewer into thinking they saw the whole thing. | Bundler raises `BundleTooLarge`; surface and ask for narrower scope. |
+| Reuse the same SDK client across calls without re-loading the key. | Leaks the key in long-lived process state. | Each invocation builds fresh clients from `load_*_key()`. |
+| Auto-spend tokens under `personal.autonomy: on`. | Autonomy ≠ permission to spend money. | Always ask before consultation, even under autonomy. |
+
+## Redaction expectations
+
+The bundler's redaction pass strips:
+
+- Paths matching `~/.config/agent-config/*.key`.
+- Lines starting with `Authorization:`.
+- `key = …`, `secret = …`, `token = …`, `password = …` assignments.
+- `sk-ant-…` and `sk-…` token-like strings.
+
+If your artefact contains other sensitive data (customer names,
+internal hostnames, contractual prose) you are responsible for
+scrubbing it before bundling. The redaction pass is a **floor**, not
+a ceiling.
+
+## Cost awareness
+
+Every consultation hits a paid API. The orchestrator enforces
+per-invocation caps from `ai_council.cost_budget`:
+
+- `max_input_tokens` / `max_output_tokens` — token caps across all members.
+- `max_total_usd` — per-invocation USD ceiling. `0` disables the USD ceiling (token caps still apply).
+- `max_calls` — maximum number of council members per invocation.
+- `daily_limit_usd` — rolling 24h spend cap across all `/council`
+  invocations. `0` disables. Persists in
+  `~/.config/agent-config/council-spend.jsonl` (mode 0600). Breach
+  fires `on_overrun(event)` with `event.breach_kind == "daily"` and,
+  if the callback returns False or is absent, tags the member
+  `daily_budget_exceeded` instead of `cost_budget_exceeded`.
+
+Prices come from `.agent-prices.md` (gitignored, refreshed weekly).
+The pricing module bootstraps it from `_default_prices.py` on first
+use and flags it stale when older than the most recent Monday 00:00
+UTC.
+
+### Pre-call estimate format
+
+Before the cost gate, compute `orchestrator.estimate(question, members,
+table)` and render a per-member table. Heuristic: `len(text) / 4` for
+input, member's `max_tokens` ceiling for output (actual spend is
+usually lower).
+
+> External council call — billable
+>
+> Mode: roadmap · Target: `agents/roadmaps/<name>.md` (~3 KB after redaction)
+>
+> | member                          | est. in / out tokens | est. USD |
+> |---------------------------------|---------------------:|---------:|
+> | anthropic / claude-sonnet-4-5   |      ~750 / 1024     |  $0.0176 |
+> | openai / gpt-4o                 |      ~750 / 1024     |  $0.0121 |
+> | **total**                       |                      | **$0.0297** |
+>
+> Budget: 50k in / 20k out tokens · USD ceiling: $0.50
+>
+> 1. Run the consultation
+> 2. Cancel
+
+### Stale price-table gate
+
+If `pricing.is_stale(table)` returns true, ask before proceeding:
+
+> Price table is stale (last_updated: YYYY-MM-DD)
+> 1. Refresh now (`python3 scripts/update_prices.py`)
+> 2. Continue with the stale table
+> 3. Cancel
+
+Do not silently auto-refresh — the user keeps control.
+
+### Mid-flow overrun callback (`on_overrun`)
+
+The orchestrator runs members **sequentially**. Before each member
+whose projected spend would breach a cap, it invokes the
+`on_overrun(event)` callback. The callback returns `True` to proceed
+with that member (raises the effective ceiling for THIS call only)
+or `False` to skip and record `cost_budget_exceeded`. The callback
+fires again for every subsequent breaching member — the user keeps
+control on each step.
+
+> Cost budget overrun — pausing before next member
+>
+> Member: openai / gpt-4o (member 2 of 2)
+> Already spent: ~620 in / ~480 out tokens · $0.0094
+> Next call estimate: ~750 in / 1024 out tokens · $0.0121
+> **Projected total after this call: $0.0215** (ceiling: $0.0150)
+>
+> 1. Continue with this member
+> 2. Skip this member (records `cost_budget_exceeded`, continues with the rest)
+
+Without `on_overrun`, breaching short-circuits all remaining members
+(v1 fallback). Do not retry silently. Surface the partial result and
+ask the user.
+
+## Multi-round debate (`rounds:N`)
+
+`consult(..., rounds=N)` enables 2-3 round critique loops. Round 1
+runs the standard single-round flow. Round 2+ rebuilds the user
+prompt as `<original artefact> + <prior round, anonymised>` so each
+member can refine, agree, or push back on the previous critique
+without seeing which provider produced which point.
+
+| Property | Behaviour |
+|---|---|
+| Anonymisation | Provider/model identity is stripped. Reviewers are labelled `Reviewer A / B / C…` in input order. |
+| Errored prior responses | Skipped — they reveal nothing useful and can leak provider error formats. |
+| Cost budget | Accumulates across rounds. A round-2 call that breaches the cap fires `on_overrun` exactly like a round-1 breach. |
+| Daily limit | Same — every billable round-2 call records spend in the rolling 24h ledger. |
+| Return value | Final round only. Use `on_round_complete(round_idx, responses)` to capture intermediate rounds for rendering. |
+
+> Iron Law: anonymisation is non-negotiable. If you ever need to
+> surface "which model said what" between rounds, that is a different
+> feature — debug-only, off by default, never enabled in user-facing
+> output. The neutrality contract dies the moment a member learns it
+> is talking to Claude vs GPT in round 2.
+
+Pre-call estimate must surface the round count: total = `N × single-round cost`. Render inline:
+
+```
+External council call — billable · 2 rounds
+Round 1: artefact only
+Round 2: artefact + anonymised round 1 critiques
+
+| member             | per-round | × 2     |
+|--------------------|----------:|--------:|
+| anthropic/sonnet   |   $0.0176 | $0.0352 |
+| openai/gpt-4o      |   $0.0121 | $0.0242 |
+| **total**          |           | $0.0594 |
+```
+
+## See also
+
+- `/council` command — the user-facing entry point.
+- `subagent-orchestration` skill — internal multi-agent variant (no
+  network, no spend, but no diversity of weights either).
+- `scripts/ai_council/prompts.py` — neutrality preamble + per-mode
+  system prompts.
+- `scripts/ai_council/bundler.py` — redaction pattern set + size
+  guard.
+- `docs/customization.md` § `ai_council.*` — settings reference.

package/.agent-src/skills/api-endpoint/SKILL.md

@@ -28,8 +28,8 @@ Do NOT use when:
 
 ### What to generate
 
-1. **Controller** — Single Action (invokable). Read `agents/docs/controller.md` and `.augment/guidelines/php/controllers.md`.
-2. **FormRequest** — Validation rules, `authorize()` via policies. Read `.augment/guidelines/php/validations.md`.
+1. **Controller** — Single Action (invokable). Read `agents/docs/controller.md` and `../../../docs/guidelines/php/controllers.md`.
+2. **FormRequest** — Validation rules, `authorize()` via policies. Read `../../../docs/guidelines/php/validations.md`.
 3. **Resource** — JSON response transformation. Read `agents/docs/api-resources.md`.
 4. **Route** — Add to the correct versioned route file.
 5. **Policy** — If authorization is needed.

package/.agent-src/skills/blade-ui/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: blade-ui
-description: "Stack-implementation skill for Laravel Blade — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project's frontend stack is Blade. Covers views, components, partials, layouts, and view logic."
+description: "Use when the project's frontend stack is Blade — dispatched by `directives/ui/{apply,review,polish}.py`. Covers views, components, partials, layouts, and view logic."
 source: package
 ---
 
@@ -8,7 +8,11 @@ source: package
 
 ## Positioning — dispatched, not standalone
 
-`blade-ui` is the **apply-step executor** for the Blade stack. Invoked by [`directives/ui/apply.py`](../../templates/scripts/work_engine/directives/ui/apply.py) once the design brief is locked, and revisited by `review.py` / `polish.py` during the design-review loop. Does **not** own the flow, drive the audit, or lock the design.
+`blade-ui` is the **apply-step executor** for the Blade stack. It is
+invoked by [`directives/ui/apply.py`](../../templates/scripts/work_engine/directives/ui/apply.py)
+once the design brief is locked, and revisited by `review.py` /
+`polish.py` during the design-review loop. It does **not** own the
+flow, does **not** drive the audit, and does **not** lock the design.
 
 | Concern | Owner |
 |---|---|
@@ -27,7 +31,7 @@ Cite this skill when:
 Do NOT use when:
 
 - API-only endpoints (use `api-endpoint` skill)
-- Livewire components (use `livewire` skill — composes Blade views internally)
+- Livewire components (use `livewire` skill — it composes Blade views internally)
 - Flux UI components (use `flux` skill)
 - Driving the full UI flow yourself — that is the `directives/ui/` orchestrator
 
@@ -39,11 +43,11 @@ Do NOT use when:
 2. Inspect existing UI patterns — layouts, partials, component naming, CSS conventions.
 3. Check form handling style — old input, validation errors, session flashes, reusable field partials.
 4. Inspect neighboring templates — match indentation, directives, slot usage, classes.
-5. Determine data flow — controller/view model vs. template.
+5. Determine data flow — what belongs in controller/view model vs. template.
 
 ### Step 1: Create the template
 
-1. Use project's existing layout system.
+1. Use the project's existing layout system.
 2. Keep template presentation-focused — no business logic, no DB queries.
 3. Extract repeated sections into partials or components.
 
@@ -72,12 +76,27 @@ Do NOT use when:
 
 ### Review pass — a11y findings + preview envelope
 
-When dispatched by `directives/ui/review.py` (test slot) or `directives/ui/polish.py` (verify slot) — review/polish run, not initial apply — also emits:
-
-- `state.ui_review.a11y` — `{violations: [{rule, selector, severity}, ...], severity_floor?, accepted_violations?}`. Use same `(rule, selector)` shape as `state.ui_audit.a11y_baseline` so engine's de-dup matches pre-existing entries on replay. Omit envelope on apply passes; engine's `_apply_a11y_gate` only fires when baseline present.
-- `state.ui_review.preview` — `{render_ok: bool, screenshot_path?, dom_dump_path?, error?, skipped?}`. `render_ok: false` with `error` populated triggers `preview_render_failed` halt; `render_ok: true` with `screenshot_path` threads screenshot into delivery report's `artifacts` list. Browser tooling (Playwright/Cypress/…) is consumer-project dependency — package does not ship one.
-
-Polish dispatch: when dispatcher skips `review` because previous review pass returned `SUCCESS`, this skill MUST itself synthesise updated `state.ui_review.findings` (including remaining `a11y_violation` entries) so engine's gate sees current state on next polish round.
+When this skill is dispatched by `directives/ui/review.py` (test slot)
+or `directives/ui/polish.py` (verify slot) — i.e. a review/polish run,
+not the initial apply — it also emits:
+
+- `state.ui_review.a11y` — `{violations: [{rule, selector, severity}, ...],
+  severity_floor?, accepted_violations?}`. Use the same `(rule, selector)`
+  shape as `state.ui_audit.a11y_baseline` so the engine's de-dup matches
+  pre-existing entries on replay. Omit the envelope on apply passes; the
+  engine's `_apply_a11y_gate` only fires when a baseline is present.
+- `state.ui_review.preview` — `{render_ok: bool, screenshot_path?,
+  dom_dump_path?, error?, skipped?}`. `render_ok: false` with `error`
+  populated triggers the `preview_render_failed` halt; `render_ok: true`
+  with `screenshot_path` threads the screenshot into the delivery
+  report's `artifacts` list. Browser tooling (Playwright/Cypress/…) is
+  a consumer-project dependency — this package does not ship one.
+
+Polish dispatch: when the dispatcher skips `review` because a previous
+review pass already returned `SUCCESS`, this skill MUST itself
+synthesise the updated `state.ui_review.findings` (including any
+remaining `a11y_violation` entries) so the engine's gate sees the
+current state on the next polish round.
 
 ## Gotcha
 

package/.agent-src/skills/blast-radius-analyzer/SKILL.md

@@ -81,7 +81,7 @@ For every dependency, mark:
 
 ### 5. Consult engineering memory
 
-Via [`memory-access`](../../guidelines/agent-infra/memory-access.md) call
+Via [`memory-access`](../../../docs/guidelines/agent-infra/memory-access.md) call
 `retrieve(types=["architecture-decisions", "ownership"],
 keys=<changed paths + changed symbol>, limit=5)`. Surface:
 

package/.agent-src/skills/bug-analyzer/SKILL.md

@@ -84,7 +84,7 @@ Gather all available evidence before forming any hypothesis:
 - Read each file in the call chain to understand the data flow.
 - Check existing context docs (`agents/contexts/`) for the affected area.
 - **Consult engineering memory.** Via
-  [`memory-access`](../../guidelines/agent-infra/memory-access.md) call
+  [`memory-access`](../../../docs/guidelines/agent-infra/memory-access.md) call
   `retrieve(types=["historical-patterns", "incident-learnings"],
   keys=[<error class>, <affected file paths>], limit=3)`. A prior
   matching pattern or incident is the single most reliable accelerator

package/.agent-src/skills/command-routing/SKILL.md

@@ -12,7 +12,7 @@ execution:
 
 ## When to use
 
-Triggered when user invokes a slash command. The `slash-commands` rule (always loaded) handles core behavior — this skill adds context inference and GitHub API patterns.
+Triggered when user invokes a slash command. The `slash-command-routing-policy` rule (always loaded) handles core behavior — this skill adds context inference and GitHub API patterns.
 
 ## Procedure: Execute a command
 

package/.agent-src/skills/command-writing/SKILL.md

@@ -67,7 +67,7 @@ suggestion:                   # required (road-to-context-aware-command-suggesti
 ---
 ```
 
-Opt-out shape:
+Or, when opting out:
 
 ```yaml
 suggestion:
@@ -75,10 +75,21 @@ suggestion:
   rationale: "one-line reason this command must be invoked deliberately"
 ```
 
-Linter enforces ≥10-char triggers when eligible; rationale required when
-ineligible. Optional `confidence_floor` (0.0–1.0) and `cooldown` (e.g. `10m`)
-override the global settings per command. Eligibility decisions live in
+Suggestion-block rules (linter-enforced):
+
+* `eligible` is **required** and must be `true` or `false`.
+* `eligible: true` → both `trigger_description` and `trigger_context` must be
+  non-empty (≥ 10 chars each); the linter rejects empty or overly generic
+  patterns. The suggestion layer never auto-executes; the user always picks.
+* `eligible: false` → `rationale` must be non-empty. Use the opt-out for
+  intentional-only invocations (settings mutations, destructive actions,
+  package-internal tools, niche maintenance).
+* Optional `confidence_floor` (0.0–1.0) and `cooldown` (e.g. `10m`)
+  override the global settings per command.
+
+Eligibility decisions are tracked in
 [`agents/contexts/command-suggestion-eligibility.md`](../../../agents/contexts/command-suggestion-eligibility.md).
+Add or revise entries there before changing a command's `suggestion` block.
 
 When iterating on the description, delegate to the
 [`description-assist`](../description-assist/SKILL.md) skill — approval-gated,
@@ -106,7 +117,7 @@ Required sections in this order:
 ### 4. Enforce the size budget
 
 Normative source: [`size-enforcement`](../../rules/size-enforcement.md) +
-`guidelines/agent-infra/size-and-scope.md`.
+`docs/guidelines/agent-infra/size-and-scope.md`.
 
 | Category | Target |
 |---|---|

package/.agent-src/skills/conventional-commits-writing/SKILL.md

@@ -66,5 +66,5 @@ Read all PR commits → identify net effect → write single Conventional Commit
 ## References
 
 - Rule: `commit-conventions` — format, types, scope
-- Guideline: `guidelines/php/git.md` — selection rules, anti-patterns, checklist
+- Guideline: `docs/guidelines/php/git.md` — selection rules, anti-patterns, checklist
 - Command: `/commit` — uses this skill

package/.agent-src/skills/copilot-agents-optimization/SKILL.md

@@ -57,7 +57,7 @@ Only after this analysis, proceed with optimization.
 **What does NOT belong here:**
 - Coding standards (→ `.augment/rules/` and `.augment/guidelines/`)
 - Architecture principles like SOLID, KISS, DRY (→ `.augment/rules/architecture.md`)
-- PHP conventions (→ `.augment/guidelines/php/`)
+- PHP conventions (→ `../../../docs/guidelines/php/`)
 - Scope control rules (→ `.augment/rules/scope-control.md`)
 - Language/tone rules (→ `.augment/rules/language-and-tone.md`)
 - Detailed module documentation (→ `app/Modules/README.md`)
@@ -115,7 +115,7 @@ both. Instead, reference with a table:
 | What | Where |
 |---|---|
 | PHP coding rules | `.augment/rules/php-coding.md` |
-| Controller guidelines | `.augment/guidelines/php/controllers.md` |
+| Controller guidelines | `../../../docs/guidelines/php/controllers.md` |
 ```
 
 ## Line Budget Enforcement

package/.agent-src/skills/developer-like-execution/SKILL.md

@@ -127,13 +127,13 @@ If important information is missing:
 - Compare with requirements, tickets, current behavior, tests, existing patterns
 - Identify likely cause and smallest correct change
 - **Consult memory — invariants and prior decisions.** Via
-  [`memory-access`](../../guidelines/agent-infra/memory-access.md), call
+  [`memory-access`](../../../docs/guidelines/agent-infra/memory-access.md), call
   `retrieve(types=["domain-invariants", "architecture-decisions"], keys=<touched paths>, limit=3)`.
   A matching `domain-invariant` is a hard constraint — violating it =
   regression, surface the conflict before proceeding. A matching
   `architecture-decision` explains *why* the current shape exists; plan
   around it, do not silently overturn it. Cite matching `id`s in the plan.
-  See [`engineering-memory-data-format`](../../guidelines/agent-infra/engineering-memory-data-format.md)
+  See [`engineering-memory-data-format`](../../../docs/guidelines/agent-infra/engineering-memory-data-format.md)
   for the schema.
 
 ### 4. Define expected behavior first

package/.agent-src/skills/existing-ui-audit/SKILL.md

@@ -128,19 +128,31 @@ Record the user's pick in `state.ui_audit.greenfield_decision` (`scaffold` | `ba
 
 ### 8. (Optional) Capture an a11y baseline
 
-R4 visual-review-loop contract reads `state.ui_audit.a11y_baseline` when present; review gate filters incoming `state.ui_review.a11y.violations` against it so pre-existing violations stay informational and only NEW or CHANGED entries block polish loop. Without baseline gate sees every violation as actionable — fine for greenfield, noisy for legacy surfaces.
+The R4 visual-review-loop contract reads `state.ui_audit.a11y_baseline`
+when present; the review gate then filters incoming
+`state.ui_review.a11y.violations` against it so pre-existing
+violations stay informational and only NEW or CHANGED entries block
+the polish loop. Without a baseline the gate sees every violation as
+actionable — fine for greenfield, noisy for legacy surfaces.
 
-Capture baseline when:
+Capture the baseline when:
 
-- Audit covers components with known a11y debt project does not intend to fix this run (legacy templates, third-party embeds, vendor widgets).
-- User says "don't block on existing a11y issues" or similar.
+- The audit covers components with known a11y debt the project does
+  not intend to fix in this run (legacy templates, third-party
+  embeds, vendor widgets).
+- The user says "don't block on existing a11y issues" or similar.
 
-Skip baseline (omit key, leave `state.ui_audit.a11y_baseline` unset) when:
+Skip the baseline (omit the key, leave `state.ui_audit.a11y_baseline`
+unset) when:
 
-- Surface is greenfield — review gate should treat every violation as new.
-- Project's a11y posture is "zero known violations" and any finding is by definition actionable.
+- The surface is greenfield — the review gate should treat every
+  violation as new.
+- The project's a11y posture is "zero known violations" and any
+  finding is by definition actionable.
 
-Shape (each entry MUST carry at least `rule` + `selector`; severity optional but recommended so review gate's severity-floor filter behaves same on replay):
+Shape (each entry must carry at least `rule` + `selector`; severity
+is optional but recommended so the review gate's severity-floor
+filter behaves the same on replay):
 
 ```
 state.ui_audit.a11y_baseline = [
@@ -150,7 +162,10 @@ state.ui_audit.a11y_baseline = [
 ]
 ```
 
-Producer parity: review skill that writes `state.ui_review.a11y.violations` MUST use same `(rule, selector)` shape, otherwise engine's de-dup will miss matches and pre-existing violations will surface as new findings on every run.
+Producer parity: the review skill that writes
+`state.ui_review.a11y.violations` MUST use the same `(rule, selector)`
+shape, otherwise the engine's de-dup will miss matches and pre-existing
+violations will surface as new findings on every run.
 
 ### 9. Validate and write findings