@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/chrome-extension/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: chrome-extension
+description: "Use when building or shipping a Manifest V3 browser extension and hitting its quirks — service worker dying and losing state, permission warnings, a Chrome Web Store rejection, content-script/worker/popup messaging, or an MV2-to-V3 migration. NOT a generic web app (that is `nextjs`), NOT a desktop shell (that is `electron`)."
+tags: [chrome-extension, manifest-v3, browser-extension, service-worker, chrome-web-store]
+recommends: [nextjs, react, gdpr-privacy, secure-coding, vercel]
+origin: ai-hub
+---
+
+# Chrome extension (Manifest V3)
+
+An MV3 extension is **three isolated JavaScript contexts that never share memory and only talk via messages**:
+
+1. **Service worker** (`background.service_worker`) — the logic and lifecycle brain. Ephemeral: Chrome kills it when idle and restarts it on the next event. It has no DOM and no `window`.
+2. **Content scripts** — run inside a web page, can read/write that page's DOM, live in an isolated JS world by default. No access to most `chrome.*` APIs except messaging and `storage`.
+3. **UI surfaces** — popup (`action.default_popup`), options page, side panel. Normal web pages that load and unload as the user opens/closes them.
+
+Internalize that picture first. Most extension bugs are someone treating one of these as if it shared state with another. They do not. The wire between them is `chrome.runtime` messaging and `chrome.storage`.
+
+Manifest V3 is the only version the Chrome Web Store accepts; MV2 phase-out began June 2024 and is still rolling out. Build MV3 from the start.
+
+## Pick a skeleton
+
+| Setup | Pick when | Cost |
+|---|---|---|
+| **Vanilla** (raw files, `load unpacked`) | tiny extension, no npm imports, you want the fastest possible reload loop | no TS, no HMR, manual reloads |
+| **Vite + CRXJS** (`@crxjs/vite-plugin`) | TS, npm imports, React/Vue popup, you want HMR | a build step; you ship `dist/`, not the repo |
+
+Default to **Vite + CRXJS** the moment you want TypeScript or a framework popup — it does the manifest wiring and HMR for you. Reach for vanilla only for a one-file experiment.
+
+Minimal tree (Vite + CRXJS):
+
+```text
+my-ext/
+  manifest.json        # source of truth; CRXJS reads it
+  src/
+    background.ts       # service worker
+    content.ts          # content script
+    popup/
+      index.html
+      popup.tsx
+  public/icons/         # 16, 48, 128 px PNGs
+  vite.config.ts
+  # build output -> dist/  (this is what you zip)
+```
+
+## manifest.json — minimum viable shape
+
+```json
+{
+  "manifest_version": 3,
+  "name": "Highlighter",
+  "version": "1.0.0",
+  "description": "Highlights selected text on the current page.",
+  "icons": { "16": "icons/16.png", "48": "icons/48.png", "128": "icons/128.png" },
+  "action": { "default_popup": "popup/index.html" },
+  "background": { "service_worker": "background.js", "type": "module" },
+  "permissions": ["activeTab", "storage", "scripting"],
+  "host_permissions": [],
+  "minimum_chrome_version": "120"
+}
+```
+
+Rules that fail review or break the worker if you get them wrong:
+
+- `manifest_version` **must be `3`**. There is no `2` path forward.
+- `background.service_worker` is a **string**, not an array. There is no `background.scripts` and no `background.page` in MV3. The `persistent` key does not exist — delete it. (Source: developer.chrome.com "Migrate to a service worker", accessed 2026-06-02.)
+- `"type": "module"` lets the worker use `import`. Use it if you bundle.
+- Keep `host_permissions` empty until you can name exactly which sites and why (see permission table).
+
+## The three contexts and how they talk
+
+The service worker is **ephemeral**. It terminates when idle and wakes on an event. Two consequences govern almost all your code:
+
+- **Register every listener synchronously at the top level.** If you call `chrome.runtime.onMessage.addListener` inside an `async` callback or after an `await`, Chrome may not have registered it when it wakes the worker, and your event is lost. (Source: developer.chrome.com "Migrate to a service worker", accessed 2026-06-02.)
+- **Never keep state in a global variable.** The worker dies and your variable resets to its initial value. Persist to `chrome.storage`.
+
+```js
+// Bad — global resets to 0 every time the worker is killed and restarts
+let clickCount = 0;
+chrome.action.onClicked.addListener(() => {
+  clickCount++;                          // silently back to 1 after idle
+});
+
+// Good — durable across worker restarts, listener registered at top level
+chrome.action.onClicked.addListener(async () => {
+  const { clickCount = 0 } = await chrome.storage.local.get("clickCount");
+  await chrome.storage.local.set({ clickCount: clickCount + 1 });
+});
+```
+
+Messaging choices:
+
+- **One-shot** request/response: `chrome.runtime.sendMessage(msg)` / `chrome.tabs.sendMessage(tabId, msg)` paired with `chrome.runtime.onMessage`. Return `true` from the listener to keep the channel open for an async `sendResponse`.
+- **Long-lived** stream (e.g. a content script feeding the popup continuously): `chrome.runtime.connect()` → `Port`, with `port.onMessage` / `port.postMessage`.
+
+Content script → service worker → popup: there is no direct content-script-to-popup channel when the popup is closed. Route through the worker or through `chrome.storage` and let the popup read on open.
+
+## Permissions — least privilege or you get rejected
+
+Reviewers reject broad permissions with no justification, and broad `host_permissions` trigger a scary install-time warning that tanks conversion. Declare the **narrowest** thing that works.
+
+| Permission | Grants | Warning? | Use when |
+|---|---|---|---|
+| `activeTab` | temporary access to the current tab, only after a user gesture (toolbar click) | none | the user clicks your icon and you act on that one page |
+| `scripting` | `chrome.scripting.executeScript` to inject programmatically | none alone (needs a host or `activeTab` to target) | inject on demand instead of on every page |
+| `host_permissions: ["https://example.com/*"]` | persistent access to those origins | yes, lists the sites | you must run in the background on specific sites |
+| `host_permissions: ["<all_urls>"]` | every site | loud, broad warning | almost never — avoid; prefer `activeTab` |
+| `optional_permissions` + `chrome.permissions.request()` | runtime opt-in inside a user gesture | shown only when requested | a feature only some users need; ask when they enable it |
+| `declarativeNetRequest` | static/dynamic rules block or modify requests, no request bodies seen | install-time warning | ad/tracker blocking — replaces blocking `webRequest` |
+| `declarativeNetRequestWithHostAccess` | same, but access granted per host instead of install-time | per-host | DNR scoped to granted hosts only |
+
+Rule: write a one-sentence justification for **every** permission before you add it. If you cannot, drop it. `activeTab` covers more cases than people expect — try it first. (Source: developer.chrome.com "Declare permissions" + "declarativeNetRequest", accessed 2026-06-02.)
+
+## Content scripts: declarative vs programmatic
+
+```json
+// Declarative — in manifest. Runs automatically on matching pages.
+"content_scripts": [{
+  "matches": ["https://example.com/*"],
+  "js": ["content.js"],
+  "run_at": "document_idle"
+}]
+```
+
+```js
+// Programmatic — inject on a gesture. Needs "scripting" + activeTab or a host match.
+chrome.action.onClicked.addListener(async (tab) => {
+  await chrome.scripting.executeScript({
+    target: { tabId: tab.id },
+    files: ["content.js"],
+  });
+});
+```
+
+- `run_at`: `document_start` (before DOM), `document_end`, or `document_idle` (default, after load). Pick `document_start` only if you must beat the page's own scripts.
+- **Isolated world** (default): your content script's JS is sandboxed from the page's JS — they share the DOM but not variables. Use **MAIN world** (`"world": "MAIN"`) only when you must touch the page's own JS objects, and know it loses the isolation guarantee.
+- For dynamic, user-supplied injection, `chrome.userScripts.execute()` exists (Chrome 135, Mar 2025) — see [references/store-and-migration.md](references/store-and-migration.md).
+
+## Storage, alarms, no remote code
+
+- `chrome.storage.local` (~10 MB, larger with `unlimitedStorage`) for most data; `chrome.storage.sync` (~100 KB, ~8 KB/item) only for small settings you want to follow the user across devices.
+- **`setTimeout`/`setInterval` are unreliable** in the worker — it may be asleep when they fire. Use `chrome.alarms` for anything beyond a few seconds. (Source: developer.chrome.com "Migrate to a service worker", accessed 2026-06-02.)
+- **Remotely hosted code is banned.** No `<script src="https://cdn...">`, no `eval`-of-fetched-string. All executable JS must ship inside the package — bundle every dependency. This is enforced by MV3's CSP and by review. (Source: developer.chrome.com "What is Manifest V3", accessed 2026-06-02.)
+
+## Shipping to the Chrome Web Store
+
+1. **Build**, then **zip the `dist/` output** — never the repo. No `node_modules`, no `.git`, no source maps you do not want public.
+2. Pay the **one-time $5 USD** developer registration (covers up to 20 extensions on the account).
+3. Upload the zip in the Developer Dashboard.
+4. Listing assets: a **128×128 PNG** icon, **at least one screenshot** (1280×800 or 640×400), a clear description, a category, and a **privacy-policy URL if you collect any data**.
+5. Review is typically **1–3 business days** (simple extensions often under 24h).
+
+(Source: developer.chrome.com "Register your developer account" + fee guide, accessed 2026-06-02.) For the full dashboard walkthrough, data-disclosure form, staged rollout, appeals, and the MV2→MV3 migration map, see [references/store-and-migration.md](references/store-and-migration.md).
+
+## Anti-patterns
+
+| Anti-pattern | Why it breaks | Do instead |
+|---|---|---|
+| `background.scripts` / `persistent: true` | MV2 shape; rejected, worker never registers | `background.service_worker: "bg.js"` (string) |
+| Listener added after an `await` | Chrome wakes the worker without your listener; event lost | register all listeners synchronously at top level |
+| State in a global var | worker dies, var resets silently | persist to `chrome.storage` |
+| `<all_urls>` when a click suffices | scary install warning, review pushback | `activeTab` triggered by the toolbar click |
+| `<script src="https://cdn…">` | remote code is banned in MV3 | bundle the dependency into the package |
+| `setInterval` for periodic work | fires only while worker is alive | `chrome.alarms` |
+| Zipping the repo / `node_modules` | bloated, leaks source, may fail review | zip only the built `dist/` |
+| Auth token in a global / `sync` | lost on restart, or synced off-device | `chrome.storage.local` (or `session` for in-memory) |
+| MAIN world by default | loses isolation, page can tamper | isolated world unless you must reach page JS |
+
+Run `scripts/verify.sh <dir>` to lint a produced `manifest.json` against the MV3 invariants above.

