@ericrisco/rsc 3.7.5 → 4.0.1

package/skills/ship/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ship
-description: "Use when a verified, review-approved branch has to land — the close of the rsc SDD chain: safety checks, then three landing options (merge, PR, park/discard), authorship always Eric and never an AI trailer. NOT running the gates (that is `verify`), NOT reading the diff for defects (that is `review`), NOT shipping to a server (that is `deployment`)."
-tags: [sdd, ship, release, pr]
+description: "Use when a verified branch that passed its closing review has to land — the close of rsc ASDD: safety checks, an explainer for the human (what changed, what the checks proved and would not catch), then three landing options (merge, PR with Testing/Risk/How to revert, park/discard). Risk tier 0-1 with CI green may self-merge; tier 2 waits for human approval. Authorship always the human, never an AI trailer. NOT running the gates (that is `verify`), NOT reading the diff for defects (that is `review`), NOT shipping to a server (that is `deployment`)."
+tags: [asdd, ship, release, pr, risk]
 recommends: []
 profiles: [core, full]
 origin: risco
@@ -9,20 +9,20 @@ origin: risco
 
 # Ship — close the development branch
 
-Ship is the **last gate** of the rsc SDD chain: `constitution → specify → clarify → plan → tasks → analyze → implement → verify → review → **ship**`. Everything upstream proved the work is *correct* and *green*; ship is the act of **landing it** — turning an approved branch into merged history, a pull request, or a clean parked branch — without breaking the trunk and without ever forging the author.
+Ship is the **last step** of ASDD's closing stage (`../asdd/SKILL.md`), after the closing review. Everything upstream proved the work is *correct* and *green*; ship is the act of **landing it** — turning an approved branch into merged history, a pull request, or a clean parked branch — without breaking the trunk and without ever forging the author.
 
 This skill owns one decision and its safe execution: **how does this work integrate?** It does not write code, run test gates, or read the diff for defects — those phases already happened. It is the **close, not the open**: creating the isolated branch or worktree is `../worktrees/SKILL.md`, taking the gates green is `../verify/SKILL.md`, reading the diff adversarially is `../review/SKILL.md`, and putting merged code onto a server is `../deployment/SKILL.md`.
 
-## The hard rule: git authorship is Eric, never Claude
+## The hard rule: git authorship is the responsible person, never an AI
 
-> **Every commit and every PR ships under Eric's name. No `Co-Authored-By: Claude`. No `Co-Authored-By` for any AI. No "🤖 Generated with Claude Code" footer. No "made by an agent" line in the PR body. Nothing that attributes the work to a tool.**
+> **Every commit and every PR ships under the name of the responsible person — the configured git user. No `Co-Authored-By: Claude`. No `Co-Authored-By` for any AI. No "🤖 Generated with Claude Code" footer. No "made by an agent" line in the PR body. Nothing that attributes the work to a tool.**
 
-This is absolute — not a preference to weigh against convenience — because a commit is a permanent, published claim about who wrote something. The work is Eric's; the agent is a tool he used, like an editor or a compiler, and you do not credit the compiler in the commit message. Once a forged trailer is pushed it is in everyone's history and only a rewrite removes it.
+This is absolute — not a preference to weigh against convenience — because a commit is a permanent, published claim about who wrote something. The work is the responsible person's; the agent is a tool they used, like an editor or a compiler, and you do not credit the compiler in the commit message. Once a forged trailer is pushed it is in everyone's history and only a rewrite removes it.
 
 Concretely, before any commit or PR:
 
-- **Never** pass `--author` to set a non-Eric author. The repo's configured `user.name` / `user.email` (Eric's) is the author and committer.
-- If `git config user.email` is unset or clearly not Eric's, **stop and ask** which identity to commit under — do not guess, and do not substitute an agent identity.
+- **Never** pass `--author` to set another author. The repo's configured `user.name` / `user.email` — the responsible person — is the author and committer.
+- If `git config user.email` is unset or is an agent/bot identity, **stop and ask** which identity to commit under — do not guess, and do not substitute an agent identity.
 - If you find a Claude/AI trailer in a commit you are about to push (e.g. left over from an upstream tool), **strip it** before the branch lands.
 
 Verify it after writing the commit. A non-empty match is a blocker: amend and re-check before the branch goes anywhere.
@@ -36,7 +36,7 @@ git log -1 --format='%an <%ae>%n%n%b' | grep -iE 'co-authored-by.*(claude|anthro
 ## Read these first
 
 1. `02-DOCS/wiki/harness/user-profile.md` — `technical_level`, the register. It sets the words only, never whether you run the safety checklist.
