[DO-NOT-MERGE] trial branch: all skill PRs merged, for install and testing

.github/CODEOWNERS

@@ -18,6 +18,12 @@
 /domains/performance/    @MetaMask/extension-platform @MetaMask/mobile-platform
 /domains/perps/          @MetaMask/perps
 /domains/pr-workflow/    @MetaMask/extension-platform @MetaMask/mobile-platform
+<<<<<<< HEAD
+/domains/stability/      @MetaMask/extension-platform @MetaMask/mobile-platform
+||||||| 4063bf1
+=======
+/domains/security/       @MetaMask/extension-platform @MetaMask/mobile-platform
+>>>>>>> origin/jongsun/add/security-domain
 /domains/swaps/          @MetaMask/swaps-engineers
 /domains/testing/        @MetaMask/qa
 /domains/ui/             @MetaMask/design-system-engineers

.github/scripts/lint-skill-entry.mjs

@@ -111,6 +111,22 @@ export function lintSkill(skill) {
     }
   }
 
+  // The installer prefixes every emitted skill, so a description advertising `/<name>`
+  // names a command no operator exposes. The description IS the discovery surface, so a
+  // wrong trigger string is a selection failure, not a typo.
+  //
+  // The lookbehind keeps a scoped package (`@metamask/gator-cli`) or a path
+  // (`skills/gator-cli`) from being read as a slash command.
+  if (raw.description && raw.name) {
+    const bare = new RegExp(`(?<![\\w@/-])/${raw.name}\\b`, 'u');
+    const prefixed = new RegExp(`(?<![\\w@/-])/${INSTALLED_PREFIX}${raw.name}\\b`, 'u');
+    if (bare.test(raw.description) && !prefixed.test(raw.description)) {
+      errors.push(
+        `\`description\` advertises \`/${raw.name}\` but the installer emits \`${INSTALLED_PREFIX}${raw.name}\`; name the installed form`,
+      );
+    }
+  }
+
   for (const section of RECOMMENDED_SECTIONS) {
     // A trailing `\b` let `## When To Use Cases` satisfy `When To Use` — a different
     // section. Anchoring to end-of-line fixes that but rejects `## Workflows` and

bin/metamask-skills.mjs

@@ -22,6 +22,7 @@ Usage:
   metamask-skills describe <skill|domain/skill> [options]
   metamask-skills sync [options]
   metamask-skills postinstall [options]
+  metamask-skills hooks [options]
   metamask-skills install [options]
 
 Options:
@@ -799,6 +800,55 @@ function invokedDirectly() {
   }
 }
 
