@event4u/agent-config 1.15.0 → 1.17.0

package/.agent-src/contexts/judges/no-consolidate-rationale.md

@@ -0,0 +1,102 @@
+---
+audience: maintainers
+status: stable
+stability: stable
+purpose: >
+  Locked decision rationale for Phase 3a of the
+  road-to-structural-optimization roadmap. The four `judge-*` skills
+  are intentionally **not** consolidated under a shared procedure
+  context. Future maintainers reading this file should not retry the
+  pattern without invalidating the data here.
+---
+
+# Why `judge-*` skills are NOT consolidated
+
+A Phase 3a spike evaluated extracting a shared procedure file
+(`contexts/judges/judge-shared-procedure.md`) loaded by all four
+`judge-*` skills. The locked Q1=A shape (separate skills + shared
+procedure context) was implemented and benchmarked. **Outcome: net
+LOC negative.** The pattern is rejected for this family.
+
+## The numbers
+
+Spike measurements on `judge-test-coverage` (the smallest persona,
+chosen per roadmap 3a.0):
+
+| State | Skill LOC | Shared LOC | Total per family of 4 |
+|---|---|---|---|
+| Baseline (4 separate) | 153 + 157 + 157 + 166 = **633** | 0 | 633 |
+| Slim attempt #1 | 138 | 134 | 4 × 138 + 134 = 686 ❌ |
+| Slim attempt #2 (aggressive) | 133 | 117 | 4 × 133 + 117 = 649 ❌ |
+
+The success-criteria threshold from the roadmap (≥ 30 % per-skill
+LOC reduction) maps to 153 → ≤ 107 for `judge-test-coverage`. The
+aggressive attempt landed at 133 — a 13 % reduction. To go further,
+each skill would have to surrender persona-specific content (analysis
+rubric, anti-pattern list, severity definitions, scope-boundary Do
+NOTs) — exactly the content that makes each persona reviewable.
+
+## Why the math doesn't work
+
+A judge skill is **not** procedurally complex. Its value is the
+persona surface:
+
+- a 6–11 row analysis table tailored to the lens (correctness, security,
+  test gaps, code quality)
+- a list of persona-specific anti-patterns and gotchas
+- a severity legend with thresholds calibrated to the lens
+- scope-boundary Do NOTs that route to sibling judges
+
+Procedural overhead (verdict semantics, validation scaffold,
+output-format frame, runtime boundary, model fallback) is small in
+absolute terms — extracting it adds a context file but only saves
+~15–25 LOC per skill. With four skills, the per-skill saving is
+amortized against the shared file once; below five or six skills,
+the structural tax dominates.
+
+The same argument applies to procedural duplication in any small
+skill family where the procedural skeleton is short and the persona
+table is the bulk of the file.
+
+## Decision
+
+Phase 3a is closed with status **DO NOT CONSOLIDATE**. The four
+`judge-*` skills remain separate, self-contained, and free of
+`load_context:` indirection. Each skill's "Procedure" section carries
+its full procedural body inline. This trades minor maintenance
+duplication for full persona isolation and zero structural tax.
+
+Phase 3b (`project-analysis-*`, 8 skills, 959 LOC) and Phase 3c
+(`skill-*`, 4 skills, 782 LOC) **continue independently** per the
+roadmap's "3b/3c continue independently" abort note. The math there
+is more favorable: 8 stack-specific analysis skills share a much
+larger procedural skeleton (project discovery, version resolution,
+docs loading, architecture mapping) than 4 judge skills do.
+
+## Reopening conditions
+
+Reopen this decision **only** if at least one of these holds:
+
+1. The `judge-*` family grows to ≥ 6 skills (procedural amortization
+   crosses break-even).
+2. A new persona-orthogonal procedural step is introduced that all
+   judges must execute identically (e.g. a CI-integrated verdict
+   reporter), and that step is non-trivial (≥ 30 LOC).
+3. The success-criteria threshold in
+   `road-to-structural-optimization.md` § 3a is renegotiated to a
+   lower per-skill LOC bar (with explicit justification — the 30 %
+   bar exists because anything less is structural noise).
+
+Until one of those holds, treat any "let's extract shared procedure
+across the judges" proposal as a regression and cite this file.
+
+## See also
+
+- [`persona-voice-rubric`](persona-voice-rubric.md) — the voice
+  preservation rubric used during the spike (still applies if a future
+  consolidation attempt needs the same check).
+- Sibling judges, all kept inline:
+  [`judge-bug-hunter`](../../skills/judge-bug-hunter/SKILL.md),
+  [`judge-code-quality`](../../skills/judge-code-quality/SKILL.md),
+  [`judge-security-auditor`](../../skills/judge-security-auditor/SKILL.md),
+  [`judge-test-coverage`](../../skills/judge-test-coverage/SKILL.md).

