@event4u/agent-config 1.19.0 → 1.21.0

package/scripts/_p43_bodies.py

@@ -0,0 +1,235 @@
+#!/usr/bin/env python3
+"""P4.3 — Write compressed rule bodies. Run after _p43_compress.py."""
+from __future__ import annotations
+import pathlib
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+RULES = ROOT / ".agent-src.uncompressed" / "rules"
+
+
+def write(name: str, content: str) -> None:
+    p = RULES / f"{name}.md"
+    p.write_text(content, encoding="utf-8")
+    print(f"  ✓ {name}: {len(content)} chars")
+
+
+# Each entry is the FULL file content (frontmatter + body).
+FILES: dict[str, str] = {}
+
+FILES["think-before-action"] = """---
+type: "auto"
+tier: "2b"
+description: "Before coding, modifying, or debugging — analyze first, verify with real tools, never guess or trial-and-error"
+alwaysApply: false
+source: package
+load_context:
+  - .agent-src.uncompressed/contexts/communication/rules-auto/think-before-action-mechanics.md
+triggers:
+  - intent: "before coding"
+  - intent: "before debugging"
+  - intent: "before modifying"
+---
+
+# think-before-action
+
+## The Iron Law
+
+```
+ANALYZE BEFORE CODING. VERIFY WITH REAL TOOLS. NEVER GUESS.
+NO BLIND TRIAL-AND-ERROR. MAX 2 RETRIES PER APPROACH.
+```
+
+- Always analyze before coding or modifying anything.
+- Never guess behavior — verify using code, data, or tools.
+- Prefer targeted inspection (jq, debugger, logs) over brute-force.
+- Always verify results after changes (API, UI, tests).
+- When behavior can be defined → prefer test-first / TDD.
+- Unclear requirements → precise clarification question, not hidden assumptions.
+- Refactors must preserve behavior, validation, examples, and anti-failure guidance unless explicitly changed.
+- Do NOT modify code you do not fully understand — read it, trace the flow, then change it.
+- Multiple valid frameworks/patterns coexist (Tailwind + Flux, multiple form libs, competing state stores) → do NOT pick one silently — ask. See [`no blind implementation`](../../docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md#2-no-blind-implementation).
+
+## Mechanics — workflow, minimum read set, verify-with-real-tools, no blind retries
+
+The five-step Understand → Analyze → Plan → Implement → Verify workflow, the minimum read set (symbol, callers, tests, abstractions, data), the memory-consult step, the verification matrix, the output-reduction patterns, the no-blind-retries protocol, and the "open files are context, not intent" clause all live in [`contexts/communication/rules-auto/think-before-action-mechanics.md`](../contexts/communication/rules-auto/think-before-action-mechanics.md). The rule above is the obligation surface; the mechanics file is the lookup material.
+
+If analysis is skipped → results are unreliable.
+"""
+
+FILES["guidelines"] = """---
+type: "auto"
+tier: "3"
+description: "Writing or reviewing code — check relevant guideline before writing or reviewing code"
+alwaysApply: false
+source: package
+load_context:
+  - .agent-src.uncompressed/contexts/communication/rules-auto/guidelines-mechanics.md
+triggers:
+  - intent: "writing code"
+  - intent: "reviewing code"
+  - keyword: "convention"
+---
+
+# Guidelines
+
+Coding guidelines live under `docs/guidelines/` organized by language. **Always check the relevant guideline** before writing or reviewing code.
+
+## How guidelines work
+
+- **Guidelines** = detailed coding conventions (reference material, read on demand).
+- **Rules** = always-active behavior constraints (auto-loaded every conversation).
+- **Skills** = agent capabilities and workflows (matched by topic).
+
+Guidelines are the "how to write code" docs. Rules enforce critical subsets automatically. Skills reference guidelines when performing related tasks.
+
+## Index — see mechanics
+
+The full file index (PHP, PHP patterns, E2E, agent-infra) plus the guidelines-vs-skills boundary and the "adding new guidelines" template live in [`contexts/communication/rules-auto/guidelines-mechanics.md`](../contexts/communication/rules-auto/guidelines-mechanics.md). The rule above is the obligation surface; the mechanics file is the catalog.
+"""
+
+FILES["token-efficiency"] = """---
+type: "auto"
+tier: "2a"
+description: "When running CLI tools, fetching logs, or producing replies — redirect verbose output, minimize tool calls, keep replies concise"
+alwaysApply: false
+source: package
+load_context:
+  - .agent-src.uncompressed/contexts/communication/rules-auto/token-efficiency-mechanics.md
+triggers:
+  - intent: "verbose CLI output"
+  - intent: "fetching logs"
+  - keyword: "minimize tool calls"
+---
+
+# Token Efficiency
+
+## The Iron Laws
+
+```
+NEVER load full command output into context. Redirect → read summary → targeted details.
+```
+
+```
+NEVER call the same tool more than 2 times in a row with similar parameters.
+If you catch yourself repeating a tool call — STOP, rethink, try a different approach, or ask the user.
+```
+
+## Fresh Output Over Memory
+
+When a tool or command returns a value (branch name, file path, PR number), use that EXACT value in subsequent API calls. NEVER substitute a value from earlier in the conversation. Context decay causes silent mismatches — fresh output is the only source of truth.
+
+## Mechanics — anti-loop patterns, conversation efficiency, exceptions
+
+The anti-loop patterns (extended-reasoning loops, "CRITICAL INSTRUCTION" self-prompting), the act-skip-narration / stop-early / keep-output-minimal / don't-re-read / minimize-tool-calls clauses, and the small-output / debugging / explicit-full-output exceptions all live in [`contexts/communication/rules-auto/token-efficiency-mechanics.md`](../contexts/communication/rules-auto/token-efficiency-mechanics.md). The rule above is the obligation surface; the mechanics file is the lookup material.
+
+This rule NEVER overrides `user-interaction` or command rules. Token efficiency means fewer *unnecessary* words — NOT skipping required questions, numbered options, or command steps.
+"""
+
+FILES["autonomous-execution"] = """---
+type: "auto"
+tier: "3"
+description: "Deciding whether to ask the user or just act on a workflow step — trivial-vs-blocking classification, autonomy opt-in detection, commit default; defers to non-destructive-by-default for the Hard Floor"
+alwaysApply: false
+source: package
+load_context:
+  - .agent-src.uncompressed/contexts/execution/autonomy-detection.md
+  - .agent-src.uncompressed/contexts/execution/autonomy-mechanics.md
+  - .agent-src.uncompressed/contexts/execution/autonomy-examples.md
+triggers:
+  - intent: "trivial workflow question"
+  - intent: "autonomy mode"
+  - keyword: "personal.autonomy"
+---
+
+# Autonomous Execution
+
+User's time is the scarce resource. Trivial workflow questions are noise. This rule defines **trivial** (just act), **blocking** (still ask), the **hard floor** (always ask, no override), and the **commit default** (never commit, never ask — review-first by design).
+
+## Hard Floor — see [`non-destructive-by-default`](non-destructive-by-default.md)
+
+The universal safety floor (production-branch merges, deploys, pushes, prod data/infra, whimsical bulk deletions, and commits containing bulk deletions or infra changes) is governed by the canonical [`non-destructive-by-default`](non-destructive-by-default.md) rule. It applies regardless of `personal.autonomy`, a standing autonomy directive, or any roadmap authorization. Nothing in **this** rule lifts it. If a trigger fires, stop and ask — every other section below assumes the floor has already been cleared.
+
+## Setting — `personal.autonomy`
+
+Three values: `on` (suppress trivial questions), `off` (ask trivial questions too), `auto` (default — same as `off` until the user opts in via a standing autonomy directive). Read once on the first turn and cache. Missing key → treat as `on`. Full table, semantics, and cloud behavior: [`contexts/execution/autonomy-mechanics.md`](../contexts/execution/autonomy-mechanics.md).
+
+## Opt-in detection — match by intent, not exact string
+
+In `auto` mode, flip to `on` for the rest of the conversation when the user expresses **"stop asking on trivial steps, just work"**. Recognize **intent**, not the literal substring. Opt-out (same intent, reversed) flips back to `off`. Both directions are **speech-act-checked**: the phrase must be a meta-instruction to the agent, not content / quote / subject / code / third-party reference / hypothetical. In doubt → keep current mode, no speculative flips.
+
+Algorithm and speech-act heuristic: [`contexts/execution/autonomy-detection.md`](../contexts/execution/autonomy-detection.md). Anchor phrases (DE+EN), no-flip patterns, counter-examples, trivial-vs-blocking taxonomy, commit-policy summary, and named failure modes: [`contexts/execution/autonomy-mechanics.md`](../contexts/execution/autonomy-mechanics.md) + [`contexts/execution/autonomy-examples.md`](../contexts/execution/autonomy-examples.md).
+
+## See also
+
+- [`non-destructive-by-default`](non-destructive-by-default.md) — universal safety floor; never overridden by autonomy
+- [`scope-control`](scope-control.md) — git-ops permission gate
+- [`ask-when-uncertain`](ask-when-uncertain.md) — vague-request triggers that always require asking
+- [`no-cheap-questions`](no-cheap-questions.md) — mode-independent floor against context-derived asks
+- [`commit-policy`](commit-policy.md) — never-commit / never-ask Iron Law
+- [`/commit:in-chunks`](../commands/commit/in-chunks.md), [`/commit`](../commands/commit.md)
+"""
+
+FILES["user-interaction"] = '''---
+type: "auto"
+tier: "3"
+description: "Asking the user a question, presenting options, or summarizing progress — numbered-options Iron Law, single-recommendation rule, progress indicators"
+alwaysApply: false
+source: package
+load_context:
+  - .agent-src.uncompressed/contexts/communication/rules-auto/user-interaction-mechanics.md
+triggers:
+  - intent: "ask user a question"
+  - intent: "numbered options"
+  - intent: "summarizing progress"
+---
+
+# User Interaction
+
+Two Iron Laws govern every reply that contains numbered options.
+They override conversation momentum, brevity, and the urge to defer
+to the user. **Missing a recommendation is a rule violation, not a slip.**
+
+## Iron Law 1 — Single-Source Recommendation
+
+```
+EXACTLY ONE LINE NAMES THE RECOMMENDED NUMBER. NO INLINE TAG. NO SECOND PROSE NUMBER.
+THE OPTION BLOCK STAYS NEUTRAL. THE RECOMMENDATION LINE IS THE ONLY SOURCE OF TRUTH.
+DRIFT BETWEEN OPTION-BLOCK AND PROSE IS STRUCTURALLY IMPOSSIBLE WHEN THE TAG DOES NOT EXIST.
+MISSING RECOMMENDATION = RULE VIOLATION, NOT A SLIP.
+POSITION-AGNOSTIC. END-OF-TURN MENUS COUNT. NEXT-STEP LISTS COUNT. NO EXCEPTIONS.
+THE RECOMMENDATION LINE LIVES DIRECTLY UNDER THE OPTIONS BLOCK. NOWHERE ELSE.
+PROSE NAMING A "RECOMMENDED" PATH ABOVE OR BEFORE THE OPTIONS BLOCK = NO RECOMMENDATION.
+WRONG-LANGUAGE LABEL (`Recommendation:` WHEN USER IS GERMAN, OR VICE VERSA) = NO RECOMMENDATION.
+```
+
+## Iron Law 2 — Pre-Send Self-Check
+
+```
+EVERY REPLY WITH NUMBERED OPTIONS RUNS THE SELF-CHECK. NO EXCEPTIONS.
+SKIPPING IT IS A RULE VIOLATION, NOT A SLIP.
+```
+
+Mechanical backstop:
+`python3 scripts/check_reply_consistency.py --stdin < draft.md`
+(non-zero exit on any rule below). Self-scan is the primary gate;
+the script is the deterministic safety net.
+
+## Mechanics — rationale, failure modes, format details, examples
+
+The "why take a position", position-agnostic clause, format
+specification (neutral block + bolded recommendation line + caveat),
+no-trailing-open-question rule, "what does NOT count" catalog, full
+five-step pre-send self-check, named failure-mode catalog (end-of-turn
+menu, trailing-question hedge, no-preference hedge, multi-block reply,
+…), slip-handling protocol, numbered-options rules, format examples,
+progress indicators, and summary-table patterns all live in
+[`contexts/communication/rules-auto/user-interaction-mechanics.md`](../contexts/communication/rules-auto/user-interaction-mechanics.md).
+The rule above is the obligation surface; the mechanics file is the
+lookup material.
+'''
+
+
+if __name__ == "__main__":
+    for name, content in FILES.items():
+        write(name, content)
+    print(f"✓ wrote {len(FILES)} compressed rule bodies")

