@event4u/agent-config 14.20.0 → 14.21.0

package/dist/scripts/ai_council/content_ceiling.js

@@ -0,0 +1,63 @@
+/**
+ * One binary content ceiling per seat — road-to-admissible-council-seats 2.2.
+ *
+ * Redaction today is a SECRETS floor and says so
+ * (`src/skills/ai-council/references/cost-and-redaction.md`). Nothing above it
+ * could express "this project's diff may not go to that seat", which is a
+ * different question with a different answer: a diff carrying no secret at all
+ * is still the consumer's private source.
+ *
+ * Deliberately BINARY. A graded scale invites a middle value nobody can define
+ * and every caller reads differently; two values force the decision at
+ * authoring time, where it belongs.
+ *
+ *   public-artifact  — repo-owned artefacts: skill descriptions, the trigger
+ *                      corpus, rule text, bench fixtures. Already public.
+ *   project-content  — everything a consumer supplies. The DEFAULT, so an
+ *                      unclassified payload is treated as private rather than
+ *                      as publishable.
+ *
+ * A seat's ceiling is the most sensitive class it may receive. `public-artifact`
+ * is therefore the NARROWER seat: it admits public artefacts only.
+ */
+export const CONTENT_CLASSES = ['public-artifact', 'project-content'];
+/** The default for anything not explicitly classified: private, not public. */
+export const DEFAULT_CONTENT_CLASS = 'project-content';
+/** The default seat ceiling: unchanged behaviour for every existing seat. */
+export const DEFAULT_SEAT_CEILING = 'project-content';
+const _SET = new Set(CONTENT_CLASSES);
+/**
+ * Any configured value → a content class. Unrecognised input becomes
+ * `project-content`, the RESTRICTIVE value: a typo must narrow what a seat may
+ * receive, never widen it.
+ */
+export function classifyContentClass(raw, fallback = DEFAULT_CONTENT_CLASS) {
+    if (typeof raw === 'string' && _SET.has(raw)) {
+        return raw;
+    }
+    return fallback;
+}
+/**
+ * Does a seat whose ceiling is `seatCeiling` admit a payload of `contentClass`?
+ *
+ * The one refusal is `project-content` into a `public-artifact` seat. Every
+ * other pairing is admitted, including public artefacts into a
+ * `project-content` seat — a seat cleared for private content is trivially
+ * cleared for public content, and refusing that would be a nonsense that
+ * disables the default seat for its own repo's fixtures.
+ *
+ * Refusal is a GREEN path (this roadmap's 2.2 verify): the caller drops the
+ * seat and the run continues. It is not an error, because a policy working as
+ * designed is not a failure.
+ */
+export function admitsContent(seatCeiling, contentClass) {
+    if (seatCeiling === 'public-artifact' && contentClass === 'project-content') {
+        return {
+            admitted: false,
+            reason: "seat ceiling is 'public-artifact'; the payload is classified " +
+                "'project-content' (consumer-supplied)",
+        };
+    }
+    return { admitted: true, reason: null };
+}
+//# sourceMappingURL=content_ceiling.js.map

package/dist/scripts/ai_council/seat_policy.js

@@ -0,0 +1,106 @@
+import { classifyContentClass as _classifyContentClass, DEFAULT_SEAT_CEILING as _DEFAULT_SEAT_CEILING, } from './content_ceiling.js';
+/**
+ * Seat policy — the vocabulary for refusing a route that IS reachable.
+ *
+ * road-to-admissible-council-seats 2.1. `AbsentReason` was exactly four values
+ * — `no_binary | no_auth | timeout | quota` — and every one of them means "the
+ * route is not reachable". A route that is reachable and **must not be used**
+ * had no name at all, so the resolver could not fail closed on terms, privacy,
+ * unproven cost, or a served model that is not the requested one. The absence
+ * of a word was the absence of the refusal: `resolveTransport`'s `api`/`cli`
+ * branches return `available: true` unconditionally, so anything the four
+ * reachability reasons could not express resolved OPEN.
+ *
+ * Fail closed on the unknown, which is the whole point.
+ * `classifyPolicyExclusion` maps anything it does not recognise to
+ * `policy_unknown`, and `policy_unknown` is an ABSENT reason like every other
+ * member of this union. An unrecognised policy token is the case where the
+ * config is trying to say something the code cannot understand; resolving it
+ * to "available" would make a typo an authorisation. This is the roadmap's own
+ * Risk 3 — "a new refusal vocabulary defaults open instead of closed".
+ *
+ * What this is NOT. It is not a secrets floor. Redaction (`skills/ai-council/references/
+ * cost-and-redaction.md`) still runs underneath and is not replaced. It is not
+ * an authorisation either: nothing here ever makes a seat available that was
+ * not already available — every value in the union only ever subtracts.
+ */
+/** Reachable-but-refused reasons. Every value means ABSENT. */
+export const POLICY_EXCLUSIONS = [
+    /** The provider's terms forbid this use of the route. */
+    'policy_terms',
+    /** A privacy constraint forbids sending to this route. */
+    'policy_privacy',
+    /** The route's cost property is asserted rather than proven. */
+    'policy_unproven_cost',
+    /** The route serves a model other than the one requested. */
+    'policy_model_mismatch',
+    /** 2.2 — the payload's content class exceeds the seat's ceiling. */
+    'policy_content_ceiling',
+    /** The config named an exclusion this build does not understand. */
+    'policy_unknown',
+];
+const _SET = new Set(POLICY_EXCLUSIONS);
+/** True for a value this build can act on. `policy_unknown` included: it is a
+ *  real, actionable verdict (refuse), not a parse failure. */
+export function isPolicyExclusion(v) {
+    return typeof v === 'string' && _SET.has(v);
+}
+/**
+ * Any configured value → a verdict. Unrecognised input, including `null` used
+ * where a string was meant, becomes `policy_unknown` — never `null`, because a
+ * `null` return would put the caller back in the position of deciding what an
+ * unreadable policy means, which is where the open default came from.
+ *
+ * `undefined` and `null` are the two ways of saying "no exclusion configured"
+ * and are the ONLY inputs that return `null`. Everything else is a refusal.
+ */
+export function classifyPolicyExclusion(raw) {
+    if (raw === undefined || raw === null) {
+        return null;
+    }
+    return isPolicyExclusion(raw) ? raw : 'policy_unknown';
+}
+/** One-line human reason for a refusal. `council:status` prints this. */
+export function policyExclusionReason(p, provider) {
+    const who = provider === undefined ? 'this seat' : provider;
+    switch (p) {
+        case 'policy_terms':
+            return `${who} is excluded by policy: the route's terms forbid this use`;
+        case 'policy_privacy':
+            return `${who} is excluded by policy: a privacy constraint forbids this route`;
+        case 'policy_unproven_cost':
+            return `${who} is excluded by policy: the route's cost property is asserted, not proven`;
+        case 'policy_model_mismatch':
+            return `${who} is excluded by policy: the route serves a model other than the one requested`;
+        case 'policy_content_ceiling':
+            return `${who} is excluded by policy: the payload exceeds the seat's content ceiling`;
+        case 'policy_unknown':
+            return `${who} is excluded by policy: an exclusion this build does not understand (failing closed)`;
+    }
+}
+export function parseSeatFields(name, raw) {
+    const dr = raw['disabled_reason'];
+    let disabled_reason = null;
+    if (dr !== undefined && dr !== null) {
+        if (typeof dr !== 'string' || dr.trim() === '') {
+            return {
+                error: `members.${name}.disabled_reason must be a non-empty string when set ` +
+                    `(got ${JSON.stringify(dr)}).`,
+            };
+        }
+        disabled_reason = dr.trim();
+    }
+    // Both of the next two fail CLOSED on an unreadable value: an unknown
+    // exclusion token becomes `policy_unknown` (which resolves ABSENT) and an
+    // unknown ceiling falls back to the RESTRICTIVE one. Throwing instead would
+    // be defensible, but a config typo would then take the whole council down
+    // rather than the one seat it names.
+    return {
+        fields: {
+            disabled_reason,
+            policy_exclusion: classifyPolicyExclusion(raw['policy_exclusion']),
+            content_ceiling: _classifyContentClass(raw['content_ceiling'], _DEFAULT_SEAT_CEILING),
+        },
+    };
+}
+//# sourceMappingURL=seat_policy.js.map

