@ericrisco/rsc 1.0.25 → 1.0.27

package/skills/git-workflow/references/gitmoji.md

@@ -0,0 +1,157 @@
+# gitmoji — the full set, and the tooling that has to accept it
+
+The commit rule lives in `../SKILL.md`: **every commit opens with a gitmoji, then the
+Conventional Commits header.** This file is the lookup table and the tooling escape hatches — read
+it when you need the right glyph for an intention, or when a parser in the repo rejects the format.
+
+```text
+<gitmoji> type(scope)!: imperative subject
+```
+
+The gitmoji says *what kind of intention* this is at a glance in `git log --oneline`; the `type`
+still drives the SemVer bump. They are two different jobs and neither replaces the other — a commit
+with 💥 but no `!`/`BREAKING CHANGE:` footer still releases as a MINOR, because tooling reads the
+type, not the picture.
+
+## Picking one
+
+Match the **intention**, not the file that changed. If two fit, take the more specific one (🚑️ over
+🐛 for a production hotfix; 🩹 over 🐛 for a trivial non-critical fix). The `semver` column is
+gitmoji's own hint, not a substitute for the type → bump table in `../SKILL.md`.
+
+The everyday dozen, mapped to the conventional types:
+
+| Type       | gitmoji | Type        | gitmoji |
+|------------|---------|-------------|---------|
+| `feat`     | ✨      | `perf`      | ⚡️      |
+| `fix`      | 🐛      | `ci`        | 👷      |
+| `docs`     | 📝      | `build`     | 📦️      |
+| `refactor` | ♻️      | `style`     | 🎨      |
+| `test`     | ✅      | `revert`    | ⏪️      |
+| `chore`    | 🔧      | breaking    | 💥      |
+
+## The full set
+
+Canonical source: <https://gitmoji.dev> (machine-readable at `https://gitmoji.dev/api/gitmojis`).
+The same 75 rows are enforced as data by the gitmoji guard, and a test compares this table against
+it — if the two ever disagree, CI says so.
+
+| Emoji | Code | SemVer | Intention |
+|-------|------|--------|-----------|
+| 🎨 | `:art:` | — | Improve structure / format of the code |
+| ⚡️ | `:zap:` | patch | Improve performance |
+| 🔥 | `:fire:` | — | Remove code or files |
+| 🐛 | `:bug:` | patch | Fix a bug |
+| 🚑️ | `:ambulance:` | patch | Critical hotfix |
+| ✨ | `:sparkles:` | minor | Introduce new features |
+| 📝 | `:memo:` | — | Add or update documentation |
+| 🚀 | `:rocket:` | — | Deploy stuff |
+| 💄 | `:lipstick:` | patch | Add or update the UI and style files |
+| 🎉 | `:tada:` | — | Begin a project |
+| ✅ | `:white_check_mark:` | — | Add, update, or pass tests |
+| 🔒️ | `:lock:` | patch | Fix security or privacy issues |
+| 🔐 | `:closed_lock_with_key:` | — | Add or update secrets |
+| 🔖 | `:bookmark:` | — | Release / Version tags |
+| 🚨 | `:rotating_light:` | — | Fix compiler / linter warnings |
+| 🚧 | `:construction:` | — | Work in progress |
+| 💚 | `:green_heart:` | — | Fix CI Build |
+| ⬇️ | `:arrow_down:` | patch | Downgrade dependencies |
+| ⬆️ | `:arrow_up:` | patch | Upgrade dependencies |
+| 📌 | `:pushpin:` | patch | Pin dependencies to specific versions |
+| 👷 | `:construction_worker:` | — | Add or update CI build system |
+| 📈 | `:chart_with_upwards_trend:` | patch | Add or update analytics or track code |
+| ♻️ | `:recycle:` | — | Refactor code |
+| ➕ | `:heavy_plus_sign:` | patch | Add a dependency |
+| ➖ | `:heavy_minus_sign:` | patch | Remove a dependency |
+| 🔧 | `:wrench:` | patch | Add or update configuration files |
+| 🔨 | `:hammer:` | — | Add or update development scripts |
+| 🌐 | `:globe_with_meridians:` | patch | Internationalization and localization |
+| ✏️ | `:pencil2:` | patch | Fix typos |
+| 💩 | `:poop:` | — | Write bad code that needs to be improved |
+| ⏪️ | `:rewind:` | patch | Revert changes |
+| 🔀 | `:twisted_rightwards_arrows:` | — | Merge branches |
+| 📦️ | `:package:` | patch | Add or update compiled files or packages |
+| 👽️ | `:alien:` | patch | Update code due to external API changes |
+| 🚚 | `:truck:` | — | Move or rename resources (e.g.: files, paths, routes) |
+| 📄 | `:page_facing_up:` | — | Add or update license |
+| 💥 | `:boom:` | major | Introduce breaking changes |
+| 🍱 | `:bento:` | patch | Add or update assets |
+| ♿️ | `:wheelchair:` | patch | Improve accessibility |
+| 💡 | `:bulb:` | — | Add or update comments in source code |
+| 🍻 | `:beers:` | — | Write code drunkenly |
+| 💬 | `:speech_balloon:` | patch | Add or update text and literals |
+| 🗃️ | `:card_file_box:` | patch | Perform database related changes |
+| 🔊 | `:loud_sound:` | — | Add or update logs |
+| 🔇 | `:mute:` | — | Remove logs |
+| 👥 | `:busts_in_silhouette:` | — | Add or update contributor(s) |
+| 🚸 | `:children_crossing:` | patch | Improve user experience / usability |
+| 🏗️ | `:building_construction:` | — | Make architectural changes |
+| 📱 | `:iphone:` | patch | Work on responsive design |
+| 🤡 | `:clown_face:` | — | Mock things |
+| 🥚 | `:egg:` | patch | Add or update an easter egg |
+| 🙈 | `:see_no_evil:` | — | Add or update a .gitignore file |
+| 📸 | `:camera_flash:` | — | Add or update snapshots |
+| ⚗️ | `:alembic:` | patch | Perform experiments |
+| 🔍️ | `:mag:` | patch | Improve SEO |
+| 🏷️ | `:label:` | patch | Add or update types |
+| 🌱 | `:seedling:` | — | Add or update seed files |
+| 🚩 | `:triangular_flag_on_post:` | patch | Add, update, or remove feature flags |
+| 🥅 | `:goal_net:` | patch | Catch errors |
+| 💫 | `:dizzy:` | patch | Add or update animations and transitions |
+| 🗑️ | `:wastebasket:` | patch | Deprecate code that needs to be cleaned up |
+| 🛂 | `:passport_control:` | patch | Work on code related to authorization, roles and permissions |
+| 🩹 | `:adhesive_bandage:` | patch | Simple fix for a non-critical issue |
+| 🧐 | `:monocle_face:` | — | Data exploration/inspection |
+| ⚰️ | `:coffin:` | — | Remove dead code |
+| 🧪 | `:test_tube:` | — | Add a failing test |
+| 👔 | `:necktie:` | patch | Add or update business logic |
+| 🩺 | `:stethoscope:` | — | Add or update healthcheck |
+| 🧱 | `:bricks:` | — | Infrastructure related changes |
+| 🧑‍💻 | `:technologist:` | — | Improve developer experience |
+| 💸 | `:money_with_wings:` | — | Add sponsorships or money related infrastructure |
+| 🧵 | `:thread:` | — | Add or update code related to multithreading or concurrency |
+| 🦺 | `:safety_vest:` | — | Add or update code related to validation |
+| ✈️ | `:airplane:` | — | Improve offline support |
+| 🦖 | `:t-rex:` | — | Code that adds backwards compatibility |
+## Tooling that has to accept the format
+
+Emoji-first is what gitmoji itself prescribes and what `gitmoji -c` writes, but a **strict
+Conventional Commits parser anchors the type at position 0** and will reject the header. Two honest
+ways out, in order of preference:
+
+**1. Teach the parser about the prefix.** commitlint, with the emoji allowed before the type:
+
+```js
+// commitlint.config.js
+export default {
+  extends: ['@commitlint/config-conventional'],
+  parserPreset: {
+    parserOpts: {
+      // <emoji> type(scope)!: subject
+      headerPattern: /^(?:\S+\s)?(\w+)(?:\(([^)]*)\))?(!)?: (.+)$/,
+      headerCorrespondence: ['type', 'scope', 'breaking', 'subject'],
+    },
+  },
+};
+```
+
+semantic-release / conventional-changelog take the same `parserOpts` under
+`@semantic-release/commit-analyzer` and `@semantic-release/release-notes-generator`. Set it in
+**both** or the bump and the changelog disagree about the same commit.
+
+**2. Put the emoji after the header** — `feat(api): ✨ add cursor paging`. Every conventional parser
+accepts it unmodified, and the guard accepts it too. Prefer this in a repo whose release pipeline
+you do not own.
+
+What **not** to do: drop the type and commit `✨ add cursor paging` (gitmoji's own minimal form).
+It is valid gitmoji and useless for releases — nothing can derive the bump, so the version has to be
+hand-picked, which `../SKILL.md` forbids for a reason.
+
+## Related
+
+- `gitmoji-cli` (`npm i -g gitmoji-cli`, then `gitmoji -c`) prompts for the emoji and writes the
+  commit. Optional — the convention is the rule, the CLI is one way to type it.
+- On Claude Code, rsc wires a `gitmoji-guard` PreToolUse hook that denies a `git commit` whose
+  message has no gitmoji, with the corrected message in the refusal. It only judges messages it can
+  actually read (`-m`, heredoc) and never blocks an editor commit, a `-F` file, or `--amend
+  --no-edit`. Opt out per project with `.rsc/.no-gitmoji`.

package/skills/ship/SKILL.md

@@ -184,7 +184,7 @@ cleanup). If a native `EnterWorktree`-style tool created it, exit through that t
 
 The commit is the durable record. Make it describe the change and tie it to the spec — and keep it Eric's.
 
