@event4u/agent-config 7.0.2 → 7.2.0

package/docs/guidelines/agent-infra/domain-pack-architecture.md

@@ -0,0 +1,56 @@
+# Domain-pack architecture — a retrospective observation (NOT a design driver)
+
+> **Status: retrospective hypothesis, N=1.** This documents the sequence the
+> **legal** pack happened to follow. It is **not** a rule and **not** a template
+> that future packs must fit. Validate it against a *second* domain before
+> promoting any of it to a rule or building scaffolding tooling — per
+> `domain-adoption-policy` and the `domain-pack-extraction-when-triggered` (N=2)
+> roadmap. Designing a new pack to fit this speculative pattern would invert the
+> lever: build the domain correctly on its own legs, then observe whether the
+> pattern recurred.
+
+## The sequence legal followed
+
+1. **Safety floor first** — a domain `*-safety-floor` rule (Iron-Law-shaped,
+   ~100 lines) before any drafting skill. A drafting skill shipped before its
+   floor is the exact liability the floor prevents.
+2. **Enforcement teeth** — the floor's machine-checkable elements become a
+   deterministic linter (`lint_legal_pack`) wired into CI. Prompt rules are not
+   governance; lint rules are. This is the differentiator vs prompt-only suites.
+3. **Eval = regression harness, not a correctness oracle** — self-labeled
+   fixtures in the maintainer's genuine-competence sub-domain; the *objective*
+   eval (attorney-validated gold set, inter-annotator ≥0.7) is a separate,
+   demand-and-funding-gated track. See `domain-eval-anti-pattern.md`.
+4. **Skills = procedure + output template only** — no default domain positions;
+   positions live in a practice profile, so one skill set behaves
+   team-specifically and the pack stays portable.
+5. **Practice profile (the keystone)** — a cold-start interview writing a
+   plain-prose profile into `.agent-settings.yml` / the setup wizard; skills read
+   it and halt on unresolved placeholders.
+6. **Deferred by default** — personas, scheduled watchers, installer hubs, and
+   broader scope are recorded as rejected/gated, not built, until evidence pulls
+   them in.
+
+## Why it is NOT yet a rule
+
+- **N=1.** Finance might need real-time-data evals; security might need red-team
+  evals; neither looks like "clause extraction + self-labeled fixtures." The
+  shape that fit legal may not fit them.
+- **Premature tooling is the maintainer's enemy.** No `domain-pack:new`
+  scaffolding ships from this observation. Extraction waits for N=2, where a
+  second domain either confirms the sequence (promote to a rule) or diverges
+  (document the delta, keep both bespoke).
+
+## What to do at N=2
+
+Build the second domain on its own merits. *Then* compare: which steps generalised,
+which broke. If the sequence held twice, promote it to a rule and consider
+scaffolding. If it diverged, this note records why a one-size pattern was wrong —
+itself a useful result.
+
+## See also
+
+- [Capability Boundary Matrix](../../contracts/capability-boundary.md) — per-pack safety posture (default-install / consent / council / disclaimer / eval / risk_class).
+- [ADR-107 — Legal domain-pack adoption](../../decisions/ADR-107-legal-domain-pack-adoption.md)
+- `domain-adoption-policy` (rule) — the three gates before opening any domain.
+- `domain-eval-anti-pattern.md` — why the legal eval is a regression harness, not an objective gate.

package/docs/guidelines/design-antipatterns-triggers.json

@@ -0,0 +1,17 @@
+{
+  "description": "Routing eval for design-antipatterns guideline: should an agent pull this catalog for a given task?",
+  "should_pull": [
+    "Design a landing page for a new SaaS product",
+    "Review this UI mockup for AI-slop patterns",
+    "Create a feature card section with icons and descriptions",
+    "Generate a hero section with a big metric and supporting stats",
+    "The design looks generic — how do I make it more distinctive?"
+  ],
+  "should_not_pull": [
+    "Fix the authentication bug in the login controller",
+    "Write a migration to add the user_id column to the orders table",
+    "Set up the CI pipeline for the monorepo",
+    "Draft a customer email reply for a billing issue",
+    "Analyze the test coverage for the payment module"
+  ]
+}

package/docs/guidelines/design-antipatterns.md