-2. The **review verdict** for this branch — ship runs only on `APPROVE` or `APPROVE WITH NITS`. `CHANGES REQUESTED` loops back to `implement`, not forward to ship. If there is no verdict on record, say so and treat it as a red flag: do not ship a diff that skipped `../review/SKILL.md` — offer to run it first.
+2. The **closing review verdict** for this branch — ship runs only on `APPROVE` or `APPROVE WITH NITS`. `CHANGES REQUESTED` loops back to `implement`, not forward to ship. If there is no verdict on record, say so and treat it as a red flag: do not ship a diff that skipped `../review/SKILL.md` — offer to run it first.
 3. `02-DOCS/wiki/sdd/decisions.md` and the spec/plan slug — so the commit message and PR body describe *what shipped against which spec*, not a vague "various changes".
 
 ## The pre-ship safety checklist
@@ -46,9 +46,11 @@ Run this before presenting the landing options. Any unchecked item is a stop —
 - [ ] **Review verdict is APPROVE / APPROVE WITH NITS** (not CHANGES REQUESTED, not absent).
 - [ ] **Working tree is clean** — `git status --short` is empty. No stray edits sneaking into the merge.
 - [ ] **On a feature branch, not the trunk** — `git rev-parse --abbrev-ref HEAD` is not `main`/`master`. If work landed directly on the trunk, that is its own problem; flag it, don't paper over it.
-- [ ] **Rebased / up to date with the base** — branch is on top of latest `main`; conflicts resolved locally, not punted to the merge.
+- [ ] **Rebased / up to date with the base, and tested there** — branch is on top of latest `main`; conflicts resolved locally, not punted to the merge; the checks re-ran on the rebased branch.
+- [ ] **Risk tier known** — `npx @ericrisco/rsc risk --base main` run; its tier, classes and `human approval` line go into the PR's Risk section.
+- [ ] **No `blocking` entry in the decision queue** (`## Decision queue` in `progress/<slug>.md`) — or the PR says which remain and it does not self-merge. `review-after` entries never block; they are listed in the PR body (or the parked summary) for the human.
 - [ ] **No secrets in the diff** — scan the staged/branch diff for keys, tokens, `.env` values (`git diff main... | grep -iE 'api[_-]?key|secret|password|token|BEGIN .*PRIVATE KEY'`). A hit is a blocker; remove it, and rotate it if it was ever pushed.
-- [ ] **Authorship is Eric** — `git config user.email` is Eric's; no AI trailer in any commit on the branch (run the grep above across `main..HEAD`).
+- [ ] **Authorship is the responsible person** — `git config user.email` is the configured human; no AI trailer in any commit on the branch (run the grep above across `main..HEAD`).
 - [ ] **Commit history is intelligible** — squashed or organized so the history reads as deliberate, not "wip wip fix fix".
 
 ```bash
@@ -56,11 +58,20 @@ Run this before presenting the landing options. Any unchecked item is a stop —
 echo "branch:   $(git rev-parse --abbrev-ref HEAD)"
 echo "clean?:   $([ -z "$(git status --short)" ] && echo yes || echo NO-dirty)"
 echo "behind:   $(git rev-list --count HEAD..origin/main 2>/dev/null || echo '?') commits behind origin/main"
-git log main..HEAD --format='%an <%ae>' | sort -u   # authors on this branch — expect only Eric
+git log main..HEAD --format='%an <%ae>' | sort -u   # authors on this branch — expect only the configured user
 git diff main...HEAD | grep -icE 'api[_-]?key|secret|password|token|BEGIN .*PRIVATE KEY' \
   | sed 's/^/secret-hits: /'
+npx @ericrisco/rsc risk --base main                 # tier, classes, reviewers, human approval
 ```
 
+### The explainer — before the PR, for the human
+
+Before any landing option, give the human a short explainer, in their register: **what the change
+does** (behaviour, not files), **what the checks proved** (which tests, criteria, review tier), and
+**what they would NOT catch** — the untested path, the environment only production has, the
+judgement no test encodes. The last part is the point: it tells the human where to look. It also
+goes into the PR's Testing section.
+
 ### Automated guard (PreToolUse) — you cannot quietly abandon a feature
 
 When rsc is installed for Claude Code, a `PreToolUse` hook (`.rsc/ship-guard.mjs`) enforces this