-- **Subject:** `type: imperative summary (<spec-slug>)` — `feat:`, `fix:`, `refactor:`, etc. Under ~72 chars.
+- **Subject:** `<gitmoji> type: imperative summary (<spec-slug>)` — `✨ feat:`, `🐛 fix:`, `♻️ refactor:`, etc. Under ~72 chars. The gitmoji is **not optional**: on Claude Code a PreToolUse guard denies a `git commit -m` without one, and the refusal hands back the corrected message. Emoji → intention table: `../git-workflow/references/gitmoji.md`.
 - **Body:** *why*, not a restatement of the diff. Reference the spec slug and any decision logged in `decisions.md`.
 - **Footer:** issue/PR refs only. **No `Co-Authored-By` for any AI. No "generated with" line.** This is where the violation usually sneaks in — leave the footer clean.
 
@@ -212,6 +212,7 @@ Read the level from `02-DOCS/wiki/harness/user-profile.md`. It changes what you
 | "The tree has a couple of stray edits, they're harmless" | A dirty tree means the merge is not the reviewed diff. Clean it or stash it first. |
 | "`main` is protected but I'll just force-merge, I'm sure" | Protected means PR. Don't bypass the gate the repo deliberately set. |
 | "I'll rebase and resolve conflicts during the merge" | Resolve before. A conflicted merge commit hides what actually shipped. |
