@event4u/agent-config 1.20.0 → 1.21.0

package/docs/decisions/ADR-rule-kernel-and-router.md

@@ -0,0 +1,122 @@
+# ADR — Rule Kernel and Router (Roadmap Closure)
+
+- **Status:** Accepted (2026-05-06)
+- **Closes:** `agents/roadmaps/road-to-kernel-and-router.md`
+- **Sibling roadmaps closed in the same window:**
+  `agents/roadmaps/road-to-token-optimization.md`
+  (Phase 1 shipped, Phase 2/3 deferred-with-trigger by design),
+  `agents/roadmaps/road-to-package-optimization.md`
+  (closed with null result per P1.1 binary acceptance gate).
+- **Related ADRs:** ADR-001 (kernel-swap deferred), ADR-002
+  (kernel-bucket cap raise 25k → 26k, per-rule Iron-Law overrides).
+
+## Context
+
+The agent rule set was an "always-loaded" surface: every conversation
+paid the full 193k-char rule cost regardless of task. There was no
+deterministic way to load only the policy actually relevant to the
+current intent, and no mechanical guard against rule-bucket creep.
+
+## Decision
+
+Adopt a **Kernel + Router** loading model with three tiers and three
+cost profiles, governed by a compiled router manifest and CI-enforced
+size budgets.
+
+### What shipped
+
+- **Kernel:** 9 always-loaded Iron-Law rules (`agent-authority`,
+  `ask-when-uncertain`, `commit-policy`, `direct-answers`,
+  `language-and-tone`, `no-cheap-questions`,
+  `non-destructive-by-default`, `scope-control`,
+  `verify-before-complete`). Locked set:
+  [`docs/contracts/kernel-membership.md`](../contracts/kernel-membership.md).
+- **Router:** `router.json` compiled deterministically from rule
+  frontmatter (`tier:`, `triggers:`, `routes_to:`) by
+  `scripts/compile_router.py`. Contract:
+  [`docs/contracts/rule-router.md`](../contracts/rule-router.md).
+- **Cost profiles:** `minimal` = kernel only · `balanced` = kernel +
+  tier-1 (default) · `full` = kernel + tier-1 + tier-2.
+- **Budget gates:** `task lint-rule-budget` enforces kernel ≤ 26k chars
+  and per-rule ≤ 2.5k (Iron-Law overrides up to 4.0k via ADR-002).
+  Daily snapshots in `agents/.rule-budget-history.jsonl`.
+- **Compression discipline:** P4.3 brought the auto-bucket from
+  ~75k → 59 220 chars (under the 60k target) without behaviour drift.
+
+### What we cut
+
+- **P4.1 / P4.2** — auto-rule → skill / guideline migrations.
+  Cancelled as scope-cut after P4.3 compression alone landed the
+  auto-bucket under target. The migrations were a means, not an end.
+- **road-to-package-optimization Phase 1.2 / 1.3 / Phase 2 / Phase 3**
+  — cancelled per P1.1's binary acceptance gate. The prototype
+  contradiction linter scanned 317 artefacts in 0.034 s and flagged
+  zero cross-artefact contradictions. The artefact surface is
+  empirically already well-governed on the heuristics tested; building
+  a production linter for a non-existent failure mode is not honest.
+- **road-to-token-optimization Phase 2 / Phase 3** — *not* cut, just
+  trigger-deferred by design (telemetry threshold + `/cost:report`
+  ship). Will reopen autonomously when their declared signals fire.
+
+### What stayed
+
+- All Iron-Law fences. SHA-verified preserved by
+  `scripts/iron_law_sha.py` across the kernel compression pass.
+- Behaviour parity. Golden transcripts pass under all three profiles.
+- The pre-existing `auto`-tier rules; only their compressed bodies
+  changed, never their obligation surface.
+
+## Profile semantics
+
+| Profile | Buckets loaded | Use case |
+|---|---|---|
+| `minimal` | kernel only | Tightly bounded automation, CLI shell-outs, "run this one command" |
+| `balanced` *(default)* | kernel + tier-1 | Day-to-day engineering work; matches pre-roadmap behaviour superset |
+| `full` | kernel + tier-1 + tier-2 | Architectural / cross-wing / governance sessions |
+
+Consumer projects opt in via `personal.cost_profile` in
+`.agent-settings.yml`. The install script keeps user-set values; only
+the template default is `balanced`.
+
+## Reversibility
+
+If the Kernel + Router model needs unwinding:
+
+1. Set every rule's frontmatter `tier:` to `kernel` and rebuild
+   `router.json` — every rule loads on every turn (legacy behaviour).
+2. Drop `lint-rule-budget` from `task ci`.
+3. The compiled `router.json` is a derived artefact; deleting it and
+   running `compile_router.py --no-router` returns the always-loaded
+   model.
+
+No data migration, no irreversible compression. Iron-Law SHA fences
+mean Iron Laws can be diffed against the pre-roadmap baseline at any
+point.
+
+## Final measurements (2026-05-06)
+
+| Metric | Pre-roadmap | Post-roadmap | Δ |
+|---|---:|---:|---:|
+| kernel bucket | n/a (always-loaded) | 25 590 | new gate |
+| auto bucket | ~75 000 | 59 220 | −21 % |
+| total rule chars | ~193 000 | 84 810 | −56 % |
+| rule count | 56 | 57 (added `token-optimizer-maintenance`) | +1 |
+| skills count | 134 | 135 (added `token-optimizer`) | +1 |
+
+Kernel-bucket-check: PASS. Per-rule cap: 16 rules over 2.5k target,
+all within 4.0k Iron-Law override per ADR-002. Trend snapshot
+appended to `agents/.rule-budget-history.jsonl`.
+
+## Consequences
+
+- New rule submissions must declare `tier:` + `triggers:` + (when
+  applicable) `routes_to:` in frontmatter; the router compiler
+  rejects malformed entries.
+- Editing Iron-Law-fenced bodies requires a fresh
+  `scripts/iron_law_sha.py --update` pass; CI fails on hash drift.
+- The `token-optimizer` skill is now the single consult surface for
+  token-cost decisions; editing any cited asset requires a same-commit
+  catalog update per `token-optimizer-maintenance` rule (CI-backstopped
+  by `scripts/check_token_optimizer_freshness.py`).
+- Deferred phases (token-opt P2/P3, kernel-swap from ADR-001) remain
+  reopenable on their declared triggers without further roadmap work.