+
+/**
+ * Print the Claude Code registration for every hook an installed skill ships.
+ *
+ * The installer copies `hooks/` like any other bundle directory, but a hook does nothing
+ * until it is registered in settings.json — and the path to register is absolute, so it
+ * differs per machine and per consumer repo and cannot be documented as a constant. This
+ * resolves it against the actual install.
+ */
+function printHookRegistration(args) {
+  const { target } = parseGlobalArgs(args);
+  const skillsDir = path.join(target, '.claude', 'skills');
+
+  let entries = [];
+  try {
+    for (const skill of readdirSync(skillsDir, { withFileTypes: true })) {
+      if (!skill.isDirectory()) continue;
+      const hooks = path.join(skillsDir, skill.name, 'hooks');
+      if (!dirExists(hooks)) continue;
+      for (const file of readdirSync(hooks)) {
+        if (file.endsWith('.py')) entries.push(path.join(hooks, file));
+      }
+    }
+  } catch {
+    warn(`no installed skills found under ${skillsDir}`);
+    return 1;
+  }
+
+  if (entries.length === 0) {
+    process.stdout.write('No installed skill ships a hook.\n');
+    return 0;
+  }
+
+  const commands = entries
+    .map((f) => `            { "type": "command", "command": "python3 ${f}" }`)
+    .join(',\n');
+
+  process.stdout.write(
+    `${entries.length} hook(s) installed. Copying a hook does not activate it — Claude Code\n` +
+      `runs one only once it is registered. Add this to ~/.claude/settings.json, or to\n` +
+      `${path.join(target, '.claude', 'settings.json')} to scope it to this repo:\n\n` +
+      '  {\n    "hooks": {\n      "PreToolUse": [\n        {\n          "matcher": "Bash",\n          "hooks": [\n' +
+      `${commands}\n` +
+      '          ]\n        }\n      ]\n    }\n  }\n',
+  );
+  return 0;
+}
+
+
 if (invokedDirectly()) {
   const [command, ...args] = process.argv.slice(2);
   if (!command || command === '-h' || command === '--help') {
@@ -817,6 +867,8 @@ if (invokedDirectly()) {
       exitCode = sync(args);
     } else if (command === 'postinstall') {
       exitCode = postinstall(args);
+    } else if (command === 'hooks') {
+      exitCode = printHookRegistration(args);
     } else if (command === 'install') {
       exitCode = install(args);
     } else {

domains/agentic/skills/agent-run-cost/skill.md

@@ -0,0 +1,108 @@
+---
+name: agent-run-cost
+maturity: experimental
+description: >-
+  Estimate what an agentic workflow costs to run before it merges — fan-out × trigger
+  frequency × no kill-switch — and say so in figures rather than adjectives. Agent token
+  spend is invisible in a diff: a workflow that spawns one agent and one that spawns forty
+  are the same few lines, and the difference only appears on a bill nobody reads during
+  review. Produces a per-run and per-month estimate with its arithmetic shown, flags the
+  three amplifiers, and proposes the cheapest mitigation that preserves the intent. Use
+  when a PR adds or widens an agentic workflow, an AEP task class, a verification recipe,
+  or a schedule that runs agents unattended.
+---
+
+# Agent run cost
+
+Scripted automation announces its cost in wall-clock time; agentic automation does not.
+A fan-out of forty subagents and a single call are the same shape in a diff, and the
+difference surfaces later, on a bill, attributed to nothing in particular.
+
+This is the token-spend counterpart to `sentry-quota`, which guards span volume. Same
+posture: operate on **code and PRs**, before the spend exists, and produce figures.
+
+## When to use
+
+- A PR adds or widens an agentic workflow, AEP task class, or verification recipe.
+- A workflow gains fan-out — an agent per file, per finding, per test, per PR.
+- Something agentic moves from opt-in to automatic (a CI trigger, a cron, a git hook).
+- An ADR or design proposes agents for work a script already does — the estimate is the
+  argument, and its absence is usually the tell.
+
+## Do not use when
+
+- The workflow is developer-invoked, one agent, no loop — the ceiling is a person's patience.
+- The change only narrows fan-out or adds a gate.
+
+## The amplifier triad
+
+Cost is not the per-agent price. It is the product of three things, any one of which can be
+the whole problem:
+
+| Amplifier | What it looks like | Effect |
+|---|---|---|
+| **Fan-out** | an agent per item — per file, per finding, per dimension, per round; nested `parallel` inside `pipeline`; a loop-until-dry with no ceiling | N× per run, and N is often data-dependent rather than fixed |
+| **Trigger frequency** | runs on every push rather than on demand; a cron; a label that re-fires on each commit; a retry that respawns the fleet | turns a one-off into a rate |
+| **No kill-switch** | no env var, feature flag, or budget cap; nothing to stop it mid-run; no way to disable without a revert | a runaway costs whatever it costs until someone merges a fix |
+
+One alone is usually fine. **Fan-out × frequency with no kill-switch is the shape that
+produces a surprise**, and it is worth naming explicitly in review when all three are present.
+
+## Producing the estimate
+
+Show the arithmetic. An estimate whose derivation is hidden is an adjective.
+
+1. **Count agents per run.** Read the fan-out literally — how many items feed the widest
+   stage, and whether that number is bounded by the code or by the data. A `pipeline` over
+   changed files is unbounded by the code; `Array.from({length: 3})` is not.
+2. **Estimate tokens per agent.** Prompt + the context it will read + its output. The context
+   dominates: an agent that reads three files is not an agent that greps a repo.
+3. **Multiply, then apply frequency.** Per-run cost × runs per week. State the assumption
+   about run count — it is the number most likely to be wrong, and naming it lets a reviewer
+   correct it.
+4. **State the worst case separately from the expected case.** The expected case is what it
+   costs on a normal PR; the worst case is what it costs on the PR that touches 400 files.
+   Budget conversations are about the second one.
+5. **Compare against the alternative.** If a deterministic script covers the same ground, the
+   estimate belongs next to that script's cost. An agentic approach can still win — for
+   adversarial review, exploration, fuzzing, or anything with no fixed oracle — but the case
+   is made by the comparison, not by the capability.
+
+Report the figures, the assumptions behind them, and the mitigation. **Do not render a
+ship/no-ship verdict** — whether a cost is worth paying is a budget decision, and it belongs
+to whoever owns the budget.
+
+## Mitigation ladder
+
+Cheapest first; stop at the rung that fits.
+
+1. **Cap the fan-out.** A literal ceiling on items, with a `log()` of what was dropped —
+   silent truncation reads as full coverage and is worse than the cost.
+2. **Narrow the trigger.** On-demand or label-gated instead of every push; on the changed
+   subset instead of the tree.
+3. **Right-size the model per stage.** Mechanical stages rarely need the top tier; reserve it
+   for the judgement stages.
+4. **Add a budget guard.** A token ceiling the workflow checks between stages, so it degrades
+   instead of running to completion at any price.
+5. **Add a kill-switch.** An env var or flag that disables it without a revert. Cheap to add
+   up front and unavailable exactly when it is needed most.
+
+## Common pitfalls
+
+| Mistake | Correct approach |
+|---|---|
+| "It's just a few agents" | Count them. Data-dependent fan-out has no "just" |
+| Estimating output tokens only | Context dominates — an agent that reads the repo costs more than one that answers at length |
+| Quoting an average with no worst case | The worst case is the budget conversation |
+| Treating a retry as free | A retried fleet is a second fleet |
+| Assuming a concurrency cap bounds cost | It bounds *parallelism*, not total spend — queued agents still run |
+| Adding a kill-switch after launch | It is needed during the incident it would have prevented |
+| Comparing capability instead of cost | "Agents can do this" is not "agents should do this at this price" |
+
+## Related
+
+- `sentry-quota` — the same guard for span volume; `fan-out × ungated × no-kill-switch`.
+- `evidence` — weighs AEP run cost when choosing an evidence lane, and tears the stack
+  down after; this skill is the review-side version for workflows others will run.
+- [`MetaMask/decisions#173`](https://github.com/MetaMask/decisions/pull/173) — ADR-0058
+  review, where the missing token-cost estimate was raised as an open question.

domains/analytics/knowledge/metrametrics-identity.md

@@ -0,0 +1,41 @@
+---
+name: metrametrics-identity
+domain: analytics
+description: isOptIn:true unconditionally strips user identity in MetaMetricsController — always sends as anonymous ID
+---
+
+# MetaMetrics Identity Stripping
+
+## The Mechanism
+
+In `MetaMetricsController` (`app/scripts/controllers/metametrics-controller.ts`):
+
+```typescript
+if (excludeMetaMetricsId || (isOptIn && !metaMetricsIdOverride)) {
+  idType = 'anonymousId';
+  idValue = METAMETRICS_ANONYMOUS_ID; // 0x0000000000000000
+}
+```
+
+When `isOptIn: true` with no `metaMetricsIdOverride`:
+- The user's real `metaMetricsId` is discarded
+- ALL such events share a single anonymous ID (`0x0000000000000000`) in Segment
+- User-level attribution is completely lost
+
+This is **unconditional** — it applies to fully opted-in users with valid IDs, not just anonymous users.
+
+## Intended Use
+
+The onboarding opt-in flow (`creation-successful.tsx`) — where the user hasn't committed to MetaMetrics yet and no `metaMetricsId` has been persisted. The event must fire regardless of opt-in state.
+
+## The Misuse Pattern
+
+Post-opt-in `trackEvent` calls with `{ isOptIn: true }` without `metaMetricsIdOverride`. Defeats the purpose of Segment user-level dimensions (account types, feature flags).
+
+## Detection
+
+```bash
+grep -r "isOptIn: true" app/scripts/ ui/ --include="*.ts" --include="*.tsx"
+```
+
+Any occurrence outside `creation-successful.tsx` (or the onboarding flow) is suspect.

domains/analytics/knowledge/segment-governance.md

@@ -0,0 +1,40 @@
+---
+name: segment-governance
+domain: analytics
+description: Segment event governance via segment-schema is advisory — no CI enforcement prevents unregistered events from shipping
+---
+
+# Segment Event Governance
+
+## Architecture
+
+| Component | Location |
+|-----------|----------|
+| Tracking plan | `Consensys/segment-schema` → `tracking-plans/metamask-extension.yaml` |
+| Event registry | `shared/constants/metametrics.ts` → `MetaMetricsEventName` enum (300+ entries) |
+| Review process | `CONTRIBUTING.md` in segment-schema; Data Council review |
+| Governance channel | `#metamask-metametrics`, `@consensys/data-council` |
+
+## The Gap
+
+There is **no CI enforcement** in the extension repo. A developer can:
+
+1. Add entry to `MetaMetricsEventName` enum
+2. Call `trackEvent` with it
+3. Merge and ship to production
+
+...without registering in segment-schema or going through Data Council review.
+
+## Implications
+
+- Schema drift between tracking plan and production events
+- No property schema validation for unregistered events
+- Billing impact goes unreviewed
+- Data Council review is bypassable by omission
+
+## Recommended Fix
+
+CI check that:
+1. Parses `MetaMetricsEventName` entries
+2. Validates each against `tracking-plans/metamask-extension.yaml`
+3. Fails build if event is missing from the plan

domains/analytics/knowledge/span-sub-sampling.md

@@ -0,0 +1,72 @@
+---
+name: span-sub-sampling
+domain: analytics
+description: Deterministic per-trace sub-sampling for high-frequency custom spans — global tracesSampleRate × span sub-rate, traceId-hash bucketed
+---
+
+# Span Sub-Sampling
+
+Durable fix for a custom span that fans out and eats the span budget. Layer a per-trace sub-rate **under** the global `tracesSampleRate`, keyed on the trace id so every span in a trace is kept-or-dropped together. Source: [PR #39891](https://github.com/MetaMask/metamask-extension/pull/39891) (`shared/lib/wrapper-sampling.ts`).
+
+## Rate Math
+
+```
+effective rate = global tracesSampleRate × span sub-rate
+```
+
+- Global `tracesSampleRate` is already small (extension prod: 0.75%).
+- The sub-rate cuts the custom span on top: `0.75% × 1% = 0.0075%`.
+- PR #39891 ships a sub-rate of 0.5% (`WRAPPER_SAMPLE_RATE = 0.005`) — a conservative pilot — and names 5% as the step-up once the denylist is confirmed effective in production.
+
+Pick the sub-rate from how many sampled traces the metric needs to stay useful — not from the quota alone. Too low and the metric goes dark.
+
+## Pattern
+
+```ts
+const WRAPPER_SAMPLE_RATE = 0.005;
+
+// Deterministic: same answer for the same traceId, so all spans in a trace
+// are kept or dropped together — clean waterfalls, no partial gaps.
+export function shouldSampleWrappers(traceId: string | undefined): boolean {
+  if (!traceId || traceId.length < 8) {
+    return false;
+  }
+  const hashBucket = parseInt(traceId.slice(0, 8), 16) % 10000;
+  return hashBucket < WRAPPER_SAMPLE_RATE * 10000;
+}
+```
+
+**Why deterministic, not `Math.random()` per call:** independent per-span sampling shreds a trace into partial waterfalls (some spans present, siblings missing) — useless for attribution. Hashing the trace id makes keep/drop a property of the whole trace.
+
+## Gate Order (cheapest check first)
+
+```ts
+const traceId = sentryGetActiveSpan()?.spanContext().traceId;
+if (!traceId || isReadOnlyAction(action) || !shouldSampleWrappers(traceId)) {
+  return doWorkWithoutSpan();
+}
+return trace({ name, op, data }, doWorkWithSpan);
+```
+
+1. No active trace → no span.
+2. Denylist → skip noise (below).
+3. Sub-sample miss → skip this trace's spans.
+
+## Denylist: cut before you sample
+
+Drop spans with no timing/attribution signal before sub-sampling. In PR #39891, read-only verbs are ~90% of `messenger.call` volume:
+
+```ts
+const READ_ONLY_VERB = /^(?:get|has|find|is|peek)(?:[A-Z]|$)/u;
+```
+
+Removing ~90% of volume before the sample multiplies headroom — a higher sub-rate then yields the same span budget, so kept traces are denser and more useful.
+
+## Where the Gate Goes
+
+- **Consumer (extension):** spans go through `trace()`. Gate at the call site, or for a whole span family inside the wrapper. `traceId` from `sentryGetActiveSpan()?.spanContext().traceId`.
+- **Controller package (core):** controllers call an injected `trace` callback. Gate in the package's trace util or the callback so every consumer inherits the cap. Pull the trace id from the controller's tracing context, not a fresh Sentry import.
+
+## Kill Switch
+
+Ship every always-on span family with an env disable flag (PR #39891: `SENTRY_DISTRIBUTED_TRACING_DISABLED` returns the messenger un-wrapped). It turns a future emergency cut into a config flip instead of a cherry-pick.