@event4u/agent-config 1.20.0 → 1.22.0

package/.agent-src/skills/test-performance/SKILL.md

@@ -15,7 +15,7 @@ Use this skill when:
 - Parallel testing needs optimization
 - Seeders need performance analysis
 - CI pipeline test jobs need to be faster
-- Investigating flaky tests caused by database state
+- Investigating flaky tests caused by DB state
 
 ## Procedure: Analyze test performance
 
@@ -55,7 +55,7 @@ Check these areas in order of typical impact:
 | **Migration count** | How many CREATE TABLE statements? | High if >20 |
 | **Schema dump** | Is `database/schema/` used? | High if missing |
 | **Seeder INSERT method** | Individual `save()` vs bulk insert? | Medium |
-| **Truncation** | Per-seeder truncate vs centralized? | Low (but causes correctness issues) |
+| **Truncation** | Per-seeder truncate vs centralized? | Low (but → correctness issues) |
 | **Connection discovery** | Dynamic `getPdo()` probing? | Low |
 | **Parallel worker setup** | Does each worker re-migrate? | High |
 
@@ -76,7 +76,7 @@ php artisan schema:dump --database=api_database
 #### B. Template DB Cloning (high ROI for parallel tests)
 
 Instead of each parallel worker running migrate+seed independently:
-1. Prepare ONE template database (migrate + seed)
+1. Prepare ONE template DB (migrate + seed)
 2. Clone template for each worker via mysqldump
 
 ```bash
@@ -92,7 +92,7 @@ mysqldump template_db | mysql worker_db_test_1
 
 #### C. Skip Migrate+Seed Flag (high ROI for local dev)
 
-Add a config flag to skip database setup when DB is already prepared:
+Add a config flag to skip DB setup when DB is already prepared:
 
 ```php
 // config/testing.php
@@ -158,7 +158,7 @@ Replace dynamic `getPdo()` probing with explicit config:
 ## Gotcha
 
 - Don't use RefreshDatabase when DatabaseTransactions suffices — full refresh is 10x slower.
-- The model forgets that parallel tests share the database — use unique identifiers in test data.
+- The model forgets that parallel tests share the DB — use unique identifiers in test data.
 - Seeder optimization has the highest ROI — a 2s seeder running 100 times = 200s wasted.
 - Don't add indexes to test databases just for test performance — the real fix is better test design.
 

package/.agent-src/skills/threat-modeling/SKILL.md

@@ -2,11 +2,12 @@
 name: threat-modeling
 description: "Use when adding auth, webhooks, uploads, queues, secrets, tenant boundaries, or public endpoints — produces trust boundaries + abuse cases mapped to files, BEFORE implementation."
 source: package
+council_depth: deep
 ---
 
 # threat-modeling
 
-> You are a reviewer specialized in **pre-implementation threat analysis**.
+> You are a reviewer specialized in **pre-impl threat analysis**.
 > Your only job is to produce a compact threat model for a planned change —
 > actors, assets, trust boundaries, abuse cases, and the minimum controls
 > the implementer must add. You do **not** audit existing code end-to-end,
@@ -186,4 +187,4 @@ run tests**.
 - [`authz-review`](../authz-review/SKILL.md),
   [`data-exposure-review`](../data-exposure-review/SKILL.md),
   [`security`](../security/SKILL.md),
-  [`security-audit`](../security-audit/SKILL.md) — sibling review / implementation skills.
+  [`security-audit`](../security-audit/SKILL.md) — sibling review / impl skills.