package/.agent-src/contexts/judges/persona-voice-rubric.md

@@ -0,0 +1,140 @@
+---
+stability: beta
+---
+
+# Persona-Voice Rubric for `judge-*` Skills
+
+> **Audience:** authors and reviewers of any future `judge-*`
+> consolidation spike. Also loaded via `load_context:` by future
+> `judge-*` slim shapes when an A-shape ships.
+
+This rubric defines **what "persona voice" means** for the four
+`judge-*` skills (`judge-bug-hunter`, `judge-code-quality`,
+`judge-security-auditor`, `judge-test-coverage`) and **how to score
+voice preservation** when comparing a slimmed (Option-A: separate skill
++ shared procedure context) output against the current single-file
+baseline. The rubric is the measurement instrument behind the 3a.0.1
+voice gate (≥ 4.0/5) and the 0.5 author + 2-reviewer protocol (avg ≥
+3.5/5).
+
+## The five dimensions
+
+Each dimension scored independently on a 1–5 integer scale. Scorers
+record one numeric score plus one short rationale per dimension.
+
+### 1. Tone
+
+The judge's posture toward the diff. Distinctive markers per persona:
+
+| Skill | Tone marker |
+|---|---|
+| `judge-bug-hunter` | Skeptical, edge-case-first ("what input breaks this?") |
+| `judge-code-quality` | Reformist, convention-bound ("this clashes with the codebase pattern at X") |
+| `judge-security-auditor` | Adversarial, threat-modeling ("what would an attacker do here?") |
+| `judge-test-coverage` | Falsification-first ("does this test fail without the fix?") |
+
+Score 5 = posture indistinguishable from baseline. Score 1 = generic
+"reviewer voice" with no persona signal.
+
+### 2. Vocabulary
+
+Domain-specific terms the persona reaches for unprompted. Captured by
+keyword profile from the baseline SKILL.md (e.g., `judge-security-auditor`
+uses *trust boundary*, *sink*, *SSRF*, *mass assignment*;
+`judge-test-coverage` uses *uncovered branch*, *over-mocking*,
+*regression test*, *tautological assertion*).
+
+Score 5 = ≥ 80% of baseline keyword profile present in slimmed output
+on a representative diff. Score 1 = < 20% present, or vocabulary leaks
+in from a sibling persona (collision marker — see § 5 below).
+
+### 3. Prompt-shape preservation
+
+The structural skeleton of the output (Verdict, Issues, Severity,
+Required fields). Must match the baseline `Output format` block
+verbatim in field order, label spelling, and severity icon set.
+
+Score 5 = byte-identical field structure (only finding content
+differs). Score 3 = minor reorder, no missing fields. Score 1 = a
+required field dropped, renamed, or merged.
+
+### 4. Refusal patterns
+
+How the judge handles out-of-scope concerns. Each `judge-*` baseline
+explicitly **refuses** to comment on dimensions another judge owns
+(e.g., `judge-test-coverage` refuses to flag correctness or style;
+`judge-security-auditor` refuses to flag pure logic bugs).
+
+Score 5 = refusal triggers fire on the same out-of-scope inputs as
+baseline, with the same handoff phrasing ("route to `judge-X`"). Score
+1 = persona accepts an out-of-scope finding silently (mode-collision
+risk realized).
+
+### 5. Evidence-citation style
+
+How findings are anchored to the diff. Baselines all cite `path:LINE`
+with a one-line reason and (where applicable) a "what the test should
+assert" / "what the attacker would do" clause.
+
+Score 5 = every finding has the same citation shape as baseline —
+`path:LINE` plus the persona-specific clause (uncovered branch /
+threat class / pattern violated / failing input). Score 1 = findings
+are vague ("there's a problem in the validator") or use a sibling
+persona's citation shape.
+
+## Scoring template
+
+For each scored output, fill out the matrix below — once per scorer
+(author + 2 reviewers, see scoring protocol):
+
+```
+Skill under test:  judge-<persona>
+Diff sample id:    <pr-number-or-fixture-id>
+Baseline output:   <attached or hash>
+Slimmed output:    <attached or hash>
+
+| Dimension                  | Score (1–5) | Rationale (≤ 30 words)         |
+|----------------------------|-------------|--------------------------------|
+| 1. Tone                    |             |                                |
+| 2. Vocabulary              |             |                                |
+| 3. Prompt-shape preservation |           |                                |
+| 4. Refusal patterns        |             |                                |
+| 5. Evidence-citation style |             |                                |
+| **Per-scorer mean**        |             | (sum / 5, one decimal)         |
+```
+
+## Acceptance arithmetic
+
+Three independent scorers produce three per-scorer means. The 3a.0.1
+gate fires on **two** thresholds simultaneously:
+
+- **Aggregate mean** (all dimensions, all scorers) **≥ 3.5/5** —
+  matches the 0.5.1 protocol.
+- **Tone dimension specifically** mean **≥ 4.0/5** — matches the
+  3a.0.1 voice-preservation kill-criterion. Tone is the load-bearing
+  dimension; vocabulary, prompt-shape, and citation style mostly track
+  it.
+
+Either threshold missed → escalate to council per 0.5.1 (any
+individual scorer < 3.0 also escalates). Council either revises the
+slim shape (one rework only) or invokes the 3a.0.2 abort branch and
+files `contexts/judges/no-consolidate-rationale.md`.
+
+## What this rubric does NOT measure
+
+- **Verdict parity** — covered separately by 3a.3 (cosine-token
+  similarity ≤ 10% drift, 100% verdict parity).
+- **Latency budget** — covered by 3a.0.1 (≤ +50ms vs. baseline).
+- **Mode-collision proxy** — explicit security-only-diff probe under
+  3a.0.1. Failure here aborts 3a regardless of voice score.
+- **Implementation correctness** — judges read diffs, this rubric
+  reads judges. The diff under test is a fixture, not the artefact
+  graded.
+
+## References
+
+- [`docs/contracts/context-paths.md`](../../../docs/contracts/context-paths.md)
+  — locked path tree (this file lives at `contexts/judges/`).
+- [`docs/contracts/load-context-schema.md`](../../../docs/contracts/load-context-schema.md)
+  — frontmatter contract for citing this rubric from a slimmed `judge-*`
+  skill in Phase 3a.2.

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

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

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

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

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

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

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

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

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

