@event4u/agent-config 14.19.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/dist/scripts/mcp_server/telemetry.js

@@ -0,0 +1,148 @@
+// MCP telemetry sink — Phase 1 J4 instrumentation.
+//
+// Per `agents/roadmaps/archive/road-to-mcp-full-coverage.md` §Phase 1 J4 +
+// `docs/contracts/mcp-tool-stub-envelope.md`, both transports log every
+// `tools/call` with `{tool_name, client_id_hash, ts, transport,
+// outcome}`. The stdio-lite surface (`src/cli/mcp/`) appends a sixth,
+// optional `host` field; callers that do not know their client omit it and
+// their records stay byte-identical to the frozen five-field envelope. Payload bodies are never logged; the client identifier is
+// hashed at the server boundary so the queryable store never sees raw
+// identity.
+//
+// Outcomes:
+//
+// - `implemented` — real handler ran (no envelope returned).
+// - `stub` — catalog entry missing this transport; `not_implemented`
+//   envelope returned.
+// - `latent_demand` — caller asked for a tool not in the catalog.
+//
+// The sink writes JSONL to `agents/runtime/mcp-telemetry/calls.jsonl` under the
+// consumer root. Failure to write must not break the wire surface: the
+// `record_call` helper swallows OSError + ValueError and emits a single
+// warning to stderr.
+//
+// TS port of the retired Python telemetry.py (ADR-200). Preserves the full public surface:
+//   - Outcome type, TELEMETRY_REL_DIR, TELEMETRY_FILENAME, hash_client_id,
+//     build_record, record_call.
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+// Stable file location relative to consumer_root. Phase 2 K1 routes
+// this into a queryable store; Phase 1 only needs the file to exist.
+export const TELEMETRY_REL_DIR = 'agents/runtime/mcp-telemetry';
+export const TELEMETRY_FILENAME = 'calls.jsonl';
+// Truncation length for the client_id hash. 12 hex chars = 48 bits of
+// entropy — enough to distinguish hundreds of consumers without
+// becoming a re-identification vector.
+const _HASH_LEN = 12;
+/**
+ * Identity components that together pin a consumer install.
+ *
+ * USER + machine hostname + repo path is a stable triple that survives
+ * sessions without leaking PII into the log. The hash never reverses.
+ */
+function _client_id_seed() {
+    const user = process.env.USER || process.env.USERNAME || 'unknown';
+    let host = process.env.HOSTNAME;
+    if (!host) {
+        // Mirrors Python `os.uname().nodename` (POSIX) — Node exposes
+        // `os.hostname()`. Guarded so an empty value falls through to "unknown".
+        try {
+            host = os.hostname();
+        }
+        catch {
+            host = undefined;
+        }
+    }
+    host = host || 'unknown';
+    const cwd = _resolvePath(process.cwd());
+    return `${user}|${host}|${cwd}`;
+}
+/** SHA-256(seed) truncated to 12 hex chars. Boundary-only call. */
+export function hash_client_id(seed) {
+    const raw = seed !== undefined ? seed : _client_id_seed();
+    const digest = crypto.createHash('sha256').update(Buffer.from(raw, 'utf-8')).digest('hex');
+    return digest.slice(0, _HASH_LEN);
+}
+/**
+ * Resolve a path like Python `Path(...).resolve()` — absolutize + realpath
+ * the existing prefix, tolerating a non-existent tail (Python resolve does
+ * not require the path to exist; `fs.realpathSync` does, so fall back to a
+ * plain absolute path on ENOENT).
+ */
+function _resolvePath(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+/** Pick the JSONL location. Defaults to CWD when no override given. */
+function _resolve_log_path(consumer_root) {
+    const root = _resolvePath(consumer_root ?? process.cwd());
+    return path.join(root, TELEMETRY_REL_DIR, TELEMETRY_FILENAME);
+}
+/** ISO-8601 UTC timestamp, seconds precision. */
+function _now_iso() {
+    // Mirrors Python `time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())`.
+    return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+/**
+ * Pure helper — assemble the record without touching the filesystem.
+ *
+ * Field insertion order matches the Python dict literal so the
+ * compact-JSON serialization is byte-identical.
+ */
+export function build_record(options) {
+    const { tool_name, outcome, transport, client_id_hash_value, ts, host } = options;
+    const record = {
+        tool_name,
+        client_id_hash: client_id_hash_value || hash_client_id(),
+        ts: ts || _now_iso(),
+        transport,
+        outcome,
+    };
+    // `host` is APPENDED, and only when a caller supplies one, so a record
+    // written by a caller that does not know its client stays byte-identical
+    // to the five-field envelope the stub contract froze. It is a closed
+    // vocabulary resolved at the boundary (see `src/cli/mcp/telemetry.ts`),
+    // never a free-form string: a record type that cannot hold arbitrary text
+    // has no scrubber to fail.
+    if (typeof host === 'string' && host !== '') {
+        record.host = host;
+    }
+    return record;
+}
+/**
+ * Append one JSONL record. Returns the record or null on failure.
+ *
+ * Failures are swallowed: telemetry must never break the wire surface.
+ * A single `mcp-server: warn: telemetry` line is emitted to stderr
+ * so silent-failure windows show up in the boot log and the J6
+ * healthcheck can detect them.
+ */
+export function record_call(options) {
+    const { tool_name, outcome, transport, consumer_root, client_id_hash_value, host } = options;
+    const record = build_record({
+        tool_name,
+        outcome,
+        transport,
+        client_id_hash_value,
+        host,
+    });
+    const target = _resolve_log_path(consumer_root ?? undefined);
+    try {
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        // json.dumps(record, separators=(",", ":")) — compact, no spaces.
+        fs.appendFileSync(target, JSON.stringify(record) + '\n', { encoding: 'utf-8' });
+    }
+    catch (exc) {
+        const message = exc instanceof Error ? exc.message : String(exc);
+        process.stderr.write(`mcp-server: warn: telemetry write failed: ${message}\n`);
+        return null;
+    }
+    return record;
+}
+//# sourceMappingURL=telemetry.js.map

package/docs/guidelines/agent-infra/naming.md

@@ -34,7 +34,7 @@ source: package
 |---|---|---|
 | `{concern}` | Behavioral constraint | `scope-control`, `ask-when-uncertain` |
 | `{domain}-{concern}` | Domain-specific rule | `php-coding`, `e2e-testing` |
-| `{action}-{target}` | Trigger-based auto rule | `capture-learnings`, `downstream-changes` |
+| `{action}-{target}` | Trigger-based auto rule | `invite-challenge`, `downstream-changes` |
 
 ### Commands
 

package/docs/guidelines/agent-infra/security-lint-containment.md

@@ -45,18 +45,51 @@ are *expected* to contain illustrative patterns. Only a full-weight (1.0×)
 **HIGH** finding in a real artifact fails the build. (`is_example_path()` in the
 shared lib defines the path set.)
 
-### 3. Per-file pragma
+### 3. Bound pragma
 
-A single check can be suppressed for one file with an auditable, reasoned
-marker placed anywhere in the file:
+A single check can be suppressed for **specific evidence** in one file with an
+auditable, reasoned, content-bound marker placed anywhere in the file:
 
 ```
-<!-- security-lint: allow instruction-smuggling "teaching example: quotes a prompt-injection string" -->
+<!-- security-lint: allow instruction-smuggling "teaching example: quotes a prompt-injection string" sha256:<hex> -->
 ```
 
 - The `<check>` token is the linter's check id (`hidden-unicode`,
-  `instruction-smuggling`, `mcp-config-security`, `dangerous-frontmatter`).
+  `mixed-script-confusable`, `instruction-smuggling`, `mcp-config-security`,
+  `dangerous-frontmatter`).
 - The `"<reason>"` is **mandatory** — an empty reason does not parse.