package/skills/shared/chrome-extension/evals/README.md

@@ -0,0 +1,12 @@
+# Evals: chrome-extension
+
+`cases.yaml` holds two things. The `should_trigger` / `should_not_trigger`
+prompts are routing checks: read each prompt cold and judge whether this skill
+(versus the named sibling) should fire — run them by hand or feed them to an
+LLM judge against the skill's description. The `capability` case is graded by
+handing the scenario to an agent loaded with the skill and checking the output
+against every item in `must_include` (a rubric, not a string match). There is no
+automated test runner here. The one mechanical check is `scripts/verify.sh
+<dir>`, which lint-checks any `manifest.json` the skill produces against the MV3
+invariants; it exits 0 when the target has no manifest, so it is safe to run on
+an empty directory.

package/skills/shared/chrome-extension/evals/cases.yaml

@@ -0,0 +1,40 @@
+skill: chrome-extension
+
+should_trigger:
+  - prompt: "Build me a Chrome extension that highlights selected text on the page."
+    why: "Clear scaffolding-from-zero request — the core use case (manifest + content script + popup)."
+  - prompt: "My extension's background script keeps losing its state between events — the counter resets to zero."
+    why: "Non-obvious symptom of the ephemeral service worker killing globals; the fix (chrome.storage, top-level listeners) is this skill's heart."
+  - prompt: "The Chrome Web Store rejected my extension for excessive permissions. Help me fix the manifest."
+    why: "Store review + least-privilege permission model — activeTab vs host_permissions, justifications."
+  - prompt: "Migrate this Manifest V2 extension to V3 — it uses background scripts and blocking webRequest."
+    why: "MV2->MV3 migration map: background page->service worker, webRequest->declarativeNetRequest."
+  - prompt: "Crear una extensión para Chrome que bloquee anuncios con declarativeNetRequest."
+    why: "Spanish phrasing + DNR ad-blocking, the canonical replacement for blocking webRequest."
+  - prompt: "How do I send a message from my content script to the popup when the popup is closed?"
+    why: "Non-obvious cross-context messaging — there is no direct channel; route via service worker or storage."
+
+should_not_trigger:
+  - prompt: "Build a desktop app with web technologies that runs outside the browser."
+    route_to: electron
+    why: "Standalone desktop shell, not a browser extension package."
+  - prompt: "Build me a Next.js dashboard with server components."
+    route_to: nextjs
+    why: "Generic web app — the explicit NOT boundary in the description."
+  - prompt: "Write the privacy policy text for my app's data collection."
+    route_to: gdpr-privacy
+    why: "Legal copy; this skill only says where the privacy URL plugs into the store listing."
+  - prompt: "Build a cross-platform desktop app in Rust with a web frontend."
+    route_to: tauri
+    why: "Native desktop via Rust, not a Chrome extension."
+
+capability:
+  - scenario: "Scaffold a Manifest V3 extension that injects a content script on toolbar click (activeTab, not <all_urls>) and shows a click count in the popup that survives service worker restarts."
+    must_include:
+      - "manifest_version set to 3"
+      - "background.service_worker declared as a string (no background.scripts/page/persistent)"
+      - "activeTab permission rather than <all_urls> host_permissions"
+      - "count persisted with chrome.storage, not a background global variable"
+      - "event listeners registered synchronously at the top level"
+      - "chrome.scripting.executeScript or a declarative content_scripts entry"
+      - "icons (16/48/128) and a privacy/store note for shipping"