+| "The gitmoji is decoration, the conventional type is what matters" | Both ship or neither does. The type is for tooling, the emoji for the human scanning `git log` — and the guard denies the commit either way. |
 | "This branch is dead, I'll just delete it" | Discard is destructive — confirm with the quoted branch name and log why first. |
 | "Squash everything, history doesn't matter" | Squash noise, preserve meaning. The history is the next reader's spec. |
 | "There's a key in the diff but it's a test key" | A secret in the diff is a blocker regardless. Pull it out before landing. |

package/skills/specify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: specify
-description: "Use when a feature, change, or product idea is still fuzzy and must become an approved WHAT/WHY spec before any planning or code — the brainstorming front door of SDD. Turns a one-line intent into problem, goals, users, scope, behaviour and acceptance criteria, via one-question-at-a-time dialogue and 2-3 approaches with a recommendation, carrying zero implementation detail. Fires whenever someone jumps to HOW before WHAT is agreed, in any language. NOT the technical plan (that is `plan`), NOT the de-risking ambiguity sweep (that is `clarify`), NOT project-wide principles (that is `constitution`)."
+description: "Use when a feature, change, or product idea is still fuzzy and must become an approved WHAT/WHY spec before any planning or code — the brainstorming front door of SDD. Turns a one-line intent into problem, goals, users, scope, behaviour and acceptance criteria, via frontier-round dialogue and 2-3 approaches with a recommendation, carrying zero implementation detail. Fires whenever someone jumps to HOW before WHAT is agreed, in any language. NOT the technical plan (that is `plan`), NOT the de-risking ambiguity sweep (that is `clarify`), NOT project-wide principles (that is `constitution`)."
 tags: [sdd, spec, requirements]
 recommends: [clarify, plan]
 profiles: [core, full]
@@ -29,9 +29,11 @@ A **yes engages autopilot** (`../sdd/SKILL.md`): you still write the spec and ev
 
 ## The one rule that defines this skill
 
-**No implementation leaks.** The moment the spec names a framework, a table schema, a library, an endpoint shape, a file path, or an algorithm, it has stopped being a spec. Those decisions belong to `plan` and the stack skills. Specify describes the *observable behaviour and the reason for it*; the system that delivers it is deliberately left open.
+A spec is a **contract**: what the system will observably do, and why that matters. Every line either belongs in the contract or belongs to how the contract gets honoured — and the second kind is `plan`'s, not yours. Framework, table schema, library, endpoint shape, file path, algorithm: all of them are how, so the moment one appears the document has stopped being a contract.
 
-If you cannot describe a requirement without naming the technology, you have found a real question — record it as a point to clarify, do not guess the answer.
+One question settles every judgement call in this skill: **is this a clause of the contract, or a detail of how it gets met?**
+
+If you cannot state a requirement without naming the technology, that is a real open question — record it as a typed point to clarify, do not guess the answer.
 
 ## Model tier — `balanced` (opt-in routing)
 
@@ -41,23 +43,25 @@ This phase's default model tier is **`balanced`** — it drafts the what/why spe
 
 Before asking anything, read `02-DOCS/wiki/harness/user-profile.md` for the technical level and accompaniment level, and adapt:
 