package/scripts/_p43_compress.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""P4.3 — Surgical compression of 22 compress-and-keep auto-rules.
+
+Writes new bodies for the largest rules (Iron Laws preserved verbatim,
+extended rationale relocated to contexts/communication/rules-auto/).
+Adds `triggers:` to all 22 so the router has a manifest entry per rule.
+Idempotent — re-running rewrites the same content.
+"""
+from __future__ import annotations
+
+import pathlib
+import re
+import sys
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+RULES = ROOT / ".agent-src.uncompressed" / "rules"
+CTXDIR = ROOT / ".agent-src.uncompressed" / "contexts" / "communication" / "rules-auto"
+
+# Triggers per rule (keyword / phrase / file_pattern / path_prefix / intent / command)
+TRIGGERS: dict[str, list[dict]] = {
+    "architecture":              [{"keyword": "controller"}, {"keyword": "service"}, {"keyword": "module"}, {"intent": "structural decision"}],
+    "artifact-drafting-protocol": [{"intent": "create new skill"}, {"intent": "create new rule"}, {"intent": "create new command"}, {"intent": "create new guideline"}],
+    "augment-source-of-truth":   [{"path_prefix": ".agent-src/"}, {"path_prefix": ".augment/"}, {"path_prefix": ".claude/"}, {"path_prefix": ".cursor/"}],
+    "autonomous-execution":      [{"intent": "trivial workflow question"}, {"intent": "autonomy mode"}, {"keyword": "personal.autonomy"}],
+    "context-hygiene":           [{"intent": "long conversation"}, {"intent": "tool loop"}, {"intent": "fresh chat"}, {"keyword": "3-failure"}],
+    "downstream-changes":        [{"intent": "after code edit"}, {"keyword": "callers"}, {"keyword": "imports"}, {"keyword": "downstream"}],
+    "guidelines":                [{"intent": "writing code"}, {"intent": "reviewing code"}, {"keyword": "convention"}],
+    "improve-before-implement":  [{"intent": "implement feature"}, {"intent": "architectural change"}, {"keyword": "refactor"}],
+    "markdown-safe-codeblocks":  [{"intent": "markdown with code blocks"}, {"keyword": "triple backticks"}, {"file_pattern": "*.md"}],
+    "minimal-safe-diff":         [{"intent": "writing a diff"}, {"intent": "reviewing a diff"}, {"keyword": "drive-by"}],
+    "missing-tool-handling":     [{"keyword": "command not found"}, {"keyword": "not installed"}, {"intent": "install tool"}],
+    "no-attribution-footers":    [{"intent": "PR body"}, {"intent": "commit message"}, {"intent": "Jira comment"}, {"keyword": "co-authored"}],
+    "no-roadmap-references":     [{"path_prefix": "agents/roadmaps/"}, {"intent": "link from stable artifact"}],
+    "preservation-guard":        [{"intent": "merge skill"}, {"intent": "compress rule"}, {"intent": "refactor artifact"}, {"keyword": "Iron Law"}],
+    "role-mode-adherence":       [{"keyword": "active_role"}, {"keyword": "role-mode"}, {"intent": "mode marker"}],
+    "runtime-safety":            [{"keyword": "execution"}, {"keyword": "automated"}, {"keyword": "assisted"}, {"keyword": "handler"}],
+    "security-sensitive-stop":   [{"keyword": "auth"}, {"keyword": "billing"}, {"keyword": "tenant"}, {"keyword": "secret"}, {"keyword": "webhook"}],
+    "size-enforcement":          [{"intent": "create rule"}, {"intent": "create skill"}, {"intent": "create command"}, {"intent": "create guideline"}],
+    "think-before-action":       [{"intent": "before coding"}, {"intent": "before debugging"}, {"intent": "before modifying"}],
+    "token-efficiency":          [{"intent": "verbose CLI output"}, {"intent": "fetching logs"}, {"keyword": "minimize tool calls"}],
+    "tool-safety":                [{"keyword": "allowed_tools"}, {"keyword": "tool registry"}, {"intent": "external API"}],
+    "user-interaction":          [{"intent": "ask user a question"}, {"intent": "numbered options"}, {"intent": "summarizing progress"}],
+}
+
+
+def _read(p: pathlib.Path) -> str:
+    return p.read_text(encoding="utf-8")
+
+
+def _split_frontmatter(text: str) -> tuple[str, str]:
+    """Return (frontmatter_inner, body) — assumes leading ---\\n…---\\n\\n."""
+    m = re.match(r"^---\n(.*?)\n---\n*", text, re.DOTALL)
+    if not m:
+        raise ValueError("no frontmatter")
+    return m.group(1), text[m.end():]
+
+
+def _format_triggers(items: list[dict]) -> str:
+    out = ["triggers:"]
+    for it in items:
+        ((k, v),) = it.items()
+        out.append(f'  - {k}: "{v}"')
+    return "\n".join(out)
+
+
+def _strip_old_triggers(fm: str) -> str:
+    """Remove an existing triggers: block (with its inline children)."""
+    lines = fm.splitlines()
+    out: list[str] = []
+    i = 0
+    while i < len(lines):
+        if lines[i].rstrip() == "triggers:":
+            i += 1
+            while i < len(lines) and lines[i].startswith(("  ", "\t")):
+                i += 1
+            continue
+        out.append(lines[i])
+        i += 1
+    return "\n".join(out)
+
+
+def patch_triggers_only(rule_id: str) -> bool:
+    """Inject triggers: into rule frontmatter without touching the body."""
+    p = RULES / f"{rule_id}.md"
+    if not p.exists():
+        print(f"  ✗ missing: {rule_id}", file=sys.stderr)
+        return False
+    text = _read(p)
+    fm, body = _split_frontmatter(text)
+    fm = _strip_old_triggers(fm).rstrip()
+    triggers = TRIGGERS.get(rule_id)
+    if triggers:
+        fm = fm + "\n" + _format_triggers(triggers)
+    p.write_text(f"---\n{fm}\n---\n\n{body.lstrip()}", encoding="utf-8")
+    return True
+
+
+def write_rule(rule_id: str, fm_extra: str, body: str) -> None:
+    """Overwrite a rule with given body + standard frontmatter additions."""
+    p = RULES / f"{rule_id}.md"
+    text = _read(p)
+    fm, _ = _split_frontmatter(text)
+    fm_clean = _strip_old_triggers(fm).rstrip()
+    triggers = TRIGGERS.get(rule_id)
+    parts = [fm_clean]
+    if fm_extra:
+        parts.append(fm_extra.rstrip())
+    if triggers:
+        parts.append(_format_triggers(triggers))
+    full_fm = "\n".join(parts)
+    p.write_text(f"---\n{full_fm}\n---\n\n{body.lstrip()}\n", encoding="utf-8")
+
+
+if __name__ == "__main__":
+    # Imported by _p43_bodies.py — when run directly, only stamp triggers.
+    for rid in TRIGGERS:
+        patch_triggers_only(rid)
+    print("✓ triggers stamped on all 22 compress-and-keep rules")

package/scripts/_p4_migrate.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""P4.1 + P4.2 migration: rule → skill / guideline / command / contract stub.
+
+Replaces 25 rules with thin stubs declaring `triggers:` + `routes_to:`.
+For move-to-guideline, copies the rule body into a new guideline file.
+For move-to-skill / command / contract, the target already carries the
+procedure — stub keeps an Iron-Law one-liner only.
+"""
+from __future__ import annotations
+import re, sys, pathlib
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+RULES = ROOT / ".agent-src.uncompressed" / "rules"
+GUIDELINES = ROOT / "docs" / "guidelines"
+
+# (rule_id, route, triggers, iron_law_one_liner)
+# route format: "kind:id"
+SKILL_MIGRATIONS = [
+    ("agent-docs", "skill:agent-docs-writing",
+     [("path_prefix", "agents/"), ("path_prefix", ".github/copilot-instructions"), ("keyword", "AGENTS.md"), ("keyword", "roadmap")],
+     "Read agent docs (`AGENTS.md`, `agents/`, module `agents/`) before work; update them after structural changes."),
+    ("analysis-skill-routing", "skill:analysis-skill-router",
+     [("keyword", "analyze"), ("keyword", "analysis"), ("phrase", "dig into the codebase")],
+     "Route analysis tasks to the narrowest matching `project-analysis-*` skill, not the broad fallback."),
+    ("capture-learnings", "skill:learning-to-rule-or-skill",
+     [("phrase", "after completing a task"), ("keyword", "learning"), ("keyword", "lesson")],
+     "After a task, capture repeated mistakes / successful patterns as a rule or skill — never lose the learning."),
+    ("cli-output-handling", "skill:rtk-output-filtering",
+     [("keyword", "git"), ("keyword", "phpstan"), ("keyword", "rector"), ("keyword", "phpunit"), ("keyword", "composer")],
+     "Wrap verbose CLI output with `rtk` when installed; fall back to `tail`/`grep` only when missing."),
+    ("commit-conventions", "skill:conventional-commits-writing",
+     [("keyword", "commit"), ("keyword", "branch"), ("phrase", "conventional commits")],
+     "Use Conventional Commits (`feat:`, `fix:`, `chore:` …); branches `<type>/<short-slug>`; never invent your own format."),
+    ("docker-commands", "skill:docker",
+     [("keyword", "docker"), ("keyword", "artisan"), ("keyword", "composer"), ("phrase", "inside the container")],
+     "Run PHP / artisan / composer / phpstan / rector / ecs / phpunit inside the project container, never on the host."),
+    ("docs-sync", "skill:agent-docs-writing",
+     [("path_prefix", ".agent-src.uncompressed/"), ("path_prefix", ".augment/"), ("keyword", "rename"), ("keyword", "delete")],
+     "On any add / rename / delete of skill / rule / command / guideline, update counts and cross-references in the same edit."),
+    ("e2e-testing", "command:e2e-heal",
+     [("keyword", "playwright"), ("keyword", "e2e"), ("phrase", "page object")],
+     "Playwright E2E: stable locators, no `waitForTimeout`, Page Objects for shared flows, fixtures over `beforeEach`."),
+    ("laravel-translations", "skill:laravel",
+     [("path_prefix", "lang/"), ("keyword", "translation"), ("keyword", "__()"), ("keyword", "trans(")],
+     "Use `__()`/`trans()` with language keys for every user-visible string; mirror keys across `lang/<locale>/` files."),
+    ("model-recommendation", "command:set-cost-profile",
+     [("phrase", "switch task"), ("phrase", "new task"), ("phrase", "which model")],
+     "On task / model switch, recommend the optimal model for the task complexity before any work begins."),
+    ("onboarding-gate", "command:onboard",
+     [("phrase", "first turn"), ("keyword", "onboarding"), ("path_prefix", ".agent-settings.yml")],
+     "First turn of a project: if `onboarding.onboarded` is false, prompt `/onboard` before executing any other request."),
+    ("package-ci-checks", "skill:lint-skills",
+     [("phrase", "task ci"), ("phrase", "before push"), ("phrase", "before pr")],
+     "Run `task ci` locally and confirm green before pushing or opening a PR in this package."),
+    ("review-routing-awareness", "skill:review-routing",
+     [("keyword", "reviewer"), ("phrase", "risk hotspot"), ("phrase", "ownership map")],
+     "Consult ownership-map and historical-bug-patterns before suggesting reviewers or claiming a change is safe."),
+    ("reviewer-awareness", "skill:review-routing",
+     [("keyword", "reviewer"), ("phrase", "suggest reviewers")],
+     "Anchor reviewer choice in paths and risk, never seniority; medium / high risk requires primary + secondary role."),
+    ("skill-improvement-trigger", "skill:skill-improvement-pipeline",
+     [("phrase", "after completing"), ("keyword", "improvement"), ("keyword", "pipeline")],
+     "After a meaningful task, trigger the post-task learning capture if `pipelines.skill_improvement` is enabled."),
+    ("slash-command-routing-policy", "skill:command-routing",
+     [("keyword", "/create-pr"), ("keyword", "/commit"), ("keyword", "/fix-ci"), ("phrase", "slash command")],
+     "On a slash-command invocation or pasted command body, route to the matching command file; never improvise."),
+    ("ui-audit-gate", "skill:existing-ui-audit",
+     [("path_prefix", "resources/views/"), ("path_prefix", "resources/js/"), ("keyword", "component"), ("keyword", "design token")],
+     "Before any non-trivial UI change, require `state.ui_audit` findings — gate, not suggestion."),
+    ("upstream-proposal", "skill:upstream-contribute",
+     [("phrase", "after creating"), ("phrase", "after improving"), ("keyword", "upstream")],
+     "After creating or significantly improving a skill / rule / guideline / command, ask whether to upstream it."),
+]
+
+GUIDELINE_MIGRATIONS = [
+    ("artifact-engagement-recording", "contract:artifact-engagement-flow",
+     [("phrase", "/implement-ticket"), ("phrase", "/work"), ("keyword", "telemetry")],
+     "After a `/implement-ticket` or `/work` phase-step, emit one `telemetry:record` call with consulted + applied ids when telemetry is enabled."),
+    ("augment-portability", "guideline:augment-portability-patterns",
+     [("path_prefix", ".augment/"), ("path_prefix", ".agent-src.uncompressed/"), ("keyword", "portable")],
+     "Files inside `.augment/` and `.agent-src.uncompressed/` MUST stay project-agnostic — no project names, domains, stacks."),
+    ("command-suggestion-policy", "contract:command-suggestion-flow",
+     [("phrase", "free-form prompt"), ("phrase", "command suggestion")],
+     "When a free-form prompt matches a command, surface matches as numbered options with as-is escape; never auto-execute."),
+    ("php-coding", "guideline:php/php-coding-patterns",
+     [("file_pattern", "*.php"), ("keyword", "phpstan"), ("keyword", "ecs")],
+     "PHP: strict types, named comparisons, early returns, Eloquent conventions — full pattern library in the guideline."),
+    ("roadmap-progress-sync", "guideline:agent-infra/roadmap-progress-mechanics",
+     [("path_prefix", "agents/roadmaps/")],
+     "Any touch to `agents/roadmaps/` regenerates the dashboard in the same response; archive the roadmap when 0 open items remain."),
+    ("rule-type-governance", "guideline:agent-infra/rule-type-governance",
+     [("path_prefix", ".agent-src.uncompressed/rules/")],
+     "Choose `always` vs `auto` per the governance table; over-broad `always` rules degrade the kernel budget."),
+    ("skill-quality", "guideline:agent-infra/skill-quality-checklist",
+     [("path_prefix", ".agent-src.uncompressed/skills/")],
+     "Every skill must be executable, validated, and self-contained — full checklist in the guideline."),
+]
+
+
+
+def yaml_triggers(triggers: list[tuple[str, str]]) -> str:
+    lines = []
+    for kind, val in triggers:
+        v = val.replace('"', '\\"')
+        lines.append(f'  - {kind}: "{v}"')
+    return "\n".join(lines)
+
+
+def parse_existing_frontmatter(text: str) -> tuple[dict, str]:
+    m = re.match(r"^---\n(.*?)\n---\n(.*)$", text, re.DOTALL)
+    if not m:
+        return {}, text
+    fm_text, body = m.group(1), m.group(2)
+    fm = {}
+    for line in fm_text.split("\n"):
+        if ":" not in line or line.startswith(" "):
+            continue
+        k, _, v = line.partition(":")
+        fm[k.strip()] = v.strip().strip('"')
+    return fm, body
+
+
+def build_stub(rule_id: str, route: str, triggers: list[tuple[str, str]],
+               iron_law: str, existing_fm: dict) -> str:
+    desc = existing_fm.get("description", "")
+    tier = existing_fm.get("tier", "3")
+    rtype = existing_fm.get("type", "auto")
+    source = existing_fm.get("source", "package")
+    new_tier = {"1": "tier-1", "2a": "tier-2", "2b": "tier-2", "3": "tier-2",
+                "mechanical-already": "tier-2", "mech": "tier-2"}.get(tier, "tier-2")
+    fm_lines = [
+        "---",
+        f'type: "{rtype}"',
+        f'tier: "{new_tier}"',
+        f'description: "{desc}"',
+        f'source: {source}',
+        "triggers:",
+        yaml_triggers(triggers),
+        "routes_to:",
+        f'  - "{route}"',
+        "---",
+        "",
+        f"# {rule_id.replace('-', ' ').title()}",
+        "",
+        f"**Iron Law.** {iron_law}",
+        "",
+        f"Body migrated to `{route}` (per P4 of `road-to-kernel-and-router.md`).",
+        "Trigger-set above activates this routing under the `balanced` and `full` profiles.",
+    ]
+    return "\n".join(fm_lines) + "\n"
+
+
+def write_guideline(rule_id: str, route: str, body: str, existing_fm: dict) -> pathlib.Path:
+    kind, _, gid = route.partition(":")
+    if kind == "guideline":
+        target = GUIDELINES / f"{gid}.md"
+    elif kind == "contract":
+        target = ROOT / "docs" / "contracts" / f"{gid}.md"
+    else:
+        raise ValueError(f"unsupported route kind for guideline migration: {kind}")
+    if target.exists():
+        return target
+    target.parent.mkdir(parents=True, exist_ok=True)
+    desc = existing_fm.get("description", "")
+    header = (f"# {rule_id.replace('-', ' ').title()}\n\n"
+              f"> {desc}\n\n"
+              f"_Origin: migrated from `.agent-src.uncompressed/rules/{rule_id}.md` "
+              f"per P4.2 of `road-to-kernel-and-router.md`._\n\n")
+    target.write_text(header + body.lstrip())
+    return target
+
+
+def main() -> int:
+    written = []
+    for rule_id, route, triggers, iron_law in SKILL_MIGRATIONS:
+        rule_path = RULES / f"{rule_id}.md"
+        if not rule_path.exists():
+            print(f"  ✗ MISSING rule: {rule_id}"); continue
+        fm, body = parse_existing_frontmatter(rule_path.read_text())
+        stub = build_stub(rule_id, route, triggers, iron_law, fm)
+        rule_path.write_text(stub)
+        written.append(("skill-stub", rule_id, route, len(stub)))
+    for rule_id, route, triggers, iron_law in GUIDELINE_MIGRATIONS:
+        rule_path = RULES / f"{rule_id}.md"
+        if not rule_path.exists():
+            print(f"  ✗ MISSING rule: {rule_id}"); continue
+        fm, body = parse_existing_frontmatter(rule_path.read_text())
+        write_guideline(rule_id, route, body, fm)
+        stub = build_stub(rule_id, route, triggers, iron_law, fm)
+        rule_path.write_text(stub)
+        written.append(("guideline", rule_id, route, len(stub)))
+    print(f"\nMigrated {len(written)} rules:")
+    for kind, rid, route, sz in written:
+        print(f"  {kind:14s} {rid:35s} → {route:55s} stub={sz}c")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/_pilot_council_question.py