@@ -1,8 +1,10 @@
 ---
 type: "auto"
 alwaysApply: false
-description: "After completing a /implement-ticket or /work phase-step (refine, memory, analyze, plan, implement, test, verify, report) or full task — emit one telemetry:record call with consulted+applied artefact ids when telemetry.artifact_engagement.enabled is true"
+description: "After a /implement-ticket or /work phase-step (refine/memory/analyze/plan/implement/test/verify/report) or full task — emit one telemetry:record call with consulted+applied ids when enabled"
 source: package
+load_context:
+  - .agent-src.uncompressed/contexts/communication/rules-auto/artifact-engagement-recording-mechanics.md
 ---
 
 <!-- cloud_safe: noop -->
@@ -15,11 +17,10 @@ Default-off; opt-in via `.agent-settings.yml`. Zero overhead when disabled.
 
 The schema, CLI, and storage layer are owned by
 [`scripts/telemetry/`](../../../scripts/telemetry/) and the
-`./agent-config telemetry:record` / `telemetry:status` commands shipped
-in Phase 1+2 of the
-[`road-to-artifact-engagement-telemetry`](../../../agents/roadmaps/road-to-artifact-engagement-telemetry.md)
-roadmap. This rule says **when** to call the CLI, not how the file is
-structured.
+`./agent-config telemetry:record` / `telemetry:status` commands. The
+recording contract lives in
+[`docs/contracts/artifact-engagement-flow.md`](../../docs/contracts/artifact-engagement-flow.md).
+This rule says **when** to call the CLI, not how the file is structured.
 
 ## Activation gate — read settings ONCE per task, then cache
 