-- **L0 "cavernícola"** — infer aggressively from the intent and any existing wiki/constitution. Ask only the questions whose answer would change the spec's scope. Draft, show, move on.
+- **L0 "cavernícola"** — infer aggressively from the intent and any existing wiki/constitution. Ask only the questions whose answer would change the contract. Draft, show, move on.
 - **L1 "breve"** — one line of *why* per question; ask the few that genuinely matter.
 - **L2 "explica decisiones"** — justify each requirement as you record it; surface the trade-offs you inferred.
-- **L3 "acompañamiento total"** — explain what a spec is and is not, walk every section, ask freely (still one question at a time), confirm each answer before recording it. Ideal for non-technical users.
+- **L3 "acompañamiento total"** — explain what a spec is and is not, walk every section, ask freely (still one round per frontier, never crossing a dependency), confirm each answer before recording it. Ideal for non-technical users.
 
 If no profile exists, default to non-technical framing and keep questions plain. Never assume fluency.
 
-## Questioning discipline — one at a time, only where you can't infer
+## Questioning discipline — ask the frontier, never cross a dependency
 
-The failure mode of specs is the wall of twenty questions. Avoid it:
+The failure mode of specs is the wall of twenty questions. The cure is not one question per turn: that spends a turn of the user's time per question even when the questions do not touch each other. The cure is the **frontier**.
 
 1. **Infer first.** Read the `constitution` (`02-DOCS/wiki/sdd/constitution.md`), the existing wiki, and sibling specs. Fill every section you reasonably can from what already exists.
-2. **Ask only the gaps that change the spec.** A question earns its place only if a different answer would change scope, a goal, a user, or an acceptance criterion. Cosmetic gaps become *points to clarify*, not questions.
-3. **One focused question per turn.** Ask, wait, record, then ask the next. Never batch. Phrase in the user's technical register.
-4. **When inference and asking both fail, mark it.** Anything you cannot resolve in this pass becomes an explicit entry in *Points to clarify* — that list is the handoff contract to the `clarify` phase, not a defect.
+2. **Ask only the gaps that change the contract.** A gap earns a question only if a different answer would move scope, a goal, a user, or an acceptance criterion. Cosmetic gaps become typed *points to clarify*, not questions.
+3. **Ask the whole frontier in one round.** The frontier is every remaining gap whose prerequisites are already settled — the questions you can ask *now* without guessing at answers you have not heard yet. Number them, give each your recommended answer, then wait. Where the harness offers a native question selector, use it; where it does not, emit the same round as numbered text.
+4. **Never cross a dependency.** A gap whose answer depends on another question open in *this* round belongs to a later round. Recompute the frontier after every set of answers: settled decisions push it outward and unblock what waited on them. If an answer redefines a question you already emitted in the same round, discard that question out loud and re-ask it next round rather than using an answer given under a premise that just moved.
+5. **Facts are your job; decisions are the user's.** When a frontier question needs a fact from the environment, go find it — and do not block on it. A running search is an unsettled prerequisite, so only the questions downstream of it wait; ask the rest of the frontier now.
+6. **When inference and asking both fail, type it.** Anything unresolved becomes a typed entry in *Points to clarify* — the handoff contract to `clarify`, not a defect.
 
-Stop asking when the WHAT and WHY are complete enough to plan against. Remaining unknowns live in *Points to clarify*; you do not need every answer before writing the file.
+A frontier of one is one question, and needs no apology. A frontier of zero is no question at all: never invent one to look diligent.
 
 ## What a good spec contains
 