package/.agent-src/skills/token-optimizer/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: token-optimizer
+description: "Use BEFORE any verbose CLI run, large file read, doc conversion, or near-context handoff — single decision tree keyed by intent that cites the canonical token-saving asset. Consult before the action."
+source: package
+execution:
+  type: assisted
+  handler: shell
+  allowed_tools: []
+---
+
+# Token Optimizer — decision tree + catalog
+
+## Iron Law
+
+```
+CONSULT THIS SKILL BEFORE THE ACTION, NOT AFTER.
+THE TREE NAMES THE CANONICAL ASSET — DO NOT RESTATE OR DUPLICATE IT.
+```
+
+## When to use
+
+Proactively, BEFORE you:
+
+- Run a verbose CLI command (tests, linters, build, git log, large `grep`)
+- Read or paste a large document, log, or tool dump
+- Repeat the same tool call across many files / records
+- Approach the context-window limit and need to hand off
+- Make a cost-aware decision (which model, which budget, when to stop)
+
+Reactively when output already burned tokens — record the lesson, do
+not re-explore. Cite the leaf, move on.
+
+## Procedure
+
+1. **Classify intent** — match the situation to one branch of the tree below.
+2. **Cite the leaf** — name the canonical asset (rule, skill, or upstream link).
+3. **Apply** — execute the cited asset's contract; do NOT inline its content.
+4. **Verify** — output respects the cited Iron Law (redirect, wrap, batch, etc.).
+
+### Decision tree
+
+```
+INTENT
+├── Verbose CLI output incoming
+│     → cite [cli-output-handling](../../rules/cli-output-handling.md)
+│       (Iron Law: redirect / tail / grep / wrap)
+│     → cite [rtk-output-filtering](../rtk-output-filtering/SKILL.md)
+│       (rtk wrapper, 60-90% savings on tests/linters/git)
+│
+├── Large document or paste (PDF, DOCX, HTML, transcript)
+│     → cite markitdown (upstream: https://github.com/microsoft/markitdown)
+│       Convert FIRST, then read the markdown — never paste raw binary.
+│
+├── Repeated tool-call across N targets
+│     → cite [token-efficiency](../../rules/token-efficiency.md)
+│       (batch, parallelize, prune; one tool call > many)
+│
+├── Near context limit, work not finished
+│     → cite [agent-handoff](../../../.claude/skills/agent-handoff/SKILL.md)
+│       (structured handoff envelope; resume in fresh chat)
+│
+└── Cost-aware decision (model pick, budget, stop-criterion)
+      → cite /cost:report (when shipped) — until then, fall back to
+        [token-efficiency](../../rules/token-efficiency.md) and
+        [direct-answers § Brevity by Default](../../rules/direct-answers.md)
+```
+
+## Catalog
+
+| Asset | Path | Trigger keywords | What it does |
+|---|---|---|---|
+| `cli-output-handling` | `.agent-src.uncompressed/rules/cli-output-handling.md` | `verbose`, `tail`, `grep`, `CLI` | Wrap-tail-grep contract for any verbose command |
+| `rtk-output-filtering` | `.agent-src.uncompressed/skills/rtk-output-filtering/SKILL.md` | `rtk`, `verbose`, `filter`, `wrap` | Project-local rtk filters; wrapper command |
+| `token-efficiency` | `.agent-src.uncompressed/rules/token-efficiency.md` | `redirect`, `verbose`, `concise`, `tool` | Batch + parallelize tool calls; brevity floor |
+| `agent-handoff` | `.claude/skills/agent-handoff/SKILL.md` | `handoff`, `fresh`, `chat`, `context` | Context envelope for fresh-chat continuation |
+| `direct-answers` | `.agent-src.uncompressed/rules/direct-answers.md` | `brevity`, `flattery`, `severity`, `tiered` | Iron-Law brevity floor (kernel) |
+| `markitdown` | upstream: github.com/microsoft/markitdown | `PDF`, `DOCX`, `HTML`, `convert` | Document → markdown converter (authoritative-link only) |
+| `/cost:report` | TBD — `road-to-ruflo-adoption.md § P1.2` | `cost`, `model spend`, `budget` | Per-session cost telemetry (planned) |
+
+## Output format
+
+1. Name the cited asset by its leaf id (e.g. `cli-output-handling`, `rtk-output-filtering`).
+2. State the Iron Law in one line; do NOT inline the asset's body.
+3. If multiple branches match, cite all relevant leaves (no merge, no rewrite).
+4. End with the action you take next, citing the asset that authorizes it.
+
+## Gotcha
+
+- Catalog rows live and die with their target asset. If you edit a
+  cited asset's trigger keywords or scope, update the matching row in
+  this skill in the same commit (enforced by
+  [`token-optimizer-maintenance`](../../rules/token-optimizer-maintenance.md)
+  rule + `scripts/check_token_optimizer_freshness.py` CI gate).
+- Tree must stay scannable (≤ 50 lines incl. labels). Catalog rows
+  carry the long form.
+- Authoritative-link assets (`rtk` upstream, `markitdown` upstream,
+  pricing constants) are never copied — always linked.
+
+## Do NOT
+
+- Do NOT inline content from a cited asset. If the leaf is "rtk does X",
+  the agent reads `rtk-output-filtering`. Duplication = drift = stale.
+- Do NOT replace any rule. The rules carry the Iron Laws; this skill
+  carries the lookup index.
+- Do NOT define new policies — every leaf must cite an existing rule,
+  skill, or upstream asset.
+- Do NOT consult this skill AFTER tokens were already burned — record
+  the lesson and move on.
+
+<!-- TELEMETRY: consulted=[uncomment + ISO timestamp on each consult] context=[CLI|doc|repeat|handoff|cost] -->

