@event4u/agent-config 9.16.0 → 9.17.0

package/dist/agent-src/commands/optimize/deep.md

@@ -8,7 +8,13 @@ sub: deep
 cluster: optimize
 skills: [ai-council, roadmap-writing, subagent-orchestration, decision-review]
 description: "Autonomous deep-refactoring loop — subagent analysis, verified findings, council, central + sub-roadmaps, PR, then N refinement loops (default 3). E.g. 'run a deep optimization pass'."
-argument-hint: "[--loops=N] [--scope=<path>] [--no-external]"
+argument-hint: "[--mode=plan|execute] [--loops=N] [--scope=<path>] [--no-external]"
+limits:
+  mode_default: plan
+  max_iterations: 3
+  hard_ceiling: 5
+  no_gain_stop: 2
+  target_metric: required
 suggestion:
   eligible: false
   rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
@@ -44,22 +50,71 @@ Do NOT invoke for: a single named bug, an interview-style sweep with the
 user in the loop (route to `/optimize project`), a code-only analysis
 (`/project-analyze`), or agent-layer file tooling (`/optimize` siblings).
 
-## Loop budget
+## Enforced limits (release-truth Phase 4)
+
+The frontmatter `limits:` block is the machine-readable pin
+(`tests/scripts/optimize_deep_limits.test.ts` fails when flow and pin
+drift); the flow steps below are the enforcement — each limit is a step
+the run MUST execute, not advice. The reviews' P0 this closes: an
+autonomous deep-refactoring loop shipped without technically enforced
+limits.
+
+### Execution mode — plan-only default
+
+`--mode=plan` is the **default**: run Steps 0–4 only — analyze, verify,
+council, author the roadmap set in the worktree — then present the plan
+plus the predicted delta on the target metric and STOP. No push, no PR, no
+refinement loop, no edit outside the worktree's roadmap drafts.
+`--mode=execute` must be **explicitly present in the invocation** to enter
+Steps 5–6; treat its absence as plan mode even when conversation momentum
+suggests otherwise. An execute-mode run still respects every gate below.
+
+### Pre-registered target metric — required before loop 1
+
+Before Step 5 may run (and therefore before any refinement loop), the
+central roadmap MUST carry a `Target metric` block naming ONE measurable
+metric (e.g. always-loaded token budget, gate wall-clock, red-test count),
+its **measured baseline at the branch SHA** (command output pasted, not
+asserted), and the predicted direction. No block → REFUSE to enter Step 5
+with: `target metric not pre-registered — record it in the central roadmap
+first`. Loops never move the goalposts: the metric named before loop 1 is
+the metric every loop is scored against.
+
+### Loop budget
 
 `--loops=N` caps the refinement loops. **Default: 3** (council-locked
 2026-08-02: autonomous loops without a fast, trustworthy CI oracle are
 compounding-error machines; 3 with a tripwire beats 5 on cost/benefit).
-Hard ceiling: 5 — above that, re-invoke deliberately with fresh context.
+Hard ceiling: 5 — a larger `--loops` value is clamped to 5 with a warning;
+above that, re-invoke deliberately with fresh context.
 
 **Halt-on-spin tripwire (checked after every loop, overrides the budget):**
 
 - A loop ends with no material roadmap delta (no step added, removed,
   re-scoped, or re-ordered) → STOP, the set has converged.
+- **Two consecutive loops deliver no measurable gain on the pre-registered
+  target metric (re-measured per loop, Step 6e) → STOP** — spinning without
+  gain is the failure the metric exists to catch.
 - The council splits on the same question twice → STOP, escalate that
   question to the user instead of burning a third loop on it.
 - Any validation target fails 3 consecutive refinement attempts → STOP
   (N=3 budget, `autonomous-execution`).
 
+### Hard exclusions — never inside this command
+
+- **Kernel rules:** the run NEVER edits a kernel rule (`is_kernel_rule` in
+  `src/scripts/_lib/kernel_rules.ts`; the `block-kernel-rule-writes`
+  PreToolUse guard denies the write anyway). A finding that wants a
+  kernel-rule change is recorded in the roadmap as a **proposal routed to
+  the kernel slow-rollout process** (`contexts/authority/kernel-rule-edits.md`:
+  own PR, ≥ 24 h soak) — the refusal names that process, never edits.
+- **Public contracts:** no change to a `docs/contracts/` surface marked
+  `stability: stable` without explicit user approval this run — record as a
+  proposal otherwise.
+- **Commit / push / PR floors:** unchanged — the invocation authorizes the
+  worktree branch and (execute mode) pushes to the run's own PR; merge,
+  deploy, and every Hard-Floor action stay this-turn gated.
+
 ## Steps
 
 ### Step 0 — Preflight (read-only)