@@ -99,7 +110,7 @@ local merge is a commit on the default branch. Present option 2 (the recommendat
 and say in one line why option 1 is absent and that «desbloquea main» (`npx @ericrisco/rsc main
 unlock`) would bring it back. The branch guard denies the local merge anyway.
 
-Recommend based on repo signals: protected `main` or an existing PR culture (look for `.github/`, prior PRs via `gh pr list`) → recommend **option 2**. A solo project with no protection and a passed review → **option 1** is honest and faster. Never default to a PR ceremony the repo doesn't use, and never force-merge a repo that gates `main`.
+Recommend based on repo signals: protected `main` or an existing PR culture (look for `.github/`, prior PRs via `gh pr list`) → recommend **option 2**. A solo project with no protection and a passed review → **option 1** is honest and faster. Never default to a PR ceremony the repo doesn't use, and never force-merge a repo that gates `main`. A tier-2 change takes option 1 only after human approval, same as a PR.
 
 ### Delivery strategy from SDD config
 
@@ -114,7 +125,13 @@ Stacked PR / feature-track support still fits inside the three landing options:
 
 ## Executing each option
 
-**Nothing below runs before the user picks an option.** Merging, pushing, opening a PR and deleting a branch are outward or irreversible — they change shared history or publish to a forge, and no later phase undoes them. A recommendation is not a yes; wait for one.
+**Nothing below runs before an option is picked.** Merging, pushing, opening a PR and deleting a branch are outward or irreversible — they change shared history or publish to a forge, and no later phase undoes them. Interactively, the user picks: a recommendation is not a yes; wait for one.
+
+**In autopilot** (the up-front yes, or `execution_mode: automatic` in `config.yaml`) the agent picks by these rules, and there is always a legal path:
+
+- **A remote exists** → option 2, the PR. Self-merge only when `rsc risk` says tier 0-1, CI is green and **no `blocking` entry** is open; otherwise leave the PR open for the human. List every `review-after` entry in the PR body.
+- **No remote** → option 3, **park**: leave the branch committed, write the explainer, the open queue entries and the exact merge command for the human (`git switch main && git merge --no-ff feature/<slug>`) into `progress/<slug>.md`, and stop.
+- **Never merge locally around the branch guard.** When `rsc main status` says `closed: true`, the guard denies a local merge — that is the signal to park, not to find another command. Autopilot never discards.
 
 ### Option 1 — direct merge
 
@@ -157,19 +174,28 @@ PR body shape (no generated-with line, ever):
 
 Implements `02-DOCS/wiki/sdd/specs/<slug>.md`. <the user-facing reason>
 
-## How
+## Testing
+
+- <what ran: lint / types / tests / verify record; acceptance criteria met, each with its evidence>
+- Closing review: APPROVE (<N> findings, all with an outcome).
+- Not covered: <what these checks would NOT catch — from the explainer>
+
+## Risk
 
-- <key implementation point>
-- <key implementation point>
+Tier <0|1|2> (`rsc risk`): <classes touched>. Human approval: <required|not required>.
+Decision queue: <open `blocking` entries, or none> · Review after: <each `review-after` entry, or none>.
 
-## Verification
+## How to revert
 
-- `verify` phase: lint / types / tests green (see the verification record).
-- Acceptance criteria from the spec: all met.
-- Review verdict: APPROVE.
+<`git revert <merge-sha>` / the squash commit; plus anything a revert alone does not undo — a migration, a flag, data written>
 ```
 
-Then either let the gate run (team/CI) or self-merge once green: `gh pr merge --squash --delete-branch` (or `--merge` to preserve the history). Squash when the branch history is noisy; preserve when each commit is meaningful.
+**Merge policy — by risk tier.** Tier 0-1, CI green and no `blocking` entry in the decision queue
+→ you may self-merge (autopilot): `gh pr merge --squash --delete-branch` (or `--merge` to preserve the
+history; squash when the branch history is noisy, preserve when each commit is meaningful). **Tier
+2 waits for human approval** — a human's approving review on the PR, or their explicit yes in the
+conversation. An agent's approval never counts as a human's: no refuter, reviewer subagent or bot
+review stands in for it, however clean.
 
 Once it is merged, pull the trunk — `git switch main && git pull --ff-only` — and the cleanup rides along with that pull: `post-merge` fires on a fast-forward too, verified. A squashed pull request is exactly the case the reaper judges by content rather than by commit identity, so it is recognised as landed; the local branch is kept, because git will not delete a squashed branch safely and while it exists the work is recoverable.
 
@@ -184,7 +210,7 @@ Never stack to hide review risk. Stack because each slice is independently revie
 
 ### Option 3 — park or discard
 
-- **Park:** leave the branch, push it so it's not lost (`git push -u origin feature/<slug>`), and log *why it's parked* to `02-DOCS/wiki/sdd/decisions.md`. Do not merge.
+- **Park:** leave the branch committed, push it if a remote exists (`git push -u origin feature/<slug>`), and log *why it's parked* to `02-DOCS/wiki/sdd/decisions.md`. Do not merge. A branch parked *ready to land* (autopilot, no remote) also gets its explainer, open queue entries and the exact merge command in `progress/<slug>.md`, so the human lands it with one command.
 - **Discard:** deletion is **destructive and unrecoverable** once the branch is gone from both sides, so it takes an explicit confirmation that quotes the branch name (the literal `yes, delete feature/<slug>`) before `git branch -D`. Anything ambiguous means keep it. Log the discard and the reason so the dead-end is remembered, not re-attempted.
 
 **Park and discard do NOT reap.** The cleanup default acts only on work that is already in the trunk;
@@ -197,7 +223,7 @@ reaper — it owns its own lifecycle and its tracking has to stay consistent.
 
 ## Commit message discipline
 
-The commit is the durable record. Make it describe the change and tie it to the spec — and keep it Eric's.
+The commit is the durable record. Make it describe the change and tie it to the spec — and keep it the responsible person's.
 
 - **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`.
@@ -205,22 +231,24 @@ The commit is the durable record. Make it describe the change and tie it to the
 
 ## Model tier — `light` (opt-in routing)
 
-Closing the branch (PR / merge / cleanup) is mechanical, so this phase's default tier is **`light`**. Routing is **off** unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`; when it is on, follow `../sdd/references/model-routing.md` for resolving and announcing the switch rather than from memory. Routing off or no profile → honor the session model silently, and skip routing on a one-line change. The Eric-only authorship rule is independent of the model and never relaxes.
+Closing the branch (PR / merge / cleanup) is mechanical, so this phase's default tier is **`light`**. Routing is **off** unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`; when it is on, follow `../asdd/references/model-routing.md` for resolving and announcing the switch rather than from memory. Routing off or no profile → honor the session model silently, and skip routing on a one-line change. The human-authorship rule is independent of the model and never relaxes.
 
 ## What ship shows
 
 Read `technical_level` from `02-DOCS/wiki/harness/user-profile.md`. It changes the words, **never** the safety checklist or the authorship rule. No profile → use analogies and proceed; don't stall the ship to ask.
 
-In the `orient` voice: the checklist result in one line, the three options as one-liners, the recommendation and its *why*, then execute on a yes — e.g. `Clean, rebased, authorship Eric. Recommend PR (main is protected). Open it?`. For a `non-technical` owner, explain the recommended option with an analogy: a protected `main` wants a PR ("asking permission before changing the shared copy"). Explain fast-forward vs `--no-ff` or what squashing trades away only when asked.
+In the `orient` voice: the explainer, the checklist result in one line, the three options as one-liners, the recommendation and its *why*, then execute on a yes — e.g. `Clean, rebased, authorship <git user>. Recommend PR (main is protected). Open it?`. For a `non-technical` owner, explain the recommended option with an analogy: a protected `main` wants a PR ("asking permission before changing the shared copy"). Explain fast-forward vs `--no-ff` or what squashing trades away only when asked.
 
 ## Anti-patterns → STOP
 
 | Rationalization | Reality |
 | --- | --- |
-| "I'll add `Co-Authored-By: Claude` / a 'Generated with Claude Code' footer to be transparent" | It forges the record. The work is Eric's — no AI trailer, ever. Strip it. |
+| "I'll add `Co-Authored-By: Claude` / a 'Generated with Claude Code' footer to be transparent" | It forges the record. The work is the responsible person's — no AI trailer, ever. Strip it. |
 | "Review didn't formally approve but it's obviously fine" | No verdict = not ready. Ship runs on APPROVE only. Route back to review. |
+| "Tier 2, but the three refuters approved — I'll self-merge" | An agent's approval never counts as a human's. Tier 2 waits for human approval. |
 | "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. |
+| "No remote and the guard denies the merge — I'll merge another way" | The denial is the answer. Park the branch with the merge command for the human. |
 | "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. |
@@ -232,7 +260,7 @@ In the `orient` voice: the checklist result in one line, the three options as on
 Ship is mostly git actions, but the outcome is recorded so the knowledge model stays whole:
 
 - **The landing decision** (which of the three options, and why) → append to `02-DOCS/wiki/sdd/decisions.md`, the same append-only log `implement`, `verify`, and `review` write to. Parks and discards are logged with their reason so dead-ends aren't re-walked.
-- A **shipped feature** flips its spec under `02-DOCS/wiki/sdd/specs/<slug>.md` to a shipped state (note the merge commit / PR). The harness owns the wiki; ship just keeps the `sdd/` rows in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer) honest.
+- A **shipped feature** flips its spec under `02-DOCS/wiki/sdd/specs/<slug>.md` to a shipped state (note the merge commit / PR). The harness owns the wiki; ship just keeps the `sdd/` rows in `02-DOCS/wiki/index.md` (the Knowledge map) honest — never the root `CLAUDE.md`.
 - An **archive bundle** closes the loop under `02-DOCS/wiki/sdd/archive/<slug>/`:
   - `final-report.md` — what shipped, why, landing decision, links.
   - `apply-progress.md` — copy or link to `progress/<slug>.md`.