package/.agent-src/skills/universal-project-analysis/SKILL.md

@@ -71,7 +71,7 @@ Goal: understand structure, identify major components, detect investigation path
 ### Investigation mode
 
 Use when there is a concrete issue inside a large or unclear system.
-Goal: isolate the affected area, route into root-cause analysis, verify likely causes with evidence.
+Goal: isolate the affected area, route into root-cause analysis, verify likely → with evidence.
 
 ### Optimization mode
 

package/.agent-src/templates/AGENTS.md

@@ -113,7 +113,7 @@ Regenerate: `task generate-tools` · Clean: `task clean-tools`
 |---|---|
 | `.env` | Main environment |
 | `.env.local` | Local overrides |
-| `.env.testing` | Testing environment |
+| `.env.testing` | Testing env |
 
 ---
 

package/.agent-src/templates/agent-settings.md

@@ -14,7 +14,7 @@ Keep the format regular — 2-space indent, no tabs, no lists, one nesting
 level only. The installer's YAML handler is a restricted stdlib parser, not
 a full YAML engine. Ask the agent to normalize after manual edits — it
 follows the merge rules in
-[`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules).
+[`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules).
 
 ### Migration from the legacy `.agent-settings` (key=value)
 
@@ -36,7 +36,7 @@ This block defines the personal and project-level settings that
 `scripts/install.py` (via `config/agent-settings.template.yml`)
 writes to `.agent-settings.yml` on first install. Subsequent edits are
 made by the user directly or by the agent on request, following the