@@ -115,22 +170,28 @@ work (whatever must be true for the rest to be verifiable — typically the
 CI oracle) gates the leverage-class work explicitly. Regenerate the
 dashboard (`roadmap:progress`) in the same response as any roadmap write.
 
-### Step 5 — Pull request
+### Step 5 — Pull request (execute mode only)
 
-Push the branch and open the PR per [`/create-pr`](../pr/create.md) — its
-mechanics and the always-active PR-surface rules govern the body and reply
-shape; do not restate them here.
+**Gate first:** `--mode=execute` present in the invocation AND the
+`Target metric` block recorded (§ Enforced limits) — otherwise STOP here
+and present the plan (plan mode's defined end state). Then push the branch
+and open the PR per [`/create-pr`](../pr/create.md) — its mechanics and the
+always-active PR-surface rules govern the body and reply shape; do not
+restate them here.
 
-### Step 6 — Refinement loops (×N, autonomous)
+### Step 6 — Refinement loops (×N, execute mode only)
 
 Each loop: (a) re-read the roadmap set with fresh subagent reviewers
 (adversarial: hunt over-building, missing evidence, lock violations,
 sequencing errors); (b) resolve contested deltas in the council; (c) any
 delta resting on a NEW factual claim re-enters the Step-2 verification gate
 before application — reviewer assertions are findings, not facts; (d) apply
-the surviving deltas to the roadmaps; (e) push to the same PR; (f) evaluate
-the tripwire. Loop output is a delta summary in the PR description's
-changelog section, not a comment (`no-pr-progress-comments`).
+the surviving deltas to the roadmaps; (e) **re-measure the pre-registered
+target metric at the new SHA and record the value in the loop verdict** —
+this is the per-loop verification the no-gain tripwire consumes; (f) push
+to the same PR; (g) evaluate the tripwire (§ Enforced limits — including
+the two-consecutive-no-gain stop). Loop output is a delta summary in the PR
+description's changelog section, not a comment (`no-pr-progress-comments`).
 
 ## Output
 

package/dist/agent-src/contexts/authority/commit-mechanics.md

@@ -16,8 +16,9 @@ Outside the four below, no commit is allowed and no commit ask is allowed.
    ahead and commit". Single commit, not standing.
 2. **Standing instruction not yet revoked** — earlier "commit after
    every phase"; cache the instruction and commit per its terms.
-3. **Commit command invoked** — `/commit` (split + confirm per commit)
-   or `/commit:in-chunks` (auto-split, Hard Floor still applies).
+3. **Commit command invoked** — `/commit` (split; ONE plan confirm;
+   terse: invoking confirms) or `/commit:in-chunks` (auto-split, Hard
+   Floor still applies).
 4. **Roadmap authorization** — roadmap lists explicit commit steps and
    the user invoked roadmap execution; each commit matches a step.
 
@@ -57,9 +58,8 @@ four exceptions cover *whether* commits happen; the Hard Floor covers
 When **executing** a roadmap that contains commit steps:
 
 - **Non-autonomous mode** (`personal.autonomy: off`, or `auto`
-  before opt-in) — agent may ask before each commit step. The user
-  authorized commits by writing them into the roadmap, but retains
-  step-level control.
+  before opt-in) — the one-shot pre-scan ask below, never per-step
+  (`commit-policy` NEVER-ask holds at every autonomy level).
 - **Autonomous mode** (`personal.autonomy: on`, or `auto` after
   opt-in) — agent does a quick pre-scan of the roadmap **before
   starting execution**. If commit steps are found, ask **once** at

package/dist/agent-src/contexts/communication/rules-auto/guidelines-mechanics.md

@@ -9,6 +9,7 @@ before writing or reviewing code); this file is the catalog.
 
 | File | Topic |
 |---|---|
+| `abstraction-thresholds.md` | Per-class extraction-threshold canon (code 2 · UI shell 3+ · stateful component ~4+state · utility-class string ≥3) — the single source every numeric threshold cites (ADR-213) |
 | `code-clarity.md` | Cross-language clarity rules — inline single-use values, carve-outs (side effects, loops, type narrowing, debugger) |
 | `component-oriented-and-oop-development.md` | Reuse-first components (FE) + OOP-where-it-reduces-complexity (backend); carve-out index; bounded by the anti-over-engineering anchors |
 

package/dist/agent-src/contexts/communication/rules-auto/skill-quality-mechanics.md