package/skills/shared/chrome-extension/references/store-and-migration.md

@@ -0,0 +1,84 @@
+# Chrome Web Store submission + MV2→MV3 migration
+
+Two long branches offloaded from SKILL.md: getting through review, and dragging
+an old MV2 extension to MV3. Facts dated 2026-06-02 from developer.chrome.com.
+
+## Store submission, step by step
+
+1. **Register the developer account.** One-time **$5 USD** fee, covers up to 20
+   extensions on that account. Use a Google account you control long-term — it
+   owns the listings.
+2. **Prepare the package.** Build, then zip the **build output only** (`dist/`).
+   Strip `node_modules`, `.git`, README, and any source map you do not want
+   public. The zip's root must contain `manifest.json`.
+3. **Create the item** in the Developer Dashboard and upload the zip. Bump
+   `version` in `manifest.json` on every upload — the store refuses a duplicate
+   version.
+4. **Listing assets:**
+   - Icon: **128×128 PNG** (the store icon; separate from the toolbar icons).
+   - Screenshots: at least one, **1280×800 or 640×400 PNG/JPEG**. More is better
+     for conversion; show the actual UI, not marketing fluff.
+   - Optional promo tiles and a YouTube link.
+   - A clear, honest **description** and a **category**.
+5. **Privacy practices form.** You must disclose what data you collect and why,
+   certify you do not sell it for unrelated purposes, and provide a
+   **privacy-policy URL** if you collect any user data. The legal copy itself is
+   out of scope here — see `../gdpr-privacy/SKILL.md` and `../data-policy/SKILL.md`;
+   this skill only tells you the URL plugs into this form.
+6. **Permission justifications.** For each permission and each broad host match,
+   the form asks why. Write one concrete sentence per permission. Vague answers
+   ("for functionality") get rejected.
+7. **Submit.** Review is typically **1–3 business days**; simple extensions often
+   under 24h. You can use **staged rollout** to ship a new version to a
+   percentage of users first and halt if metrics tank.
+
+### Surviving review
+
+- Least privilege: every permission must map to a visible feature. `activeTab`
+  over `host_permissions`; specific origins over `<all_urls>`.
+- No remotely hosted code — bundle everything. Reviewers run static checks for
+  remote `<script src>` and `eval` of fetched strings.
+- Single clear purpose per extension; do not bundle unrelated features.
+- If rejected, the email names the policy. Fix the named issue, reply via the
+  **appeals** flow in the dashboard with what changed, and resubmit. Do not
+  silently re-upload the same package.
+
+## MV2 → MV3 migration map
+
+| MV2 | MV3 | Notes |
+|---|---|---|
+| `background.page` / `background.scripts` + `persistent: true` | `background.service_worker` (string), `"type": "module"` for imports | no DOM, no `window`; it terminates when idle |
+| long-lived global state in the background page | `chrome.storage` (+ `chrome.storage.session` for in-memory) | worker restarts wipe globals |
+| `setInterval` / `setTimeout` for periodic work | `chrome.alarms` | timers do not survive worker sleep |
+| blocking `chrome.webRequest` (modify/block requests) | `chrome.declarativeNetRequest` (static + dynamic rules) | DNR never sees request bodies; declare rule resources |
+| `chrome.tabs.executeScript(tabId, {code/file})` | `chrome.scripting.executeScript({ target: { tabId }, files })` | new signature; needs `scripting` permission |
+| `chrome.tabs.insertCSS` | `chrome.scripting.insertCSS` | same shape change |
+| remote `<script src>` / CDN libraries | bundle the library into the package | remote code is banned by MV3 CSP + policy |
+| `browser_action` / `page_action` | unified `action` | one toolbar entry point |
+| MV2-style host access by default | explicit `host_permissions` + prefer `activeTab` | broad hosts now warn loudly at install |
+
+### Migration order that works
+
+1. Flip `manifest_version` to `3` and convert `background` to a `service_worker`
+   string. Move every event listener to the top level, synchronous.
+2. Replace background-page globals with `chrome.storage` reads/writes.
+3. Swap timers for `chrome.alarms`.
+4. Convert `webRequest` blocking rules to `declarativeNetRequest` rule sets.
+5. Update every `tabs.executeScript`/`insertCSS` to the `scripting.*` signature
+   and add the `scripting` permission.
+6. Remove all remote code; bundle dependencies.
+7. Re-audit permissions — MV3 is the moment to drop `<all_urls>` for `activeTab`.
+
+## Recent platform notes (version-dated)
+
+- `chrome.userScripts.execute()` — Chrome 135 (Mar 2025): run dynamic,
+  user-supplied scripts under a dedicated permission.
+- `chrome.sidePanel.getLayout()` — Chrome 140 (Sep 2025).
+- `chrome.storage` viewer/editor in DevTools — Chrome 132 (Jan 2025): inspect
+  extension storage without a debug page.
+- Cross-browser `browser` namespace exposed in Chrome — Chrome 148 (May 2026):
+  the `browser.*` promise-based namespace now works in Chrome too, easing
+  Firefox/Edge portability.
+
+(Source: developer.chrome.com "What's new in Chrome extensions", accessed
+2026-06-02.)