@@ -60,73 +61,16 @@ consulted three times in the same boundary records once.
 When in doubt → record as `consulted` only. Over-recording `applied`
 inflates the engagement signal and defeats the purpose.
 
-## What to record — id-only, no payload
-
-```bash
-./agent-config telemetry:record \
-  --task-id "$TASK_ID" \
-  --boundary task \
-  --consulted skills:php-coder \
-  --consulted skills:eloquent \
-  --consulted rules:scope-control \
-  --applied skills:php-coder \
-  --applied rules:scope-control
-```
-
-- `--task-id` — the ticket key (`PROJ-123`) for `/implement-ticket`, or a
-  short opaque slug derived from the prompt for `/work`. **Never** a
-  branch name, a file path, or a free-text title.
-- `--boundary` — `task` or `phase-step`, matching the cadence above.
-- `--consulted <kind>:<id>` — repeat per artefact. `<kind>` is one of
-  `skills`, `rules`, `commands`, `guidelines`, `personas`.
-- `--applied <kind>:<id>` — repeat per artefact actually applied.
-- Exit `0` always when disabled (silent). Exit `1` on schema validation
-  failure (rule must NOT swallow this — surface to the user). Exit `2`
-  on IO failure.
-
-## Privacy contract — what NEVER goes into a record
-
-The CLI rejects most violations on the input boundary, but the agent must
-not even attempt these:
-
-- ❌  File paths (`src/Foo.php`, `tests/...`) — id fields are
-  artefact identifiers only.
-- ❌  Source code, prompt text, ticket body, AC text.
-- ❌  Branch names, commit shas, PR numbers, URLs.
-- ❌  Secrets, env vars, credentials, customer data.
-- ❌  Free-text strings longer than 200 chars (CLI enforces; agent must
-  not generate).
-
-When in doubt → **don't record**. A missing event is cheap; a leaked
-prompt is not.
-
-## Failure modes — DO NOT block the user's task
-
-- Schema rejection (CLI exit `1`) → log the message internally, continue
-  the user's task. Do **not** halt the dispatch loop.
-- IO failure (CLI exit `2`) → same. The telemetry is **observation**, not
-  a delivery requirement.
-- Settings malformed → already handled by the CLI: it falls back to
-  disabled and exits `0`. Agent treats it as "disabled this task".
-
-The only error the agent surfaces is when the user explicitly asked for
-recording (`telemetry:status` confirms enabled) but no event reached the
-log — that is a real bug, not a swallowed error.
-
-## What this rule does NOT do
-
-- Run when `enabled: false` (cost floor is zero — see
-  [`tests/telemetry/test_cost_floor.py`](../../../tests/telemetry/test_cost_floor.py)).
-- Track the agent's tool calls, file reads, or token spend — that is
-  out of scope, see the roadmap's "out-of-scope" section.
-- Decide retirement. Phase 4's aggregator + report renderer are the only
-  consumers that may interpret the JSONL.
-- Run on cloud surfaces (Claude.ai Web, Skills API). The
-  `cloud_safe: noop` marker keeps it inert there.
+## Mechanics — CLI invocation, privacy contract, failure handling
+
+The exact `telemetry:record` call shape with all flags, the privacy
+contract (what NEVER goes into a record), the failure-mode handling
+(do NOT block the user's task), and the "what this rule does NOT do"
+catalog live in
+[`contexts/communication/rules-auto/artifact-engagement-recording-mechanics.md`](../contexts/communication/rules-auto/artifact-engagement-recording-mechanics.md).
 
 ## See also
 
-- [`road-to-artifact-engagement-telemetry`](../../../agents/roadmaps/road-to-artifact-engagement-telemetry.md) — phase contract
 - [`docs/contracts/artifact-engagement-flow.md`](../../docs/contracts/artifact-engagement-flow.md) — recording contract details
 - [`/implement-ticket`](../commands/implement-ticket.md) and [`/work`](../commands/work.md) — boundary points where this rule fires
 - [`scripts/telemetry/`](../../../scripts/telemetry/) — engine source

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

@@ -17,16 +17,13 @@ ONE QUESTION PER TURN. NO EXCEPTIONS.
 ASK. WAIT FOR THE ANSWER. THEN ASK THE NEXT.
 ```
 
-This is absolute. Not a default, not a guideline, not "usually".
-Every turn that contains a question contains **exactly one** question.
-Even if the questions look trivial. Even if they look independent.
-Even if they would fit on one screen. Even if batching "feels more
-efficient". Full self-check, ordering, and handoff rules under
-[How to ask](#how-to-ask).
+Absolute. Not a default, not "usually". Every turn with a question
+has **exactly one**. Even if trivial, independent, or batchable.
+Self-check, ordering, handoff under [How to ask](#how-to-ask).
 
 ## When to ask
 
-- Requirement is ambiguous or could be interpreted multiple ways
+- Requirement ambiguous or multi-interpretable
 - Not 100% sure which approach is correct
 - About to touch code you haven't fully understood
 - Choosing between multiple valid approaches
@@ -34,47 +31,35 @@ efficient". Full self-check, ordering, and handoff rules under
 
 ## Vague-request triggers — MUST ask
 
-The following patterns are almost always too vague to execute safely. When the user's
-request matches one of these without further context, ask **before** touching code:
+These patterns are too vague to execute safely. Match without further
+context → ask **before** touching code:
 
-| Pattern | Missing info | Example question |
-|---|---|---|
-| "improve / optimize this" | What metric? Speed, readability, memory? | "Optimize for what — execution speed or readability?" |
-| "add caching" | Cache store? Scope? Invalidation rules? | "Which cache driver, and what invalidates it?" |
-| "make it better / cleaner" | By what standard? | "What specifically feels wrong in the current code?" |
-| "clean up this file" | Dead code? Formatting? Refactor? | "Remove unused code, reformat, or restructure?" |
-| "fix this" (without specifying) | What's the symptom? | "What output/behavior is wrong right now?" |
-| "refactor X" | Target pattern? Boundaries? | "Refactor toward what — smaller methods, extract class, or something else?" |
-| "use best practices" | Whose? For what? | "Best practices for what specifically — testing, naming, structure?" |
-| "handle errors properly" | Which errors? How? Log, retry, propagate? | "For which failure modes, and what should happen on error?" |
-| "add a UI / component / tile / page" when the repo mixes frameworks | Which stack? Tailwind? Flux? Livewire? Custom? | "This repo uses {A} and {B} for UI — which one for this?" |
+- "improve / optimize this" — metric? speed, readability, memory?
+- "add caching" — store? scope? invalidation?
+- "make it better / cleaner" — by what standard?
+- "clean up this file" — dead code? format? refactor?
+- "fix this" (no symptom) — what output is wrong?
+- "refactor X" — target pattern? boundaries?
+- "use best practices" — whose? for what?
+- "handle errors properly" — which errors? log/retry/propagate?
+- "add a UI/component/tile/page" in mixed-framework repo — which stack?
 
-**Escape hatch:** If surrounding context (ticket, open file, prior conversation)
-makes the answer unambiguous, proceed — but state the assumption explicitly.
+Example questions per pattern:
+[`asking-and-brevity-examples`](../../docs/guidelines/agent-infra/asking-and-brevity-examples.md#vague-request-triggers--example-questions).
 
-## How to ask
-
-Be specific. Present numbered options (per `user-interaction`). Keep it short.
+**Escape hatch:** if context (ticket, open file, prior turn) makes
+the answer unambiguous, proceed — but state the assumption.
 
-The Iron Law (one question per turn) is at the top of this file.
-This section adds the rationale, self-check, and ordering.
-
-The user must never have to track sub-numbers, scroll through stacked
-option blocks, or split their reply across multiple questions. One
-question, numbered options (per `user-interaction`), one short
-answer, next turn.
+## How to ask
 
-Rationale — why even "trivial" batches fail:
+Numbered options (per `user-interaction`). Short. The Iron Law is at
+the top; this section adds self-check and ordering.
 
-| Situation | Why serial always wins |
-|---|---|
-| Design / architecture decisions | Answer to Q1 reframes Q2 |
-| Naming / command-syntax / API shape | Later choices depend on it |
-| Scope / PR boundaries | Changes what the other questions even mean |
-| Tool / library selection | Downstream choices branch from it |
-| "Which approach: A vs B vs C" | Each answer opens a different follow-up |
-| Even "independent" yes/no pairs | User still has to parse two contexts |
-| Any question the user has to **think** about, not just pick | Thinking load compounds when stacked |
+The user must never track sub-numbers, scroll stacked option blocks,
+or split a reply across multiple questions. Rationale shorthand: if
+the user has to *think* about an answer, that answer almost always
+reframes the next question. Full rationale:
+[`asking-and-brevity-examples`](../../docs/guidelines/agent-infra/asking-and-brevity-examples.md#one-question-per-turn--why-serial-always-wins).
 
 ### Self-check before asking
 
@@ -94,7 +79,7 @@ are related".
 - **Session handoff** (`/agent-handoff`, fresh-chat proposal): ask LAST,
   after all domain / clarifying questions — so the user's answers can be
   folded into the handoff prompt. Full rationale in
-  [`agent-interaction-and-decision-quality`](../guidelines/agent-infra/agent-interaction-and-decision-quality.md#handoff--model-switch-questions).
+  [`agent-interaction-and-decision-quality`](../../docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md#handoff--model-switch-questions).
 - **Model switch**: different phase — [`model-recommendation`](model-recommendation.md)
   triggers at task start with its own STOP-AND-WAIT gate, standalone, not
   appended to a Q&A block. Do not conflate the two.

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

@@ -2,6 +2,8 @@
 type: "auto"
 description: "Editing or creating files inside .augment/ directory — skills, rules, commands, templates, contexts must be project-agnostic"
 source: package
+load_context:
+  - .agent-src.uncompressed/contexts/communication/rules-auto/augment-portability-mechanics.md
 ---
 
 # Package Portability
@@ -36,76 +38,28 @@ content into any of them pollutes downstream projects or misleads agents.
 
 ## Runtime invocations — no `task` commands
 
-Skills, rules, commands, guidelines, personas, and context docs
-shipped by this package run in **consumer projects**. Consumer
-projects may not have [Task](https://taskfile.dev) installed —
-they might use npm scripts, Composer scripts, Make, or nothing at
-all. A skill that instructs an agent to run `task <something>`
-silently breaks in every project without a `Taskfile.yml`.
-
-**Rule:** Never reference a `task <something>` invocation inside any
-artefact file under `.agent-src.uncompressed/{skills,rules,commands,guidelines,personas,contexts}/`
+Skills, rules, commands, guidelines, personas, and context docs run in
+**consumer projects**, which may not have Task installed. **Never**
+reference a `task <something>` invocation inside any artefact file
+under `.agent-src.uncompressed/{skills,rules,commands,guidelines,personas,contexts}/`
 (and therefore also not in the compressed mirror under `.agent-src/`).
-Use the direct script invocation instead:
-
-| ❌ Forbidden | ✅ Portable |
-|---|---|
-| `task sync` | `bash scripts/compress.sh --sync` |
-| `task sync-check` | `bash scripts/compress.sh --check` |
-| `task sync-check-hashes` | `bash scripts/compress.sh --check-hashes` |
-| `task sync-changed` | `bash scripts/compress.sh --changed` |
-| `task sync-mark-done -- X` | `bash scripts/compress.sh --mark-done X` |
-| `task generate-tools` | `python3 scripts/compress.py --generate-tools` |
-| `task lint-skills` | `python3 scripts/skill_linter.py --all` |
-| `task check-refs` | `python3 scripts/check_references.py` |
-| `task check-portability` | `python3 scripts/check_portability.py` |
-| `task check-compression` | `python3 scripts/check_compression.py` |
-| `task validate-schema` | `python3 scripts/validate_frontmatter.py` |
-| `task counts-check` | `python3 scripts/update_counts.py --check` |
-| `task roadmap-progress` | `./agent-config roadmap:progress` |
-| `task ci` | run each underlying script directly (no single portable equivalent) |
-
-Task remains a convenience shortcut for maintainers working on the
-package repo itself — `task ci` is the recommended local gate before
-a PR and lives in `Taskfile.yml`, `AGENTS.md`, and the package README.
-Those maintainer-facing surfaces are outside the scope of this rule.
-Artefact files must assume Task is absent.
-
-The detection pattern *"if the consumer has a `Makefile` / build
-script, prefer its targets over raw commands"* is still allowed when
-the skill adapts to the **consumer's own** tooling (e.g.
-`tests-execute` detecting `php artisan test` vs `vendor/bin/pest`).
-It is not allowed to reference `task <name>` as the detected target —
-every direct invocation must resolve to a real script path.
+Use direct script invocations instead.
 
 ## Consumer CLI — `./agent-config`
 
 A subset of package scripts is exposed through a project-local CLI
 wrapper `./agent-config` (written into the project root by the
 installer, gitignored). Artefacts MUST prefer the CLI over raw
-`python3 scripts/…` paths for every command the CLI already covers,
-because the raw paths only resolve inside the package repo — in a
-consumer project the scripts live under `node_modules/` or `vendor/`.
+`python3 scripts/…` paths for every command the CLI already covers.
 
-| ❌ Forbidden in artefacts | ✅ Portable |
-|---|---|
-| `python3 scripts/mcp_render.py` | `./agent-config mcp:render` |
-| `python3 scripts/mcp_render.py --check` | `./agent-config mcp:check` |
-| `python3 .augment/scripts/update_roadmap_progress.py` | `./agent-config roadmap:progress` |
-| `python3 .augment/scripts/update_roadmap_progress.py --check` | `./agent-config roadmap:progress-check` |
-| `bash scripts/first-run.sh` | `./agent-config first-run` |
-| `PYTHONPATH=… python3 -m implement_ticket` | `./agent-config implement-ticket` |
-| `python3 scripts/memory_lookup.py` | `./agent-config memory:lookup` |
-| `python3 scripts/memory_signal.py` | `./agent-config memory:signal` |
-| `python3 scripts/memory_hash.py` | `./agent-config memory:hash` |
-| `python3 scripts/check_memory.py` | `./agent-config memory:check` |
-| `python3 scripts/check_memory_proposal.py` | `./agent-config memory:check-proposal` |
-| `python3 scripts/check_proposal.py` | `./agent-config proposal:check` |
-| `python3 scripts/refine_ticket_detect.py` | `./agent-config refine-ticket:detect` |
+## Translation tables — see mechanics
 
-Commands not covered by the CLI stay as direct script invocations
-(e.g. `bash scripts/compress.sh --sync`) — those are maintainer-only
-and not reachable from a consumer project anyway.
+The full `task`-to-script translation table, the `./agent-config`
+CLI mapping, and the rationale (Task absence on consumers,
+maintainer-vs-artefact split) all live in
+[`contexts/communication/rules-auto/augment-portability-mechanics.md`](../contexts/communication/rules-auto/augment-portability-mechanics.md).
+Pull it whenever an artefact is about to mention a runtime
+invocation.
 
 ## Enforcement