@@ -71,7 +75,7 @@ Write these sections into `02-DOCS/wiki/sdd/specs/<slug>.md` using `references/s
 | Users & context | Who acts, their context, what they're trying to achieve | An imagined user no one asked for |
 | Behaviour | What the system does, in observable terms, incl. main + edge + error paths | A verb that's actually a HOW ("queries", "caches") |
 | Acceptance criteria | Testable, binary checks that say "done" | Vague critera ("works well", "is fast") |
-| Points to clarify | Open questions, assumptions made, decisions deferred | Pretending there are none |
+| Points to clarify | The typed handoff to `clarify` — see the four types below | An untyped list, or pretending there are none |
 
 ### Acceptance criteria carry the weight
 
@@ -85,6 +89,33 @@ Then they see an empty-cart message and the "pay" button is disabled
 
 A criterion that needs a human to "decide if it's good enough" is not done yet — sharpen it or move the soft part to *Points to clarify*.
 
+### Points to clarify carry a type
+
+*Points to clarify* is the handoff to `clarify`, and it holds four different objects that need four
+different actions. An untyped list makes `clarify` treat all of them as questions, so it re-asks what
+you already decided and touches what you deliberately deferred. Type every entry:
+
+| Type | What it is | What `clarify` does with it |
+| --- | --- | --- |
+| **pregunta abierta** | Formulable with precision right now, unanswered | Asks it |
+| **suposición tomada** | You decided it; the basis is written down | Validates it — does it still hold? |
+| **decisión diferida** | Sharp, out of this cycle on purpose | Leaves it alone |
+| **área no formulable** | Known to be coming, not yet sharp enough to phrase | Notes it; it graduates when it sharpens |
+
+The test that separates the last two from a question is **sharpness, not difficulty**: *can you state
+the question precisely now?* — not *can you answer it?* Sharp → **pregunta abierta**. Not sharp →
+**área no formulable**. Beyond what this change is for → `Non-goals`, where it never graduates.
+
+Write the type in bold at the head of the entry, and give a `suposición tomada` its basis:
+
+```text
+- **suposición tomada** — el enlace caduca en minutos, no en horas. *Base:* el patrón de los
+  proveedores que ya usamos. *Riesgo:* si el soporte pide horas, el criterio de aceptación cambia.
+```
+
+An entry with no type is read as **pregunta abierta**, the costliest of the four. The default never
+saves you work.
+
 ## The pass, end to end
 
 Run these in order. It is a collaborative dialogue, not a form you fill in silence — and **you do not skip to a design dump.** Track the steps with a todo list so none is dropped.
@@ -94,23 +125,40 @@ Run these in order. It is a collaborative dialogue, not a form you fill in silen
 2. SCOPE check            → if the request is several independent subsystems, DECOMPOSE into sub-specs first,
                             then brainstorm the FIRST one; each gets its own spec → plan → build cycle
 3. RESTATE in one sentence→ confirm you understood the intent before anything else
-4. ASK, one at a time     → only the gaps that change scope; multiple-choice when you can; wait, record, repeat
+4. ASK the frontier       → only gaps that change the contract; whole frontier per round, numbered, each
+                            with your recommendation; never cross a dependency; wait, record, recompute
 5. PROPOSE 2-3 approaches → distinct directions with honest trade-offs; lead with your recommendation and why
 6. PRESENT the design     → section by section (problem, users, behaviour, acceptance), scaled to complexity;
                             after EACH section ask "does this look right?" and adjust before moving on
 7. WRITE the spec         → 02-DOCS/wiki/sdd/specs/<slug>.md (WHAT/WHY), index it in 02-DOCS/wiki/index.md
                             (the Knowledge map; root CLAUDE.md keeps only a short pointer), commit if a repo
-8. SELF-REVIEW            → scan for TODO/placeholder, contradictions, ambiguity, scope creep; fix inline.
-                            On L2/L3 or a high-risk spec, also dispatch a FRESH-EYES review (below)
+8. SELF-REVIEW            → run the EXIT GATE (below) until green; scan for contradictions, ambiguity,
+                            scope creep; fix inline. On L2/L3 or high risk, add a FRESH-EYES review
 9. USER APPROVES          → ask them to read the written spec and confirm; loop on changes until they approve
 10. HAND OFF              → only now, result envelope → clarify/plan. NEVER to implement.
 ```
 
-**The gate is steps 5-9, and it is the point of this skill.** Implementation does not begin — not `plan`-to-code, not a stack skill, not "just a quick version" — until the user has approved the design at step 9. This holds for **every** feature, including ones that feel too small to design; "too simple to spec" is exactly where unexamined assumptions cost the most. The only thing that skips the loop is a literal one-line, zero-risk change (a typo, a copy tweak) — name it as such and do it.
-```
+**Steps 5-9 are the gate**, stated once under *Detect the moment* above and not restated here: approval at step 9 is what unlocks implementation.
 
 `<slug>` is a short kebab-case name derived from the feature (e.g. `bulk-csv-import`, `magic-link-login`). If a spec with that slug exists, read it and update rather than overwrite.
 
+### Exit gate — checked, not felt
+
+"Complete enough to plan against" cannot tell done from not-done, and the write/review/approve steps
+are visible while you are still asking, pulling attention toward being finished. So the bound is a
+property of the **file**, not of your confidence:
+
+> Every template section carries content or an explicit typed open point, and no section holds an
+> unmarked assumption.
+
+Run `npm run spec:gate <path>` on the spec you just wrote (no path: the whole corpus). It reports the
+missing and the empty sections by name, and it prints what it does **not** check — the unmarked
+assumption is yours to catch, because no parser can. A red gate means the spec is not closed: name
+the section that failed and fix it before step 9.
+
+A gate that has never been seen fail is not known to work, so this one ships with the test that
+watches it fail and pass (`tests/spec-gate.test.js`).
+
 ### Fresh-eyes spec review (step 8, scaled to the dial)
 
 The author's own context is blind to its own gaps — the same mind that wrote the spec self-reviews it
@@ -191,8 +239,12 @@ A returning user on a new device who does not remember a password.
   link can be requested.
 
 ## Points to clarify
-- Link validity window? (assumed: short, exact value deferred to clarify)
-- Rate-limit on requests per email? (deferred)
+- **pregunta abierta** — ¿cuánto vale la ventana de validez del enlace?
+- **suposición tomada** — la ventana es corta, en minutos. *Base:* el patrón de los proveedores que
+  ya usamos. *Riesgo:* si soporte pide horas, cambia el criterio de aceptación.
+- **decisión diferida** — límite de peticiones por email; fuera de este ciclo.
+- **área no formulable** — qué pasa con las cuentas compartidas; sospecho que hay una pregunta y
+  todavía no sé enunciarla.
 ```
 
 Note what is *absent*: no token format, no table, no email provider, no framework. Those are `plan`'s job.