@@ -259,13 +287,13 @@ End with:
     "fallback": [],
     "compact_rules": ["Keep exactly three landing options.", "Archive the final state."]
   },
-  "evidence": ["review verdict", "verification record", "PR/merge/park/discard reference"]
+  "evidence": ["closing review verdict", "rsc risk tier", "verification record", "PR/merge/park/discard reference", "human approval when tier 2"]
 }
 ```
 
 ## Next in the chain
 
-Ship is the end of the SDD loop for a feature. Two onward paths: the merged code still has to reach a **server / release** → hand off to **deployment** (`../deployment/SKILL.md`); or the next feature restarts the loop at **specify** (`../specify/SKILL.md`), or at **constitution** if the project's principles changed. The `sdd` dispatcher (`../sdd/SKILL.md`) routes whichever comes next.
+Ship is the end of the ASDD loop for a feature. Two onward paths: the merged code still has to reach a **server / release** → hand off to **deployment** (`../deployment/SKILL.md`); or the next feature restarts the loop at **specify** (`../specify/SKILL.md`), or at **constitution** if the project's principles changed. The `asdd` dispatcher (`../asdd/SKILL.md`) routes whichever comes next. Later, a revert of what shipped is an escape: `review` turns it into a case (`rsc review escapes`).
 
 ## Orientación (siempre)
 

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 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`)."
+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 ASDD stage 2 (Spec). Turns a one-line intent into problem, goals, users, out-of-scope, the four ASDD questions (what the user can do, what result they get, what it must respect, how it proves it) 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]
@@ -9,7 +9,7 @@ origin: risco
 
 # Specify — intent becomes a spec
 