package/docs/getting-started.md

@@ -115,7 +115,7 @@ Your agent is now:
 - **Respecting your codebase** — no conflicting patterns
 - **Following standards** — consistent code quality
 
-This is enforced automatically by 56 rules. No configuration needed.
+This is enforced automatically by 58 rules. No configuration needed.
 
 ---
 
@@ -153,7 +153,7 @@ Your agent now understands slash commands:
 | `/quality-fix` | Run and fix all quality checks |
 | `/chat-history` | Inspect the persistent chat-history log (read-only `show`) |
 
-→ [Browse all 94 active commands](../.agent-src/commands/)
+→ [Browse all 95 active commands](../.agent-src/commands/)
 
 ---
 

package/docs/guidelines/agent-infra/roadmap-progress-mechanics.md

@@ -0,0 +1,176 @@
+# Roadmap Progress Sync
+
+> Any touch to agents/roadmaps/ — create/rename/delete/move, edit checkboxes ([x]/[~]/[-]), add/rename/remove phases — must regenerate dashboard and archive if 0 open items, same response
+
+_Origin: migrated from `.agent-src.uncompressed/rules/roadmap-progress-sync.md` per P4.2 of `road-to-kernel-and-router.md`._
+
+<!-- cloud_safe: degrade -->
+<!-- Authoring discipline applies in cloud; local script + regen are no-ops there. -->
+
+# Roadmap Progress Sync
+
+> **Enforced by:** [`scripts/roadmap_progress_hook.py`](../../scripts/roadmap_progress_hook.py)
+> on Augment + Claude Code (`PostToolUse`). Hook is primary; the prose
+> below is the specification the hook implements and the fallback when
+> the platform has no hook surface.
+
+## Iron Law — dashboard sync
+
+```
+ANY ROADMAP TOUCH → REGENERATE THE DASHBOARD, SAME RESPONSE.
+NO EXCEPTIONS. NO "I'LL DO IT AT THE END". NO BATCHING ACROSS TURNS.
+A ROADMAP NOT IN THE DASHBOARD IS A RULE VIOLATION, NOT AN OVERSIGHT.
+```
+
+**Roadmap touch =** create the file, rename it, delete it, move it
+between `roadmaps/` ↔ `archive/` ↔ `skipped/`, add/rename/remove a
+phase, **OR** flip any checkbox (`[ ]` ↔ `[x]` ↔ `[~]` ↔ `[-]`).
+
+`agents/roadmaps-progress.md` is the read-only dashboard. Every
+unsynced edit makes it lie to the next reader. Created a roadmap
+without regenerating? The dashboard claims it does not exist. Marked
+8 steps `[x]` and forgot the regen? The dashboard says 0 done.
+
+## Iron Law — every active roadmap is trackable
+
+```
+EVERY ACTIVE ROADMAP MUST CONTAIN AT LEAST ONE TRACKABLE CHECKBOX
+(`- [ ]`) PER NON-INTRO PHASE. ROADMAPS WITHOUT EXECUTABLE STEPS
+EITHER GET A CHECKLIST OR THE `status: draft` FLAG.
+CI-ENFORCED: `scripts/check_roadmap_trackable.py` (CANNOT BE DEFERRED).
+```
+
+**Active roadmap =** any file in `agents/roadmaps/` (root, not
+`archive/` or `skipped/`) without `status: draft` frontmatter.
+
+**Trackable checkbox =** an actionable `- [ ]` line under a `## Phase N`
+or `### Phase N` heading (numeric `Phase 1`, roman `Phase II`, or
+letter-track `Phase A1` — matched by the dashboard's `PHASE_RE`).
+Tables of decisions, ICE matrices, ADR captures, and "block
+sequencing" tables are valid **rationale**, but they do not satisfy
+this rule on their own — they must be paired with at least one
+`## Phase N` section whose checkboxes execute the decision.
+Headings such as `## Phase steps`, `### Sequencing — Phase 1 …`,
+`### P0 #1 — …`, or `## Block A` do **not** count — only the
+canonical `Phase <id>` form parsed by the dashboard.
+
+**CI backstop.** `scripts/check_roadmap_trackable.py` (package-shipped,
+wire into the consumer's pre-commit / pre-push / Actions gate) fails
+when an active roadmap has zero canonical `Phase` headings or when
+any parsed phase has zero checkboxes. Last line of defence — real-time
+authoring still flips checkboxes and regenerates the dashboard the
+same response.
+
+## Status — binary `ready` (default) vs `draft`
+
+```yaml
+---
+status: draft          # hidden from the dashboard until flipped
+---
+```
+
+Two values, no synonyms. Anything else — no frontmatter at all,
+`status: ready`, an unknown value — counts as **ready** and lands
+in the dashboard.
+
+- **Ready** is the implicit default. New roadmaps are created
+  ready unless the user explicitly says draft. Ready roadmaps are
+  listed in the dashboard, count towards open/done totals, and
+  trip the "completed but not archived" warning when they close.
+- **Draft** hides the file from the dashboard entirely (not
+  counted, not listed). Use it while the roadmap is still being
+  authored, while waiting for upstream decisions, or as a
+  capture-only synthesis that has not yet been promoted to
+  executable phases. Flip to ready (or remove the field) the
+  moment the roadmap is ready to track.
+
+**Completion = archival, same response.** When the edit takes a
+roadmap to `count_open == 0` (every item is `[x]`, `[~]`, or `[-]`),
+`git mv` it into `agents/roadmaps/archive/` (or `skipped/` if no `[x]`
+at all) **before** regenerating the dashboard. A 100%-complete
+roadmap left under `agents/roadmaps/` is a rule violation, not an
+optional cleanup. See `roadmap-management` skill for the archive vs
+skipped decision table.
+
+## Agent-authored roadmaps — placement is mandatory
+
+```
+A FILE THE AGENT DROPS INTO agents/roadmaps/ MUST EITHER
+(a) PASS check_roadmap_trackable.py AND LAND IN THE DASHBOARD, OR
+(b) NOT BE IN agents/roadmaps/ AT ALL.
+NO "DECISION MATRIX" / "DESIGN NOTE" SHORTCUT.
+```
+
+When the agent autonomously creates a roadmap, it owns the placement
+in the **same response**:
+
+- **Phase plan** (checkboxes, multi-turn execution) → `agents/roadmaps/<name>.md`, `status: ready` (default), regen dashboard.
+- **Decision matrix / ADR / pattern / lookup** (no `Phase N`, durable rationale) → `agents/contexts/<name>.md`.
+- **Completed work snapshot** → `agents/roadmaps/archive/<name>.md`.
+
+A non-trackable file in `agents/roadmaps/` is a rule violation — the
+trackable CI fails it, the dashboard hides it. The agent that
+created it moves it the same response. If the autonomous run also
+**finishes** the roadmap within the session (every box `[x]`/`[~]`/`[-]`),
+the completion-archival rule above fires too — same response.
+
+## Autonomous execution — checkbox cadence
+
+When executing a roadmap autonomously (multi-turn, no per-step user
+prompt), the user loses progress visibility unless checkboxes flip
+**as work lands**, not in a batch at the end. Iron Law:
+
+```
+EVERY DONE STEP FLIPS [ ] → [x] IN NEXT REPLY THAT ACKNOWLEDGES IT.
+NO "I UPDATE ROADMAP AT END OF PHASE."
+NO "FOUR STEPS DONE, ONE COMMIT, ONE REGEN."
+```
+
+Step counts as completed when:
+
+- Code / docs change for that step has been **written and saved** AND
+- Verification cited in the step (project CI command, targeted test, lint) has
+  **passed in this response or an earlier one** — fresh output, not memory.
+
+Then in the **same reply**: flip the checkbox, regenerate the
+dashboard, commit if commit policy allows.
+
+**Forbidden:** four turns of step work, dashboard flat, single regen at the end.
+**Required:** each turn — implement step, flip `[x]`, regen, commit (if policy allows).
+A reply that lands a verified step without flipping its checkbox is a rule violation.
+
+**In-progress marker:** when a step takes more than one reply,
+mark it `[~]` the moment work starts on it and regenerate. The
+user sees one row move from `[ ]` to `[~]` to `[x]` instead of
+silent rows. `[~]` is treated as open for `count_open` but moves
+the phase percentage forward in the dashboard.
+
+## Mechanics — triggers, regen command, self-check, failures
+
+The triggers table, the regen command (`./agent-config roadmap:progress`),
+the mandatory pre-send self-check, the failure-mode catalog, and the
+`Do NOT` list live in
+[`contexts/communication/rules-auto/roadmap-progress-sync-mechanics.md`](../contexts/communication/rules-auto/roadmap-progress-sync-mechanics.md).
+Pull it whenever a trigger fires — the rule above is the obligation
+surface; the mechanics file is the lookup material.
+
+## Copilot fallback
+
+GitHub Copilot has no `PostToolUse` hook surface, so
+`scripts/roadmap_progress_hook.py` cannot detect roadmap-file writes
+structurally. The dashboard at `agents/roadmaps-progress.md` will
+not regenerate on its own.
+
+The cooperative path: every time a roadmap touch fires (per the
+trigger list in the mechanics context above), the agent regenerates
+the dashboard in the same response — which is the same Iron Law the
+hook enforces, just executed manually:
+
+```bash
+./agent-config roadmap:progress
+```
+
+The hook implementation is the specification; on Copilot the agent
+runs the regenerator itself after the same triggers fire. Skipping
+it is a rule violation, not a hook gap — the Iron Law on dashboard
+sync survives the missing hook surface.

package/docs/guidelines/agent-infra/rule-type-governance.md

@@ -0,0 +1,73 @@
+# Rule Type Governance
+
+> Creating or editing rules, or auditing rule types — decides when a rule should be always vs auto
+
+_Origin: migrated from `.agent-src.uncompressed/rules/rule-type-governance.md` per P4.2 of `road-to-kernel-and-router.md`._
+
+# rule-type-governance
+
+## `always` = loaded every conversation
+
+Use ONLY when the rule applies to virtually every interaction:
+
+- Universal agent behavior (language, tone, interaction style)
+- Safety constraints (scope control, verification before completion)
+- Token/efficiency constraints
+- First-message checks that cannot wait for auto-trigger
+
+## `auto` = loaded on demand by description match
+
+Use for everything else:
+
+- Language-specific rules (PHP, JS, SQL)
+- Tool-specific rules (Docker, Git, quality tools)
+- Workflow-specific rules (commands, skill creation, E2E testing)
+- Domain-specific rules (translations, architecture)
+
+## Decision test
+
+> "Does this rule need to be active when the user asks a simple question, reviews a PR, or discusses architecture?"
+
+- Yes → `always`
+- No → `auto` with a clear trigger description
+
+## Auto description quality
+
+The `description` field IS the trigger. It must describe **when** the rule applies, not **what** it contains.
+
+- ❌  `"PHP coding standards"` — too vague, won't match reliably
+- ✅  `"Writing or reviewing PHP code — strict types, naming, Eloquent conventions"`
+
+## Hard constraint
+
+- Default to `auto`. Justify `always`.
+- If >50% of conversations don't need a rule → it must be `auto`.
+- `optimize-agents` command checks this and suggests changes.
+
+## Hardening tier — required on new or edited rules
+
+Every new rule, and every edited rule whose body changes the trigger
+or the obligation, MUST classify itself against the hardening tiers
+documented in [`rule-trigger-matrix.md`](../../agents/contexts/rule-trigger-matrix.md):
+
+| Tier | Meaning |
+|---|---|
+| `1` | Mechanically enforceable — hook acts, rule body stays minimal. |
+| `2a` | Marker nudge — hook injects signal, agent acts on it. |
+| `2b` | Structured injection / tool-call gate — hook reads/writes state, may deny. |
+| `3` | Soft, judgment-bound — no platform surface; self-check rule. |
+| `safety-floor` | Iron-Law subset, never modified. |
+| `mechanical-already` | Precedent — script enforces, rule body documents. |
+
+Classification surface: the optional `tier:` frontmatter field
+(declared in `scripts/schemas/rule.schema.json`). Recommended for new
+rules; bulk-retrofit of existing rules is tracked separately.
+
+Tier 3 dispositions are recorded centrally in
+[`agents/contexts/tier-3-dispositions.md`](../../agents/contexts/tier-3-dispositions.md)
+with a 6-month re-audit clock. New Tier 3 rules append to that list
+on landing.
+
+The `optimize-agents` command checks the tier alongside `type`/`source`
+and suggests escalations when a rule's trigger matches a hardening
+opportunity that has shipped since the rule was authored.

package/docs/guidelines/agent-infra/size-and-scope.md

@@ -33,6 +33,11 @@ Size is a signal — not the goal.
 - Acceptable: **< 100–120 lines**
 - Hard limit: **< 200 lines**
 
+Linter (council review 2026-05-06): the > 40 / > 60 line warnings are
+**density-gated** — rules with ≥ 30 % fenced content (verbatim Iron-Law
+blocks, worked-example fences) are exempt from the line-count warning.
+The 200-line hard error stays unconditional.
+
 Reason:
 - Loaded frequently
 - Must be reliably followed
@@ -43,8 +48,10 @@ Reason:
 ## Skills
 
 - Target: **300–900 words**
-- Warning: **>1200 words**
-- Strong split signal: **>1500 words**
+- Warning: **> 400 lines** (raised from 300, council review 2026-05-06)
+- Strong split signal: reference-rich skills (analyzer, quality-tool
+  catalog, council orchestration) may legitimately sit between 300 and
+  400 lines without being split-candidates
 
 Focus:
 - scanability
@@ -57,6 +64,10 @@ Focus:
 
 - Target: **200–600 words**
 - Acceptable: **up to ~1000 words**
+- Warning: **> 1000 words AND lacks delegation structure** (< 5
+  sub-sections OR < 3 code blocks). Well-factored orchestrators with ≥ 5
+  sub-sections AND ≥ 3 code blocks are exempt — the size reflects
+  dispatch breadth, not bloat (council review 2026-05-06).
 
 Commands orchestrate — not implement.
 

package/docs/guidelines/agent-infra/skill-quality-checklist.md

@@ -0,0 +1,119 @@
+# Skill Quality
+
+> Creating, editing, or reviewing skills — minimum quality standard, every skill must be executable, validated, and self-contained
+
+_Origin: migrated from `.agent-src.uncompressed/rules/skill-quality.md` per P4.2 of `road-to-kernel-and-router.md`._
+
+# Skill Quality
+
+## Minimum Sharpness
+
+Every skill must answer four questions. If ANY answer is weak, the skill is not done.
+
+| # | Question | Section | Standard |
+|---|---|---|---|
+| 1 | When should I use this? | `When to use` | Concrete trigger, not generic |
+| 2 | What exactly do I do? | `Procedure` | Executable steps with decisions |
+| 3 | How do I verify it worked? | `Procedure` (validation step) | Concrete checks, not "verify it works" |
+| 4 | What common failure must I avoid? | `Gotcha` + `Do NOT` | Real failure patterns, not platitudes |
+
+## Required Sections
+
+Every skill MUST have: `When to use`, `Procedure`, `Gotcha`, `Output format`, `Do NOT`.
+
+## Frontmatter Contract
+
+Every skill's YAML frontmatter MUST validate against `scripts/schemas/skill.schema.json`.
+Violations are reported by `scripts/skill_linter.py` as `schema_<rule>` errors
+and fail `python3 scripts/validate_frontmatter.py` and the full CI pipeline.
+
+## Description Triggering
+
+Claude routes skills by their frontmatter `description`. Pushy,
+trigger-rich descriptions are required — polite or hedged ones cause
+undertriggering. The full recipe (concrete verb phrase, ≥2 triggers,
+`even if they don't explicitly ask for …` tail, ≤200 chars,
+litmus test) lives in
+[`contexts/communication/rules-auto/skill-quality-mechanics.md`](../contexts/communication/rules-auto/skill-quality-mechanics.md)
+§ Description Triggering.
+
+## Skill Independence
+
+```
+If a skill is not executable without opening a guideline, it is broken.
+```
+
+- Skills MAY reference guidelines for detailed conventions
+- Skills MUST NOT outsource their core workflow to guidelines
+- If removing guideline references makes the skill useless → the skill is too weak
+
+**Litmus test:** Cover all guideline references in the Procedure. Is it still executable?
+If not → the skill needs more own steps, decisions, and validation — not more guideline links.
+
+## Merge & Compression Preservation
+
+When merging or compressing skills, the result MUST preserve the
+strongest validation, strongest examples, all anti-patterns, all
+decision criteria, and trigger quality. Full preservation invariants
+and "merge is invalid if …" / "compression may remove …" lists in
+[`contexts/communication/rules-auto/skill-quality-mechanics.md`](../contexts/communication/rules-auto/skill-quality-mechanics.md)
+§ Merge Preservation and § Compression Preservation.
+
+## Refactor Safety
+
+When refactoring or optimizing skills:
+
+- NEVER weaken validation to pass linter
+- NEVER remove anti-patterns to reduce size
+- NEVER replace concrete checks with "verify it works"
+- NEVER merge skills if the result is broader than either source
+- ALWAYS run linter before and after — fail count must not increase
+
+## Senior-Tier Required Structure
+
+Skills with `tier: senior` in YAML frontmatter MUST carry four named
+blocks beyond the standard required sections:
+
+| # | Block | Heading / Location | Standard |
+|---|---|---|---|
+| 1 | Context-First lead | Frontmatter `description` | First sentence anchors the cognition cluster (domain + senior role); second sentence names the trigger. |
+| 2 | Related Skills | `## Related Skills` | Two-list pattern — `**WHEN to use this**` (situations this skill resolves) + `**WHEN NOT to use this**` (route-elsewhere peers, named). |
+| 3 | Proactive Triggers | `## When the agent should load this` | 3–5 concrete user-prompt patterns (paraphrases users actually type), not abstract categories. |
+| 4 | Output Artifacts | `## Output` | 1–4 named artifacts with shape (file path, table, markdown structure) — orchestrator-citable identifier each. |
+
+**Forward-only.** `scripts/skill_linter.py` enforces these blocks for
+`tier: senior` skills only; mid-tier and untiered skills skip the
+check. No retrofit pass on existing Wing-1 skills.
+
+Subsection specs (≤ 6-line spec + 1 reference example each), good /
+bad pattern pairs, and the WHEN-NOT routing peer rules live in
+[`contexts/communication/rules-auto/skill-quality-mechanics.md`](../contexts/communication/rules-auto/skill-quality-mechanics.md)
+§ Senior-tier patterns.
+
+## Structural Malice Floor
+
+`scripts/skill_linter.py` runs five regex patterns against every
+skill / rule / command body — credential exfiltration, remote
+execution, force-push to a protected ref, world-readable secret
+files, and shell-injection in subprocess calls. A match emits
+``Issue("error", "malice:<pattern>", "<line>:<matched>")`` and the
+linter exits with code **3** (security-failure), distinct from
+exit 2 (build-failure) so CI surfaces can split the two.
+
+The check is **structural**, not semantic — it catches the shapes
+the [`tool-safety`](tool-safety.md) rule denies in prose: hidden
+credentials, arbitrary execution, write-without-approval. Fixtures
+and the exit-code-3 contract live in
+[`tests/test_skill_linter_malice.py`](../../tests/test_skill_linter_malice.py).
+
+## Confidence Tagging
+
+Senior-tier procedure steps MAY append `[CONFIDENCE: high|medium|low]`
+at the end of multi-step chains where the agent's evidence varies
+across steps. Optional but recommended when a step's output feeds a
+downstream decision.
+
+Text-tag form is deliberate. Emoji 🟢 / 🟡 / 🔴 is **not** allowed —
+collides with [`direct-answers`](direct-answers.md) § Emoji scope
+(functional markers only). Linter does not enforce the tag itself;
+the rule documents the placement so authors converge on one form.

package/docs/guidelines/augment-portability-patterns.md

@@ -0,0 +1,68 @@
+# Augment Portability
+
+> Editing or creating files inside .augment/ directory — skills, rules, commands, templates, contexts must be project-agnostic
+
+_Origin: migrated from `.agent-src.uncompressed/rules/augment-portability.md` per P4.2 of `road-to-kernel-and-router.md`._
+
+# Package Portability
+
+Everything that ships with the `event4u/agent-config` package MUST be
+**project-agnostic**. That includes:
+
+- Everything inside `.augment/` (skills, rules, commands, guidelines,
+  templates, contexts)
+- The package repo's own root `AGENTS.md`
+- The package repo's own `.github/copilot-instructions.md`
+
+All three are either installed into consumer projects (`.augment/` via
+`install.sh`) or read by AI tools when working on the package itself
+(`AGENTS.md`, `copilot-instructions.md`). Leaking consumer-specific
+content into any of them pollutes downstream projects or misleads agents.
+
+## Rules
+
+- NEVER reference a specific consumer project, repo name, domain, or tech
+  stack directly. The package repo itself (`event4u/agent-config`) MAY be
+  named inside its own root `AGENTS.md` and `copilot-instructions.md` —
+  that is meta about the package, not a leak.
+- NEVER hardcode consumer-project paths, class names, or conventions.
+- Write content so it works as a **reusable package** across any project.
+- Project-specific behavior belongs in the **consumer's** `.agent-settings.yml`,
+  `AGENTS.md`, or `agents/` — never in files shipped by this package.
+- If a skill or rule needs project-specific input, read it from
+  `.agent-settings.yml` or accept it as a parameter.
+- When reviewing or editing package files, always ask: "Would this still
+  make sense in a completely different project?"
+
+## Runtime invocations — no `task` commands
+
+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 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.
+
+## Translation tables — see mechanics
+
+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
+
+`scripts/check_portability.py` scans `.augment/`, `.agent-src.uncompressed/`,
+and the package repo's root `AGENTS.md` + `.github/copilot-instructions.md`
+for forbidden identifiers, for any `task <name>` invocation inside
+artefact files, and for direct script invocations that bypass the
+`./agent-config` CLI. It runs in CI and must pass before any PR.

package/docs/guidelines/php/php-coding-patterns.md

@@ -0,0 +1,62 @@
+# Php Coding
+
+> Writing or reviewing PHP code — strict types, naming, comparisons, early returns, Eloquent conventions
+
+_Origin: migrated from `.agent-src.uncompressed/rules/php-coding.md` per P4.2 of `road-to-kernel-and-router.md`._
+
+# PHP Coding Rules
+
+- Use `declare(strict_types=1)` in every **new** PHP file. Not required when modifying existing files that don't have it.
+- If the project has a `Math` helper class, use it for ALL business calculations. Never use native PHP arithmetic operators (`+`, `-`, `*`, `/`) for business calculations. Search for the `Math` class in the project.
+- Never use `var_dump()`, `print_r()`, or `dd()` — they are disallowed by PHPStan config. Exception: legacy projects where these are already used and no alternative is feasible.
+- Never use `float` for money — use `decimal` or the `Math` helper.
+- Always use `===` / `!==` (strict comparison), Yoda style: `null === $var`.
+- Early return over nested if/else.
+- No one-liner if statements.
+- Single quotes for strings without interpolation. `sprintf()` for complex strings.
+- Variables: `camelCase`. Array keys: `snake_case`. Constants: `UPPER_SNAKE_CASE`.
+- Typed properties, parameters, and return types — always.
+- Constructor property promotion where it makes sense.
+
+## Eloquent Models — Attribute Access
+
+Read `eloquent.access_style` from `.agent-settings.yml` to determine the preferred style.
+Default: `getters_setters`. See the `eloquent` skill for the full reference table and examples.
+
+- **`getters_setters`** (strict): Every attribute has a typed getter + fluent setter. Inside the model: `getAttribute('column_name')`/`setAttribute('column_name', $value)`. Outside: always getters/setters. If a getter doesn't exist yet, create it first.
+- **`get_attribute`**: Use `getAttribute('column_name')`/`setAttribute('column_name', $value)` everywhere, no getters/setters needed.
+- **`magic_properties`**: Laravel default `$model->column_name` everywhere.
+
+### Relationship Getters
+
+- Every relationship MUST have a typed getter method **above** the relationship method.
+- **Inside the getter:** use `$this->getAttribute('relationship_name')`, NEVER `$this->relationship_name`.
+- **Outside the model:** ALWAYS use the getter (`$model->getEquipment()`), NEVER access the magic property (`$model->equipment`).
+- Use `instanceof` checks instead of `null ===` when checking relationship results.
+
+## Eloquent Models — Observers over `booted()`
+
+- Do NOT use `booted()` / `boot()` for model lifecycle hooks (saving, saved, deleted, etc.).
+- Use a dedicated **Observer** class registered via `#[ObservedBy]` attribute.
+- This keeps models slim and lifecycle logic testable and discoverable.
+
+## PHPStan
+
+- Always fix the root cause. Do NOT add entries to `phpstan-baseline.neon`.
+- Adding `ignoreErrors` to `phpstan.neon` is allowed for **structural toolchain limitations** (e.g., Pest runtime bindings). NOT for individual code issues. **If unsure → ask the user.**
+- If a fix is truly impossible (confirmed false positive), use an inline ignore as last resort:
+  ```php
+  // @phpstan-ignore-next-line — false positive: reason here
+  ```
+
+## Testing
+
+- Always write tests in **Pest**, not PHPUnit class syntax — unless the user explicitly asks for PHPUnit.
+- Pest tests in `tests/Unit/` automatically use `UnitTestCase` as the base class (configured in `tests/Pest.php`).
+
+## PHPDoc
+
+- Only add PHPDoc when type hints are insufficient (e.g. generic arrays: `@param array<int, MyObject> $items`).
+- Do NOT add PHPDoc that just repeats the method signature.
+- One docblock per method — never split into multiple `/** */` blocks.
+- Tag order: `@param` → `@return` → `@throws`.