-[section-aware merge rules](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules).
+[section-aware merge rules](../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules).
 
 ```yaml
 # Agent Settings
@@ -45,14 +45,19 @@ made by the user directly or by the agent on request, following the
 
 # --- Cost profile ---
 #
-# Controls which agent surfaces are active. See `docs/customization.md` for
-# the authoritative description.
+# Master switch that controls which rule tiers load each session.
+# See `docs/customization.md` for the authoritative description and
+# `docs/contracts/rule-router.md` for the kernel + router architecture.
 #
-# minimal  = rules, skills, and commands only (zero extra surface, default)
-# balanced = + runtime dispatcher for skills that declare a shell command
-# full     = + tool adapters (GitHub / Jira, read-only, opt-in)
-# custom   = ignore profile — every matrix value must be set explicitly
-cost_profile: minimal
+# minimal  = kernel only (always-loaded Iron-Law floor, ≤ 26k chars).
+#            No router, no auto-rules. Lowest token footprint.
+# balanced = kernel + router + tier-1 auto-rules (default — current behaviour
+#            superset; matches what existing consumer projects expect).
+# full     = kernel + tier-1 + tier-2 (everything). Highest fidelity,
+#            highest token cost. Pick this when working on agent-config
+#            itself or when you need every behavioural rule active.
+# custom   = ignore profile — every matrix value must be set explicitly.
+cost_profile: balanced
 
 # --- Personal preferences ---
 personal:
@@ -199,12 +204,12 @@ pipelines:
 
 # --- Roadmap execution ---
 #
-# Controls when /roadmap execute runs the project's quality pipeline.
+# Controls when /roadmap:process-* runs the project's quality pipeline.
 # Step checkboxes and the dashboard are ALWAYS updated in the same
 # response — that cadence is governed by `roadmap-progress-sync` and
 # is non-negotiable. This setting only governs *quality tool runs*.
 roadmap:
-  # When to run quality tools during /roadmap execute.
+  # When to run quality tools during /roadmap:process-step|phase|full.
   #   end_of_roadmap = once, before archiving (default — fastest, fewest tokens)
   #   per_phase      = once after every completed phase
   #   per_step       = after every completed step (legacy; highest token cost)
@@ -288,14 +293,24 @@ commands:
     # Commands to never suggest. Still work when typed explicitly.
     blocklist: []
 
+  # Pre-creation preview of the generated PR description in `/create-pr`.
+  # When `false` (default): skip the title/body preview + adjust loop;
+  # use the generated content directly to create the PR. Saves agent
+  # tokens by avoiding a re-render of the full description in chat.
+  # When `true`: show title and body in copyable code blocks and ask
+  # for adjustments before creating the PR.
+  # `/create-pr:description-only` always previews — that is its sole purpose.
+  create_pr:
+    preview_description: false
+
 # --- Telemetry (artefact engagement, default-off) ---
 #
 # Records — at task / phase-step boundaries — which artefacts (skills,
 # rules, commands, guidelines, personas) the agent consulted and
 # applied. Local only, append-only JSONL, never reaches a consumer
 # repo (gitignored). Maintainer-targeted feature; consumers leave it
-# off. See `docs/contracts/artifact-engagement-flow.md` (once Phase 3
-# of road-to-artifact-engagement-telemetry lands).
+# off. See `.augment/contexts/contracts/artifact-engagement-flow.md`
+# (once Phase 3 of road-to-artifact-engagement-telemetry lands).
 telemetry:
   artifact_engagement:
     # Master switch. `false` (default) produces zero file IO and zero
@@ -323,7 +338,7 @@ telemetry:
 
 Personal and project-level settings (initial file written by
 `scripts/install.py`, edits follow the merge rules in
-[`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)).
+[`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)).
 **Key paths use dot-notation** to denote nesting: `personal.user_name`
 lives under `personal:` in YAML.
 
@@ -353,16 +368,16 @@ lives under `personal:` in YAML.
 | `hooks.halt_surface_audit` | `true`, `false` | `true` | Defense-in-depth check that every halt surfaced by the dispatcher carries the expected shape. Cheap. |
 | `hooks.state_shape_validation` | `true`, `false` | `true` | Re-run the state schema validator on `AFTER_LOAD` and `BEFORE_SAVE`. Cheap, catches drift. |
 | `hooks.directive_set_guard` | `true`, `false` | `true` | Verify the dispatcher-resolved directive set matches the input envelope intent. Cheap, catches routing drift. |
-| `hooks.chat_history.enabled` | `true`, `false` | `true` | Register chat-history hooks (`append` on `after_step`, `halt_append` on `on_halt`). Gated by **both** this flag AND `chat_history.enabled`; either off → no chat-history hook registers. Schema v4: every entry self-identifies via 16-char session fingerprint, no ownership/sidecar layer. |
+| `hooks.chat_history.enabled` | `true`, `false` | `true` | Register the chat-history hooks (`append` on `after_step`, `halt_append` on `on_halt`). Gated by **both** this flag AND `chat_history.enabled`; either off → no chat-history hook registers. Schema v4: every entry self-identifies via a 16-char session fingerprint, no ownership/sidecar layer. |
 | `hooks.chat_history.script` | path | `scripts/chat_history.py` | Override path to the chat-history CLI. Set only when the script lives outside the standard location. |
 | `pipelines.skill_improvement` | `true`, `false` | `true` | When `true`: propose learning capture after meaningful tasks. When `false`: silent. Included in every profile except `custom`. |
-| `roadmap.quality_cadence` | `end_of_roadmap`, `per_phase`, `per_step` | `end_of_roadmap` | When `/roadmap execute` runs the project's quality pipeline. Default skips per-step / per-phase runs and gates only the final archival. `per_phase` runs once after every phase; `per_step` is the legacy verbose mode. Step checkboxes and the dashboard are always updated regardless. `verify-before-complete` still requires fresh output before any "roadmap complete" claim. |
+| `roadmap.quality_cadence` | `end_of_roadmap`, `per_phase`, `per_step` | `end_of_roadmap` | When `/roadmap:process-step|phase|full` runs the project's quality pipeline. Default skips per-step / per-phase runs and gates only the final archival. `per_phase` runs once after every phase; `per_step` is the legacy verbose mode. Step checkboxes and the dashboard are always updated regardless. `verify-before-complete` still requires fresh output before any "roadmap complete" claim. |
 | `subagents.implementer_model` | model alias or empty | _(empty)_ | Model for implementer subagents. Empty = same tier as session model. See [subagent-configuration](../contexts/subagent-configuration.md). |
 | `subagents.judge_model` | model alias or empty | _(empty)_ | Model for judge subagents. Empty = one tier above implementer (opus if sonnet, sonnet if haiku). |
 | `subagents.max_parallel` | integer | `3` | Maximum parallel subagent invocations. `1` serializes. |
-| `roles.default_role` | `""`, `developer`, `reviewer`, `tester`, `po`, `incident`, `planner` | _(empty)_ | Role the agent defaults to at the start of a session. See [`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md). |
+| `roles.default_role` | `""`, `developer`, `reviewer`, `tester`, `po`, `incident`, `planner` | _(empty)_ | Role the agent defaults to at the start of a session. See [`role-contracts`](../docs/guidelines/agent-infra/role-contracts.md). |
 | `roles.active_role` | same as `default_role` | _(empty)_ | Role currently active; set by `/mode <name>`, cleared by `/mode none`. Enables the `role-mode-adherence` rule. |