+- Each `sha256:<hex>` **binds the suppression to one accepted match**. Repeat the
+  token once per accepted match; a file with three accepted matches carries three
+  hashes. Anything the check finds that is not in that set is still reported.
+- The fingerprint covers the **check id**, the artifact's **source identity**, and
+  the **normalized text of the matched line** — ASCII whitespace runs collapse so
+  a reflow does not break the binding, and nothing else is stripped, because the
+  zero-width characters this suite hunts are exactly what a wider normalizer
+  would erase. It is deliberately NOT the line number (an unrelated insert above
+  would break every pragma in the file) and NOT the whole file (every unrelated
+  edit would re-fire it, which is how blanket suppressions get written).
+  A `dist/agent-src/` path folds to its `src/` original first: the projection is
+  byte-exact by contract, so an artifact and its copy are one identity.
+- **A pair pinned equal by a parity test carries ONE HASH PER IDENTITY.** The
+  fold above covers `dist/agent-src/` and nothing else, so where a second
+  hand-maintained copy exists and a test asserts the two are byte-identical —
+  `src/subagents/<stem>.md` and `docs/wedge/<stem>/<stem>.md`, pinned by
+  `tests/scripts/subagent_distribution.test.ts` — one hash cannot satisfy both:
+  giving each file its own makes the lines differ and reds the parity test,
+  which is exactly how this was found. Put BOTH hashes in BOTH files. That is
+  what the repeatable token is for, and it is why the grammar has one. A purely
+  GENERATED third copy (`.claude/agents/<stem>.md`) needs no hash of its own:
+  nothing scans it and nobody edits it, so binding it would be a fingerprint
+  for an identity no finding can arise at.
+- Compute one with the linter itself, never by hand — a hash typed from memory
+  is a suppression nobody audited.
+
+**The unbound form still parses**, suppresses the whole file as it always did,
+and reports itself as a `legacy-pragma` LOW finding. That is a migration signal,
+not a mode to choose: a key lookup with no content binding accepts whatever the
+matched text is later changed to say, which is the defect the hash exists to
+close. There are zero unbound pragmas in the tree.
+
 - Pragmas are **counted and capped**: crossing **20** across the repo means the
   linter is mis-scoped. Stop adding pragmas; redesign or narrow the check
   (escalate per `autonomous-execution` — the allowlist-growth antipattern).