-This is the **specify** phase of the rsc-sdd chain: `constitution` → **`specify`** → `clarify` → `plan` → `tasks` → `analyze` → `implement` → `verify` → `review` → `ship`. Its single job is to turn a fuzzy intent into a written specification that states **WHAT** the change is and **WHY** it matters — and nothing about **HOW** it gets built.
+This is the drafting half of ASDD stage 2, **Spec** (`../asdd/SKILL.md`): **`specify`** writes the draft → `clarify` hunts its gaps → the human approves. Its single job is to turn a fuzzy intent into a written specification that states **WHAT** the change is and **WHY** it matters — and nothing about **HOW** it gets built.
 
 A spec is a contract about behaviour and outcomes, readable by a non-technical stakeholder and precise enough that a `plan` can be derived from it. The output is one file: `02-DOCS/wiki/sdd/specs/<slug>.md`, indexed in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer).
 
@@ -40,7 +40,7 @@ If, having looked, there is no real objection, **say so in one line and move on
 **Offer autopilot once, right here.** At this boundary, propose how to run the rest of the chain:
 > *"¿Quieres que lo lleve hasta el final yo solo — spec → plan → código → verify, parando solo si algo es ambiguo — o prefieres que pare a que apruebes en cada fase?"*
 
-A **yes engages autopilot** (`../sdd/SKILL.md`): you still write the spec and every artifact, but you auto-advance through the phases without re-asking — that up-front yes is the approval that satisfies the hard gate above, for the whole run. A **no** (or silence) keeps the default gated flow: write the spec, hand to `clarify`/`plan`, stop for approval before code. Either way the spec gets written; autopilot only changes whether you pause *between* phases — and it still stops for genuine ambiguity, hard failures, or destructive/outward actions (ship still confirms). If `sdd.autopilot: true` in config, autopilot is the default — still surface it once.
+A **yes engages autopilot** (`../asdd/SKILL.md`): you still write the spec and every artifact, but you auto-advance through the phases without re-asking — that up-front yes is the approval that satisfies the hard gate above, for the whole run. A **no** (or silence) keeps the default gated flow: write the spec, hand to `clarify`/`plan`, stop for approval before code. Either way the spec gets written; autopilot only changes whether you pause *between* phases — and it still stops for genuine ambiguity, hard failures, or destructive/outward actions (ship still confirms). If `sdd.autopilot: true` in config, autopilot is the default — still surface it once.
 
 ## The one rule that defines this skill
 
@@ -52,7 +52,7 @@ If you cannot state a requirement without naming the technology, that is a real
 
 ## Model tier — `balanced` (opt-in routing)
 
-This phase's default model tier is **`balanced`** — it drafts the what/why spec through dialogue, not architecture. Routing is **off** unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`. When on: resolve this phase's tier (`models.overrides` wins over `models.phases`), map it to a model via `models.tiers`, and apply per `../sdd/references/model-routing.md` — announce the switch in one line when it differs from the session model, and dispatch any `Task`/`parallel` subagents on that model. Routing off or no profile → honor the session model silently. Never fake a switch a tool can't make; skip routing on a one-line change.
+This phase's default model tier is **`balanced`** — it drafts the what/why spec through dialogue, not architecture. Routing is **off** unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`. When on: resolve this phase's tier (`models.overrides` wins over `models.phases`), map it to a model via `models.tiers`, and apply per `../asdd/references/model-routing.md` — announce the switch in one line when it differs from the session model, and dispatch any `Task`/`parallel` subagents on that model. Routing off or no profile → honor the session model silently. Never fake a switch a tool can't make; skip routing on a one-line change.
 
 ## Read the room first (register)
 