-| `personas.override` | list of persona ids | `[]` | Developer-local override of the team default lens cast. Empty = inherit `personas.default` from `.agent-project-settings.yml`. See [`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md). |
+| `personas.override` | list of persona ids | `[]` | Developer-local override of the team default lens cast. Empty = inherit `personas.default` from `.agent-project-settings.yml`. See [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md). |
 | `personas.ignore` | list of persona ids | `[]` | Persona ids dropped from the default cast locally. Ignored personas stay invokable via `--personas=<id>`. |
 | `onboarding.onboarded` | `true`, `false` | `false` | Whether `/onboard` has run on this project. The `onboarding-gate` rule prompts for `/onboard` when this is `false`. Missing entirely = legacy project, treated as onboarded. |
 | `commands.suggestion.enabled` | `true`, `false` | `true` | Master switch for the command-suggestion layer. `false` = the layer is silent; explicit `/commands` still work. See `rules/command-suggestion-policy.md`. |
@@ -370,6 +385,7 @@ lives under `personal:` in YAML.
 | `commands.suggestion.cooldown_seconds` | integer | `600` | Cooldown between re-suggestions of the same `(command, evidence)` pair. `600` = 10m. |
 | `commands.suggestion.max_options` | integer | `4` | Max number of command suggestions before the always-present "run as-is" option (total rendered = `max_options + 1`). |
 | `commands.suggestion.blocklist` | list of command names | `[]` | Commands that never appear as a suggestion. They still work when typed explicitly. |
+| `commands.create_pr.preview_description` | `true`, `false` | `false` | When `false`: `/create-pr` skips the title/body preview + adjust loop and uses the generated content directly. Saves agent tokens. When `true`: show title and body before creating and ask for adjustments. `/create-pr:description-only` always previews regardless of this setting. |
 | `telemetry.artifact_engagement.enabled` | `true`, `false` | `false` | Master switch for the artefact engagement log. Default-off; zero file IO and zero token cost when `false`. Maintainer-targeted; consumers leave it off. |
 | `telemetry.artifact_engagement.granularity` | `task`, `phase-step`, `tool-call` | `task` | Boundary at which events are recorded. `tool-call` is expensive — opt-in only. |
 | `telemetry.artifact_engagement.record.consulted` | `true`, `false` | `true` | When `true`: record artefacts loaded into context. |
@@ -427,7 +443,7 @@ they ship with a live consumer in code and get documented here, not before.
 ## Sync rules
 
 When new settings are added to this template, the
-[section-aware merge rules](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
+[section-aware merge rules](../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
 govern the update:
 
 1. Missing keys are added with their **default value** from this template,

package/.agent-src/templates/command.md

@@ -20,6 +20,11 @@ name: {command-name}
 description: {Short description of what the command does}
 disable-model-invocation: true
 skills: [{optional-skill-1}, {optional-skill-2}]
+suggestion:
+  eligible: true
+  trigger_description: "natural-language pattern, comma-separated examples"
+  trigger_context: "concrete signal — branch name, file pattern, recent tool output"
+# council_depth: deep   # uncomment for architecture/refactor/bug-diagnose commands
 ---
 
 <!-- FRONTMATTER RULES (delete this comment when done):
@@ -27,6 +32,17 @@ skills: [{optional-skill-1}, {optional-skill-2}]
   - description: short, human-readable — what the command does
   - disable-model-invocation: ALWAYS true for commands (prevents Claude from auto-invoking)
   - skills: optional — list skills this command references or delegates to
+  - suggestion: REQUIRED — drives the in-host command suggester
+    - eligible: true  → set trigger_description + trigger_context
+    - eligible: false → set rationale (why never auto-suggested)
+    See agents/contexts/command-suggestion-eligibility.md for guidance.
+  - council_depth: optional — only `deep` is accepted. **Omit the key
+    for default depth** (`standard` is the implicit default and is
+    rejected by the schema — every frontmatter byte counts). Set `deep`
+    when this command triggers AI Council on architecture, refactoring,
+    or bug-diagnosis artefacts. The host translates `deep` into
+    `--depth deep` on the council CLI, raising the round floor to
+    `ai_council.deep_min_rounds`. See .augment/skills/ai-council/SKILL.md.
 -->
 
 # /{command-name}
@@ -74,7 +90,7 @@ Ask the user:
 
 Before considering a command complete:
 
-- [ ] **Frontmatter**: has `name`, `description`, `disable-model-invocation: true`
+- [ ] **Frontmatter**: has `name`, `description`, `disable-model-invocation: true`, `suggestion` block
 - [ ] **Steps**: numbered sub-headings (`### 1.`, `### 2.`, ...)
 - [ ] **Source of truth**: works on `.agent-src.uncompressed/`, not `.agent-src/` or `.augment/`
 - [ ] **No auto-apply**: presents findings, asks before destructive changes

package/.agent-src/templates/contexts/tenant-boundaries.md

@@ -16,10 +16,10 @@
 - [ ] **Single-tenant** — one database per deployment. No cross-tenant
       leakage is possible at the infra layer. Delete this file if true
       and the app will never shard.
-- [ ] **Multi-tenant, shared database** — one table with a tenant key
+- [ ] **Multi-tenant, shared DB** — one table with a tenant key
       column (e.g., `tenant_id`, `workspace_id`).
 - [ ] **Multi-tenant, schema per tenant** — one DB, one schema each.
-- [ ] **Multi-tenant, database per tenant** — each tenant has its own
+- [ ] **Multi-tenant, DB per tenant** — each tenant has its own
       connection.
 
 ## Tenant identifier

package/.agent-src/templates/contexts.md

@@ -24,7 +24,7 @@ agents (and developers) quickly orient themselves when working in that area.
 |---|---|---|
 | **Module** | Document a module's structure and purpose | `client-software.md` |
 | **Domain** | Document a business domain across modules | `import-pipeline.md` |
-| **Service** | Document a complex service and its dependencies | `customer-service.md` |
+| **Service** | Document a complex service and its deps | `customer-service.md` |
 | **Integration** | Document an external API/system integration | `probaus-api.md` |
 | **Infrastructure** | Document infrastructure or DevOps concerns | `queue-system.md` |
 

package/.agent-src/templates/copilot-instructions.md

@@ -86,6 +86,27 @@ This repository contains {{project_description_oneline}}.
 - Do NOT review or suggest changes to unmodified code in the same file.
 - Do NOT nitpick style issues that linters/formatters auto-fix.
 
+## ✅ Known False Positives — Do NOT Flag
+
+The repo ships agent-config rules and skills under `.augment/`,
+`.agent-src/`, and `.agent-src.uncompressed/`. These trees use a
+deliberate path convention; the following patterns are **correct by
+design** — do not flag them as broken:
+
+- **Relative cross-references inside markdown rules / skills** like
+  `[x](../docs/guidelines/foo.md)` or `[y](../contexts/bar.md)`. The
+  base resolves from the file's delivered location (e.g.
+  `.augment/rules/<rule>.md`) — these paths are valid via the
+  `.augment/` tree, even when the file is symlinked into
+  `.claude/rules/`, `.cursor/rules/`, or `.clinerules/`.
+- **`path_prefix:` triggers containing `.agent-src.uncompressed/`**
+  in YAML frontmatter. This is a literal match pattern for the
+  host's router, **not** a file reference — keeping the verbatim
+  source path is required for the rule to fire on the right edits.
+- **Symlinked rule files** under `.claude/rules/`, `.cursor/rules/`,
+  `.clinerules/`. Targets resolve into `.augment/rules/`; missing-file
+  reports here are renderer artifacts, not real bugs.
+
 ## ✅ Code Review Comment Behavior
 
 - **Never create duplicate comments** — one comment per concern per location.