@@ -226,17 +278,16 @@ The proposal is allowed to mention options and tradeoffs; the spec that follows
 
 ## Anti-patterns → STOP
 
+Only failures with no positive statement elsewhere in this skill. The rules about the frontier, the
+constitution, the 2-3 approaches, the gate, and answer-is-not-approval are stated positively above
+(§Questioning discipline, §Detect the moment, the pass, §Approval is its own exchange) and are not
+repeated here as prohibitions: naming a behaviour makes it more available, not less.
+
 | If you're about to… | Reality / Fix |
 | --- | --- |
 | Name a framework, table, endpoint, or library | That's HOW. Strip it; describe the behaviour instead, or log the open question. |
-| Dump 12 questions in one message | One focused question per turn. Infer the rest from the constitution and wiki. |
-| Ask a question you could answer from the constitution | Read it first. Only ask what genuinely changes the spec. |
 | Write "it should work well / be fast / be intuitive" | Not testable. Make it a binary Given/When/Then or move it to Points to clarify. |
-| Skip the whole loop because "this is too simple to design" | That's the rationalization that wastes the most work. Every feature gets the loop; only a literal one-line, zero-risk change skips. |
-| Present one approach as the answer | Offer 2-3 distinct directions with trade-offs and a recommendation; let the user choose before you write the spec. |
 | Hand to `plan`/`implement` before the user approved the written spec | The approval at step 9 is the gate. No design approved → nothing gets built. |
-| Treat the answer to your question as the approval of the spec | They answered the question, and the answer *changed* the spec. Fold it in, say what changed, show it, ask again. |
-| Write `status: aprobada` after a blanket "just run it" | That is autopilot. Record it as such — the record must not overstate the strongest gate in the chain. |
 | Skip non-goals because "it's obvious" | Unsaid scope becomes assumed scope. State what you are *not* doing. |
 | Resolve every ambiguity yourself to look finished | Inventing answers is worse than naming gaps. List them in Points to clarify. |
 | Start designing the solution because it's clearer | Stay on WHAT/WHY. The plan is a later, separate phase. |
@@ -287,7 +338,7 @@ If `clarify` surfaces answers, they get baked back into this same spec file. Onl
 - `../plan/SKILL.md` — turns the de-risked spec into a technical implementation plan (the HOW).
 - `../harness/SKILL.md` — the 02-DOCS wiki + accompaniment dial + decisions log this skill honors.
 - `references/spec-template.md` — the exact section template written to `02-DOCS/wiki/sdd/specs/<slug>.md`.
-- `references/eliciting-requirements.md` — inference checklist + the one-question-at-a-time elicitation patterns.
+- `references/eliciting-requirements.md` — inference checklist + the frontier-round elicitation pattern.
 
 ## Orientación (siempre)
 

package/skills/specify/evals/cases.yaml

@@ -63,20 +63,20 @@ should_not_trigger:
 capability:
   - scenario: "A user says: 'I want to add magic-link (passwordless) login.' There is a constitution at 02-DOCS/wiki/sdd/constitution.md but no spec yet. Produce the spec."
     must_include:
-      - "Reads the accompaniment level from 02-DOCS/wiki/harness/user-profile.md and the constitution first, inferring everything it can before asking, then asks only scope-changing questions ONE at a time (not a batch of ten)."
+      - "Reads the accompaniment level from 02-DOCS/wiki/harness/user-profile.md and the constitution first, inferring everything it can before asking, then asks only contract-changing gaps — the whole FRONTIER in one numbered round, each with its recommendation, and nothing whose answer depends on another question open in that same round."
       - "Stays strictly WHAT/WHY: no framework, token format, database table, endpoint shape, email provider, library, or file path appears in the spec — implementation-laden answers are flagged as points to clarify instead of guessed."
       - "Produces the spec sections: Problem & why, Goals, Non-goals / out of scope, Users & context, Behaviour (main + edge + error paths), Acceptance criteria, Points to clarify."
       - "Writes testable acceptance criteria in Given/When/Then form that verify could later check (e.g. expired-link refusal, unknown-email revealing nothing)."
       - "Writes the file to 02-DOCS/wiki/sdd/specs/<slug>.md (kebab-case slug), indexes it in the root CLAUDE.md Knowledge map under sdd/specs, and logs the spec creation to the canonical SDD decisions log at 02-DOCS/wiki/sdd/decisions.md."