package/skills/shared/chrome-extension/scripts/verify.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# verify.sh — lint a Manifest V3 manifest.json against MV3 invariants.
+# Read-only. Exits 0 on a clean/empty target (no manifest = nothing to check).
+# Usage: scripts/verify.sh [target-dir]   (defaults to current directory)
+set -euo pipefail
+
+TARGET="${1:-.}"
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "verify.sh: node not found; skipping manifest lint." >&2
+  exit 0
+fi
+
+# Find manifest.json files, ignoring build/vendor dirs. No matches => clean pass.
+MANIFESTS="$(
+  find "$TARGET" \
+    -type d \( -name node_modules -o -name dist -o -name .git \) -prune -o \
+    -type f -name manifest.json -print 2>/dev/null
+)"
+
+if [ -z "$MANIFESTS" ]; then
+  echo "verify.sh: no manifest.json under '$TARGET' — nothing to check."
+  exit 0
+fi
+
+FAIL=0
+while IFS= read -r m; do
+  [ -z "$m" ] && continue
+  node - "$m" <<'NODE' || FAIL=1
+const fs = require("fs");
+const path = process.argv[2];
+const errs = [];
+let mf;
+try {
+  mf = JSON.parse(fs.readFileSync(path, "utf8"));
+} catch (e) {
+  console.error(`FAIL ${path}: invalid JSON — ${e.message}`);
+  process.exit(1);
+}
+if (mf.manifest_version !== 3) errs.push(`manifest_version must be 3 (got ${JSON.stringify(mf.manifest_version)})`);
+const bg = mf.background || {};
+if ("scripts" in bg) errs.push("background.scripts is MV2; use background.service_worker (string)");
+if ("page" in bg) errs.push("background.page is MV2; use background.service_worker (string)");
+if ("persistent" in bg) errs.push("background.persistent does not exist in MV3; remove it");
+if (mf.background !== undefined) {
+  if (typeof bg.service_worker !== "string") errs.push("background.service_worker must be a string");
+}
+if (typeof mf.name !== "string" || !mf.name) errs.push("missing name");
+if (typeof mf.version !== "string" || !mf.version) errs.push("missing version");
+if (mf.icons === undefined || typeof mf.icons !== "object") errs.push("missing icons");
+if (errs.length) {
+  console.error(`FAIL ${path}:`);
+  for (const e of errs) console.error(`  - ${e}`);
+  process.exit(1);
+}
+console.log(`OK   ${path}`);
+NODE
+done <<EOF
+$MANIFESTS
+EOF
+
+exit "$FAIL"