package/.agent-src/templates/copilot-review-instructions.md

@@ -0,0 +1,76 @@
+# Copilot Code Review — Repository-Specific Suppressions
+
+> Read by GitHub Copilot Code Review (PR bot) when reviewing this repo.
+> Companion to `.github/copilot-instructions.md`. **This file is the
+> path-resolution suppression floor** — it carries the rules Copilot
+> needs to *not* flag, sharply scoped to the agent-config layout.
+
+## Why this file exists
+
+The repo ships agent-config rules, skills, commands, and contexts under
+`.augment/`, `.agent-src/`, and (during authoring) `.agent-src.uncompressed/`.
+Cross-references inside those trees are valid via the **delivered**
+`.augment/` layout — not via raw git checkout. Copilot's static checker
+walks the git tree, so it sees broken paths where there are none.
+
+This is **intentional, not a bug**. The installer (`scripts/install.sh`)
+projects `.agent-src/` → `.augment/` and creates the symlinks that make
+the paths resolve at agent runtime.
+
+## ✅ Known False Positives — Do NOT Flag
+
+### Relative cross-references inside markdown rules / skills / commands
+
+```markdown
+[link](../docs/guidelines/foo.md)
+[link](../contexts/bar.md)
+[link](../docs/guidelines/baz.md)
+```
+
+These resolve from the file's delivered location (e.g.
+`.augment/rules/<rule>.md`). Even when the file is symlinked into
+`.claude/rules/`, `.cursor/rules/`, or `.clinerules/`, the relative
+form is correct by construction.
+
+### `path_prefix:` triggers containing `.agent-src.uncompressed/`
+
+```yaml
+triggers:
+  - path_prefix: ".agent-src.uncompressed/rules/"
+```
+
+This is a **literal match string** for the host's router — *not* a file
+reference. Source-of-truth meta-rules (`augment-source-of-truth`,
+`augment-portability`, `skill-quality`, `docs-sync`,
+`rule-type-governance`) legitimately match against the authoring tree.
+
+### Symlinked rule / skill / command files
+
+Targets resolve into `.augment/rules/`, `.augment/skills/`,
+`.augment/commands/` via installer-managed symlinks. Missing-file
+reports under `.claude/`, `.cursor/`, `.clinerules/` are renderer
+artifacts, not real bugs.
+
+### Body-link forms `../docs/guidelines/...`
+
+Single-up form is the post-rewrite shape produced by
+`scripts/compress.py`. The compressed `.agent-src/rules/` tree is one
+level deeper than the source `.agent-src.uncompressed/rules/`, so the
+rewriter collapses `../../docs/...` to `../docs/...`. Both forms are
+expected — one in source, one in compressed output.
+
+## ✅ What TO flag
+
+- Code defects, security issues, broken tests, type errors — normal
+  review.
+- New `.agent-src.uncompressed/` substrings introduced into
+  `.agent-src/rules/` body content (the `check-compressed-paths` task
+  already gates this — flag it as a regression if it slips through).
+- Rule frontmatter with `load_context:` entries that don't follow the
+  logical-name convention (`contexts/<area>/<file>.md`).
+
+## Pointer
+
+The full architecture is in `docs/architecture.md` § "Path resolution
+and Copilot integration". The compressed-path validator is
+`scripts/check_compressed_paths.py`, wired into `task ci`.