@@ -0,0 +1,170 @@
+# Design Anti-Patterns — AI-Slop Catalog
+
+> Lazy-loaded reference guideline. Pull this before proposing, generating, or
+> reviewing any UI. Used by `design-intelligence`, `fe-design`, `design-review`,
+> `existing-ui-audit`.
+
+This catalog enumerates patterns that make AI-generated UI **recognizably
+AI-generated**. Every entry carries a concrete override condition — the goal is
+not prohibition but deliberateness. A pattern on this list used *knowingly* for
+a specific brief is a design decision; used *reflexively* from a default, it is
+slop.
+
+**How to use:** Before generating UI, scan the applicable category. Flag any
+pattern you were about to reach for. Either (a) choose a different approach, or
+(b) invoke the override condition and state the reason explicitly in the brief.
+
+**Agent self-check principle:** These are guidance rules, not linter rules. The
+agent reads the brief, checks its first impulse against this catalog, and adjusts
+or overrides. The enforceable subset (contrast ratio, font-size, heading
+hierarchy, reduced-motion, focus indicator) is in `lint_design_quality`
+(Phase 5).
+
+**Who owns what (boundary — avoid drift):**
+
+| Layer | Owns | Artifact |
+|---|---|---|
+| **Guidance** | Subjective taste — Visual / Typography / Color / Layout / Copy patterns, override judgment, the originality self-test | this catalog |
+| **Enforcement** | Objective floors — Q1–Q6 (WCAG contrast, font-size, line-length, reduced-motion, heading hierarchy, focus indicator) as exit-code-2 CI | `lint_design_quality` |
+| **Audit method** | HOW to test WCAG (keyboard nav, ARIA, screen-reader procedures) | `accessibility-auditor` |
+| **Stack manifestation** | Concrete Tailwind class / hex bans, shadcn defaults | `tailwind-engineer`, `react-shadcn-ui` (per `framework-neutrality-in-generic-skills`) |
+| **Register** | Brand mode vs product mode — which patterns apply | `docs/guidelines/design-modes.md` |
+
+This catalog is the canonical *index*; it states the pattern stack-agnostically.
+The stack-specific bans live in the apply skills and link back here by entry ID.
+The objective floors are cited from the linter, never re-eyeballed by an agent.
+
+---
+
+## Visual
+
+| # | Pattern | Why it reads as AI-generated | Override condition |
+|---|---|---|---|
+| V1 | Side-stripe `border-left` or `border-right` > 1px as a colored accent | The single most recognizable AI-UI signature; every scaffold-default card uses it | Brand token explicitly defines a stripe; document the decision in the design brief |
+| V2 | Glassmorphism as decoration (`backdrop-blur` + `bg-white/10`) with no functional depth hierarchy | Model defaults to it for "premium feel"; result looks like 2021 Material You clip-art | Element genuinely sits above a complex, blurred background layer; use sparingly and only for top-level floating surfaces |
+| V3 | Ghost card: `border: 1px solid` + box-shadow ≥ 16px spread together | The combination creates visual noise — the ghost card signals no confident decision about depth | Choose either border OR shadow to indicate depth; never both on the same surface |
+| V4 | Over-rounded small cards or badges: `border-radius` > 16px on elements < 200px wide | Excessive rounding on small surfaces looks toy-ish; standard cap is 12–16px | Pill shape (`border-radius: 9999px`) is intentional on single-line tags/chips only |
+| V5 | Hand-drawn or illustrated SVG icons mixed with crisp icon-system icons | Visual register collision; instantly reads as "generated asset" | Intentional illustrative section (hero illustration, empty-state art); isolate from the icon system |
+| V6 | Repeating diagonal stripes as a background texture | A cliché background default; reads as generated CSS art | Brand explicitly uses pattern backgrounds (e.g., a textile brand); document the stripe definition |
+| V7 | Nested cards: a card inside a card inside a card | Depth hierarchy collapses; user cannot parse elevation intent | A truly three-level hierarchy (e.g., project → board → card); ensure each level has distinct visual weight |
+
+---
+
+## Typography
+
+| # | Pattern | Why it reads as AI-generated | Override condition |
+|---|---|---|---|
+| T1 | Flat type hierarchy: body and headings use the same optical weight and nearly the same size | Type hierarchy is invisible; user cannot scan the page | Deliberately minimal aesthetic where all text is body-weight; must be an explicit brand decision |
+| T2 | Oversized italic serif as the primary hero headline | The "AI startup landing page" template; seen on ~60% of AI-generated marketing pages | Brand adopts editorial-magazine aesthetic with a documented italic serif rationale |
+| T3 | Icon tile (small rounded-square container) above heading | The universal AI feature-card template; reads as scaffold | Listed features genuinely benefit from visual-icon-then-title affordance AND the icons are custom, not library defaults |
+| T4 | Eyebrow / ALL-CAPS label above every section heading | Overuse collapses the emphasis; maximum is 1 eyebrow per 3 sections (countable: grep tracking classes) | Used for genuine section-type differentiation with meaningful vocabulary (not just "FEATURES", "PRICING") |
+| T5 | Repeated section kickers ("Our mission", "What we offer", "Why choose us") | Filler vocabulary; every AI-generated page has the same three section titles | Every kicker is substantive and uses brand-specific vocabulary, not generic marketing speak |
+| T6 | Crushed letter-spacing on display text (`letter-spacing` < −0.04em) | Below −0.04em glyphs collide optically; reads as "designer-ish effect" with no grounding | Intentional tight display treatment with a documented minimum floor; verify at the actual render size |
+| T7 | Overused fonts without a brand reason: Inter, Roboto, DM Sans, Geist, Space Grotesk, Instrument Serif | These are the default AI-coding-tool font picks; every generated UI uses one of them | Brand has explicitly adopted one of these AND there is a documented reason (e.g., Inter for its variable metrics in a data-dense dashboard) |
+| T8 | Single typeface for everything | Missed typographic contrast opportunity; all-Inter reads as "I did not think about fonts" | Intentional mono-typeface aesthetic (e.g., terminal-inspired); must be stated in the brief |
+| T9 | All-caps body paragraphs or field labels | Reduces legibility below WCAG AA for sustained reading; reads as flair over function | Short UI labels (e.g., button text in a brutalist layout); never for body paragraphs |
+| T10 | Wide letter-spacing on body text (`letter-spacing` > 0.05em) | Reduces readability for sustained reading; reserved for display use | Display text (headlines, pull quotes) where intentional tracking is a brand element |
+
+---
+
+## Color
+
+| # | Pattern | Why it reads as AI-generated | Override condition |
+|---|---|---|---|
+| C1 | Purple/violet + cyan-on-dark palette as the primary scheme | The most recognizable AI-UI color combination in 2024–2026; instantly signals "generated" | Brand color system genuinely defines a violet primary; must come from `brand-to-tokens`, not from model defaults |
+| C2 | Gradient text via `background-clip: text` as a primary accent | Overused to the point of invisibility; also has rendering edge cases on some platforms | Headline treatment in a brand that explicitly uses gradient identity (e.g., a product whose logo is a gradient) |
+| C3 | Glowing colored accents on dark mode (bright neon `box-shadow` or `text-shadow`) | Looks like a 2020 gaming UI; reads as an AI attempt at "moody" | Brand explicitly defines neon accents with a documented usage rule (e.g., error or alert states in a security product) |
+| C4 | Gray text on colored background without WCAG AA check | Muted gray chosen for "elegance" often fails 4.5:1 contrast; the failure is invisible until audited | Any use — always verify the contrast ratio; if it fails, either darken the text or lighten/darken the background |
+| C5 | Cream/sand body background (OKLCH L 0.84–0.97, C < 0.06) with brass/clay/oxblood accents | The 2025 "premium-consumer" AI palette; every generated "sophisticated" product uses this exact combination | Brand has an explicit warm-neutral design language documented in `brand-to-tokens`; the palette is first-party, not a default reach |
+
+---
+
+## Layout
+
+| # | Pattern | Why it reads as AI-generated | Override condition |
+|---|---|---|---|
+| L1 | Hero metric template: giant number, small label, 3–4 stats in a row, gradient | The default SaaS dashboard hero; appears on ~70% of AI-generated dashboard screens | Data storytelling genuinely requires a primary metric with supporting context; must vary the arrangement |
+| L2 | Three identical feature cards in a grid with the same visual weight | The scaffold-default; no visual rhythm, no hierarchy among features | Product genuinely has three equally weighted features; must still vary padding, or use a different composition |
+| L3 | Monotonous spacing: one spacing value (usually 24px) used for everything | Spacing is rhythm; uniform spacing collapses the hierarchy of proximity | Intentional grid where every element has equal weight; must document the grid definition |
+| L4 | Numbered section markers (01 / 02 / 03) as a primary section-order device | Universal AI-generated marketing page tell; seen on virtually every generated landing page | A genuinely numbered process or sequenced guide where the step number carries meaning beyond decoration |
+| L5 | Line length > 80ch in body copy without column constraint | Reduces readability; WCAG recommends 45–75 characters; beyond 80 the eye struggles to track | Data-dense dashboards where column width is driven by tabular data, not narrative text |
+| L6 | `position: absolute` dropdown inside `overflow: hidden` container | Dropdown clips; a common AI-generated layout bug | Refactor: use `<dialog>`, the Popover API, or `position: fixed` / portal to escape the stacking context |
+| L7 | Content that overflows its container | Text truncation or reflow failures at non-default viewport widths; reads as untested | Never acceptable in production output; test at 320px, 768px, 1280px minimally |
+| L8 | Z-index values of 99, 999, 9999 without a semantic z-index scale | Magic numbers; the first time two elements compete, the scale breaks | Establish a named semantic z-index scale (`--z-modal: 400`, `--z-toast: 500`, etc.) and use it |
+
+---
+
+## Motion
+
+| # | Pattern | Why it reads as AI-generated | Override condition |
+|---|---|---|---|
+| M1 | Bounce or elastic easing curves on UI elements | Bounce draws attention to the animation itself; UI motion should serve the action, not perform | Intentional playful affordance (game UI, onboarding celebration state); must be brief and non-repeating |
+| M2 | Animating layout properties (width, height, top, left, padding) | Triggers browser layout recalculation; janky on mid-range devices; always solvable with `transform` | Never — use `transform: scaleX()` for width-like effects, `transform: translateY()` for position |
+| M3 | Animating `<img>` element on hover (scale, filter, transform) | Triggers composite + image decode; often causes content shift | Animate the card's background, border, or shadow instead; leave the image static |
+| M4 | `transition: all` shorthand | Animates every property including layout, color, opacity simultaneously; unpredictable and expensive | Enumerate only the properties that should animate: `transition: transform 200ms ease-out, opacity 200ms` |
+| M5 | Missing `@media (prefers-reduced-motion: reduce)` alternative for any animation | Accessibility violation; vestibular disorders make animated UI unusable | Never acceptable; always add a `prefers-reduced-motion` variant — gentler animation (reduced distance/opacity) is preferred over `display: none` |
+
+---
+
+## Copy
+
+| # | Pattern | Why it reads as AI-generated | Override condition |
+|---|---|---|---|
+| CP1 | Em-dash (`—`) overuse | The #1 syntactic LLM signature; appears in AI copy at 3–5× the frequency of human editorial copy; maximum 2 per 500 words | Specific editorial voice that uses em-dashes deliberately; count them before shipping |
+| CP2 | Marketing buzzwords: streamline, empower, supercharge, world-class, enterprise-grade, seamlessly, robust, leverage | These words carry no information; an AI-slop test: replace each with nothing — the sentence still communicates the same thing | No override; if a word can be deleted without loss, delete it |
+| CP3 | Aphoristic manufactured contrast ("We don't do X. We do Y." / "Not just A, but B.") | A generated sentence rhythm that sounds like brand writing but carries no specificity | Aphoristic copy is legitimate when the contrast reveals a genuine product distinction; test by asking whether the Y side says something concrete |
+| CP4 | "Theater" framing — copy that announces what the product does without saying how or why | "The platform for modern teams." communicates nothing; it is content-shaped noise | Every tagline must pass the "so what" test: can a skeptic follow it with "but how?" and get a concrete answer? |
+
+---
+
+## Quality floors — measurable thresholds
+
+These are not stylistic — they are objective quality failures detectable without
+aesthetic judgment. The `lint_design_quality` CI linter enforces a subset of
+these. The rest are agent self-checks.
+
+| # | Threshold | Measurement | CI-enforced? |
+|---|---|---|---|
+| Q1 | Text contrast ≥ 4.5:1 normal / ≥ 3:1 large text (WCAG AA) | `contrastRatio(text, bg) < threshold` | Yes (`lint_design_quality`) |
+| Q2 | Body `font-size` ≥ 14px (floor); ≥ 16px strongly preferred | Computed `font-size` on `p`, `li`, `td` | Yes |
+| Q3 | Line length ≤ 75 characters (prose) | Character count before soft wrap | Yes |
+| Q4 | All `@keyframes` / `animation` have a `prefers-reduced-motion` alternative | CSS `@media` check | Yes |
+| Q5 | Heading levels not skipped (h1→h3 direct, not h1→h4) | DOM heading sequence | Yes |
+| Q6 | All interactive elements have a `:focus-visible` indicator | CSS rule check | Yes |
+| Q7 | Display `letter-spacing` floor: ≥ −0.04em (tighter reads cramped) | Computed tracking | Agent self-check |
+| Q8 | `line-height` ≥ 1.3 on body text | Computed `line-height` | Agent self-check |
+| Q9 | Small-card `border-radius` cap: 12–16px (not 24px+) | Computed `border-radius` on elements < 200px | Agent self-check |
+| Q10 | Body background: avoid OKLCH L 0.84–0.97, C < 0.06 (cream/sand) unless brand-defined | Color space calculation | Agent self-check |
+| Q11 | Padding floors: ≥ 8px (inline elements), ≥ 16px (card/panel bodies) | Computed padding | Agent self-check |
+| Q12 | Justified text only with CSS hyphenation (`hyphens: auto`) | Presence of `text-align: justify` without `hyphens` | Agent self-check |
+
+---
+
+## The AI-slop originality self-test
+
+Before finalizing any UI design, run this two-tier check:
+
+1. **Category test:** Could someone guess the aesthetic from the product
+   category alone? (e.g., "SaaS → dark mode + purple gradient" /
+   "fintech → navy + gold" / "health → teal + rounded sans"). If yes,
+   rework the concept.
+
+2. **Anti-reference test:** Could someone still guess it after knowing the
+   category AND having seen 3 references you explicitly avoided? If yes,
+   dig deeper. A direction that is merely "not the worst cliché" is still
+   a cliché.
+
+The bar: a visitor should ask "how was this made?", not "which AI made this?"
+
+---
+
+## See also
+
+- `design-intelligence` — corpus-grounded style/color/typography selection
+- `fe-design` — stack-agnostic heuristics (form, table, responsive, a11y)
+- `design-review` — structured UI/UX review methodology
+- `existing-ui-audit` — mandatory pre-step: inventory before designing
+- `motion-choreographer` — animation heuristics (should-it, which-easing, how-much)
+- `typography-system` — modular-scale construction and pairing
+- `accessibility-auditor` — WCAG audit method
+- `brand-to-tokens` — first-party brand token extraction (the legitimate override source for most anti-patterns above)