@@ -72,7 +105,14 @@ marker placed anywhere in the file:
 
 `security-example` fence → confidence weight → pragma. A HIGH finding survives
 to fail the build only when it is full-weight (not in an example path), not
-inside a `security-example` fence, and not covered by a matching pragma.
+inside a `security-example` fence, and not covered by a pragma whose fingerprint
+set contains that match.
+
+One consumer deliberately departs from the weighting rung: `skill_scout`'s
+`security_licence` gate refuses a quarantined candidate on **any** HIGH finding,
+whatever its weight. Path-based confidence is a false-positive containment device
+for a corpus whose provenance is known; a third-party candidate has none, and a
+directory named `examples/` in it is the submitter's word for it.
 
 ## See also
 

package/docs/guidelines/agent-infra/self-improvement-pipeline.md

@@ -4,10 +4,10 @@ Five-stage flow that turns real project experience into reviewed
 rule / skill / command / guideline changes. No autonomous self-edits;
 every upstream change ships via a human-reviewed PR.
 
-Referenced by `road-to-curated-self-improvement.md`. Consumed by the
-existing skills `capture-learnings`, `learning-to-rule-or-skill`,
-`skill-improvement-pipeline`, and `upstream-contribute` — each becomes
-a stage, not a standalone invocation.
+Referenced by `road-to-curated-self-improvement.md`. Consumed by the live
+artifacts — the `skill-improvement-trigger` rule and the existing skills
+`learning-to-rule-or-skill`, `skill-improvement-pipeline`, and
+`upstream-contribute` — each becomes a stage, not a standalone invocation.
 
 ## The five stages
 