@@ -20,7 +20,7 @@ Make descriptions "pushy" — explicit about when to fire:
 - Name 2+ concrete triggers — domains, symptoms, file types, user phrasing.
 - End with: `... even if they don't explicitly ask for \`<skill-name>\`.`
 - Avoid hedges: `may help with`, `can be useful for`, `covers various`.
-- **Keep it ≤ 200 characters.** `scripts/skill_linter.ts` warns at
+- **Keep it ≤ 200 characters.** `scripts/skill_linter.ts` errors at
   `description_too_long` above this. If the pushy tail pushes you over, cut
   adjectives, drop the second example phrasing, or collapse a list — do
   **not** drop the trigger vocabulary or the `even if ...` tail.

package/dist/agent-src/contexts/communication/rules-auto/think-before-action-mechanics.md

@@ -81,7 +81,12 @@ Never load full datasets into context. Extract what you need:
 - Do NOT retry the same approach hoping for a different result.
 - Do NOT loop through trial-and-error when one targeted inspection
   would reveal the cause.
-- Max 2 retries for the same approach — then stop and rethink.
+- Max 2 retries for the same approach — then stop and rethink. The 2
+  retries plus the initial attempt ARE the three attempts of
+  `autonomous-execution`'s N=3 stop: the 3rd consecutive failure on the
+  same target escalates to stop-and-ask, then to `context-hygiene`'s
+  fresh-session recommendation — one ladder, not competing budgets
+  ([`autonomy-mechanics § Retry-budget escalation ladder`](../../execution/autonomy-mechanics.md)).
 
 ## Open files are context, not intent
 

package/dist/agent-src/contexts/communication/rules-auto/token-efficiency-mechanics.md

@@ -53,7 +53,10 @@ command says "ask the user", you ask.
   or ask the user.
 - Max 3 diagnostic commands per error. Read the error, think, act.
 - One hypothesis at a time. Pick the most likely, try it. Fails →
-  ask.
+  next hypothesis; failures on the same target accrue to the ONE
+  retry ladder (2 retries per approach → N=3 stop-and-ask, per
+  [`autonomy-mechanics § Retry-budget escalation ladder`](../../execution/autonomy-mechanics.md))
+  — never a separate one-strike cap.
 
 ### Keep intermediate output minimal
 

package/dist/agent-src/contexts/execution/autonomy-mechanics.md