package/dist/scripts/ai_council/transport_resolver.js

@@ -40,6 +40,8 @@
  */
 import { classifyBilling, isCommunityCli, strongestAuth, PROVIDER_CLI_META, } from '../_lib/environment_detector.js';
 import { resolve_mode } from './modes.js';
+import { admitsContent, DEFAULT_SEAT_CEILING, } from './content_ceiling.js';
+import { policyExclusionReason } from './seat_policy.js';
 /** The accepted values of the `mode` key, including the resolver-only `auto`. */
 export const VALID_TRANSPORT_MODES = new Set([
     'api',
@@ -84,6 +86,22 @@ export function resolveTransport(opts) {
     const auth = strongestAuth(report, provider);
     const authSource = auth?.source ?? null;
     const billing = classifyBilling(provider, authSource);
+    // Policy first (2.1). Before the mode dispatch, because `api` and `cli`
+    // below return `available: true` UNCONDITIONALLY — a refusal placed after
+    // them would be unreachable for exactly the seats it exists to stop.
+    const exclusion = opts.policyExclusion ?? null;
+    if (exclusion !== null) {
+        return unavailable(provider, billing, policyExclusionReason(exclusion, provider), exclusion);
+    }
+    // Content ceiling (2.2). Only runs when the caller declared what it would
+    // send; an undeclared pass is unchanged, not silently refused.
+    const contentClass = opts.contentClass ?? null;
+    if (contentClass !== null) {
+        const verdict = admitsContent(opts.seatCeiling ?? DEFAULT_SEAT_CEILING, contentClass);
+        if (!verdict.admitted) {
+            return unavailable(provider, billing, `${provider}: ${verdict.reason ?? 'content ceiling refused the payload'}`, 'policy_content_ceiling');
+        }
+    }
     if (mode === 'manual') {
         return {
             available: true,
@@ -173,6 +191,9 @@ export function resolveMemberTransport(opts) {
         // optional-boolean field, so the key is omitted entirely rather than
         // forwarded as `apiKeyPresent: undefined`.
         ...(opts.apiKeyPresent !== undefined ? { apiKeyPresent: opts.apiKeyPresent } : {}),
+        policyExclusion: opts.policyExclusion ?? null,
+        seatCeiling: opts.seatCeiling ?? null,
+        contentClass: opts.contentClass ?? null,
     });
     return { ...resolved, configuredMode };
 }

package/llms.txt

@@ -37,11 +37,11 @@ brand-strategy: Ground a brand strategy from the corpus — archetype, opposable
 brand-to-tokens: Turn a confirmed brand identity into a DTCG .tokens.json source of truth — emit CSS vars + Tailwind via design-tokens, export locked brand deck templates.
 bug-analyzer: Use when the user shares a Sentry error, Jira bug ticket, or error description and wants root cause analysis. Also for proactive bug hunting and code audits for hidden bugs.
 build-buy-partner: Use when deciding insource vs outsource vs acquire — integration-cost analysis, dependency-risk, optionality preservation. Triggers on 'should we build', 'buy vs partner'.
-canvas-design: Use when creating static visual art — posters, marketing visuals, brand assets, PDF/PNG design pieces — even if the user just says 'design a poster' or 'mach uns ein Visual'.
+canvas-design: Creating static visual art — posters, marketing visuals, brand assets, PDF/PNG design pieces — on 'design a poster' or 'mach uns ein Visual'. Grounded by design-intelligence.
 character-consistency: Use when a character must stay visually identical across AI video scenes — locks identity tokens (silhouette, palette, wardrobe, prop) in JSON. Triggers 'character lock', 'same character'.
 check-refs: Use when verifying cross-references between skills, rules, commands, guidelines, and context documents are not broken after edits, renames, or deletions.
 churn-prevention: Use when designing churn defence — health-score signals, churn-cause split (involuntary / value / relationship / fit), early-warning loop. Triggers on 'why are accounts leaving'.
-code-intelligence: Route codebase-structure questions (who calls X, where used, what imports, change-impact) to a code-graph first, grep fallback. Triggers 'who calls', 'where is this used', 'call graph'.
+code-intelligence: Route codebase-structure questions (who calls X, where is this used, what imports, change-impact) to an existing code-graph first: cheaper, never more precise; grep stays routine. Also 'call graph'.
 code-refactoring: When the user says 'refactor this', 'rename class', or 'move method'. Safely refactors code in any language — finds all callers, updates downstream dependencies, verifies via quality tools.
 code-review: Use when the user says \"review this\", \"check my code\", or wants feedback on changes. Reviews for correctness, quality, security, and coding standards.
 command-routing: Use when the user invokes a slash command like /create-pr, /commit, /fix-ci, or pastes command file content — routes to the right command with context inference and GitHub API patterns.
@@ -57,7 +57,7 @@ context-authoring: Use when filling knowledge-layer context files — auth-model
 context-document: Use when the user says \"create context\", \"document this area\", or wants a structured snapshot of a codebase area for agent orientation.
 contract-review: Use when reviewing a contract clause-by-clause from your party's side — buyer/seller/vendor/licensee. Triggers on 'review this contract', 'redline this MSA', 'is this clause a problem'.
 contracts-cognition: Use when reading a contract for risk and constraint — clause shape, redline priority, what the contract actually binds. Triggers on 'review this contract', 'what does this MSA constrain'.
-conventional-commits-writing: When writing commit messages or squash-merge titles — `feat:`, `fix:`, `chore:`, scopes, breaking changes — even when the user just says 'commit this' without naming Conventional Commits.
+conventional-commits-writing: When writing a commit message, branch name or squash title — measure the repo's own convention first, Conventional Commits as fallback — even on a bare 'commit this'.
 copilot-agents-optimization: Use when optimizing AGENTS.md or copilot-instructions.md — deduplicates against .augment/ content, enforces line budgets, and focuses each file on its audience.
 copilot-config: Tune the GitHub Copilot AI — `copilot-instructions.md`, PR-review patterns, suggestion behavior, output verbosity. NOT for dev-environment setup (use `devcontainer`).
 corpus-grounding: Shared corpus-grounding engine — BM25 + structured filters + decision rules over CSV corpora via a domain manifest. Use when a skill needs grounded pre-action option-space constraints.
@@ -74,11 +74,11 @@ deep-reading-analyst: Deep analysis of articles/long-form via thinking framework
 defense-in-depth: Use when validation needs entry, business-logic, environment, and instrumentation guards so a bad value cannot reach the failure point — turns a local bug fix into a structural one.
 dependency-upgrade: Use when upgrading dependencies — 'update framework X', 'bump runtime version', or 'upgrade packages'. Covers changelog review, breaking-change detection, and verification. Stack-agnostic.
 description-assist: Use when polishing a skill/rule/command/guideline frontmatter description — pushier phrasing, trigger coverage, undertrigger audit — even if the user just says 'make this pushier'.
-design-intelligence: Grounded design brief from the adopted corpus — style, WCAG-checked color tokens, typography, layout pattern, anti-patterns. Use on ui-design-brief or any which-style/palette/font/chart decision.
-design-review: When the user says \"review the design\", \"check the UI\", or wants a comprehensive UI/UX review. Uses a 7-phase methodology covering interaction, responsiveness, accessibility and more.
+design-intelligence: Grounded design brief from the corpus — style, WCAG color tokens, typography, layout, anti-patterns. Use on ui-design-brief or any which-style/palette/font/chart call; feeds fe-design.
+design-review: When the user says \"review the design\", \"check the UI\", or wants a comprehensive UI/UX review. 7 phases: interaction, responsiveness, accessibility. Inventory via existing-ui-audit.
 design-system-capture: Write and maintain DESIGN.md + PRODUCT.md — captures visual decisions and interaction patterns so design tasks stay consistent across sessions without re-scanning past work.
 design-tokens: Author a 3-layer DTCG token system (primitive → semantic → component) with light/dark theming; generate CSS vars + Tailwind colors and lint hardcoded values. Use on design tokens / CSS variables.
-design-variations: Produce 3+ substantively distinct hi-fi design variations — basic to bold, one file with tweak controls — when the user asks for options, alternatives, or \"show me a few takes\".
+design-variations: Produce 3+ distinct hi-fi design variations — basic to bold, one file with tweak controls — when the user asks for options, alternatives, \"show me a few takes\". Extends fe-design.
 devcontainer: Wire up DevContainers / GitHub Codespaces — `devcontainer.json`, container images, secrets, VS Code features, port forwarding. NOT for tuning Copilot itself (use `copilot-config`).
 developer-like-execution: Use when implementing, debugging, refactoring, or reviewing code — enforces the think → analyze → verify → execute workflow — even when the user just says 'implement X' without naming it.
 discovery-interview: When running discovery interviews — question-bank build, bias audit, insight extraction. Triggers on 'audit my guide', 'extract insights from transcript', 'is my hypothesis falsifiable'.
@@ -92,10 +92,10 @@ emit-tickets: Use when materialising a roadmap into a ticket bundle — 'turn th
 error-handling-patterns: Use when picking a failure-reporting strategy — exceptions vs Result types, recoverable vs not, retry / circuit-breaker / graceful degradation — decision framework only, catalogues externalized.
 "estimate-ticket": Estimate a Jira/Linear ticket — 'estimate PROJ-123', 'wie groß ist das?', 'should we split this?' — size + risk + split + uncertainty, sibling of /refine-ticket, close-prompt.
 evaluate-llm-feature: Black-box evaluation of a shipped LLM feature — adversarial probes for hallucination, prompt-injection, and cost-runaway vs stated expectations. Not RAG/embedding. Triggers 'review my chatbot'.
-existing-ui-audit: Use BEFORE writing or editing any non-trivial UI — inventories components, design tokens, shadcn primitives, and reusable patterns into state.ui_audit. Hard gate for the ui directive set.
+existing-ui-audit: Use BEFORE writing or editing any non-trivial UI — inventories components, design tokens, shadcn primitives, and reusable patterns into state.ui_audit. Hard gate for fe-design.
 expansion-playbook: Use when designing account-expansion mechanics — upsell vs cross-sell, expansion-trigger signals, NRR cognition. Triggers on 'lift NRR', 'when do we upsell vs cross-sell'.
 experiment-loop: Use to drive a scalar metric down or up across bounded iterations — keep on strict improvement, revert otherwise, state on disk. Triggers 'minimize X', 'optimize until it stops improving'.
-fe-design: Frontend design heuristics — and, outside the ticket engine, the loop that applies them: audit, brief, inventory, build, review. Use when building or changing any UI, not only when planning one.
+fe-design: Frontend design heuristics and the loop applying them: existing-ui-audit, brief, inventory, build, review. Use when building or changing any UI, not only when planning one.
 feature-planning: Use when the user says \"plan a feature\", \"brainstorm\", \"explore this idea\", or wants to go from idea to structured plan and roadmap.
 file-editor: Use when opening edited files in the user's IDE. Reads settings from .agent-settings.yml to determine IDE and whether auto-open is enabled.
 finishing-a-development-branch: Use when the feature is implementation-complete and the next step is 'ship it' — verifies, cleans up, routes to merge/PR/park/discard; never destroys work without explicit confirmation.
@@ -225,7 +225,7 @@ prompt-optimizer: When the user wants a prompt optimized for ChatGPT, Claude, Ge
 prompt-validator: Pre-spend contradiction gate for AI-video runs: checks every prompt in the batch, blocks on style / character / physics mismatch. Triggers 'validate the prompts', 'check the storyboard'.
 quality-tools: Use when PHPStan, Rector, or ECS output appears — \"phpstan says mixed\", type errors, \"fix code style\", \"run rector\" — even when Eloquent/Laravel/model code is also mentioned.
 react-native-setup: Use when setting up React Native or Expo dev environments — Xcode, Android Studio, CocoaPods, EAS, Metro, New Architecture — even when the user just says 'my RN build won't start'.
-react-shadcn-ui: Use when building React UI on shadcn/ui primitives + Tailwind — the apply/review/polish skill dispatched by `directives/ui/*` for the `react-shadcn` stack.
+react-shadcn-ui: Building React UI on shadcn/ui primitives + Tailwind — the apply/review/polish skill dispatched by `directives/ui/*` for the `react-shadcn` stack; idiom from tailwind-engineer.
 readme-reviewer: Use when reviewing a README for accuracy, usability, and alignment with the actual repository. Detects invented content, broken setup steps, and structural issues.
 readme-writing: Use when creating, rewriting, or significantly improving a README based on the actual repository structure, commands, and intended audience.
 readme-writing-package: Use when creating or rewriting a README for a reusable package or library. Focus on installability, minimal usage example, compatibility, and developer onboarding.
@@ -275,22 +275,22 @@ subagent-orchestration: Use when orchestrating implementer/judge subagents — f
 supply-chain-intake: Before adding/installing any dependency the agent named — verify the package exists (slopsquatting: ~1 in 5 AI suggestions are hallucinated), isn't typo-adjacent, is pinned + locked, and CVE-scanned
 symfony-workflow: Writes Symfony PHP — DI container, bundles, Doctrine, Messenger, Security voters, console commands. For Laravel / Eloquent / Artisan use `laravel`. For framework-free PHP use `php-coder`.
 systematic-debugging: Use on a bug, test failure, crash, or unexpected behavior — enforce reproduce → isolate → hypothesize → verify before any fix; fires even on 'this is broken' / 'quick fix'.
-tailwind-engineer: Use when writing or reviewing Tailwind CSS — utility-first, design-token discipline, no inline-style drift, responsive variants, dark mode — even on 'style this' or 'mach das hübsch'.
+tailwind-engineer: Writing or reviewing Tailwind CSS — utility-first, design tokens, no inline-style drift, responsive variants, dark mode — 'style this' or 'mach das hübsch'. Pairs with react-shadcn-ui.
 tech-debt-tracker: Use when surfacing tech debt as trackable items — interest-vs-principal framing, prioritisation by carrying cost, repayment plan — even if the user just says 'this codebase is a mess'.
 technical-specification: Use when the user says \"write a spec\", \"create RFC\", \"write a PRD\", or \"document this decision\". Writes technical specifications, PRDs, RFCs, and ADRs with clear structure.
 terraform: Use when writing Terraform — AWS modules, resources, variables, outputs, remote state — even when the user just says 'provision this infra' or 'add an S3 bucket' without naming Terraform.
 terragrunt: Use when working with Terragrunt — DRY multi-env configs, module dependencies, remote state orchestration — even when the user just says 'deploy this to staging and prod' without naming Terragrunt.
 test-case-discovery: Use BEFORE writing any test — enumerate cases per behavior (happy / boundary / error / abuse), prioritize by likelihood × impact, cross-check via subagent — even if the user just says 'add tests'.
-test-driven-development: Use when implementing a feature, fixing a bug, or refactoring — write the failing test first, then the code, even on 'add this function'. Owns the ORDER; test shape is `testing-anti-patterns`.
+test-driven-development: Implementing a feature, fixing a bug, refactoring — failing test first, then the code. For a WRONG test, `testing-anti-patterns` wins.
 test-performance: Use when optimizing test suite performance — database setup, seeder optimization, parallel testing, CI pipeline efficiency, or RefreshDatabase alternatives.
-testing-anti-patterns: Use BEFORE writing/changing tests or adding mocks — mocking-the-mock, production pollution, overfit assertions — even on 'is this test any good?'. Test SHAPE; the order is `test-driven-development`.
+testing-anti-patterns: BEFORE writing/changing tests, mocks, or test-only methods on production classes — mocking-the-mock, production pollution, overfit assertions; for order, `test-driven-development` wins.
 threat-modeling: Use when adding auth, webhooks, uploads, queues, secrets, tenant boundaries, or public endpoints — produces trust boundaries + abuse cases mapped to files, BEFORE implementation.
 throughput-vs-morale-tradeoff: Use when balancing eng-team velocity vs quality vs burnout — on-call load, focus fragmentation, reorg shock. Triggers on 'team is burning out', 'why is velocity dropping'.
 token-optimizer: Use BEFORE any verbose CLI run, large file read, doc conversion, or near-context handoff — decision tree keyed by intent citing the canonical token-saving asset.
 traefik: Use when setting up Traefik as a local reverse proxy — real domains on 127.0.0.1, trusted HTTPS via mkcert, automatic service discovery, and multi-project routing.
 typography-system: Derive a type system from a style constraint — font pairings, scale/line-height/weights, DTCG tokens via design-tokens. Use to choose fonts or build a typographic scale.
-ui-apply-generic: Use when implementing a UI brief on a stack with no framework executor — Svelte, Astro, Angular, plain HTML. Carries the stack-independent contract; idiom comes from the stack corpus.
-ui-component-architect: Use when shaping a UI component tree — composition vs inheritance, slot patterns, prop API design, controlled vs uncontrolled, polymorphic — even on 'split this component'.
+ui-apply-generic: Use when implementing a UI brief on a stack with no framework executor — Svelte, Astro, Angular, plain HTML. Stack-independent sibling of react-shadcn-ui; idiom from the stack corpus.
+ui-component-architect: Shaping a UI component tree — composition vs inheritance, slot patterns, prop API design, controlled vs uncontrolled, polymorphic — on 'split this component'. Feeds react-shadcn-ui.
 unit-economics-modeling: Use when modeling CAC, LTV, payback, contribution margin, or burn-multiple per customer — SaaS, marketplace, or transactional. Triggers on 'are we unit-economic', 'what is our LTV/CAC'.
 universal-project-analysis: Deep multi-pass codebase audit — orchestrates project-analysis-core plus the framework-specific project-analysis-*; explicit request only. Single-pass scan → project-analyzer.
 upstream-contribute: Use when a learning, new skill, rule improvement, or bug fix from a consumer project should be contributed back to the shared agent-config package.

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@event4u/agent-config",
     "mcpName": "io.github.event4u-app/agent-config",
-    "version": "14.20.0",
+    "version": "14.21.0",
     "description": "Governed skills, rules and commands for AI coding tools (Claude Code, Cursor, Windsurf, Copilot) — every claim machine-checked, including the counts in these badges.",
     "license": "MIT",
     "private": false,

package/src/config/gate-violation-baselines.json

@@ -34,9 +34,9 @@
       "note": "The nine active non-draft roadmaps that predate the `relates:` requirement (road-to-agentic-engineering-assurance, road-to-component-library-lifecycle, road-to-council-evidence-integrity, road-to-frontend-fidelity-calibration, road-to-monorepo-scope-and-detection, road-to-observability-plate, road-to-role-scoped-spawn-profiles, road-to-skill-delivery-over-mcp, road-to-standing-payload-diet). This is a NEW obligation rather than a repaired scan root, and the ratchet is the point: `depends:` shipped in the template with nothing requiring it and measured 0 adoption, so requiring `relates:` retroactively across the estate would be an owner-reserved write with no analysis behind the edges it would have to invent (held as step 4.3, deferred). Clearing an entry here is one roadmap at a time: run `agent-config roadmap:context` on it, write the rows the probe surfaces, and lower the count."
     },
     "check_source_size_budget": {
-      "count": 18062,
-      "landed": "2026-09-06",
-      "note": "Lowered 18,068 -> 18,062 on 2026-09-06 by drain/host-enforcement-truth. Collapsing the five per-host binding constants in install.ts into src/scripts/hooks/host_lowering.yaml removed 29 lines from a file ~3,900 past the 1500 cap, where every line costs one excess; the journal's surface column and its extracted migration helper gave 23 back. Lowered 18,245 -> 18,230 on 2026-09-02 by drain/publication-integrity-option-a. Phase 2 Option A moved the authoring instruction out of the generator: release.ts, which sits ~530 lines PAST the 1500 cap so every line there costs one excess, loses the comment emission, a 16-line HEAD_DEFAULT doc block and its alias const, and gains a shorter writer docstring. The doc block moved to _lib/release_material.ts, which is 289 lines and therefore UNDER the cap, so the same prose now costs nothing. Net -15. The branch first came in at +8 and paid its own way down rather than raising the baseline.",
+      "count": 18016,
+      "landed": "2026-09-07",
+      "note": "MERGE RECONCILIATION 2026-09-07, 18,061/18,017 -> 18,016. drain/admissible-council-seats and fix/release-obligation-answerable each lowered from the SAME 18,062 base in parallel — main to 18,061 (net -1: curlJsonPost, the seat-status helpers and the per-seat config parsing moved out of the three over-ceiling council files) and the branch to 18,017 (net -45: the /dev/tty prompt helpers moved out of release.ts into _lib/tty_prompt.ts, 76 lines and UNDER the cap, taking release.ts 1871 -> 1826). Taking either side alone is wrong in a different direction, which is the reconciliation doctrine this entry already carried from 2026-09-03: main's value silently discards the branch's earned -45, and the branch's value RAISES the baseline against main and weakens the gate. The committed number is neither — it is the gate's own output on the MERGED tree, where both reductions apply, and it equals the arithmetic (18,062 - 45 - 1 = 18,016) rather than being reconciled by it. LOCAL READING, ADMISSIBLE ON THIS ENTRY'S OWN DISCRIMINATOR: the gate walks only SOURCE_ROOTS=['src'] counting excess over the 1500-line ceiling, and `git status --porcelain -uall -- src/` reports ZERO untracked files, so a clean CI checkout of this commit measures the same 18,016. If CI reads anything else, CI's number is the correct one and this note is the record of why. Carried in the merge commit because tests/scripts/check_source_size_budget.test.ts asserts baseline == live and therefore BLOCKS where the gate only advises. PRIOR ENTRY: Lowered 18,062 -> 18,061 on 2026-09-07 by drain/admissible-council-seats. The branch's own additions to the three over-ceiling files (ai_council/config.ts, council_cli.ts, ai_council/clients.ts) came in at +96 excess and were paid down to -1 rather than baselined, in the four ways this entry's doctrine prescribes: `curlJsonPost` moved out of clients.ts into ai_council/api_transport.ts (UNDER the cap, so the prose and the three new provider shims cost nothing); the seat-status helpers moved out of council_cli.ts into ai_council/status_surface.ts, taking an orphaned doc comment with them; the three new per-seat config fields' parsing moved out of config.ts into ai_council/seat_policy.ts::parseSeatFields; and three prose blocks that the branch's own transport repair made FACTUALLY FALSE (the `openai` / `google-genai` Python-SDK claims, and a `_curlJsonPost` pointer to a function that had moved) were corrected and shortened in the same change. LOCAL READING, ADMISSIBLE ON THIS ENTRY'S OWN DISCRIMINATOR: the gate walks only SOURCE_ROOTS=['src'] counting excess over the 1500-line ceiling, and `git status --porcelain -uall -- src/` reports zero untracked files with the five new src/ files staged, so a clean CI checkout of this commit measures the same 18,061. If CI reads anything else, CI's number is the correct one and this note is the record of why. Carried here because tests/scripts/check_source_size_budget.test.ts:166 asserts baseline == live and therefore blocks where the gate only advises -- the lowering commit must carry its own baseline update. Lowered 18,068 -> 18,062 on 2026-09-06 by drain/host-enforcement-truth. Collapsing the five per-host binding constants in install.ts into src/scripts/hooks/host_lowering.yaml removed 29 lines from a file ~3,900 past the 1500 cap, where every line costs one excess; the journal's surface column and its extracted migration helper gave 23 back. Lowered 18,245 -> 18,230 on 2026-09-02 by drain/publication-integrity-option-a. Phase 2 Option A moved the authoring instruction out of the generator: release.ts, which sits ~530 lines PAST the 1500 cap so every line there costs one excess, loses the comment emission, a 16-line HEAD_DEFAULT doc block and its alias const, and gains a shorter writer docstring. The doc block moved to _lib/release_material.ts, which is 289 lines and therefore UNDER the cap, so the same prose now costs nothing. Net -15. The branch first came in at +8 and paid its own way down rather than raising the baseline.",
       "reason": "Lowered 18,230 -> 18,209 on 2026-09-03 by drain/artifact-location. `doctor --strict` needed 16 lines of integration wiring in cmd_doctor.ts, which sits ~2,100 lines PAST the 1500 cap so every line there costs one excess. The branch first came in at +137 and paid its own way down rather than raising the baseline: the strict semantics, threshold, kill switch, payload helper and argv fragments moved to _cli/_doctor_strict.ts (~160 lines, under the cap, costs nothing), taking it to +15; then the 37-line drift renderer moved to _cli/_doctor_emit.ts. Net -21. The renderer was chosen deliberately: pure rendering, two dependencies, no argparse involvement and therefore none of the byte-parity risk the parser surface carries against the retired Python implementation; nothing outside cmd_doctor.ts imported it. An AI council on the residual split (a: raise by 15 / d: descope the feature); neither was taken, because a parallel branch demonstrated the same day that paying down is achievable in this codebase, which is the evidence the split lacked. This gate's own test comment prescribes it: a commit that splits a god-file lowers the excess and must carry the lowered baseline. MERGE RECONCILIATION 2026-09-03, 18,209 -> 18,205: drain/wired-instruments and drain/artifact-location each lowered from the SAME 18,230 base in parallel -- the branch to 18,226 (net -4, run_continuation_hook.ts's termination ladder moved to _lib/continuation_ladder.ts and runtime_journal.ts's prose to _lib/outcome_vocabularies.ts, both under the cap) and main to 18,209 (net -21, the doctor --strict split above). Taking either side alone is wrong in a different direction: main's value silently discards the branch's earned -4, and the branch's value RAISES the baseline against main and weakens the gate. The committed number is neither -- it is the gate's own output on the merged tree, where both reductions apply. THIS LOCAL READING IS ADMISSIBLE HERE, and the discriminator matters because this file's ci-parity:local-only entry records a 165 -> 164 lowering that was reverted for exactly the opposite case: that count depends on how the environment resolves the projection surface, whereas this gate walks only SOURCE_ROOTS = ['src'] (check_source_size_budget.ts:88) counting excess lines over the 1500 ceiling, and `git status --porcelain -uall -- src/` reported ZERO untracked files, so a clean CI checkout of this commit measures the same 18,205. If CI reads anything else, CI's number is the correct one and this note is the record of why. LOWERED 18,205 -> 18,193 on 2026-09-03 by fix/release-curation-ask. The change adds a fifth publication guard, and its own additions landed at +10 excess: release.ts 2,008 -> 2,018, every line of which is past the 1500 cap. Paid down rather than baselined, in the two ways this gate's doctrine prescribes. The guard's rationale (~13 lines of docstring, including why prMerged is a parameter rather than a call-site if) lives in release_publication.ts, 915 lines and therefore UNDER the cap, so the prose costs nothing; and the two pure text helpers _splitlines and _rstrip moved out of release.ts into release_env.ts (333 lines, also under the cap), taking release.ts to 1,996 -- 12 BELOW where it started. The branch came in at +10 and leaves at -12. Recorded while moving them: _splitlines is duplicated a third and fourth time at adoption_report.ts:106 and readme_linter.ts:418; collapsing all three onto one definition touches three modules and was left out of this change rather than done silently. LOWERED 18,193 -> 18,180 on 2026-09-03 by fix/release-branch-reuse. The step-1 branch decision -- twenty lines of if/else in release.ts -- became one call to checkout_release_branch in release_publication.ts, which is 1,019 lines and therefore UNDER the 1500 cap, so the twenty lines plus a ~35-line rationale now cost nothing. release.ts 1,996 -> 1,983, every one of those lines being past the cap. The drill grew 765 -> 918 for two new scenarios and the snapshot/restore that keeps them from writing the real CHANGELOG, and it is under the cap too. A change that adds a feature and lowers the excess is the shape this gate's doctrine asks for; the alternative was a +13 raise for logic that had no business in the god-file. LOWERED 18,180 -> 18,068 on 2026-09-05 by fix/release-gate-producer-parity. The change wires the governance-mix obligation into the writer and the two local guards and adds a release-gate locality registry; its own additions to release.ts landed at +19 excess, every one of those lines past the 1500 cap. Paid down rather than baselined, in the way this entry's doctrine prescribes: the 132-line test-count-trend unit (_TEST_COUNT_LINE_RE, _TEST_LIST_MAX_BUFFER, _count_from_list_result, _count_tests_current, _previous_test_count_from_changelog, _render_test_trend_line) moved from release.ts into release_publication.ts, which is under the cap and where it now belongs on merit rather than only on arithmetic -- the same diff makes the missing `Tests: N` footer a section-level publication blocker, so the writer that emits the footer and the guard that refuses its absence sit in one module. release.ts 1,983 -> 1,871. All four names are re-exported from release.ts, so tests/scripts/release.test.ts is unchanged. LOCAL READING, ADMISSIBLE ON THIS ENTRY'S OWN DISCRIMINATOR: the gate walks only SOURCE_ROOTS=['src'] counting excess over the ceiling, and `git status --porcelain -uall -- src/` reports ZERO untracked files with the two new src/ files staged, so a clean CI checkout of this commit measures the same 18,068. If CI reads anything else, CI's number is the correct one and this note is the record of why."
     },
     "ci-parity:local-only": {

package/src/config/release-gate-locality.yml

@@ -90,9 +90,10 @@ jobs:
     guard: ~
 
   highlight-plausibility:
-    # The job that failed 14.17.0. All four sub-checks (authoring instruction,
-    # unrewritten derived marker, `_none_` contradiction, governance-mix
-    # response) run locally from local tags alone — no origin, no HEAD_REF.
+    # The job that failed 14.17.0. All three sub-checks (authoring instruction,
+    # unrewritten derived marker, `_none_` contradiction) run locally from local
+    # tags alone — no origin, no HEAD_REF. It was four until ADR-261 deleted the
+    # governance-mix written answer and its promise read-back.
     local: './scripts-run src/scripts/check_release_highlights --version ${VERSION}'
     verify: true
     script: src/scripts/check_release_highlights.ts

package/src/scripts/_lib/blocked_by_marker.ts

@@ -0,0 +1,189 @@
+/**
+ * Ask before park — the inline `blocked-by:` marker, and the decision that must
+ * precede writing one.
+ *
+ * road-to-asked-not-parked Phase 3. `terminal-states.md` defines `blocked` to
+ * include "a decision only the user can make", and `roadmap-process-loop.md`
+ * writes and reads the inline marker with NO ask in between. The result is a
+ * decision the user never sees: it is filed, correctly labelled, in a file
+ * nobody is watching.
+ *
+ * This module is the executable half of the fix. It answers two questions and
+ * nothing else:
+ *
+ *   1. Given a context — is the host interactive, was the question put, was it
+ *      answered, did it time out — what does the run DO? ({@link decideAsk})
+ *   2. What does the marker then look like? ({@link renderBlockedByMarker})
+ *
+ * The obligations it encodes:
+ *
+ * - On an interactive host a user-decision block is PUT TO THE USER FIRST. Only
+ *   a decline, a timeout, or a non-interactive context writes a marker.
+ * - A TIMEOUT IS NOT CONSENT, and neither is a non-interactive context. Where
+ *   the ask cannot be completed the run ends `approval-required` — a state
+ *   `terminal-states.md` already defines — carrying the unanswered question
+ *   verbatim and its conservative default UNADOPTED. Nothing here ever returns
+ *   the default as an answer.
+ * - The marker records WHETHER the question was put, and when it was not, WHY.
+ *   `asked: no` with no reason is not a legal marker: the whole point is that a
+ *   later reader can tell a decision that was declined from one that was never
+ *   offered.
+ */
+import type { RunTerminalState } from './outcome_vocabularies.js';
+
+/** A parsed inline `<!-- blocked-by: … -->` marker. */
+export interface BlockedByMarker {
+    /** The blocker id the marker points at. */
+    readonly id: string;
+    /** Whether the question was put to the user. `null` when the marker predates the field. */
+    readonly asked: boolean | null;
+    /** Why it was not put. Required whenever `asked` is `false`. */
+    readonly reason: string | null;
+}
+
+/**
+ * The marker grammar, extended with an optional `| asked: …` tail.
+ *
+ * The tail is OPTIONAL in the grammar and required by the linter for the
+ * user-decision class only. Parsing and policy are separated on purpose: a
+ * parser that rejects the old shape would make every archived roadmap
+ * unreadable, which is a migration, not a fix.
+ */
+export const BLOCKED_BY_MARKER_RE =
+    /<!--[ \t]*blocked-by:[ \t]*([a-z0-9-]+)[ \t]*(?:\|[ \t]*asked:[ \t]*(yes|no)[ \t]*(?:[—-][ \t]*([^>]*?))?[ \t]*)?-->/i;
+
+/** Parse one marker, or `null` when the text carries none. */
+export function parseBlockedByMarker(text: string): BlockedByMarker | null {
+    const m = BLOCKED_BY_MARKER_RE.exec(text);
+    if (m === null) {
+        return null;
+    }
+    const asked = m[2] === undefined ? null : m[2].toLowerCase() === 'yes';
+    const reason = m[3] === undefined || m[3].trim() === '' ? null : m[3].trim();
+    return { id: (m[1] as string).toLowerCase(), asked, reason };
+}
+
+/** Render a marker. Throws on `asked: no` with no reason — the state the field exists to prevent. */
+export function renderBlockedByMarker(marker: BlockedByMarker): string {
+    if (marker.asked === null) {
+        return `<!-- blocked-by: ${marker.id} -->`;
+    }
+    if (marker.asked) {
+        return `<!-- blocked-by: ${marker.id} | asked: yes -->`;
+    }
+    const reason = (marker.reason ?? '').trim();
+    if (reason === '') {
+        throw new Error(
+            `blocked-by marker for '${marker.id}': asked: no needs a reason — ` +
+                'a marker that does not say why the question was not put is the parking ' +
+                'lot this field exists to end',
+        );
+    }
+    return `<!-- blocked-by: ${marker.id} | asked: no — ${reason} -->`;
+}
+
+/** What the run knows when it reaches a step blocked on a user decision. */
+export interface AskContext {
+    /** The blocker id. */
+    readonly id: string;
+    /** The question, in the words it would be put in. */
+    readonly question: string;
+    /** The conservative option, named so a reader can see what was NOT adopted. */
+    readonly conservativeDefault: string;
+    /** Can this run reach the user at all? */
+    readonly interactive: boolean;
+    /** Why not, when it cannot. Required whenever `interactive` is `false`. */
+    readonly nonInteractiveReason?: string | undefined;
+    /** The user's answer, when one arrived. */
+    readonly answer?: string | undefined;
+    /** The ask was put and no answer came back. */
+    readonly timedOut?: boolean | undefined;
+}
+
+/** What the run does next. */
+export interface AskDecision {
+    /**
+     * `ask` — put the question and come back with an answer or a timeout.
+     * `answered` — an answer exists; nothing is parked.
+     * `park` — write the marker; the run may continue with other steps.
+     * `approval-required` — the run stops and hands the unanswered question back.
+     */
+    readonly action: 'ask' | 'answered' | 'park' | 'approval-required';
+    /** The terminal state to report, when this decision ends the run. */
+    readonly terminal: RunTerminalState | null;
+    /** The marker to write, when one is written. */
+    readonly marker: string | null;
+    /** The text the run puts in front of the user. Never a silent default. */
+    readonly surfaced: string | null;
+    /** Whether the conservative default was adopted. ALWAYS false — see the module header. */
+    readonly defaultAdopted: false;
+}
+
+/**
+ * Decide, for one user-decision block, whether to ask, park, or stop.
+ *
+ * Order matters: an ANSWER wins over everything, then a timeout, then a
+ * non-interactive context, then the interactive path. A timeout is checked
+ * before interactivity so a run that asked and got nothing is never quietly
+ * re-classified as "could not ask".
+ */
+export function decideAsk(ctx: AskContext): AskDecision {
+    const unanswered =
+        `${ctx.question}\n\nConservative option (NOT adopted): ${ctx.conservativeDefault}`;
+
+    if (ctx.answer !== undefined && ctx.answer.trim() !== '') {
+        return {
+            action: 'answered',
+            terminal: null,
+            marker: null,
+            surfaced: null,
+            defaultAdopted: false,
+        };
+    }
+
+    if (ctx.timedOut === true) {
+        return {
+            action: 'approval-required',
+            terminal: 'approval-required',
+            marker: renderBlockedByMarker({
+                id: ctx.id,
+                asked: true,
+                reason: null,
+            }),
+            surfaced: unanswered,
+            defaultAdopted: false,
+        };
+    }
+
+    if (!ctx.interactive) {
+        const why = (ctx.nonInteractiveReason ?? '').trim();
+        return {
+            action: 'park',
+            terminal: null,
+            marker: renderBlockedByMarker({
+                id: ctx.id,
+                asked: false,
+                reason: why === '' ? 'non-interactive context, reason not recorded' : why,
+            }),
+            surfaced: unanswered,
+            defaultAdopted: false,
+        };
+    }
+
+    return {
+        action: 'ask',
+        terminal: null,
+        marker: null,
+        surfaced: ctx.question,
+        defaultAdopted: false,
+    };
+}
+
+/**
+ * The user declined to decide. That IS an answer about the ask — the question
+ * was put — so the marker records `asked: yes` and the decline is the reason
+ * the step stays blocked.
+ */
+export function parkAfterDecline(id: string): string {
+    return renderBlockedByMarker({ id, asked: true, reason: null });
+}

package/src/scripts/_lib/host_capability.ts

@@ -67,6 +67,23 @@ export interface HostCapabilityManifest {
      * stop-loss behaviour — loudly, never silently.
      */
     worker_respawn: boolean;
+    /**
+     * The host exposes its own structured-ask tool — a native question picker
+     * the agent can call instead of rendering a numbered-options block as prose.
+     *
+     * A STRICT BOOLEAN, and the per-host detail deliberately lives elsewhere.
+     * The source draft for road-to-asked-not-parked proposed a nested object
+     * carrying the tool name and the question/option ceilings; `asBool` below
+     * coerces every non-`true` value to `false`, so such an object would
+     * normalize silently to nothing. The shape lives in
+     * `_lib/structured_ask.ts` (`STRUCTURED_ASK_SHAPES`), which a caller reads
+     * explicitly; this field answers only whether there is anything to read.
+     *
+     * `false` is the safe default on purpose: an unknown host degrades to a
+     * text ask, and the agent never fires a tool call into a host that has no
+     * such tool.
+     */
+    structured_ask: boolean;
     /**
      * The host reads a PROJECT-scope MCP config file (`.mcp.json` or its
      * per-host equivalent) and starts the servers it names.
@@ -105,6 +122,7 @@ const SAFE_DEFAULT: HostCapabilityManifest = {
     separate_quota_pool: false,
     agent_teams: false,
     worker_respawn: false,
+    structured_ask: false,
     reads_project_mcp_config: false,
     // `true` because the safe answer here is "there is still a step", not
     // "there is nothing to do" — see the field's own note.
@@ -137,6 +155,7 @@ export function normalizeHostManifest(input: unknown): HostCapabilityManifest {
         separate_quota_pool: asBool(src.separate_quota_pool),
         agent_teams: asBool(src.agent_teams),
         worker_respawn: asBool(src.worker_respawn),
+        structured_ask: asBool(src.structured_ask),
         reads_project_mcp_config: asBool(src.reads_project_mcp_config),
         // Inverted coercion, matching the inverted default: only an explicit
         // `false` clears the residual, so an absent or malformed value keeps
@@ -215,9 +234,26 @@ export function normalizeHostManifest(input: unknown): HostCapabilityManifest {
  *
  * `agent_teams` — out of scope for a row by construction; see its own field
  *   doc comment and the protocol section.
+ *
+ * `structured_ask: false` — OBSERVED ABSENT, not never-looked, and the
+ *   difference is why it is written rather than omitted. claude (Claude Code
+ *   2.1.263, Opus 5 1M session, 2026-09-07). The host delivers the session's
+ *   tool surface at session start; that surface carried no structured-ask tool
+ *   under any name `_lib/structured_ask.ts` matches, and no per-host shape is
+ *   recorded for it in `STRUCTURED_ASK_SHAPES`. Artefact:
+ *   `agents/evidence/analysis/structured-ask-host-observation-2026-09.md`.  code-comment-allow provenance-comment -- the observation protocol declares a row inadmissible without its artefact citation, so this pointer is part of the contract the row satisfies, not evidence duplicated from a roadmap
+ *   The observation is about the delivered surface of one session on one
+ *   version; it is not a claim that the vendor ships no such tool anywhere,
+ *   and a later session observing one writes the `true` row over it.
+ *
+ * NO ROW ANYWHERE SETS THE STRUCTURED-ASK FIELD TRUE, and the observation
+ * protocol above is the only path to the first one that does. A vendor's
+ * documentation is not that path — and the phrasing here avoids the literal
+ * key-value pair on purpose, because the roadmap step that ships this field
+ * verifies the absence with a grep for exactly that string.
  */
 const HOST_CAPABILITY_REGISTRY: Readonly<Record<string, Partial<HostCapabilityManifest>>> = {
-    claude: { subagent_spawn: true, parallel_spawn: true },
+    claude: { subagent_spawn: true, parallel_spawn: true, structured_ask: false },
 };
 
 /**
@@ -323,6 +359,7 @@ const CAPABILITY_FIELDS: readonly CapabilityField[] = [
     'separate_quota_pool',
     'agent_teams',
     'worker_respawn',
+    'structured_ask',
     'reads_project_mcp_config',
     'mcp_needs_manual_activation',
 ];