package/.agent-src/templates/features.md

@@ -22,7 +22,7 @@ Templates for feature plan files stored in `agents/features/` or `app/Modules/{M
 | 💡 | Idea | Rough concept, not yet validated |
 | 🔍 | Exploring | Being researched and brainstormed |
 | 📋 | Planned | Structured plan complete, ready for roadmap |
-| 🗺️ | Roadmapped | Roadmap(s) generated, ready for implementation |
+| 🗺️ | Roadmapped | Roadmap(s) generated, ready for impl |
 | 🔄 | In Progress | Implementation started |
 | ✅ | Complete | Feature shipped |
 | ❌ | Rejected | Decided not to build |

package/.agent-src/templates/roadmaps.md

@@ -36,14 +36,22 @@ Templates for roadmap files stored in `agents/roadmaps/` or `app/Modules/{Module
     creating the roadmap — not during execution. Default: stay on the
     current branch. If the user declines, the topic is closed for this
     roadmap. See [`scope-control`](../rules/scope-control.md#decline--silence--no-re-asking-on-the-same-task).
+15. **Declare complexity tier.** Every roadmap declares
+    `complexity: lightweight` or `complexity: structural` in frontmatter.
+    Lightweight (default): ≤ 6 phases, ≤ 600 lines, no nested council
+    debates inside the roadmap. Structural (rare, opt-in): contract-layer
+    or budget-invariant changes; multi-round council, file-ownership
+    matrices, > 600 lines. Enforced by `task lint-roadmap-complexity`.
+    Standard: [`docs/contracts/roadmap-complexity-standard.md`](../docs/contracts/roadmap-complexity-standard.md).
 
 ---
 
 ## Quality Gates (always apply at completion)
 
 Every roadmap must pass the project's quality pipeline before it is
-considered done. **When** the pipeline runs during `/roadmap execute` is
-governed by `roadmap.quality_cadence` in `.agent-settings.yml`
+considered done. **When** the pipeline runs during
+`/roadmap:process-step|phase|full` is governed by
+`roadmap.quality_cadence` in `.agent-settings.yml`
 (`end_of_roadmap` default → once before archival; `per_phase` → after
 every phase; `per_step` → after every step). Either way, a final fresh
 run is mandatory before "complete" per `verify-before-complete`.