@@ -103,8 +103,12 @@ Write these sections into `02-DOCS/wiki/sdd/specs/<slug>.md` using `references/s
 | Cost of not building it | What concretely happens if nobody does this, and what it costs | Softening a genuinely small cost — "not much" IS the finding |
 | The cheapest alternative | What would solve most of it without building this, and why that is not enough | "Nothing" — there is always a manual workaround or a smaller version |
 | Goals | What success delivers, in outcome terms | A "goal" that's actually a HOW |
-| Non-goals / out of scope | What is explicitly NOT done now — adjacent work, deferred features | Silence — unsaid scope becomes assumed scope |
+| Non-goals / out of scope | What is explicitly NOT done now — adjacent work, deferred features, and what an agent could add "just in case" (the dropped token, the QR nobody asked for) | Silence — unsaid scope becomes assumed scope, and a long run fills it |
 | Users & context | Who acts, their context, what they're trying to achieve | An imagined user no one asked for |
+| What the user can do | The action, its starting conditions, who is allowed to do it | A capability with no actor or no precondition |
+| What result they get | The observable result against a reference the **human approved**: a screenshot or sketch for UI, the expected response for an API | An agent judging that two screenshots "look alike" — that is not a reference |
+| What it must respect | Constraints and prior behaviour that must keep working. Consult the project's brain if it has one, otherwise `02-DOCS/wiki/sdd/decisions.md` and existing specs, so the spec never steps on a prior decision | A constraint you remember but did not look up |
+| How it proves it | How the check runs and what evidence remains afterwards | "Yes, I tested it" — that is a claim, not evidence |
 | 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 | The typed handoff to `clarify` — see the four types below | An untyped list, or pretending there are none |
@@ -121,7 +125,7 @@ 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*.
 
-**Two of those sections are enforced, not suggested.** For a spec dated 2026-09-06 or later, `spec:gate` refuses the file if *Cost of not building it* or *The cheapest alternative* is missing or still holding the template's guidance. Specs written before that date are exempt — they cannot answer honestly after the fact. The two exist because every other gate in the chain compares artifacts to each other, so a spec that is wrong-but-coherent passes all of them; these are the only two lines that ask whether the thing should exist at all.
+**Six of those sections are enforced, not suggested, each from its own date.** For a spec dated 2026-09-06 or later, `rsc spec gate` refuses the file if *Cost of not building it* or *The cheapest alternative* is missing or still holding the template's guidance; from 2026-11-03 it also refuses one missing any of the four ASDD questions — *What the user can do*, *What result they get*, *What it must respect*, *How it proves it* (Spanish headings accepted: *Qué podrá hacer el usuario*, *Qué resultado obtiene*, *Qué debe respetar*, *Cómo lo demuestra*). Specs written before each date are exempt — they cannot answer honestly after the fact. The first two ask whether the thing should exist at all, because every other gate compares artifacts to each other and a wrong-but-coherent spec passes all of them. The four make the spec something a long autonomous run can be checked against: tests prove the code works, not that it does what was asked.
 
 ### Points to clarify carry a type
 
@@ -155,7 +159,8 @@ saves you work.
 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.
 
 ```text