@@ -0,0 +1,57 @@
+"""Build the Phase-1 council question file (one-off)."""
+from pathlib import Path
+
+OUT = Path("/tmp/council-p1/question.md")
+OUT.parent.mkdir(parents=True, exist_ok=True)
+
+framing = """# Cross-check request — Phase 1 of "Road to Rule Kernel and Router"
+
+We are about to compress a 56-rule "always-active" set down to a small
+hard-capped kernel + a router-loaded auto bucket. Phase 1 is purely
+classification + projection — no source rules edited yet. Two contracts
+were produced. We want a neutral second opinion BEFORE Phase 2 ships
+compression to the actual rule files.
+
+## What we want from you
+
+1. **Disposition calls.** Look at the 56-rule classification. Are any
+   `keep-in-kernel` rules over-included (could safely become auto-tier)?
+   Are any `move-to-skill` / `move-to-guideline` calls wrong (e.g.
+   carrying an Iron Law that should stay always-on)? Cite the rule id
+   and the better disposition.
+2. **Kernel inclusion criteria.** Section 1 of `kernel-membership.md`
+   lists 4 criteria (Iron-Law floor / mode-independent / pre-action
+   gate / cross-cutting). Are these the right gates? Is anything
+   missing or redundant?
+3. **Compression-rate r = 0.742.** Three pilots gave r-values 0.677 /
+   0.712 / 0.838. We locked the **mean**. Reasonable, or should we use
+   median (0.712) / max (0.838) as a more conservative budget cushion?
+   Note: pilot range straddles the typical 0.6-0.75 band; max came
+   from the shortest rule (already-lean floor effect).
+4. **The 1.5k per-rule cap with ADR-override.** Two of the three pilots
+   land >1.5k post-compression and would need an `iron-law-override`
+   ADR. Is the per-rule cap realistic, or should we raise the per-rule
+   ceiling (e.g. 2.5k or 3.5k) and lower the bucket cap (e.g. from 25k
+   to 20k)? What's the failure mode you'd be most worried about?
+5. **Anything we missed.** Risks, blind spots, sequencing problems.
+
+Be specific. Cite the rule id or the section number. We will reject
+generic "looks good" reviews.
+
+---
+
+## Contract 1 — docs/contracts/rule-classification.md
+
+"""
+
+OUT.write_text(framing)
+with OUT.open("a") as fh:
+    fh.write(Path("docs/contracts/rule-classification.md").read_text())
+    fh.write("\n\n---\n\n## Contract 2 — docs/contracts/kernel-membership.md\n\n")
+    fh.write(Path("docs/contracts/kernel-membership.md").read_text())
+    fh.write("\n\n---\n\n## Pilot inputs (compressed bodies, for reference)\n")
+    for rid in ("agent-authority", "direct-answers", "language-and-tone"):
+        fh.write(f"\n### Pilot — {rid}\n\n")
+        fh.write(Path(f"docs/contracts/pilot/{rid}.md").read_text())
+
+print(f"wrote {OUT} — {OUT.stat().st_size} bytes")