package/docs/guidelines/design-modes.md

@@ -0,0 +1,97 @@
+# Design Modes — Brand vs Product
+
+> Reference doc. Pull this when deciding which design skills to prioritize
+> or when the brief is ambiguous about the design register.
+
+## The two registers
+
+Every design task operates in one of two registers. Getting the register
+wrong is the root cause of most AI-generated design failures:
+
+| | Brand mode | Product mode |
+|---|---|---|
+| **Core thesis** | The impression IS the product | Design serves the task |
+| **Primary failure** | Flatness / genericness — looks like every other AI startup | Strangeness without purpose — "clever" choices that obscure the tool |
+| **The user's question** | "How was this made?" (genuine curiosity) | "Where do I click?" (the tool disappears into the task) |
+| **Key skill cluster** | `brand-identity`, `iconography`, `fe-design § Aesthetic direction`, `design-intelligence` | `accessibility-auditor`, `ui-component-architect`, `fe-design § Table/Form Design` |
+| **Typography strategy** | Distinctive pairing — two contrasting families, deliberate tracking | One reliable family — Inter or equivalent; predictable hierarchy |
+| **Color strategy** | Brand identity — often unexpected; the palette IS the differentiator | Semantic function — primary/danger/success/neutral; predictable meaning |
+| **Motion strategy** | Expressive — motion reinforces the brand's personality | Utilitarian — motion confirms state changes; nothing decorative |
+| **Spacing strategy** | Breathing room; generous whitespace as a brand signal | Dense/efficient; optimize for information density |
+| **Success criterion** | Originality test: a skeptic can't guess "which AI made this?" | Earned familiarity: the tool disappears; users focus on their task |
+
+## How to determine the register
+
+Ask: **What is the output of this UI being used for?**
+
+- A consumer-facing surface where the FIRST impression determines whether the
+  user trusts/buys → **Brand mode**. The product has 3 seconds; every pixel
+  contributes to the brand's identity.
+
+- An internal tool, dashboard, admin panel, or workflow-critical surface where
+  users return dozens of times per day → **Product mode**. Strangeness wastes
+  their time; predictability builds trust.
+
+- A marketing landing page → **Brand mode**. It has one job: create desire.
+
+- A data entry form → **Product mode**. It has one job: accept correct data.
+
+**Ambiguous cases:** many products have both (a brand-heavy landing page +
+a product-mode dashboard). The register applies per-surface, not per-product.
+When unclear: ask — *"Is the user here to be impressed, or to accomplish a
+task?"*
+
+## Brand-mode failure modes
+
+- **Genericness:** Choosing the safe AI-slop palette (cream + brass, purple/violet gradient, three equal cards). The product is invisible in its category. Cross-check with `docs/guidelines/design-antipatterns.md` § Color and Visual.
+- **Inconsistency:** Brand direction picked for the hero, abandoned for the body. The page reads as two different products.
+- **Aesthetics-without-function:** Beautiful but confusing navigation, stunning hero with no CTA clarity.
+
+## Product-mode failure modes
+
+- **Strangeness-without-purpose:** A clever typographic choice that makes the CTA harder to scan. A gradient background on a data table. An animated page transition in an admin panel.
+- **Premature originality:** Reinventing a standard UI pattern (data table, form validation, dropdown) when the standard is what users expect.
+- **Over-engineering:** Five different card elevations in a dashboard that needs two.
+
+## The AI-slop originality self-test (applies to brand mode primarily)
+
+Run BOTH tiers before approving a brand-mode design direction:
+
+**Tier 1 — Category test:**
+Would a designer seeing 20 AI-generated [product category] UIs recognize this
+aesthetic as part of that category's default? (e.g., "SaaS → dark mode + purple
+gradient"; "health app → teal + rounded sans serif + white space").
+- If YES: rework the concept. The design is invisible in its category.
+- If NO: proceed to Tier 2.
+
+**Tier 2 — Anti-reference test:**
+Given the category AND three explicit aesthetics you've avoided — could a
+skeptic still guess the direction? (e.g., "fintech that's not navy-and-gold,
+not minimal white, not brutalist → everyone picks terminal dark").
+- If YES: dig deeper. "Avoiding the worst cliché" is not differentiation.
+- If NO: the direction is genuinely distinctive.
+
+**The bar:** a visitor should ask "how was this made?" not "which AI made this?"
+
+## Routing to skills by mode
+
+**Brand mode brief:**
+1. `design-intelligence` (grounded style/palette/typography selection — run the corpus first)
+2. `brand-identity` (archetype → token system)
+3. `iconography` (icon system selection for brand expression)
+4. `fe-design § Aesthetic direction` (direction → composition → typography → color)
+
+**Product mode brief:**
+1. `existing-ui-audit` (mandatory — inventory first)
+2. `accessibility-auditor` (WCAG compliance from the start)
+3. `ui-component-architect` (reuse existing primitives)
+4. `fe-design § Component Architecture, Form Design, Table Design` (standard patterns)
+
+**Both modes:** `design-antipatterns` (always pull), `design-review` (with anti-slop check)
+
+## See also
+
+- `docs/guidelines/design-antipatterns.md` — the slop-tell catalog; brand mode especially needs this
+- `brand-source-of-truth` — when a registered brand profile is present, it governs
+- `brand-consistency` — validates emitted artifacts against the brand profile
+- `design-system-capture` — DESIGN.md/PRODUCT.md capture the mode's decisions for cross-task consistency

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "7.0.2",
+    "version": "7.2.0",
     "description": "Universal AI Agent OS — audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
     "license": "MIT",
     "private": false,

package/src/config/agent-settings.template.yml

@@ -84,6 +84,24 @@ rule_loading_tier: __RULE_LOADING_TIER__
 lean_projection:
   mode: eager-all
 
+# --- Token-rich skills governance ---
+#
+# Skills marked `token_budget_class: rich` in their frontmatter are exempt
+# from telegraph-speak condensation and thin-projector trimming. They load
+# their full content (examples, tables, code blocks) to maximize design-output
+# quality. This setting controls whether that extra spend is allowed globally.
+#
+# Values:
+#   on   — rich skills load in full (default; recommended for design-intensive workflows)
+#   off  — rich skills fall back to standard condensed behavior
+#   ask  — before loading a rich skill, the agent surfaces an estimated token
+#          delta (≈ file size in chars / 4, reported in tokens not dollars) and
+#          asks the user once; the answer is cached for the session
+#
+# Configurable in the browser setup wizard (Setup → Skills → Token budget).
+tokens:
+  rich_skills: on
+
 # --- Cost tracking + budget enforcement ---
 #
 # USD budgets evaluated against `agents/cost-tracking/sessions.jsonl` by
@@ -393,12 +411,81 @@ quality:
   #         themselves (default — saves agent runtime and tokens)
   wait_for_remote_ci: false
 
+# --- Design fidelity ---
+#
+# Controls how strictly the agent must follow a user-provided, finished
+# design — a prototype, mockup, screenshot, or design-system file. Consumed
+# by the `design-fidelity` rule. The provided design is the spec, not a
+# starting point for the agent's own taste.
+design:
+  # strict | structural | hard-floor  (default: strict)
+  #
+  # strict     = build it 1:1. EVERY visible deviation (font, control type,
+  #              component, layout, spacing, colour, an omitted/added element)
+  #              needs explicit confirmation. A "better" idea is surfaced as a
+  #              numbered option, never executed.
+  # structural = structure is locked (fonts, control types, component set,
+  #              layout, no omissions still need confirmation). Where the spec
+  #              is genuinely silent (hover / empty / error states), the agent
+  #              may fill the gap in the spec's style and MUST state the
+  #              assumption.
+  # hard-floor = any deviation is a Hard-Floor action (never autonomous; no
+  #              autonomy setting, roadmap, or standing instruction lifts it).
+  fidelity_mode: strict
+
 # --- Subagent orchestration ---
 #
-# Controls model selection and parallelism for subagent-based workflows
-# (/do-and-judge, /do-in-steps, /judge). Empty values fall back to the
-# runtime defaults described in .augment/contexts/subagent-configuration.md.
+# Controls model selection, parallelism, and AUTOMATIC orchestration for
+# subagent-based workflows (/do-and-judge, /do-in-steps, /judge, and the
+# auto-dispatch layer). Empty values fall back to the runtime defaults
+# described in .augment/contexts/subagent-configuration.md and
+# .augment/contexts/execution/auto-orchestration-activation.md.
 subagents:
+  # Global master switch for the whole subagent layer.
+  # true (default) = the layer is available; false = fully disabled, the
+  # canonical kill-switch (no auto-dispatch, no model routing, in-session only).
+  enabled: true
+
+  # Automatic-dispatch mode:  off | ask | on
+  #
+  # off = never auto-dispatch; subagents only via an explicit command.
+  # ask = classify the task; when delegable, ask once before dispatching.
+  # on  = auto-dispatch delegable tasks without asking (surface the choice
+  #       in one line).
+  #
+  # Initial SHIPPED default is `ask` on hosts whose capability manifest reports
+  # `subagent_spawn: true`, and `off` on hosts without a subagent primitive.
+  # The shipped default flips toward `on` (host-gated) only behind the Phase-6
+  # benchmark gate of road-to-auto-subagent-orchestration.md — never on an
+  # unmeasured claim. Auto-dispatch is also a no-op wherever the host manifest
+  # reports `subagent_spawn: false`, regardless of this value.
+  auto: ask
+
+  # Route delegable sub-tasks to the lowest-capable model tier (cost + speed
+  # via model downshift). true (default) = downshift per declared model_tier;
+  # false = every subagent runs on the session tier.
+  downshift: true
+
+  # Prefer a separate-quota-pool model for delegable sub-tasks WHERE the host
+  # manifest reports `separate_quota_pool: true` (e.g. a subscription whose
+  # Sonnet allowance is distinct from Opus). Optional bonus only — behaviour is
+  # identical (minus the quota win) where unsupported. Never load-bearing.
+  quota_arbitrage: true
+
+  # Optional per-tier model map for downshift routing. Empty value = use the
+  # tier's runtime default (see model-recommendations.md). Keys are the
+  # vendor-neutral capability bands.
+  model_map:
+    lite: ""
+    medium: ""
+    high: ""
+
+  # Optional host-capability override (see
+  # .augment/contexts/execution/host-capability-manifest.md). Any field set
+  # here wins; any field omitted falls back to the all-false safe default.
+  # Leave empty to let the agent resolve the manifest from host knowledge.
+  host_capabilities: {}
+
   # Model for implementer subagents (empty = same tier as the session model)
   implementer_model: ""
 
@@ -716,6 +803,19 @@ update_check:
 explain:
   enable_last: true
 
+# ─── legal-review-prep consent gate ──────────────────────────────────────────
+# The legal-review-prep pack is high-risk (EU/DE legal review-prep, NOT legal
+# advice). It stays inactive until you acknowledge it is not legal advice — set
+# by the setup wizard's consent checkbox, or here by hand. The legal-safety-floor
+# rule refuses every legal-review-prep skill until `acknowledged: true`.
+legal_review_prep:
+  acknowledged: false
+  consented_at: ""
+  # Gate legal work-product behind a multi-model council / deep-research pass
+  # (defense-in-depth + audit trail; fail-closed). Off lets single-model legal
+  # output through — not recommended for this high-risk pack.
+  require_council: true
+
 # ─── secrets ────────────────────────────────────────────────────────────────
 # Local-only secret material. This whole file is gitignored, so the key never
 # enters the tracked tree.

package/src/config/discovery/packs.yml

@@ -167,6 +167,7 @@
   workspaces: [finance, founder]
   trust_level_default: professional
   domain: finance
+  risk_class: medium   # advisory (finance-safety-floor): not-financial-advice disclaimer
   size_class: medium
   onboarding:
     first_win_doc: FIRST_WIN.md
@@ -180,6 +181,7 @@
   requires: [finance-basic]
   trust_level_default: core
   domain: finance
+  risk_class: medium   # advisory (finance-safety-floor)
   size_class: medium
 
 - id: gtm-sales
@@ -223,6 +225,7 @@
   trust_level_default: core
   domain: founder
   size_class: medium
+  risk_class: medium   # advisory (strategy-safety-floor)
   onboarding:
     first_win_doc: FIRST_WIN.md
     example_workflow: vision-articulation
@@ -240,6 +243,27 @@
   workspaces: [construction]
   trust_level_default: professional
 
+- id: legal-review-prep
+  label: Legal Review Prep
+  description: "NOT LEGAL ADVICE — a research/drafting aid to PREPARE for attorney review, not a substitute for a lawyer. EU/DE-scoped contract/NDA/DPA review and triage, procedure-only (no default legal positions); general information + templates only, never individual-case examination; every output a draft for attorney review. Opt-in + council-gated. See LEGAL_NOTICE.md."
+  workspaces: [legal-review-prep]
+  trust_level_default: experimental
+  surface_tier: lab
+  domain: legal
+  size_class: medium
+  # High-risk posture (road-to-legal-review-prep Phase 4). Documentation-first;
+  # enforcement lives in the legal-safety-floor rule + consent gate + lint.
+  risk_class: high
+  risk_profile: rdg_regulated_eu_de
+  requires_explicit_consent: true
+  requires_council: true
+  default_install: false
+  promotion_gate: attorney_framing_review
+  onboarding:
+    first_win_doc: FIRST_WIN.md
+    example_workflow: dpa-review
+    time_to_first_value_minutes: 8
+
 - id: ai-video
   label: AI Video
   description: AI video pipeline.

package/src/config/discovery/workspaces.yml

@@ -64,6 +64,13 @@
   default_packs: [construction]
   optional_packs: []
 
+- id: legal-review-prep
+  label: Legal Review Prep
+  description: In-house legal review-prep — EU/DE-scoped contract/NDA/DPA review and triage to PREPARE for attorney review. Not legal advice; opt-in + council-gated.
+  example_roles: [In-house Counsel, DPO, Legal Ops]
+  default_packs: [legal-review-prep]
+  optional_packs: []
+
 - id: agent-config-maintainer
   label: Maintainer
   description: Skills/rules/commands that maintain this package.

package/src/scripts/_lib/auto_dispatch.ts

@@ -0,0 +1,95 @@
+/**
+ * Auto-dispatch classification (v1 — deterministic).
+ *
+ * Pure, no-I/O encoding of the rule-based classifier described in
+ * `src/agent-src/contexts/execution/auto-dispatch-classification.md`.
+ *
+ * Decides whether a task is delegable to subagents and which
+ * `subagent-orchestration` mode fits — with NO per-turn LLM meta-call.
+ *
+ * Contract highlights:
+ * - A task is delegable only on an enumerated structural signal.
+ * - Trivial tasks below the size floor never delegate.
+ * - Ambiguity → `ask` (when `auto == 'ask'`) or in-session, never speculative
+ *   spawn.
+ * - The activation gate (`enabled`, `auto != off`, `subagent_spawn`) runs
+ *   first; any failure short-circuits to in-session.
+ */
+
+/** Minimum task-size estimate (exclusive) below which a task never delegates. */
+export const SIZE_FLOOR = 1;
+
+export type AutoMode = 'off' | 'ask' | 'on';
+export type DispatchMode = 'do-in-steps' | 'do-in-parallel';
+export type DispatchAction = 'dispatch' | 'ask' | 'in-session';
+
+/** Task descriptor — structural signals only, no task body. */
+export interface TaskSignals {
+    /** Frontmatter `parallelizable:` value of the skill/command in play, if any. */
+    parallelizable?: 'steps' | 'files' | 'independent' | null;
+    /** Task is an explicit ordered plan (numbered steps / phase / checklist). */
+    ordered_plan?: boolean;
+    /** Count of independent same-shape targets (e.g. 5 files to review). */
+    independent_slices?: number;
+    /** Orchestrator's pre-dispatch size estimate (abstract units). */
+    size_estimate: number;
+}
+
+/** Activation inputs resolved from settings + the host-capability manifest. */
+export interface ActivationInputs {
+    enabled: boolean;
+    auto: AutoMode;
+    subagent_spawn: boolean;
+}
+
+export interface Classification {
+    delegable: boolean;
+    action: DispatchAction;
+    mode: DispatchMode | null;
+    reason: string;
+}
+
+function inSession(reason: string): Classification {
+    return { delegable: false, action: 'in-session', mode: null, reason };
+}
+
+/**
+ * Classify a task for auto-dispatch. Activation gate first, then the
+ * deterministic delegable-signal rules.
+ */
+export function classifyTask(signals: TaskSignals, activation: ActivationInputs): Classification {
+    // ── Activation gate — any failure short-circuits to in-session ──
+    if (!activation.enabled) return inSession('subagents.enabled is false');
+    if (activation.auto === 'off') return inSession('subagents.auto is off');
+    if (!activation.subagent_spawn) return inSession('host has no subagent_spawn primitive');
+
+    // ── Size floor — trivial tasks never delegate ──
+    if (!(signals.size_estimate > SIZE_FLOOR)) {
+        return inSession(`task below size floor (${signals.size_estimate} <= ${SIZE_FLOOR})`);
+    }
+
+    // ── Delegable-signal rules (enumerated; ambiguity never spawns) ──
+    const slices = signals.independent_slices ?? 0;
+    let mode: DispatchMode | null = null;
+    let reason = '';
+
+    if (signals.parallelizable === 'steps' || signals.ordered_plan === true) {
+        mode = 'do-in-steps';
+        reason = signals.parallelizable === 'steps' ? 'declared parallelizable: steps' : 'ordered-plan structure';
+    } else if (signals.parallelizable === 'files' || signals.parallelizable === 'independent' || slices >= 2) {
+        mode = 'do-in-parallel';
+        reason = signals.parallelizable ? `declared parallelizable: ${signals.parallelizable}` : `independent slices (${slices})`;
+    }
+
+    if (mode === null) {
+        // No enumerated signal matched → ambiguous. Ask under `ask`, else in-session.
+        if (activation.auto === 'ask') {
+            return { delegable: false, action: 'ask', mode: null, reason: 'no delegable signal — borderline, ask' };
+        }
+        return inSession('no enumerated delegable signal matched');
+    }
+
+    // Matched a signal. Dispatch under `on`, ask under `ask`.
+    const action: DispatchAction = activation.auto === 'on' ? 'dispatch' : 'ask';
+    return { delegable: true, action, mode, reason };
+}