@event4u/agent-config 1.19.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

@@ -151,41 +151,33 @@ Your agent now understands slash commands:
 | `/optimize skills` | Audit skills, find duplicates, run linter |
 | `/feature plan` | Interactively plan a feature |
 | `/quality-fix` | Run and fix all quality checks |
-| `/chat-history` | Inspect the persistent chat-history log |
-| `/chat-history-resume` | Recover context after a crashed or switched session |
-| `/chat-history-clear` | Wipe the chat-history log (with confirmation) |
+| `/chat-history` | Inspect the persistent chat-history log (read-only `show`) |
 
 → [Browse all 95 active commands](../.agent-src/commands/)
 
 ---
 
-## Crash recovery — `.agent-chat-history`
+## Crash recovery — `agents/.agent-chat-history`
 
 When `chat_history.enabled: true` in `.agent-settings.yml` (on by default
 for every profile), the agent keeps a JSONL log of your conversation in
-`.agent-chat-history` at the project root. The file is git-ignored and
-rotates at the size configured in the profile (`128 KB` on `minimal`,
-`256 KB` on `balanced`, `512 KB` on `full`).
-
-When a chat opens and finds an existing log, the host agent is
-instructed to run a 4-state ownership check and choose the right
-flow:
-
-- **match** — this chat already owns the file. Append silently.
-- **foreign** — a different session's file. You get 3 options:
-  Resume (adopt), New start (archive + init), Ignore (skip logging).
-- **returning** — this chat once owned the file, but another session
-  took over in between. You get 3 options: Merge (your history in front
-  of the foreign entries), Replace (wipe foreign entries, keep yours
-  only), Continue (just leave the file and append from now on).
-- **missing** — no file yet. Init and proceed.
-
-Run `/chat-history-resume` to walk through the prompts explicitly, or
-let the agent ask on the first turn of a new chat. All merge/replace/
-resume paths read the on-disk entries into context before any write.
-
-See the [`chat-history` rule](../.agent-src/rules/chat-history-ownership.md) and
-[`scripts/chat_history.py`](../scripts/chat_history.py) for the mechanics.
+`agents/.agent-chat-history`. The file is git-ignored and rotates at the
+size configured in the profile (`128 KB` on `minimal`, `256 KB` on
+`balanced`, `512 KB` on `full`).
+
+Logging is **hook-only**: a structural Augment hook fires on
+`session_start` and binds the log to the current session via auto-adopt
+— no agent prompts, no ownership questions. The file is rewritten
+transparently if the fingerprint does not match (fresh chat) and
+otherwise appended to.
+
+Run `/chat-history` (a.k.a. `/chat-history show`) any time to inspect
+the log size, last entries, and current fingerprint. For the rare case
+where auto-adopt misfires (corrupted file, hook misconfiguration), run
+`./agent-config chat-history:adopt` as the manual recovery lever.
+
+See [`agents/contexts/chat-history-platform-hooks.md`](../agents/contexts/chat-history-platform-hooks.md)
+and [`scripts/chat_history.py`](../scripts/chat_history.py) for the mechanics.
 
 ---
 

package/docs/guidelines/agent-infra/ask-when-uncertain-demos.md

@@ -106,7 +106,7 @@ Agent: Bevor ich die Roadmap übergebe:
 - Welcher Branch?
 - Soll ich PRs erwähnen?
 - Welches Modell für die Fortsetzung?
-- Soll ich .agent-chat-history zitieren?
+- Soll ich agents/.agent-chat-history zitieren?
 
 Antworte als 1, 2, 3, 4.
 ```

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.