@@ -14,7 +14,10 @@ relevant. Detection logic lives in [`autonomy-detection.md`](autonomy-detection.
 
 The value is read once on the first turn (per
 [`layered-settings`](../../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules))
-and cached. Missing key → treat as `on`.
+and cached. Missing key → treat as `auto` (fail-closed — same behavior
+as the shipped template default; absence of a key never grants the most
+permissive mode). The one exception is the explicit cloud carve-out
+below, where the whole settings file is absent by construction.
 
 ## Cloud platforms — settings degrade to `on`
 
@@ -129,6 +132,29 @@ knob. The per-dimension uncertainty score (see
 [`notes-first-reasoning`](../../rules/notes-first-reasoning.md)) feeds this
 decision. Engage per [`rdp-gate`](rdp-gate.md).
 
+## Retry-budget escalation ladder — 2, 3, and the fresh session are ONE ladder
+
+The suite states three retry numbers; they are **stages of one escalation
+ladder on the same failing target**, not competing budgets:
+
+1. **Attempt 1 fails → up to 2 retries of the same approach**
+   ([`think-before-action`](../../rules/think-before-action.md) "MAX 2
+   RETRIES PER APPROACH") — the soft, agent-side stage: rethink between
+   attempts, switch approach when the same signature repeats
+   ([`context-hygiene`](../../rules/context-hygiene.md) "same failure
+   signature twice → pivot").
+2. **The 3rd consecutive failed attempt on the target trips N=3**
+   (this file, above): 2 retries + the initial attempt ARE the three
+   attempts N=3 counts. Terminal action: STOP, surface the attempts,
+   ask the user.
+3. **Repeated N=3 cycles on the same task** escalate to
+   [`context-hygiene`](../../rules/context-hygiene.md)'s 3-Failure Rule:
+   state dump + recommend a fresh session.
+
+No artifact may mint a fourth budget or a stricter one-strike cap for the
+same subject; per-tool loop caps (`token-efficiency` >2 same-tool calls)
+are a different subject (tool-call repetition, not fix attempts).
+
 **Concrete diminishing-returns stop-signal.** "Marginal evidence drops" is
 otherwise fuzzy; operationalize it so it is checkable, not vibes: when **two
 consecutive investigative probes** (a read, a grep, a query) yield **no new

package/dist/agent-src/contexts/execution/roadmap-process-loop.md

@@ -127,8 +127,11 @@ only: lines matching `commit:` / `git commit` / `Commit phase`.
   Cache the answer for the whole run; do **not** re-ask per step.
   Hard-Floor diffs (bulk deletions, infra) still trigger the
   per-commit gate from [`commit-mechanics`](../authority/commit-mechanics.md).
-- **Commit steps present, non-autonomous** → ask before each commit
-  step inside the loop.
+- **Commit steps present, non-autonomous** → same one-shot pre-scan
+  ask as above, before the run starts; never per step
+  (per [`commit-mechanics`](../authority/commit-mechanics.md) —
+  `commit-policy` § NEVER ask about committing holds regardless of
+  autonomy).
 
 ## 4. Resolve cadences — read once, cache for the run
 

package/dist/agent-src/profiles/agency.yml

@@ -17,9 +17,9 @@ profile:
   defaults:
     preset_id: strict
     personas:
-      - reviewer
-      - product-strategist
-      - editor
+      - qa
+      - product-owner
+      - tech-writer
     skills_hint:
       - doc-coauthoring
       - decision-record

package/dist/agent-src/profiles/content_creator.yml

@@ -12,8 +12,8 @@ profile:
   defaults:
     preset_id: balanced
     personas:
-      - editor
-      - brand-voice
+      - tech-writer
+      - brand-strategist
     skills_hint:
       - voice-and-tone-design
       - messaging-architecture

package/dist/agent-src/profiles/developer.yml

@@ -13,8 +13,8 @@ profile:
   defaults:
     preset_id: balanced
     personas:
-      - reviewer
-      - security
+      - qa
+      - security-engineer
     skills_hint:
       - developer-like-execution
       - verify-completion-evidence

package/dist/agent-src/profiles/finance.yml

@@ -15,7 +15,7 @@ profile:
     preset_id: strict
     personas:
       - finance-partner
-      - reviewer
+      - qa
     skills_hint:
       - dcf-modeling
       - forecasting

package/dist/agent-src/profiles/founder.yml

@@ -16,8 +16,8 @@ profile:
   defaults:
     preset_id: fast
     personas:
-      - product-strategist
-      - reviewer
+      - strategist
+      - qa
     skills_hint:
       - refine-prompt
       - rice-prioritization

package/dist/agent-src/profiles/ops.yml

@@ -16,8 +16,8 @@ profile:
   defaults:
     preset_id: strict
     personas:
-      - reviewer
-      - security
+      - qa
+      - security-engineer
     skills_hint:
       - incident-commander
       - dashboard-design

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

@@ -31,7 +31,7 @@ Fires on new files, classes, controllers, modules, or any structural decision ab
 - **Business logic lives in services / use-cases** — calculations, orchestration, cross-aggregate validation.
 - **Domain models stay behavior-rich but I/O-free** — no HTTP, no DB transactions in the model; only domain rules, relationships, derived properties.
 - Always check the existing directory structure before creating new files.
-- Respect existing patterns — apply modern standards to **new** code only.
+- Respect existing patterns — apply modern standards to **new** code only. Stale idioms in *existing* code you touch are governed by the [`active-remediation`](active-remediation.md) ladder (fix-now / note + ask), not by this line.
 
 → Laravel-specific patterns (FormRequest, single-action `__invoke`, Eloquent scopes): see [`laravel`](../skills/laravel/SKILL.md), [`laravel-validation`](../skills/laravel-validation/SKILL.md).
 → Symfony: see [`symfony-workflow`](../skills/symfony-workflow/SKILL.md).
@@ -40,7 +40,7 @@ Fires on new files, classes, controllers, modules, or any structural decision ab
 ## Reusable components + object-oriented design
 
 - **Think in reusable units** — decompose UI into composable components; reuse the project's primitives / shared abstractions before building; extract a new unit only when the same shape repeats (audit existing first, per [`ui-audit-gate`](ui-audit-gate.md)).
-- **Object-oriented where it reduces complexity** — in an object-oriented / class-based codebase, encapsulation, single responsibility, composition over inheritance, behavior-rich domain objects, and design patterns *where they earn their place* are the high-priority default — never speculative abstraction, and never imposed on a functional / pipeline codebase (detect + defer to its paradigm). Bounded by [`minimal-safe-diff`](minimal-safe-diff.md) + [`senior-engineering-discipline`](senior-engineering-discipline.md), which **win on conflict**: a reviewer should be able to name the concrete duplication or second axis of change the abstraction removes (rule of thumb: two real repetitions before you extract).
+- **Object-oriented where it reduces complexity** — in an object-oriented / class-based codebase, encapsulation, single responsibility, composition over inheritance, behavior-rich domain objects, and design patterns *where they earn their place* are the high-priority default — never speculative abstraction, and never imposed on a functional / pipeline codebase (detect + defer to its paradigm). Bounded by [`minimal-safe-diff`](minimal-safe-diff.md) + [`senior-engineering-discipline`](senior-engineering-discipline.md), which **win on conflict**: a reviewer should be able to name the concrete duplication or second axis of change the abstraction removes (rule of thumb: two real repetitions before you extract a **code-level** abstraction; UI classes carry deliberately higher bars — per-class canon: [`abstraction-thresholds`](../docs/guidelines/abstraction-thresholds.md)).
 
 Full standard — split FE / backend, with the stack carve-out index and the anti-over-engineering deference: [`component-oriented-and-oop-development`](../docs/guidelines/component-oriented-and-oop-development.md).
 

package/dist/agent-src/rules/autonomous-execution.md

@@ -25,7 +25,7 @@ The universal safety floor (production-branch merges, deploys, pushes, prod data
 
 ## 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).
+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 `auto` (fail-closed, same as the shipped default; only the explicit cloud carve-out — no settings file at all — degrades to `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
 

package/dist/agent-src/rules/context-hygiene.md

@@ -18,7 +18,7 @@ enforced_by:
 
 > **Enforced by:** [`scripts/context_hygiene_hook.ts`](../../scripts/context_hygiene_hook.ts)
 > on Augment + Claude Code (`PostToolUse`). The hook maintains
-> `agents/runtime/state/context-hygiene.json` (turn count, loop signal,
+> `agents/state/context-hygiene.json` (tool-call count, loop signal,
 > freshness milestones at 20/40/60); the prose below is the spec the
 > hook implements and the agent-side fallback.
 
@@ -30,7 +30,8 @@ Monitor for **context decay** — long conversations degrade quality and waste t
 re-reading files already in context · 15+ completed tasks and a new unrelated
 topic · branch changed since start · ~24 hours passed.
 
-**Repeat** at multiples: messages 20/40/60, tasks 15/30/45.
+**Repeat** at multiples: messages 20/40/60, tasks 15/30/45 (the task
+15/30/45 ladder is agent-side only — the hook tracks no task counter).
 **ONLY at exact thresholds.** Between: silence. Suggestion template
 (token-cost estimate + numbered options): the mechanics guideline below.
 

package/dist/agent-src/rules/domain-safety-pii.md

@@ -127,7 +127,7 @@ k-anonymity rule of thumb: combinations of {birth date, ZIP/postal code, gender}
 | Internal analyst, BYO-device, cloud analytics | Pseudonymized + aggregated only |
 | External partner, signed DPA | Pseudonymized + minimum-necessary columns |
 | External partner, no DPA | Refuse; require DPA first |
-| Public dataset | Aggregated, k-anonymity ≥ 5, no quasi-identifier combos |
+| Public dataset | Aggregated, k-anonymity ≥ 5 as the release floor, no quasi-identifier combos — a stricter bar (k ≥ 50) applies before *classifying* a metric as anonymous, per [`data-handling-judgment`](../skills/data-handling-judgment/SKILL.md) |
 
 ## Surface 4 — Legal privilege markers (legal pack)
 

package/dist/agent-src/rules/output-discipline.md

@@ -42,8 +42,15 @@ in a broken state:
 | `[Your component here]` / `<YourComponentName>` | Use the actual component name or write the component |
 | `Lorem ipsum` / `dolor sit amet` in UI output intended for review | Use realistic placeholder content or ask for content |
 
-The banned patterns above are also detected by `lint_output_slop.ts` (see
-`src/scripts/lint_output_slop.ts`) — violations cause a CI exit-code-2.
+A subset of the banned patterns is detected by `lint_output_slop.ts` (see
+`src/scripts/lint_output_slop.ts`) — Lorem-ipsum filler, bracket placeholders,
+`// rest of component` / `// ... (unchanged)`-style implementation
+placeholders, "for brevity" in code, standalone Unicode `…` lines, and
+`// TODO … implement` stubs — violations cause a CI exit-code-2. Three rows
+are NOT linter-detected (`/* similar pattern */`, `// rest follows same
+pattern`, ASCII `...`), and the linter scans only the suite's authored
+markdown (`src/skills/`, `src/rules/`, `docs/guidelines/`) as a backstop; for
+generated output the ban itself is model-carried.
 
 ## On budget overflow — PAUSED protocol
 

package/dist/agent-src/rules/token-budget-discipline.md

@@ -50,8 +50,8 @@ A skill claiming `rich` MUST satisfy ALL three:
    carry a `load_context` pointer instead.
 
 3. **≤ 15 % of the suite's skills may claim `rich`** — the CI linter counts
-   rich-tagged skills and hard-fails if the ratio is exceeded. With ~230 skills, the
-   cap is ~35. Do not claim `rich` for convenience; claim it only for
+   rich-tagged skills and hard-fails if the ratio is exceeded. With ~290 skills
+   (288 as-of 2026-08), the cap is ~43. Do not claim `rich` for convenience; claim it only for
    irreducible-complexity skills.
 
 ## Telegraph-speak amendment

package/dist/agent-src/rules/user-interaction.md

@@ -46,12 +46,11 @@ Mechanical backstop:
 (non-zero exit on any rule below). Self-scan is the primary gate;
 the script is the deterministic safety net.
 
-## Question pacing — simple vs complex
+## Question pacing — one decision point per turn
 
-- **Simple, binary, or independent questions** may be grouped into a single reply with numbered options.
-- **Complex, dependent, or branching questions** must be asked **one at a time** — one question per turn — so each answer informs the next.
+[`ask-when-uncertain`](ask-when-uncertain.md)'s Iron Law is canonical: **one question per turn**. What counts as "one question" is **one decision point** — a single numbered-options block is ONE question even when its options span multiple dimensions (a depth-and-framework matrix answered with a single number is one decision). Multiple separate asks in one reply, or a block whose answer would need a structured reply (`1a, 2b`), violate the kernel rule's self-check.
 
-If in doubt, prefer one question at a time over a long batched prompt.
+If in doubt, split into serial turns — never a long batched prompt.
 
 ## Mechanics — rationale, failure modes, format details, examples
 

package/dist/agent-src/skills/build-buy-partner/SKILL.md

@@ -70,7 +70,7 @@ Integration cost is the most under-counted number. For each option:
 2. **Buy** — vendor integration (weeks to first value) + ongoing change-management cost + lock-in (cost to switch off).
 3. **Partner** — boundary management + divergence cost (what happens when partner changes their roadmap?).
 
-A buy decision with 2-week integration is rare; budget 4–8 weeks for non-trivial integrations and 3–6 months for enterprise-grade ones.
+A buy decision with 2-week integration is rare; industry-typical ranges (public integration benchmarks — not a prediction of your timeline, per `direct-answers` § no duration estimates) run 4–8 weeks for non-trivial integrations and 3–6 months for enterprise-grade ones.
 
 ### Step 3: Inversion — name the failure mode for each option
 

package/dist/agent-src/skills/copilot-agents-optimization/SKILL.md

@@ -47,7 +47,7 @@ Only after this analysis, proceed with optimization.
 |---|---|
 | **Audience** | Augment Agent, other AI agents |
 | **Can read `.augment/`?** | ✅ Yes — can follow references |
-| **Line budget** | Max 1000, ideal ≤ 500 |
+| **Size budget** | ≤ 3,000 chars (package root; consumer template ≤ 2,500) — enforced by `lint_agents_md.ts`; see `size-and-scope.md` |
 | **Purpose** | Project-specific setup, Docker, testing, quality tools |
 
 **What belongs here:**
@@ -73,7 +73,7 @@ Only after this analysis, proceed with optimization.
 |---|---|
 | **Audience** | GitHub Copilot (Code Review bot + Chat) |
 | **Can read `.augment/`?** | ❌ Code Review cannot, ✅ Chat can |
-| **Line budget** | Max 1000, ideal ≤ 500 |
+| **Line budget** | < 150 lines (ideal < 60); Copilot Code Review reads only the first 4,000 chars |
 | **Purpose** | Coding standards, review rules, architecture constraints |
 
 **What belongs here:**
@@ -127,8 +127,8 @@ both. Instead, reference with a table:
 
 | File | 🟢 Good | 🟡 Warning | 🔴 Over budget |
 |---|---|---|---|
-| `AGENTS.md` | ≤ 500 | 501–800 | > 1000 |
-| `copilot-instructions.md` | ≤ 500 | 501–800 | > 1000 |
+| `AGENTS.md` | ≤ 2,800 chars | 2,801–3,000 chars | > 3,000 chars — `lint_agents_md.ts` fails (consumer template: warn 2,300 / fail 2,500) |
+| `copilot-instructions.md` | < 60 lines | 60–150 lines | > 150 lines, or key rules past the 4,000-char Copilot read window |
 
 ### Reduction strategies (when over budget)
 

package/dist/agent-src/skills/copilot-config/SKILL.md

@@ -197,7 +197,7 @@ Copilot and Augment complement each other:
 
 - copilot-instructions.md is for GitHub Copilot, NOT for Augment — don't mix audiences.
 - Don't duplicate .augment/ content into copilot-instructions.md — it bloats the file and causes drift.
-- Copilot reads the ENTIRE instructions file on every request — keep it under 500 lines.
+- Keep copilot-instructions.md under 150 lines (per `size-and-scope.md`) — Copilot Code Review reads only the first 4,000 characters, so put the highest-priority rules up top.
 
 ## Do NOT
 

package/dist/agent-src/skills/deep-reading-analyst/SKILL.md

@@ -49,11 +49,14 @@ Every framework module is a project-local guideline under `docs/guidelines/agent
 
 ### Step 1: Initialize Analysis
 
-Ask the user three things in **one** message (not three turns), per `ask-when-uncertain` Iron Law (one question per turn — these three are bundled into a single numbered-options block):
+Open with ONE decision point (per `ask-when-uncertain` — a single numbered-options block answerable with a single number is one question; never three separate asks):
 
-1. **Goal** — problem-solving · learning · writing · decision-making · curiosity.
-2. **Depth** — L1 Quick (15 min) · L2 Standard (30 min) · L3 Deep (60 min) · L4 Research (120 min+).
-3. **Framework override** — defaults are auto-suggested by content type (table below); user may name specific frameworks.
+1. **Standard read** — L2 depth, auto-selected frameworks (default).
+2. **Quick skim** — L1 depth, auto-selected frameworks.
+3. **Deep dive** — L3/L4 depth, auto-selected frameworks.
+4. **Custom** — name your goal (problem-solving · learning · writing · decision-making · curiosity), depth level, and/or specific frameworks in your reply.
+
+Depth levels are scope descriptors, not wall-clock promises (per `direct-answers` — no duration estimates): L1 skim · L2 standard · L3 deep · L4 exhaustive-research.
 
 If the user does not answer, default to L2 Standard with auto-selected frameworks.
 

package/dist/agent-src/skills/description-assist/SKILL.md

@@ -52,7 +52,7 @@ Normative source: [`skill-quality`](../../rules/skill-quality.md) § *Descriptio
 
 | Check | Pass when… |
 |---|---|
-| **Length** | ≤ 200 characters (soft cap; linter warns `description_too_long`) |
+| **Length** | ≤ 200 characters (hard cap; linter errors `description_too_long`) |
 | **Trigger prefix** | Starts with "Use when …" or equivalent trigger phrasing |
 | **Trigger classes** | Names ≥ 2 of: domain, symptom, user phrasing, tool, file type |
 | **Undertrigger tail** | Ends with "… even if the user doesn't say `{name}`" or equivalent |

package/dist/agent-src/skills/fe-design/SKILL.md

@@ -107,7 +107,7 @@ React island vs. Vue SFC) is the apply-step's concern, not this skill's.
 - **One stateful component per concern** — don't build mega-components.
 - **Compose with reusable UI components** for shared shells, headers, fields.
 - **Use the project's library primitives first** — never rebuild what the design system already provides (audit findings tell you which).
-- **Extract when used 3+ times** — DRY applies to UI too.
+- **Extract a props-only UI shell when used 3+ times** — DRY applies to UI too; stateful components carry a higher bar (~4 + real state) — per-class canon: [`abstraction-thresholds`](../../../docs/guidelines/abstraction-thresholds.md).
 - **Component workshop when the project is large enough** — for a real, growing shared-component library, isolate and document each reusable component in a component workshop so it stays discoverable and reused, not re-invented; skip it for a small surface of one-offs. Tool-specific setup is a carve-out (Storybook et al.) — see the implementation skill (e.g. [`react-shadcn-ui`](../react-shadcn-ui/SKILL.md) § Component workshop), never a generic mandate.
 
 ## Form Design

package/dist/agent-src/skills/market-entry-analysis/SKILL.md

@@ -144,7 +144,7 @@ Horizontal SaaS, US-only, mid-market, considering EU expansion.
 
 - Step 0 — axis = geo (EU). Defer segment (stay mid-market) and vertical (stay horizontal).
 - Step 1 — candidate beachheads: DACH, Nordics, UK, Benelux. Scored: UK wins on constraint-favour (English-language sales motion translates, common-law contract familiarity), reference-reachability (5 mid-market UK customers reachable via existing channels), regulatory delta (UK-GDPR ≈ EU-GDPR floor with thinner data-residency requirement), expansion path (UK → Benelux → DACH).
-- Step 2 — Sales motion: existing AE motion translates to UK. Product delta: data-residency in EU (12 weeks). Operating cost: UK Ltd entity, VAT registration ≈ 3 months.
+- Step 2 — Sales motion: existing AE motion translates to UK. Product delta: data-residency in EU (industry-typical ~12 weeks, illustrative). Operating cost: UK Ltd entity, VAT registration (industry-typical ≈ 3 months, illustrative — not a prediction).
 - Step 3 — failure mode: "incumbent's UK channel partnerships locked us out of mid-market." Mitigation: direct-AE motion + content-led pipeline.
 - Step 4 — sequence: UK (beachhead) → Benelux (same motion, thin regulatory delta) → DACH (German-speaking sales hire required, larger TAM).
 - Step 5 — emit entry plan + compose P3 for UK-vs-incumbents positioning.

package/dist/agent-src/skills/persona-writing/SKILL.md

@@ -107,8 +107,8 @@ A single Markdown file at `src/agent-src/personas/{id}.md`:
 3. `## Unique questions` — 4–7 decidable questions
 4. `## Output expectations` — verdict format, severity vocabulary
 
-Length: ≤ 80 lines for a tier-core persona; longer signals the focus
-is too broad.
+Length: ≤ 120 lines for a tier-core persona (specialists ≤ 100; wings
+3–4: ≤ 140); longer signals the focus is too broad.
 
 ## Gotchas
 

package/dist/agent-src/skills/readme-reviewer/SKILL.md

@@ -132,7 +132,8 @@ Size checks:
 - **< 150 lines** — healthy
 - **150–300 lines** — expect a Table of Contents; flag if missing
 - **300–500 lines** — flag as overloaded; deep content should be in `/docs/`
-- **> 500 lines** — flag as broken entry point; hard split required
+- **> 500 lines** — flag as broken entry point; split strongly recommended
+- The enforced lint limit is **750 lines** (`lint_readme_size.ts` fails above it); the 150/300/500 bands are editorial
 
 Structure checks:
 

package/dist/agent-src/skills/rule-writing/SKILL.md

@@ -66,7 +66,9 @@ don't need it, it is `auto`.
 ### 2. Write a trigger-style description
 
 The `description` field **is** the trigger. Describe **when** the rule
-applies, not **what** it contains. Soft cap: **200 characters**.
+applies, not **what** it contains. Hard cap: **200 characters** (the
+linter errors `description_too_long` above it); the rule schema
+(`rule.schema.json`) additionally sets `maxLength: 190`.
 
 ```yaml
 # Bad — describes content, won't match reliably:
@@ -185,7 +187,7 @@ diffing the full lint output. See
 ```yaml
 ---
 type: "auto"              # or "always"
-description: "Trigger-shaped sentence — domain + symptoms — soft cap 200 chars"
+description: "Trigger-shaped sentence — domain + symptoms — schema max 190 chars"
 alwaysApply: false        # true only if type: always
 source: package           # or project for consumer-local rules
 load_context:             # logical names only — `contexts/<area>/<file>.md`

package/dist/agent-src/skills/skill-reviewer/SKILL.md

@@ -90,7 +90,7 @@ The highest-signal content in a skill. Documents failure patterns.
 
 Skill exceeds size limits (see `docs/guidelines/agent-infra/size-and-scope.md`).
 
-**Check:** Review at >300 lines. Strongly consider split at >1200 words / >1500 words.
+**Check:** Review at >400 lines. Strongly consider split at >1200 words / >1500 words.
 **Fix:** Extract reference tables, templates, and examples into separate files
 in the skill folder, or split by responsibility.
 

package/dist/agent-src/skills/skill-writing/SKILL.md

@@ -158,8 +158,8 @@ generic descriptions cause **undertriggering**. Normative source:
 
 Three rules: name 2+ triggers (domains, symptoms, user phrasing), end with
 `... even if they don't explicitly ask for \`<skill-name>\`.`, and stay
-**≤ 200 characters** (`skill_linter.ts` warns `description_too_long` above
-that). When trimming to fit, drop adjectives or the second example phrasing
+**≤ 200 characters** (`skill_linter.ts` errors `description_too_long` above
+that — a hard cap). When trimming to fit, drop adjectives or the second example phrasing
 before you drop a trigger class or the `even if ...` tail.
 
 Canonical before/after (2026-04-21 audit baseline):