package/skills/shared/clarify/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: clarify
+description: "Use when a spec exists and must be de-risked before planning — hunt its ambiguities, unstated assumptions and edge cases, ask the few build-changing questions, bake the answers back into the spec. The ai-hub Spec-Kit gate between `specify` (writes the spec) and `plan` (designs the build). NOT the cross-artifact consistency check (that is `analyze`)."
+tags: [sdd, clarify, questions]
+recommends: [plan]
+profiles: [core, full]
+origin: ai-hub
+---
+
+# Clarify — the de-risking gate before planning
+
+A spec written in one sitting always lies a little. It states what the author *thought of*, and stays silent on everything they didn't — the edge cases, the unstated defaults, the words that mean two things. Those silences don't disappear; they get discovered later, mid-implementation, where they cost ten times as much to fix. **Clarify is the gate that drags those silences into the open while they are still cheap.**
+
+This is the fourth phase of the ai-hub Spec-Kit chain (`constitution` → `specify` → **`clarify`** → `plan` → `tasks` → `analyze` → `implement` → `verify` → `review` → `ship`); the method itself lives in `../sdd/SKILL.md`. `specify` turned a fuzzy intent into a spec; clarify interrogates that spec, asks the user the questions that actually change the build, and writes the answers back so the spec becomes safe to plan from. It produces **no new artifact** — it sharpens the existing one in place. The line is **specify creates, clarify de-risks, plan designs**: if you find yourself proposing how to *build* it, you have left clarify.
+
+**Model tier: `balanced`** — this phase ranks and asks the few high-leverage questions, it does not design architecture. Resolve and apply it per `../sdd/references/model-routing.md`; routing is off unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`.
+
+**Register.** Read `technical_level` from `02-DOCS/wiki/harness/user-profile.md` (the `02-DOCS/wiki/` convention is owned by `../harness/SKILL.md`). Clarify is question-heavy, so the voice matters here more than almost anywhere. Ask only the questions whose answer changes the build; propose safe defaults for everything else and list them as "assumed unless you object". Each question carries one line of *why* and the trade-off behind each option, in the `orient` voice. For a `non-technical` reader, frame each option with an everyday analogy. With no profile: use analogies and ask once "technical or with analogies?".
+
+## Read first — the inputs
+
+Clarify never works blind. Before asking a single question, load three things:
+
+1. **The spec.** Read the target spec under `02-DOCS/wiki/sdd/specs/<slug>.md` end to end. If the path wasn't given, find the most recently touched spec or ask which one. Its *Points to clarify* is a **typed** handoff, not a question list — read the types before you plan a single question (below).
+2. **The constitution.** Read `02-DOCS/wiki/sdd/constitution.md` if it exists. Its principles (stack canon, quality bars, conventions) resolve a surprising number of "ambiguities" without bothering the user — if the constitution already fixes the auth method or the data region, that's answered, not open.
+3. **The harness profile.** `02-DOCS/wiki/harness/user-profile.md`, for the register above.
+
+Citing what you read ("checked the constitution — auth is already fixed to OAuth, so that's not an open question") shows your work and prevents re-litigating settled decisions.
+
+## The typed handoff — what `specify` already decided
+
+*Points to clarify* holds four different objects, and each one gets a different action from you.
+Treating all four as questions is how clarify re-asks what was already decided and disturbs what was
+deliberately deferred:
+
+| Type in the spec | What it means | Your action |
+| --- | --- | --- |
+| **pregunta abierta** | Formulable, unanswered | Ask it — this is your queue |
+| **suposición tomada** | `specify` decided it; the basis is written | **Validate**, don't re-ask: state the assumption and its basis back, and ask only whether it still holds |
+| **decisión diferida** | Sharp, out of this cycle on purpose | Leave it. Do not reopen scope the author closed |
+| **área no formulable** | Known to be coming, not yet phrasable | Note it. If your pass sharpens it into a real question, it graduates — say that it did |
+
+**Declare what you did with each entry.** Close the pass with one line per point: asked, validated
+(held / broke), left deferred, or graduated. An entry you silently dropped is the gap that comes back
+at implementation time.
+
+**An untyped entry** (an older spec, or a hurried one) is read as **pregunta abierta** — the
+costliest reading, so nothing gets skipped by accident. Type it as you go, so the spec improves on
+the way through.
+
+Sharpness, not difficulty, is what separates a question from an unformulable area: *can you state it
+precisely now?* Not *can you answer it?*
+
+## The ambiguity taxonomy — where specs hide their gaps
+
+Scan the spec against these categories. Most real gaps fall into one of them; walking the list is how you find the ones the author didn't think to write down.
+
+| Category | What to hunt | Tell-tale phrasing in the spec |
+| --- | --- | --- |
+| **Underspecified behavior** | A described feature with a missing branch — what happens in the *other* case | "the user logs in" (and if it fails? locked out? wrong password vs no account?) |
+| **Unstated assumptions** | Defaults the author assumed everyone shares | no mention of auth, tenancy, currency, timezone, locale |
+| **Edge & boundary cases** | Empty, zero, max, duplicate, concurrent, first-run, offline | lists with no empty-state, counts with no upper bound |
+| **Ambiguous terms** | A word doing two jobs | "user" (end-user or admin?), "delete" (soft or hard?), "fast" (how fast?) |
+| **Missing acceptance criteria** | A goal with no observable done-condition | "should be performant", "easy to use", "handle errors gracefully" |
+| **Scope edges** | What's explicitly OUT vs left dangling | features hinted at but never bounded — "for now", "eventually" |
+| **Data & state** | Lifecycle, ownership, retention, migration of existing data | new entity with no story for what happens to old records |
+| **Failure & recovery** | What happens when a dependency is down, a write half-completes, input is hostile | happy-path-only flows |
+| **Non-functional** | Performance, scale, security, accessibility, i18n targets | vague "non-functional requirements" or none at all |
+| **Actors & permissions** | Who can do each thing | a verb with no subject — "can be edited" (by whom?) |
+
+You are not filling every cell for every spec. You are scanning all ten so the gaps that *do* exist surface instead of hiding.
+
+## The pass — five steps
+
+Run in order. The discipline is: find many candidate gaps, keep only the ones that change the build, ask those well, write the answers back.
+
+1. **Inventory.** Walk the spec against the taxonomy above. Produce a raw list of every candidate ambiguity, edge case, and unstated assumption. Over-collect here; you'll prune next. Note for each which category it is and where in the spec it lives.
+
+2. **Resolve what you already can.** For each candidate, check the constitution and the spec's own later sections before asking the user. Many "gaps" are answered elsewhere. Mark each candidate **resolved-internally** (cite the source), **inferable** (a safe default you'll propose, not silently assume), or **must-ask** (only the user can decide).
+
+3. **Rank by leverage.** Sort the must-ask list by impact: how much does the build change depending on the answer? A question whose two answers lead to two different architectures ranks above a cosmetic one. Cut low-leverage questions — clarify is not an interrogation, it's the *few* questions that matter.
+
+4. **Ask — one focused batch.** How you ask determines whether you get a usable answer:
+   - **Make it a decision, not an essay prompt.** "Should deletes be soft (recoverable, hidden) or hard (gone immediately)? I'd recommend soft because the spec mentions an audit trail — confirm?" beats "How should deletion work?".
+   - **Carry your own recommendation** when there's a defensible default, matched to the constitution. The user confirms or overrides — far less effort than authoring from scratch.
+   - **Quote the spec.** Anchor each question to the exact line or section it came from, so the user sees *why* it's open.
+   - **One batch, ranked, then stop.** Don't drip questions one at a time over many turns; don't dump thirty at once. Then wait: never ask and answer in the same breath, and never assume the user's intent on a must-ask item.
+
+5. **Bake the answers back into the spec.** This is the deliverable — an un-baked answer is a lost answer. For each resolved item, edit the spec in place:
+   - Tighten the relevant section with the decided behavior.
+   - Add or sharpen acceptance criteria so the decision is now observable.
+   - Append a `## Clarifications` log to the spec: dated entries of `Q → decision → why`, so the *reasoning* survives, not just the result.
+   - Move anything explicitly dropped into an `## Out of scope` section so it's bounded, not dangling.
+
+   Then re-read the spec once more: did resolving one gap open a new one? If so, one more short loop. Otherwise, the gate is passed.
+
+## Worked micro-example
+
+Spec line: *"Users can upload a profile photo."*
+
+Clarify's inventory against the taxonomy:
+
+```text
+- Ambiguous term  : "photo" — which formats? (PNG/JPG/HEIC/SVG?)
+- Boundary        : max file size? max dimensions? what if it's 50 MB?
+- Edge case       : no photo uploaded — is there a default/placeholder?
+- Failure         : upload fails mid-transfer — retry, or lose it?
+- Data lifecycle  : replacing a photo — is the old file deleted or orphaned?
+- Actors          : can an admin change another user's photo?
+- Non-functional  : is the image resized/compressed server-side? stored where?
+- Security        : is the file type validated, or can someone upload an .svg with script?
+```
+
+Resolved-internally (cite): constitution fixes storage to the project's object store → "stored where" is answered. Must-ask, ranked: formats + max size (changes validation and UX), security validation (changes the upload path), old-file deletion (changes data model). Cosmetic placeholder choice → propose a default, don't burn a question on it.
+
+After baking back, the spec line becomes a bounded, testable behavior with acceptance criteria ("rejects files >5 MB with a clear message", "accepts PNG/JPG/HEIC only", "replacing a photo deletes the prior file") and a `## Clarifications` entry recording why.
+
+## Anti-patterns
+
+| Anti-pattern | Why it breaks the gate / do instead |
+| --- | --- |
+| Skipping clarify because the spec "reads clear enough" | Clear to the author ≠ unambiguous. Run the taxonomy; the gaps you can't see are exactly the expensive ones. |
+| Assuming the sensible default and moving on | An assumption is an unrecorded decision. Either it's resolvable from the constitution (cite it) or it's a must-ask. Silent defaults resurface as bugs — and "the user is busy" is not an exception; a wrong guess costs more than a one-tap question. |
+| Sketching how you'd build it while you're in there | That's `plan`. Clarify decides *what*, not *how*. Proposing architecture means you left the gate. |
+| Asking everything you can think of, to be safe | Thirty questions is noise that buries the three that matter. Rank by leverage, ask the few, default the rest — and batch them once instead of dripping one per turn. |
+| Answering the questions in your head and leaving the spec as-is | The deliverable is the *edited spec* plus the Clarifications log, not a clean conscience. |
+| Leaving edge cases "to the implementer" | Edge cases are *spec* problems. Resolving them now is the whole point of the gate. |
+
+## Exit gate
+
+The gate is passed when the spec, constitution and profile were all read (settled questions cited, not re-asked); **every typed point in the handoff has its declared outcome** (asked / validated / left deferred / graduated), with nothing silently dropped; all ten taxonomy categories were considered; only the build-changing gaps were put to the user, as one ranked batch of decisions with recommendations; every answer is baked into the spec body with observable acceptance criteria, logged under `## Clarifications` and bounded under `## Out of scope`; and the final re-read opened no new gap.
+
+## Result envelope
+
+End with the parseable block every SDD phase shares, so the dispatcher can chain without
+interpreting prose (contract: `../sdd/SKILL.md`):
+
+```json result-envelope
+{
+  "status": "complete|blocked|failed",
+  "executive_summary": "Open points resolved; the spec is de-risked and ready to plan against.",
+  "artifact": "02-DOCS/wiki/sdd/specs/<slug>.md",
+  "next_recommended": "plan",
+  "risk": "low|medium|high",
+  "skill_resolution": {
+    "used": ["clarify"],
+    "missing": [],
+    "fallback": [],
+    "compact_rules": ["Ask only what changes the spec.", "An unanswered question is recorded, never invented."]
+  },
+  "evidence": ["answers folded back into the spec", "remaining open points listed with their owner"]
+}
+```
+
+## Next in the chain
+
+Hand off to **`plan`** — turn the now-sharp spec into a technical implementation plan (architecture, interfaces, data flow, testing strategy, risks), deferring stack specifics to the relevant stack skill. The chain continues: clarify → **plan** → tasks → analyze → implement → verify → review → ship. `debug` is callable any time if what you are "clarifying" turns out to be a runtime fault, not a spec gap.
+
+## Orientación (siempre)
+
+Habla con la voz de `orient`: frases cortas, una idea por frase, y cada respuesta se entiende sola. Registro técnico o con analogías según `technical_level` en `02-DOCS/wiki/harness/user-profile.md`. Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ➡️ siguiente, terminando en pregunta; ✅ y 🧭 cuando hay algo hecho o decidido). **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el "¿instalo la skill que falta?".)