-      - "Lists honest Points to clarify (e.g. link validity window, rate-limiting) as the handoff rather than inventing those values."
+      - "Lists honest Points to clarify as the handoff rather than inventing values, and TYPES each one (pregunta abierta / suposición tomada / decisión diferida / área no formulable) so clarify knows whether to ask it, validate it, or leave it alone; a suposición carries its basis."
       - "Ends by pointing to the clarify phase as the next step in the SDD chain."
 
   - scenario: "A user pastes a rough one-liner: 'Let users export all their data as a download.' Show how you'd elicit and capture this without over-asking."
     must_include:
       - "Recovers the underlying problem/why rather than treating the feature request as the problem, and inherits any relevant constraints from the constitution."
-      - "Applies the 'would a different answer change the spec?' test and asks only the genuinely scope-changing question(s), one at a time, in the user's register."
+      - "Applies the 'would a different answer change the contract?' test, then splits what is left by dependency: independent gaps go out together in one round with recommendations, and any gap whose answer hinges on another still-open one is held for the next round rather than asked blind."
       - "Captures observable behaviour (what the user sees/can do) and explicit non-goals / out-of-scope rather than implementation (no file format library, storage, or job-queue detail)."
-      - "Turns answers into binary acceptance criteria and defers unresolved items (e.g. data scope, retention, format) to Points to clarify instead of fabricating decisions."
+      - "Turns answers into binary acceptance criteria and defers unresolved items (e.g. data scope, retention, format) to typed Points to clarify instead of fabricating decisions, and checks the written file against the phase's exit gate before calling it done."
       - "Notes that the spec is complete-enough-to-plan with open points remaining, and hands off to clarify — not to plan or implementation."
       - "After the user answers a question, folds the answer in, states what changed, shows the revised spec, and asks for approval AGAIN — it does not treat the answer as approval of the spec, including when the user picked the recommended option."
       - "If told to run the whole chain up front, records the approval as autopilot rather than item-by-item, and says the spec is the artifact to review after the fact."

package/skills/specify/references/eliciting-requirements.md

@@ -31,13 +31,49 @@ and the intent itself. Only what survives as unknown becomes a question or a
 What you genuinely cannot resolve here is exactly what `clarify` exists for.
 Naming it is the correct outcome, not a failure.
 
-## The one-question-at-a-time pattern
+## The frontier pattern
 
-A question earns a turn only if a *different answer would change the spec*.
+A gap earns a question only if a *different answer would change the contract*.
 Apply this test before asking:
 
 > "If they answer A vs B, does a goal, a user, the scope, or an acceptance
-> criterion change?" — No → don't ask; infer or defer. Yes → ask, alone.
+> criterion change?" — No → don't ask; infer or type it as a point to clarify.
+> Yes → it is a question.
+
+Then decide *when* to ask it. Model the gaps as a tree: every decision branches
+into the decisions hanging off it. The **frontier** is every gap whose
+prerequisites are already settled — what you can ask now without guessing at
+answers you have not heard. Ask the whole frontier in one round; ask nothing
+that depends on an answer still pending in that same round.
+
+```text
+Round 1 (frontier: 3 independent gaps)
+❓ **Q1 — <title>**: <body, options if you have them>
+➡️ <your recommended answer>
+---
+❓ **Q2 — <title>**: …
+➡️ …
+---
+❓ **Q3 — <title>**: …
+➡️ …
+
+→ user answers → fold in → recompute the frontier → Round 2
+```
+
+Where the harness offers a native question selector, emit the round through it;
+otherwise emit the numbered text above. Same content either way.
+
+**Facts are yours, decisions are theirs.** A gap that needs a fact from the
+environment (a file, a config, a version) is legwork, not a question: go find
+it. Don't block the round on it — a running search is an unsettled prerequisite,
+so only its dependents wait. Ask the rest of the frontier now.
+
+**A frontier of one** is one question, and needs no apology. **A frontier of
+zero** is silence: never invent a question to look diligent.
+
+**If an answer redefines a question you already emitted this round**, say so and
+drop it. Re-ask it next round. An answer given under a premise that has since
+moved is worse than no answer, because it looks settled.
 
 Phrase by register:
 
@@ -48,8 +84,10 @@ Phrase by register:
 - **Technical / L0-L1** — terse, decision-shaped:
   > "Expired-link recovery in scope, or defer?"
 
-Always: ask → wait → record the answer in the relevant section → confirm at L2/L3
-→ ask the next. Never present a numbered list of ten questions.
+Always: emit the round → wait → record each answer in its section → confirm at
+L2/L3 → recompute the frontier. The thing to avoid was never two questions in
+one message; it was ten questions whose answers depend on each other, which is
+what crossing a dependency produces.
 
 ## Turning answers into testable criteria
 
