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

package/skills/shared/ship/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: ship
+description: "Use when a verified, review-approved branch has to land — the close of the ai-hub Spec-Kit chain: safety checks, then three landing options (merge, PR, park/discard), authorship always Daner Alejandro Salazar Colorado 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]
+recommends: []
+profiles: [core, full]
+origin: ai-hub
+---
+
+# Ship — close the development branch
+
+Ship is the **last gate** of the ai-hub Spec-Kit 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.
+
+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 Daner Alejandro Salazar Colorado, never Claude
+
+> **Every commit and every PR ships under Daner Alejandro Salazar Colorado'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.**
+
+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 Daner Alejandro Salazar Colorado'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.
+
+Concretely, before any commit or PR:
+
+- **Never** pass `--author` to set a non-Daner Alejandro Salazar Colorado author. The repo's configured `user.name` / `user.email` (Daner Alejandro Salazar Colorado's) is the author and committer.
+- If `git config user.email` is unset or clearly not Daner Alejandro Salazar Colorado's, **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.
+
+```bash
+git log -1 --format='%an <%ae>%n%n%b' | grep -iE 'co-authored-by.*(claude|anthropic|ai)|generated with|claude code' \
+  && echo "AUTHORSHIP VIOLATION — strip the trailer before shipping" \
+  || echo "authorship clean"
+```
+
+## 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.
+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
+
+Run this before presenting the landing options. Any unchecked item is a stop — surface it, don't ship around it.
+
+- [ ] **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.
+- [ ] **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 Daner Alejandro Salazar Colorado** — `git config user.email` is Daner Alejandro Salazar Colorado's; 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
+# one-shot pre-ship snapshot (read-only)
+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 Daner Alejandro Salazar Colorado
+git diff main...HEAD | grep -icE 'api[_-]?key|secret|password|token|BEGIN .*PRIVATE KEY' \
+  | sed 's/^/secret-hits: /'
+```
+
+### Automated guard (PreToolUse) — you cannot quietly abandon a feature
+
+When ai-hub is installed for Claude Code, a `PreToolUse` hook (`.ai-hub/ship-guard.mjs`) enforces this
+phase at the one deterministic moment it matters: it **denies** any Bash command that switches to
+`main`/`master` or merges while the current feature branch has **uncommitted changes** or **commits
+that were never pushed**. The denial reason names the branch and routes you here. The guard is
+local-only (no network), **fail-open** (any ambiguity — detached HEAD, no repo, git error — allows
+the command), and can be disabled per project with `.ai-hub/.no-ship-guard`. It guarantees the
+commit → push step; opening the PR is still this skill's job (and its hard rule). If the guard
+blocks you, do not work around it — run ship.
+
+The same guard also enforces the **sello** where it was opted into — per project
+(`.ai-hub/sello-config.json`) or for all of them (`~/.ai-hub/sello-config.json` via
+`sello on --global`, with the project switch always winning; `ai-hub sello status` prints which
+scope decided): commit, push and PR are denied unless the change's exact bytes match the
+sealed, approved review — one byte of drift, a moved base, or a missing review on a risk>0 change
+all block, and every denial names its way out (re-run `review`, or `npx ai-hub sello off`).
+Risk-0 changes (docs/copy) always pass silently. Off by default; the flow lives in the `review`
+skill. Note `.ai-hub/.no-ship-guard` opts out of the branch-hygiene rules above but **not** of the
+sello, which has its own switch. The sello binds bytes, not intent — it proves what ships is what
+was reviewed, never that the review was any good.
+
+## The three landing options — always present exactly three
+
+This mirrors the harness "siempre 3 opciones" pattern. Gather the one fact that changes the answer (does this repo use PRs / require review on `main`?), then present **exactly three** with an honest recommendation matched to the workflow, in the user's register.
+
+| Option | What it does | Choose it when |
+| --- | --- | --- |
+| **1. Direct merge to trunk** | Fast-forward or `--no-ff` merge into `main`, push, delete the branch | Solo repo or trusted-trunk workflow; `main` is not protected; you are the only reviewer and review already passed |
+| **2. Pull request** | Push the branch, open a PR with a spec-linked body, let CI / a human gate the merge | `main` is protected; a team or CI must sign off; you want the change reviewable in the forge even if you self-merge |
+| **3. Park or discard** | Keep the branch un-merged (park) or delete it (discard) | The approach was superseded, the spike answered its question, or the work is paused — it should not land |
+
+**When the default branch is closed for the agent** (team-safe-default: the project is complex or in
+production — `npx ai-hub main status` says `closed: true`), **option 1 is not offered**: a
+local merge is a commit on the default branch. Present option 2 (the recommendation) and option 3,
+and say in one line why option 1 is absent and that «desbloquea main» (`npx ai-hub 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`.
+
+### Delivery strategy from SDD config
+
+Read `02-DOCS/wiki/sdd/config.yaml` and the `Review Workload Forecast` in the plan if present.
+
+- `single-pr` keeps option 2 as one PR.
+- `ask-on-risk` pauses when the forecast exceeds the review budget and asks before landing a large diff.
+- `autochain` uses stacked PRs when tasks are reviewable in dependency order.
+- `exception` permits a larger single PR only when the user explicitly accepts the review risk.
+
+Stacked PR / feature-track support still fits inside the three landing options: it is a shape of **option 2**, not a fourth option. Use a feature-track branch when several stacked PRs should integrate together before trunk.
+
+## 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.
+
+### Option 1 — direct merge
+
+```bash
+git switch main && git pull --ff-only
+git merge --no-ff feature/<slug> -m "feat: <what shipped> (<spec-slug>)"   # no AI trailer
+git push origin main
+# the merge above already retired the worktree and its branch: post-merge does it
+git branch -d feature/<slug> 2>/dev/null || true   # no worktree involved? then the branch alone
+git push origin --delete feature/<slug> 2>/dev/null || true
+```
+
+Use `--no-ff` so the feature is one legible merge commit tied to the spec. Confirm the trunk still builds after the merge if the repo has a local gate (defer the actual run to `verify`).
+
+**You no longer run the cleanup; you check that it ran.** A `post-merge` hook retires the worktree and its branch the moment the work lands, on both landing paths — the local merge above and the `pull --ff-only` after a forge merge. It removes only what the reaper already classifies as safe, so anything holding unsaved work survives with its reason, exactly as before.
+
+This used to be an instruction in this paragraph, and it was skipped on both features that reached it. That is why it is a hook now: an instruction at the end of a long phase is the least reliable place to put a step that matters (P1).
+
+If something did survive, it survived *for a reason* — read it rather than forcing it: `npx ai-hub worktrees` lists what is left and why. `worktrees reap <path>` still exists for the backlog and for anything the hook deliberately refused; name the path, because bare `reap` retires every worktree that qualifies and with `parallel` running two streams that is how shipping A deletes B. Naming a path selects it, it does not accept the risk: add `--confirm` only after the user has seen the reason and said yes.
+
+### Option 2 — pull request
+
+Write the **commit(s)** clean, push, then open the PR with `gh`. The PR body links the spec/plan and lists what shipped — **and carries no AI attribution.**
+
+```bash
+git push -u origin feature/<slug>
+gh pr create \
+  --title "feat: <what shipped> (<spec-slug>)" \
+  --body-file /tmp/ship-pr-body.md          # body authored per the template below — NO AI footer
+```
+
+PR body shape (no generated-with line, ever):
+
+```markdown
+## What
+
+<one-paragraph summary of the change, in plain terms>
+
+## Why
+
+Implements `02-DOCS/wiki/sdd/specs/<slug>.md`. <the user-facing reason>
+
+## How
+
+- <key implementation point>
+- <key implementation point>
+
+## Verification
+
+- `verify` phase: lint / types / tests green (see the verification record).
+- Acceptance criteria from the spec: all met.
+- Review verdict: APPROVE.
+```
+
+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.
+
+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.
+
+For stacked PRs, create each PR against the previous branch or against a feature-track branch, with bodies that name their dependency:
+
+```markdown
+Depends on: <previous PR or feature-track branch>
+Part of: <spec-slug>
+```
+
+Never stack to hide review risk. Stack because each slice is independently reviewable and follows the task dependency order.
+
+### 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.
+- **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;
+a parked branch is the opposite of that, and `worktrees reap` refuses it by design. Leave the worktree
+where it is — the next `ship` that lands the branch will retire it. Discarding a worktree along with
+unmerged work stays what it always was: explicit, confirmed with the quoted branch name, and logged.
+
+If a native `EnterWorktree`-style tool created the workspace, exit through that tool rather than the
+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 Daner Alejandro Salazar Colorado'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`.
+- **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.
+
+## 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 Daner Alejandro Salazar Colorado-only 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 Daner Alejandro Salazar Colorado. 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 Daner Alejandro Salazar Colorado'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. |
+| "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. |
+
+## Where this writes
+
+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.
+- 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`.
+  - `verification.md` — copy or link to the verification record.
+  - `review.md` — review verdict and nits.
+  - `state.yaml` — `shipped`, `parked` or `discarded`, PR/merge refs, date.
+
+Archive after option 1/2 lands, and also after option 3 parks/discards so paused or abandoned work is remembered.
+
+## Result envelope
+
+End with:
+
+```json result-envelope
+{
+  "status": "complete",
+  "executive_summary": "Branch landed/parked/discarded and SDD archive updated.",
+  "artifact": "02-DOCS/wiki/sdd/archive/<slug>/final-report.md",
+  "next_recommended": "none",
+  "risk": "low|medium|high",
+  "skill_resolution": {
+    "used": ["ship"],
+    "missing": [],
+    "fallback": [],
+    "compact_rules": ["Keep exactly three landing options.", "Archive the final state."]
+  },
+  "evidence": ["review verdict", "verification record", "PR/merge/park/discard reference"]
+}
+```
+
+## 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.
+
+## 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/ship/evals/README.md

@@ -0,0 +1,89 @@
+# Eval harness — ship
+
+These evals run through an **agent harness** (an agent that loads skills on
+demand), not a plain shell script. `cases.yaml` is the fixture; this file is the
+procedure. Two things are measured: **triggering** (does `ship` fire on
+"close the branch / merge / open the PR" and stay quiet for its siblings) and
+**capability** (does loading `ship` produce a safe, Daner Alejandro Salazar Colorado-only landing — runs the
+pre-ship checklist, strips AI authorship, picks the right of three options).
+
+## Setup
+
+- Use the same agent/model for every trial; vary only which skills are loaded.
+- Triggering trials: load the **full skill catalog** so the agent can route to a
+  sibling, then observe which skill it selects.
+- Capability trials: compare **only `ship` loaded** vs **no skill loaded**.
+
+## 1. Triggering
+
+For each item in `should_trigger` and `should_not_trigger`:
+
+1. Start a fresh agent session with the full catalog available.
+2. Feed the `prompt` verbatim as the user message.
+3. Record which skill (if any) the agent invokes.
+4. Run **3–5 trials** per prompt — selection is stochastic.
+
+Pass conditions:
+
+- `should_trigger`: **ship** is invoked in the majority of trials. The set mixes
+  the three landing modes — direct merge ("merge into main", "squash and merge"),
+  pull request ("open the PR"), and park/discard ("clean up the branch, shouldn't
+  merge") — plus the authorship concern ("don't credit Claude", "strip the
+  generated-with footer"). All must fire `ship`.
+- `should_not_trigger`: ship is **not** invoked; ideally the agent routes to the
+  listed `route_to` sibling. These near-misses are the adjacent phases that ship
+  explicitly defers to: **verify** (run the gates), **review** (read the diff),
+  **deployment** (reach a server), **worktrees** (open isolated work), and the
+  **postgresdb** stack skill (author SQL). All five siblings exist in this repo,
+  so a correct routing lands on the named target.
+
+**Pass bar: >= 90% trigger accuracy** across all trials. A prompt that flaps
+below majority counts as a fail for that prompt; >= 90% of prompts must pass
+clean.
+
+## 2. Capability
+
+For the `capability` scenario, run two arms:
+
+- **WITH**: only `ship` loaded.
+- **WITHOUT**: no skill loaded (baseline model behavior).
+
+Run each arm 3 times. Grade every response against the scenario's `must_include`
+rubric — one point per item that is genuinely present (actually performed, not
+hand-waved). The scenario is built to discriminate on the skill's reason to
+exist: an approved branch carrying a leftover `Co-Authored-By: Claude` trailer
+and a "Generated with Claude Code" footer, in a repo with a protected `main`. The
+win is (a) detecting and **stripping** the AI authorship before pushing, (b)
+recommending the **PR** option because `main` is protected, and (c) producing a
+spec-linked commit/PR body with **no AI attribution**.
+
+Pass conditions:
+
+- **WITH** the skill covers **>= 80%** of `must_include` items on average.
+- The skill **measurably improves** the output: WITH coverage must beat WITHOUT
+  by a clear margin (target **>= 25 percentage points**). The discriminating
+  items are the authorship ones — baselines frequently *add* a Co-Authored-By
+  Claude trailer or a "generated with" footer as a default courtesy; the skill
+  should flip that to actively stripping it. A response that adds any AI
+  attribution is a hard fail on those items regardless of other coverage.
+
+## Scoring summary
+
+| Dimension | Metric | Pass bar |
+|---|---|---|
+| Triggering | trigger accuracy across all prompts/trials | >= 90% |
+| Capability | rubric coverage WITH skill | >= 80% |
+| Capability | WITH minus WITHOUT (lift) | >= 25 pts |
+
+## Notes / honesty
+
+- These are LLM-graded, stochastic evals — re-run on skill edits and treat small
+  score deltas as noise, not signal.
+- `route_to` targets (`verify`, `review`, `deployment`, `worktrees`,
+  `postgresdb`) all exist in this repo's catalog, so a near-miss that lands on
+  the named sibling is a clean pass. A mis-route to an *absent* skill would be a
+  catalog gap, not a `ship` fault — but none of these targets are absent.
+- The authorship items are the point of the skill, not a side check. Grade them
+  strictly: "stripped the trailer" must be an actual amend/edit, and the produced
+  commit/PR body must contain zero AI attribution. "Mentioned authorship" without
+  acting is not a pass.

package/skills/shared/ship/evals/cases.yaml

@@ -0,0 +1,44 @@
+skill: ship
+
+should_trigger:
+  - prompt: "Review's done and approved. Ship it — open the PR and get this branch landed."
+    why: "Flagship trigger: approved diff, explicit 'ship it' + 'open the PR' + 'land the branch'. Squarely the ship phase, the close of the SDD chain."
+  - prompt: "Esta rama ya pasó verify y review. Haz el merge a main y borra la rama."
+    why: "Spanish trigger — branch passed verify+review, 'merge to main and delete the branch'. Same close-the-branch action in the user's other language."
+  - prompt: "I'm done with the feature and everything's green. What now — how do I land this?"
+    why: "Non-obvious phrasing: no literal 'merge'/'PR' word, but 'done', 'green', 'how do I land this' is exactly the moment ship presents the three landing options."
+  - prompt: "Can you write a clean commit message and open a pull request for this change? Make sure it doesn't credit Claude or any AI as a co-author."
+    why: "Directly invokes the authorship hard rule (no Co-Authored-By Claude) alongside the commit+PR action — the defining concern this skill owns."
+  - prompt: "This spike didn't pan out — the approach is superseded. Clean up the branch, I don't think it should merge."
+    why: "The park/discard landing option (option 3). 'Clean up the branch', 'shouldn't merge' is the abandon path ship handles, including the destructive-confirm + log-the-reason discipline."
+  - prompt: "Squash my wip commits into one good commit and push it so I can merge into main."
+    why: "Commit-history hygiene + landing to trunk. Squashing noisy wip commits and merging is ship's commit-message discipline and option 1 (direct merge)."
+  - prompt: "The PR body got auto-generated with a 'Generated with Claude Code' footer — strip that and make sure the author is me before this lands."
+    why: "Authorship-violation cleanup: stripping the generated-with footer and confirming the human contributor is the author, immediately before landing. Core ship safety behavior."
+
+should_not_trigger:
+  - prompt: "Run lint, type-check and the whole test suite on my branch and tell me if it's green before I do anything else."
+    route_to: "verify"
+    why: "Running the gates to green is the verify phase. Ship assumes green and refuses to run when the gates haven't passed; this is the prerequisite, not the close."
+  - prompt: "Tear this diff apart before it goes out — what's actually wrong with the logic?"
+    route_to: "review"
+    why: "Adversarial reading of the diff for defects is the review phase. Ship lands an already-approved diff; it never reads code for correctness."
+  - prompt: "The merge is in. Now provision the server and roll this out to production with a rollback plan."
+    route_to: "deployment"
+    why: "Server provisioning, release pipeline and rollback are the deployment phase. Ship lands code in the repo; deployment puts it in front of users — explicitly routed out in 'When NOT to use'."
+  - prompt: "I'm starting a new feature and want it isolated from my current work — set up a worktree."
+    route_to: "worktrees"
+    why: "Creating the isolated branch/worktree to OPEN work is the worktrees phase. Ship is the close, not the open; opposite end of the loop."
+  - prompt: "Write me a Postgres migration to add a nullable discount_cents column to the orders table."
+    route_to: "postgresdb"
+    why: "Authoring SQL/migration code is owned by the postgresdb stack skill. There is no branch to land here — it's implementation work, not a close."
+
+capability:
+  - scenario: "An approved branch `feature/discount-codes` is ready to land. The user asks to commit and open a PR. The repo's `main` is protected (a `.github/` with prior PRs exists), and a leftover commit on the branch carries the trailer 'Co-Authored-By: Claude <noreply@anthropic.com>' plus a 'Generated with Claude Code' footer. Decide how to land it and produce the commit/PR."
+    must_include:
+      - "Runs the pre-ship safety checklist: confirms the review verdict is APPROVE, the tree is clean, the branch is rebased on main, and scans the diff for secrets — before presenting any option."
+      - "Detects the AI authorship trailer/footer and treats it as a BLOCKER: strips the Co-Authored-By Claude trailer and the 'Generated with Claude Code' footer (amends the commit) before anything is pushed."
+      - "Confirms git author is the human contributor (checks git config user.email) and never passes --author for an agent identity."
+      - "Presents exactly THREE landing options (direct merge / pull request / park-or-discard) and recommends the PR option BECAUSE main is protected / the repo has a PR culture (.github + prior PRs)."
+      - "Writes a spec-linked commit message and PR body (What/Why/How/Verification referencing specs/<slug>/spec.md) that contains NO AI attribution — no Co-Authored-By, no generated-with footer."
+      - "Logs the landing decision to .planning/history.md and keeps the sdd/ Knowledge-map rows honest; verifies authorship clean (the git log grep) before claiming the branch is shipped."

package/skills/shared/shopify/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: shopify
+description: "Use when building or customizing a Shopify store across its three code surfaces — themes (Liquid, Online Store 2.0 sections, blocks and JSON templates), apps (Remix with the versioned GraphQL Admin API and its query-cost model), and checkout (UI extensions, Functions, Web Pixels), plus the CLI flow and checkout-extensibility migration. NOT WooCommerce or PHP stores (that is `wordpress`), NOT the React layer of a headless storefront (that is `nextjs`), NOT non-Shopify payment integrations (that is `stripe`)."
+tags: [shopify, liquid, ecommerce, themes, checkout, graphql, storefront]
+recommends: [nextjs, stripe, wordpress, api-design, seo-geo]
+origin: ai-hub
+---
+
+# Shopify themes, apps & checkout
+
+The single authoritative skill for building and customizing a Shopify store. The mental model:
+**a Shopify store is a hosted platform you extend at well-defined seams — never a server you
+control.** You render on the storefront with Liquid, you mutate data through the versioned
+GraphQL Admin API, and you customize checkout through sandboxed extensions. The platform owns
+hosting, the database, PCI scope, and the checkout DOM; you own only the seams. Three surfaces,
+three toolchains — name the surface before you write a line of code.
+
+Pinned stack (verify against shopify.dev before pinning in a repo):
+
+- **Shopify CLI 4.x** — auto-upgrades via the package manager it was installed with; skips CI,
+  project-local installs, and major bumps. `shopify app config push` is removed; use `shopify app deploy`.
+- **GraphQL Admin API `2026-04`** — latest stable; supported window 2026-04 / 2026-01 / 2025-10 /
+  2025-07†. Each version is supported ~12 months. Pin `apiVersion` and bump quarterly.
+  † `2025-07` is at the edge of its window — accessible only until 2026-07-16; treat it as
+  sunsetting and do not pin it in new work. Re-check the live list at shopify.dev/docs/api/usage/versioning.
+- **Remix app template** (`@shopify/shopify-app-remix`, App Bridge, Polaris React). GraphQL > REST —
+  REST Admin API is legacy; Shopify steers all new app work to GraphQL.
+- **Dawn** — Shopify's source-available reference theme; OS 2.0 architecture is the baseline.
+
+## Pick your surface first
+
+Most Shopify mistakes are surface confusion — answering with a headless React build when the ask
+was a Liquid section, or editing `checkout.liquid` when the seam is now an extension. Branch here:
+
+| Surface | You're working on… | Tool & entry | Reference |
+|---|---|---|---|
+| **Theme** | `.liquid` files, `{% schema %}`, JSON templates, storefront rendering, merchant-editable content | `shopify theme dev` on a Dawn-based theme | `references/liquid-themes.md` |
+| **App** | embedded admin UI, reading/writing store data, webhooks, automation | `shopify app dev` on the Remix template + Admin GraphQL | `references/apps-graphql.md` |
+| **Checkout** | checkout/thank-you/order-status UI or logic, discounts, shipping, tracking | Checkout UI extensions / Functions / Web Pixels | `references/checkout-extensibility.md` |
+
+If the answer is "the React rendering layer of a headless storefront", that is `../nextjs/SKILL.md`,
+not this skill — Shopify is only the data seam (Storefront API) there.
+
+## Theme surface — Online Store 2.0 architecture
+
+OS 2.0 (GA 2021, sometimes marketed "3.0") is the architecture: JSON templates + sections-
+everywhere + theme blocks + `@app` blocks + dynamic sources. The file map:
+
+```text
+layout/theme.liquid            # the HTML shell (one per theme)
+templates/product.json         # JSON template: which sections render, in what order
+sections/main-product.liquid   # a section: markup + {% schema %} of merchant settings
+sections/*.liquid              # section groups (header/footer) live here too
+blocks/*.liquid                # theme blocks (reusable, nestable) — OS 2.0
+snippets/*.liquid              # partials rendered via {% render %}
+config/settings_schema.json    # global theme settings
+```
+
+**Rule: every section carries a `{% schema %}` with `presets` so merchants edit content in the
+theme editor without a deploy.** The why: content belongs in `section.settings` and metafields, not
+in code — if a merchant has to ask you to change a headline, the section is built wrong.
+
+```liquid
+<!-- Bad: copy hardcoded in Liquid; merchant can't touch it -->
+<h2>Summer Sale — 20% off everything</h2>
+
+<!-- Good: editable in the theme editor, with a preset so it appears in "Add section" -->
+<h2>{{ section.settings.heading | escape }}</h2>
+{% schema %}
+{
+  "name": "Promo banner",
+  "settings": [
+    { "type": "text", "id": "heading", "label": "Heading", "default": "Summer Sale" }
+  ],
+  "blocks": [{ "type": "@app" }],
+  "presets": [{ "name": "Promo banner" }]
+}
+{% endschema %}
+```
+
+The `{ "type": "@app" }` block lets merchant-installed apps drop content into your section. The
+Shopify Theme Store **requires** the main product and featured-product sections to support `@app`
+blocks. See `references/liquid-themes.md` for setting types, section groups, and dynamic sources.
+
+## Liquid rules
+
+- **`{% render %}`, never `{% include %}`.** `render` is scoped (the snippet only sees what you
+  pass) and cacheable; `include` leaks the parent scope and is deprecated.
+
+  ```liquid
+  {% comment %} Bad {% endcomment %}
+  {% include 'price' %}
+  {% comment %} Good — explicit, scoped, cacheable {% endcomment %}
+  {% render 'price', product: product, variant: variant %}
+  ```
+
+- **Bound every collection loop with `limit:`** and never nest unbounded loops — storefront render
+  cost is real and slow pages cost conversions. `{% for p in collection.products limit: 8 %}`.
+- **Pipe all dynamic output.** `| money` for prices (raw values render cents/locale wrong),
+  `| escape` for any user/merchant string (XSS), `| json` when emitting data into a `<script>`.
+- **Push branchy logic into metafields/metaobjects, not conditional chains.** A `case`/`if` ladder
+  over product types is data pretending to be code — bind a metafield and let Liquid do a lookup.
+
+## CLI workflow
+
+Theme work (hot-reloads against a dev theme; never edits live unprompted):
+
+```bash
+shopify theme dev                      # local preview + hot reload
+shopify theme pull                     # sync live/named theme down
+shopify theme push --only templates/*  # push a subset; --ignore excludes paths
+shopify theme check                    # Theme Check linter — wire into CI
+```
+
+Multi-environment lives in `shopify.theme.toml`; `--environment` is repeatable
+(`shopify theme push --environment staging --environment prod`).
+
+App work:
+
+```bash
+shopify app dev      # tunnel + env + reload; provisions admin.graphql()
+shopify app deploy   # release app + extensions  (NOT `app config push` — removed in 4.x)
+```
+
+CLI 4.x auto-upgrades via your package manager but skips CI and project-local installs — pin the
+version in CI so a silent bump never changes a release.
+
+## App surface — Remix + GraphQL Admin API
+
+Apps are the Remix template. The shape:
+
+```text
+app/shopify.server.js     # shopifyApp({ apiVersion, sessionStorage, webhooks, ... })
+app/routes/app.*.jsx      # embedded admin pages (App Bridge + Polaris)
+shopify.app.toml          # app config, scopes, webhook subscriptions
+extensions/*              # app extensions (theme app ext, UI ext, Functions, Flow)
+```
+
+- **Pin `apiVersion` in `shopify.server` and bump it quarterly** — an unpinned client silently
+  follows Shopify's default and can break on a version rollover.
+- **Use the GraphQL Admin API, not REST.** REST is legacy; new fields ship to GraphQL only.
+
+  ```js
+  // Bad — legacy REST Admin endpoint
+  await fetch(`https://${shop}/admin/api/2026-04/orders.json`);
+
+  // Good — authenticated GraphQL through the template
+  const { admin } = await authenticate.admin(request);
+  const res = await admin.graphql(
+    `#graphql
+     query Orders { orders(first: 10) { nodes { id name } } }`
+  );
+  ```
+
+- **Verify webhook HMAC** before trusting any payload — `authenticate.webhook(request)` in the
+  template does this; never parse a raw webhook body without it.
+
+See `references/apps-graphql.md` for OAuth/session storage, mutations, App Bridge, and extensions.
+
+## GraphQL query-cost model
+
+Admin GraphQL meters by **calculated query cost (points), not request count.** Every response
+carries `extensions.cost`:
+
+```json
+{ "extensions": { "cost": {
+  "requestedQueryCost": 92, "actualQueryCost": 30,
+  "throttleStatus": { "maximumAvailable": 2000, "currentlyAvailable": 1970, "restoreRate": 100 }
+}}}
+```
+
+- **Over-budget returns HTTP 200 with a `MAX_COST_EXCEEDED` error** — you must handle it in code; it
+  is not an HTTP-level failure your client will throw on.
+- **Read `throttleStatus` and back off on `restoreRate`** (points restored per second) rather than
+  blindly retrying.
+- **Large reads use bulk operations, not paginated loops.** A 10k-product export through `first:`
+  pagination will throttle; `bulkOperationRunQuery` runs async and returns a JSONL file.
+
+## Checkout surface — the post-`checkout.liquid` model
+
+`checkout.liquid` and additional scripts are **deprecated and being removed**. Dated facts:
+
+- **2024-08-13** — Information/Shipping/Payment steps lost `checkout.liquid` support.
+- **2025-08-28** — Plus self-migrate deadline for Thank-you & Order-status customizations (additional
+  scripts, script tags, `checkout.liquid`). This was the *deadline to act*, not the auto-upgrade date.
+- **2026-01** — **automatic upgrades** of Thank-you & Order-status pages begin (30-day email notice);
+  any remaining additional-scripts / script-tag / `checkout.liquid` customizations stop running.
+- **2026-04-15** — legacy Shopify Scripts can no longer be edited or published (existing scripts still run).
+- **2026-06-30** — legacy Shopify Scripts (Script Editor discount/shipping/payment scripts) stop executing entirely.
+
+Migrate by surface — match the old mechanism to its new seam:
+
+| Old (deprecated) | New seam | Notes |
+|---|---|---|
+| `checkout.liquid` UI tweaks | **Checkout UI extensions** | sandboxed React/JS targets, not DOM access |
+| Script Editor / additional-script discounts, shipping, payment logic | **Functions** (Rust or JS → Wasm) | deterministic, run server-side |
+| `<script>` tracking / analytics in checkout | **Web Pixels** + server-side events | sandboxed; no arbitrary DOM scripts |
+| custom checkout colors/fonts/CSS | **Checkout Branding API** | GraphQL, not CSS injection |
+
+Several checkout surfaces (full checkout UI customization, some Functions) are **Shopify Plus-only**.
+The full migration map, extension targets, and Functions structure are in
+`references/checkout-extensibility.md`.
+
+## App extensions catalog
+
+- **Theme app extension** — your app injects an `@app` block / blocks into themes (no theme edit).
+- **Admin UI extension** — surfaces inside admin pages (product, order) without leaving Shopify.
+- **Customer-account UI extension** — extends the new customer accounts.
+- **Functions** — discount / shipping / payment / cart logic as Wasm; the `checkout.liquid` logic seam.
+- **Flow** — triggers/actions for Shopify Flow automation, exposed by your app.
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong | Do instead |
+|---|---|---|
+| `{% include %}` in new code | deprecated, leaks parent scope, not cacheable | `{% render %}` with explicit args |
+| Raw `{{ price }}` / `{{ user_input }}` | wrong locale/cents; XSS | `\| money`, `\| escape`, `\| json` |
+| Editing `checkout.liquid` / additional scripts | deprecated; auto-upgraded away starting 2026-01 | UI extensions / Functions / Web Pixels |
+| REST Admin calls in a new app | legacy; new fields are GraphQL-only | `admin.graphql()` |
+| Unpinned or stale `apiVersion` | breaks on Shopify's version rollover | pin a supported version, bump quarterly |
+| Paginated `first:` loop for big reads | throttles on query cost | `bulkOperationRunQuery` |
+| Ignoring `extensions.cost.throttleStatus` | silent `MAX_COST_EXCEEDED` at HTTP 200 | read cost, back off on `restoreRate` |
+| Hardcoded copy in Liquid | merchant can't edit without a deploy | `section.settings` / metafields |
+| Section with no `presets` | won't appear in "Add section" in the editor | add a `presets` entry to `{% schema %}` |
+| Secrets committed in `shopify.app.toml` | leaks API credentials | env vars; keep secrets out of TOML |
+| No Theme Check in CI | regressions ship to the storefront | `shopify theme check` in the pipeline |
+| Answering with a headless React build | wrong surface for a Liquid/theme ask | confirm the surface; route React to `../nextjs/SKILL.md` |
+
+Run `scripts/verify.sh <theme-or-app-dir>` for an advisory scan of these foot-guns.