package/docs/guidelines/agent-infra/untrusted-input-spotlighting.md

@@ -1,4 +1,4 @@
-<!-- security-lint: allow instruction-smuggling "defense guideline: quotes role-takeover phrases (ignore previous instructions, you are now, <IMPORTANT>) to teach refusal" -->
+<!-- security-lint: allow instruction-smuggling "defense guideline: quotes role-takeover phrases (ignore previous instructions, you are now, <IMPORTANT>) to teach refusal" sha256:d84759534e0fd3ebc5a66533b4a9f52364ef5286eaf3674a611c9c2adf89b969 sha256:f08c68182232149c7ecd881e88ca81dc98a9313c06ba6d010b065f9feef2c149 sha256:4f5936bb0a57de8ff3ce590fb12607cdcb046a31262b5e4d40377c6e6184f494 -->
 
 # untrusted-input spotlighting + least-agency mapping
 

package/docs/guidelines/redundancy-taxonomy.md

@@ -86,6 +86,34 @@ translation frequently denote different mechanisms — here `route`, `dispatch`,
 five ways — so a sweep over them destroys information the echo classes exist to
 protect.
 
+## The avoid-list — one term, one concept
+
+A homonym collision is only half-diagnosed when it is classified. The other
+half is the **decision**: which concept keeps the word, and what every other
+sense is called instead. This list carries the decided ones. A word is added
+here when the same term has been observed denoting more than one shipped
+mechanism; it is removed only when the collision is gone from the tree, never
+because the entry became inconvenient.
+
+Read the columns as a rename instruction for **prose you write from now on**.
+The identifier layer is decided separately and per cluster, exactly as the
+prose/identifier split above requires — a term may be `canonicalize-term` in
+prose and `keep-distinct` in identifiers, and both verdicts are recorded.
+
+| Term | Concept that keeps the word | Other senses, and what to call them | Identifier verdict |
+|---|---|---|---|
+| `envelope` | The **transport wrapper** around a payload — `OutcomeEnvelope` (a run's terminal outcome, `src/scripts/_lib/outcome_envelope.ts`) and the `CHECKPOINT` envelope a worker capsule rides in. | The **session continuity record** is a **capsule**. The word is not chosen for readability — it is the shipped discriminator (`CAPSULE_SCHEMA_VERSION`, `CAPSULE_VARIANTS = ['worker','main_session']`, `src/scripts/_lib/subagent_capsule.ts`), so the surviving term is read off what ships rather than off what reads best. | `keep-distinct` for now. `MainSessionRecycleEnvelope` and `RECYCLE_ENVELOPE_*` keep their names until a rename is costed on its own; the prose rule binds immediately and the symbols are a separate blast radius. |
+| `handoff` | The **session-to-session continuity handover** a developer invokes — the `handoff` verb and the `/agent-handoff` command. | The lint over senior-tier skills' `## Related Skills` edges is a **cross-wing skill link**, never "a handoff". | `keep-distinct`, recorded reason: `lint_handoffs.ts` mirrors a ported CLI contract (ADR-200) whose name is an external surface. Its module docstring already says "cross-wing", which is the disambiguation the prose rule now requires everywhere else. |
+
+**Why a list and not a linter.** `lint_canonical_terms` decides *spelling*
+pairs, where one side is mechanically wrong. A homonym is not mechanically
+wrong anywhere — every occurrence is a legitimate word for a legitimate
+concept, and only the reader's inability to tell them apart is the defect. A
+gate that flagged `envelope` would flag the entry that is supposed to survive.
+So this list is enforced at review, by citation, and its cost of being ignored
+is the cost the taxonomy already names: the model telling you it has not
+decided.
+
 ## Why any of this is worth a gate at all
 
 Generated code trends toward duplication rather than reuse: measured

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.19.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,