@@ -64,14 +102,16 @@ link" action that issues a fresh one.
 ```
 
 If the answer is fuzzy ("it should feel fast"), do not invent a number — push
-once for a concrete figure; if none is available, file it under *Points to
-clarify* with the assumption you're carrying meanwhile.
+once for a concrete figure; if none is available, file it as a
+**suposición tomada** with its basis and its risk, which is what makes it
+something `clarify` can validate instead of re-ask.
 
 ## When to stop
 
-Stop eliciting when the WHAT and WHY are complete enough that `plan` could start
-without guessing at scope. Lingering unknowns are fine — they belong in *Points
-to clarify*. Over-asking to feel thorough is itself an anti-pattern: it burns the
+Stop when the frontier is empty: every branch visited, nothing left silently
+assumed. Then run the exit gate (`npm run spec:gate <path>`) on the written
+file — the bound is a property of the artifact, not of your confidence.
+Lingering unknowns are fine, and belong in *Points to clarify*, typed. Over-asking to feel thorough is itself an anti-pattern: it burns the
 user's patience and pushes them to rubber-stamp answers they haven't thought
 through. A short spec with three honest open points beats a long spec with three
 fabricated ones.

package/skills/specify/references/spec-template.md

@@ -50,16 +50,30 @@ checkable by `verify` and convertible to a `tasks` done-check.>
 - Given <state>, When <action>, Then <observable outcome>.
 
 ## Points to clarify
-<The handoff to the `clarify` phase. Open questions, assumptions you made and
-on what basis, decisions deferred. This list being non-empty is normal.>
-- [ ] <Open question> — (assumption made: <…>, basis: <…>)
-- [ ] <Deferred decision>
+<The typed handoff to `clarify`. Every entry declares which of the four it is,
+because each one gets a different action from the next phase. Non-empty is
+normal; untyped is not — an untyped entry is read as `pregunta abierta`, the
+costliest of the four.>
+- **pregunta abierta** — <formulable now, unanswered. clarify asks it.>
+- **suposición tomada** — <what you decided.> *Base:* <why.> *Riesgo:* <what
+  changes if it turns out wrong.> clarify validates it rather than re-asking.
+- **decisión diferida** — <sharp, out of this cycle on purpose. clarify leaves
+  it.>
+- **área no formulable** — <you can tell something is coming and cannot phrase
+  the question yet. clarify notes it; it graduates when it sharpens.>
 ```
 
 ## Field notes
 
 - **Status** moves `draft` → `clarified` (after the `clarify` phase) → `planned`
-  (once `plan` exists). Don't invent other states.
+  (once `plan` exists). Don't invent other states. An approval obtained as a
+  blanket "just run it" is recorded as **approved in autopilot**, not flat.
+- **Before you call it written**, run `npm run spec:gate <path>`. It checks that
+  every section here carries content or an explicit open point, and prints the
+  clauses it cannot check (the unmarked assumption is yours).
+- **Sharpness, not difficulty**, sorts the last two types from the first: *can
+  you state the question precisely now?* Not *can you answer it?* Anything past
+  what this change is for goes to **Non-goals**, where it never graduates.
 - **Behaviour** is where HOW leaks in most. Audit every verb: "queries",
   "caches", "calls", "stores in" are implementation. Replace with the observable
   effect ("shows", "lets the user", "prevents", "remembers across visits").

package/targets/claude.js

@@ -113,6 +113,21 @@ export function wireHook(paths) {
   );
   settings.hooks.PreToolUse.push({ matcher: 'Bash', hooks: [{ type: 'command', command: dgCmd }] });
 
+  // Gitmoji guard: a PreToolUse(Bash) hook that DENIES a `git commit` whose message
+  // carries no gitmoji (gitmoji.dev) in front of the Conventional Commits header. The
+  // convention lives in `git-workflow`; prose asks, this hook decides — at the one
+  // deterministic moment the message exists. Only fires when the message is inline and
+  // readable (-m / heredoc); editor commits, -F files and --amend --no-edit are allowed.
+  // Materialized + node-run (Windows-safe), idempotent, fail-open, opt-out via
+  // .rsc/.no-gitmoji.
+  const gmDest = join(paths.projectRoot, '.rsc', 'gitmoji-guard.mjs');
+  copyFileSync(join(HERE, 'gitmoji-guard.mjs'), gmDest);
+  const gmCmd = `node "${gmDest}" "${paths.projectRoot}"`;
+  settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
+    (e) => !JSON.stringify(e).includes('.rsc/gitmoji-guard.'),
+  );
+  settings.hooks.PreToolUse.push({ matcher: 'Bash', hooks: [{ type: 'command', command: gmCmd }] });
+
   // New-feature gate: a UserPromptSubmit hook that re-injects the SDD new-feature gate as
   // the most-recent instruction on every user turn. SessionStart injects the full gate (the
   // `suggest` body) once; this keeps the precedence rule salient regardless of how many
@@ -132,5 +147,5 @@ export function wireHook(paths) {
 
   mkdirSync(dirname(file), { recursive: true });
   writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
-  return [file, scriptDest, wlDest, sgDest, dgDest, fgDest];
+  return [file, scriptDest, wlDest, sgDest, dgDest, gmDest, fgDest];
 }