package/skills/shared/clarify/evals/README.md

@@ -0,0 +1,70 @@
+# Eval harness — `clarify` skill
+
+These evals check two things: that the skill **triggers** on the right prompts
+(and stays quiet on near-misses that belong to a neighbouring SDD phase), and
+that it **measurably improves** the de-risking pass over a spec. Cases live in
+`cases.yaml`. There is no pure shell runner — grading is a judgment call done by
+an **agent harness** (a Claude Code agent with the skill catalog loaded) plus a
+human spot-check.
+
+## What's in `cases.yaml`
+
+- `should_trigger` — prompts that MUST load `clarify` (a spec exists; the user
+  wants it de-risked / hole-poked / readiness-checked before planning).
+- `should_not_trigger` — near-misses routed to the genuinely correct sibling
+  via `route_to` (`specify`, `plan`, `analyze`, `debug`, `constitution`).
+- `capability` — a scenario with a `must_include` rubric to grade WITH vs
+  WITHOUT the skill loaded.
+
+## Triggering eval
+
+Goal: the skill fires when a spec needs de-risking, and never on an adjacent
+SDD phase.
+
+1. Configure an agent with the **full catalog of skill descriptions** available
+   for routing — the SDD chain siblings (`specify`, `plan`, `analyze`, `debug`,
+   `constitution`, and the rest) plus the stack/process skills (`harness`,
+   `init`, `fastapi`, `nextjs`, `go`, `postgresdb`, `flutter`, `design`,
+   `marketing`, …) so routing competes realistically.
+2. For each `should_trigger` prompt: feed it cold and record whether `clarify`
+   is the skill loaded. Run **3–5 trials** per prompt with fresh context.
+3. For each `should_not_trigger` prompt: confirm `clarify` does NOT load and
+   that the chosen skill matches `route_to`. Same 3–5 trials.
+4. Score: `triggered_correctly / total_trials` across both lists.
+
+**Pass bar: ≥ 90% trigger accuracy** over all prompts and trials, with **zero
+systematic false-positives** on the `specify` and `plan` near-misses — those are
+the known traps. The boundary clarify must hold: no-spec-yet is `specify`,
+how-to-build-it is `plan`. If it grabs either, the description is leaking.
+
+## Capability eval
+
+Goal: prove the skill changes the de-risking pass, not just the routing.
+
+1. For the `capability` scenario, run it **twice**:
+   - **WITHOUT** the skill (base agent, no `clarify` loaded).
+   - **WITH** the `clarify` skill loaded.
+2. Grade each output against the `must_include` checklist — one point per
+   checkable item covered. A human or grading agent marks each present / absent.
+3. Compute coverage = `items_covered / total_items` per run.
+
+**Pass bar: WITH the skill covers ≥ 80% of `must_include`; WITHOUT clearly
+lower** (target a ≥ 30-point gap). The discriminating behaviors are the ones a
+base agent reliably misses: reading the constitution and citing what's already
+resolved, ranking gaps by leverage instead of dumping every question, framing
+questions as decisions-with-a-recommendation, and — the highest-signal item —
+actually **baking answers back into the spec with a dated Clarifications log**
+rather than just listing questions in chat.
+
+## Notes on honesty
+
+- Trials are stochastic; report the raw fraction, not a rounded "pass".
+- The single highest-signal capability check is **the edit-back**: an answer
+  that asks good questions but never modifies the spec or records the reasoning
+  is a capability failure even if the questions are sharp. Clarify's deliverable
+  is the sharpened spec, not the conversation.
+- A second tell: a base agent often slides into proposing *how to build* the
+  feature. A correct clarify pass stays on WHAT and defers HOW to `plan`. Treat
+  architecture suggestions as a scope-leak failure.
+- Re-run after any edit to `SKILL.md` — wording changes shift both triggering
+  (especially the `specify`/`plan` boundary) and rubric coverage.