-1. EXPLORE context        → profile + sdd config + constitution + existing specs + wiki + recent git
+1. EXPLORE context        → profile + sdd config + constitution + existing specs + decisions log (or the
+                            project's brain) + wiki + recent git
 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 + OBJECT     → one sentence of what you understood, plus the strongest objection you can
@@ -188,13 +193,11 @@ 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`).
+Run `npx @ericrisco/rsc spec gate <path>` on the spec you just wrote (no path: every spec in the
+project's `02-DOCS/wiki/sdd/specs/`). It prints `PASS`/`FAIL` per file, reports the missing and the
+empty sections by name, exits non-zero on any `FAIL`, and 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.
 
 ### Fresh-eyes spec review (step 8, scaled to the stakes)
 
@@ -239,7 +242,11 @@ ask → user answers → fold it in → say what changed → show the revised sp
   **approved in autopilot, not item by item**, in the spec's `status:`. The spec then becomes the
   artifact the user reviews *after the fact*, and the work claims correspondingly less certainty
   about having captured their intent. Writing "aprobada" flat, when what happened was a blanket
-  go-ahead, is the record telling a small lie about the strongest gate in the chain.
+  go-ahead, is the record telling a small lie about the strongest gate in the chain. The same goes
+  for *What result they get*: with no human to approve a reference, write one that can be checked
+  mechanically (the expected transcript, response or output), and record it as a `review-after`
+  entry in the decision queue (`## Decision queue`, `02-DOCS/wiki/sdd/progress/<slug>.md`) — the
+  run continues, the human confirms the reference afterwards.
 - **Rejection is information — keep it.** If the user turns the spec down, revise it in place and
   append the reason to `## Revisions`. Never delete and start clean: what they rejected, and why,
   is the most useful thing in the file.
@@ -268,10 +275,25 @@ drop-off, because the friction is the password itself, not the reset.
 ## Non-goals / out of scope
 - Social login (Google/Apple) — deferred.
 - Replacing existing sessions for already-signed-in users.
+- A QR code to sign in from another device — nobody asked for it.
 
 ## Users & context
 A returning user on a new device who does not remember a password.
 
+## What the user can do
+Any registered user, signed out, can request a link to their own email.
+
+## What result they get
+The sign-in screen matches the approved sketch (linked); following the link
+lands them signed in on the page they started from.
+
+## What it must respect
+Existing sessions keep working; the decisions log says unknown emails reveal nothing.
+
+## How it proves it
+An end-to-end check per acceptance criterion; its run log and a screenshot of
+the signed-in page stay in the verification file.
+
 ## Behaviour
 - Main: user enters email → receives a link → following it signs them in.
 - Edge: an expired link shows a "request a new link" path.
@@ -296,28 +318,7 @@ Note what is *absent*: no token format, no table, no email provider, no framewor
 
 ## Optional proposal / pre-execution briefing
 
-For a tiny feature, skip this. For ambiguous, architectural, high-risk, high-review-cost or research-heavy work, write a proposal before the spec:
-
-```text
-02-DOCS/wiki/sdd/proposals/<slug>.md
-```
-
-Proposal grammar:
-
-```markdown
-# Proposal — <slug>
-
-## Problem
-## Intent
-## Scope / Non-scope
-## Research input
-## Alternatives considered
-## Tradeoffs
-## Risks
-## Rollback
-## Success criteria
-## Recommendation
-```
+For a tiny feature, skip this. For ambiguous, architectural, high-risk, high-review-cost or research-heavy work, write `02-DOCS/wiki/sdd/proposals/<slug>.md` before the spec, with these sections: Problem · Intent · Scope / Non-scope · Research input · Alternatives considered · Tradeoffs · Risks · Rollback · Success criteria · Recommendation.
 
 The proposal is allowed to mention options and tradeoffs; the spec that follows still stays WHAT/WHY. If research came from a transcript, doc, spike, or external briefing, cite it in `Research input` so the decision trail survives the chat.
 
@@ -333,7 +334,7 @@ repeated here as prohibitions: naming a behaviour makes it more available, not l
 | Name a framework, table, endpoint, or library | That's HOW. Strip it; describe the behaviour instead, or log the open question. |
 | 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. |
 | 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. |
-| Skip non-goals because "it's obvious" | Unsaid scope becomes assumed scope. State what you are *not* doing. |
+| Skip non-goals because "it's obvious" | Unsaid scope becomes assumed scope. State what you are *not* doing, including what an agent would add "just in case". |
 | 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. |
 | Write the spec somewhere other than 02-DOCS/wiki/sdd/specs/ | That's the canonical location the rest of the chain reads. Use it. |
@@ -370,11 +371,11 @@ End with:
 
 ## Next in the chain
 
-A spec is the input to **`clarify`**, not the finish line. End by pointing there:
+A spec is the input to **`clarify`**, not the finish line — both are ASDD stage 2 (**Spec**), which closes only when the human approves. End by pointing there:
 
-> "Spec written to `02-DOCS/wiki/sdd/specs/<slug>.md` with N open points. Next: run **`clarify`** to resolve them and de-risk the spec before planning."
+> "Spec written to `02-DOCS/wiki/sdd/specs/<slug>.md` with N open points. ASDD stage 2 (Spec) continues: run **`clarify`** to hunt its gaps before the human approves and `plan` starts."
 
-If `clarify` surfaces answers, they get baked back into this same spec file. Only once the spec is de-risked does `plan` derive the technical approach.
+If `clarify` surfaces answers, they get baked back into this same spec file. Only once the spec is de-risked and approved does stage 3 (`plan`) derive the technical approach.
 
 ## See Also
 

package/skills/specify/evals/cases.yaml

@@ -65,9 +65,9 @@ capability:
     must_include:
       - "Reads technical_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, Cost of not building it, The cheapest alternative, Goals, Non-goals / out of scope, Users & context, Behaviour (main + edge + error paths), Acceptance criteria, Points to clarify — and neither of the two doubt sections is left as a formality: 'Cost of not building it' names a concrete consequence, and 'The cheapest alternative' names something that would solve most of it without building this, plus why that is not enough."
+      - "Produces the spec sections: Problem & why, Cost of not building it, The cheapest alternative, Goals, Non-goals / out of scope (including what an agent might add 'just in case'), Users & context, What the user can do, What result they get (against a human-approved reference), What it must respect (checked against the decisions log or the project's brain), How it proves it (what evidence remains), Behaviour (main + edge + error paths), Acceptance criteria, Points to clarify — and neither of the two doubt sections is left as a formality: 'Cost of not building it' names a concrete consequence, and 'The cheapest alternative' names something that would solve most of it without building this, plus why that is not enough."
       - "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."
+      - "Writes the file to 02-DOCS/wiki/sdd/specs/<slug>.md (kebab-case slug), indexes it in 02-DOCS/wiki/index.md under sdd/specs (never the root CLAUDE.md), and logs the spec creation to the canonical SDD decisions log at 02-DOCS/wiki/sdd/decisions.md."
       - "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."
 

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

@@ -109,7 +109,7 @@ something `clarify` can validate instead of re-ask.
 ## When to stop
 
 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
+assumed. Then run the exit gate (`npx @ericrisco/rsc 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

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

@@ -41,13 +41,33 @@ version, or doing nothing. Required for specs dated 2026-09-06 or later.>
 
 ## Non-goals / out of scope
 - <What is explicitly NOT done in THIS change — adjacent features, deferred
-  work, things a reader might assume are included. Be explicit, not silent:
-  unsaid scope becomes assumed scope.>
+  work, things a reader might assume are included, and what an agent could be
+  tempted to add "just in case" (a feature nobody asked for). Be explicit, not
+  silent: unsaid scope becomes assumed scope.>
 
 ## Users & context
 <Who acts, the situation they're in, and what they're trying to achieve.
 Real users from the constitution/wiki, not invented personas.>
 
+## What the user can do
+<The action, the starting conditions it needs, and who is (and is not)
+allowed to do it. Required for specs dated 2026-11-03 or later.>
+
+## What result they get
+<The observable result, against a reference the human approved: a screenshot
+or sketch for UI, the expected response for an API. An agent's own judgement
+that two screenshots "look alike" is not a reference. Required from 2026-11-03.>
+
+## What it must respect
+<Constraints and prior behaviour that must keep working. Look them up in the
+project's brain if it has one, otherwise in 02-DOCS/wiki/sdd/decisions.md and
+the existing specs, so this spec never steps on a prior decision. Required from
+2026-11-03.>
+
+## How it proves it
+<How the check runs and what evidence remains afterwards. "Yes, I tested it" is
+not evidence. Required from 2026-11-03.>
+
 ## Behaviour
 - Main path: <what the system does, observably, in the common case>
 - Edge cases: <empty, maximum, boundary, concurrent, repeated…>
@@ -78,13 +98,15 @@ costliest of the four.>
 - **Status** moves `draft` → `clarified` (after the `clarify` phase) → `planned`
   (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
+- **Before you call it written**, run `npx @ericrisco/rsc 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).
-- **The two doubt sections are dated, not retroactive.** `Cost of not building
+- **The enforced sections are dated, not retroactive.** `Cost of not building
   it` and `The cheapest alternative` are required only for specs whose
-  frontmatter `timestamp` is `2026-09-06` or later. Specs written before that
-  are exempt — they cannot answer honestly after the fact, and a gate that turns
+  frontmatter `timestamp` is `2026-09-06` or later; the four ASDD questions
+  (`What the user can do`, `What result they get`, `What it must respect`, `How
+  it proves it`, or their Spanish headings) from `2026-11-03`. Specs written
+  before are exempt — they cannot answer honestly after the fact, and a gate that turns
   the whole corpus red is a gate that gets switched off. A spec with no readable
   `timestamp` falls on the exempt side too.
 - **Sharpness, not difficulty**, sorts the last two types from the first: *can

package/skills/suggest/SKILL.md

@@ -29,9 +29,9 @@ intent is ambiguous, ask one question and stay here — ambiguity slows the lane
 
 **You choose the lane; never hand that choice to the person.** Simple → **FTD**: one feature document
 in `02-DOCS` (intent, scope, checklist, evidence, next step), tasks checked off against observed proof.
-Big, or decisions that affect each other → **SDD**: enter the chain; the person approves the spec and
+Big, or decisions that affect each other → **ASDD**: enter the chain; the person approves the spec and
 clarify, then picks manual or autopilot. Say which and why in one line; switch if asked.
-→ `../ftd/SKILL.md` · `../sdd/SKILL.md`.
+→ `../ftd/SKILL.md` · `../asdd/SKILL.md`.
 
 **Where.** Default branch open (chosen at install, or nothing complex) → work on it, no branch
 question. Closed («ramas y PR», CI, team) → before each code change ask: this branch, a new one, or
@@ -40,9 +40,9 @@ question. Closed («ramas y PR», CI, team) → before each code change ask: thi
 Judge the **meaning**, not the wording: the trigger is semantic in any language. A bug fix restoring
 intended behaviour is `debug`. Autopilot consent covers a whole run — advance without re-asking.
 
-Lane's skill missing? Offer it (§2) first. SDD recorded as deferred in `.rsc.json`? Run
+Lane's skill missing? Offer it (§2) first. ASDD recorded as deferred in `.rsc.json`? Run
 `npx @ericrisco/rsc@latest reassess`; silent on `RSC_REASSESSMENT_NO_CHANGE`, and on new evidence
-show the plan command — SDD still needs a newly accepted plan id, never added silently.
+show the plan command — ASDD needs a newly accepted plan id, never added silently.
 
 ---