skilldrop-cli 0.13.0 → 0.13.2

package/README.md

@@ -3,13 +3,13 @@
 [![npm](https://img.shields.io/npm/v/skilldrop-cli)](https://www.npmjs.com/package/skilldrop-cli)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-**[Browse the catalogue →](https://sananthanarayan.github.io/skilldrop/)** — all 62 skills, filterable by outcome, pack, tag, and model tier.
+**[Browse the catalogue →](https://sananthanarayan.github.io/skilldrop/)** — all 63 skills, filterable by outcome, pack, tag, and model tier.
 
-**62 portable AI-agent skills for the deliverables knowledge workers actually ship** — diagrams, design docs, ADRs, PRDs, runbooks, decks, decision logs, threat models, adversarial reviews — installable into **Claude Code**, **Cursor**, **Kiro**, **Codex**, **GitHub Copilot**, and any AI tool that accepts custom instructions, one skill or one role-based pack at a time:
+**63 portable AI-agent skills for the deliverables knowledge workers actually ship** — diagrams, design docs, ADRs, PRDs, runbooks, decks, decision logs, threat models, adversarial reviews — installable into **Claude Code**, **Cursor**, **Kiro**, **Codex**, **GitHub Copilot**, and any AI tool that accepts custom instructions, one skill or one role-based pack at a time:
 
 ```bash
-npx skilldrop-cli install --pack product-manager     # or: solution-architect, dev-team,
-npx skilldrop-cli list                               #     sre-oncall, stakeholder-comms, ai-engineering, claude-api
+npx skilldrop-cli install --pack product-manager     # or: solution-architect, dev-team, sre-oncall,
+npx skilldrop-cli list                               #     stakeholder-comms, ai-engineering, claude-api (each brings core)
 ```
 
 Originally scoped to solution architects, now broadly useful to PMs, founders, consultants, engineering leaders, exec assistants — anyone who turns ideas into stakeholder-ready artifacts.
@@ -24,13 +24,14 @@ skilldrop ships **loops**, not just parts. A loop is a named sequence of stages
 
 A loop *sequences* skills — it never contains one. Every skill stays independently installable and runnable on its own, which is what keeps a single-folder copy working in Cursor, Kiro, or Aider.
 
-Four loops cover the lifecycle, and they are separated by **reversibility** — how expensive the mistake is to unwind — which is why each gets its own gate rather than folding into a neighbour:
+Five loops cover the lifecycle, and they are separated by **reversibility** — how expensive the mistake is to unwind — which is why each gets its own gate rather than folding into a neighbour:
 
 | Loop | Takes | Gate | Produces | Mistake costs |
 |---|---|---|---|---|
 | [`discover`](loops/discover/LOOP.md) | interviews, journeys, a strategy question | **G0** human — a person ratifies the brief | a ratified requirement | a re-brief |
 | [`design`](loops/design/LOOP.md) | a ratified requirement | **G1** review — `council-review`'s panel | a recorded decision (ADR) | months, unwound in code |
 | [`build`](loops/build/LOOP.md) | an agreed requirement or triaged defect | **G2** mechanical — `pre-merge-review`'s gate script decides | merged code | a revert |
+| [`release`](loops/release/LOOP.md) | merged code | **G2.5** review — `launch-readiness` on evidence; **G2.6** human go/no-go | a live, reversible rollout | users and data, often irreversible |
 | [`operate`](loops/operate/LOOP.md) | a shipped service | **G3** human — the incident is closed | a postmortem and runbook deltas | live users, irreversible |
 
 Plus one **wrapper**, which is not a lifecycle stage but the two passes either side of *any* generator:
@@ -144,6 +145,41 @@ flowchart LR
 
 <!-- loop:build:end -->
 
+### `release` — merged code to live users
+
+Plan the rollout and the way back, judge readiness on evidence, draft the release notes, then a human makes the go/no-go call. The gap between a merge you can revert and a launch you often cannot.
+
+<!-- loop:release:start -->
+
+```mermaid
+%%{init: {'theme':'base','themeVariables':{'fontFamily':'Segoe UI, Helvetica, Arial','fontSize':'15px','lineColor':'#9AA5B1'},'flowchart':{'curve':'basis','rankSpacing':70,'nodeSpacing':50,'padding':16}}}%%
+flowchart LR
+    classDef gen    fill:#E8F0FE,stroke:#4C7DF0,stroke-width:1.5px,color:#1A3A8F;
+    classDef review fill:#FDEAEA,stroke:#E05B5B,stroke-width:1.5px,color:#8A1F1F;
+    classDef gate   fill:#FBE3A2,stroke:#D9971E,stroke-width:2px,color:#6B4500,font-weight:bold;
+    classDef ship   fill:#E6F7EC,stroke:#34A853,stroke-width:2px,color:#0F6B33,font-weight:bold;
+
+    plan["plan<br/><small>migration-plan</small>"]:::gen
+    ready["ready<br/><small>launch-readiness</small>"]:::review
+    announce["announce<br/><small>release-notes</small>"]:::gen
+    go["go<br/><small>council-review</small>"]:::gate
+    G2_5{"G2.5 · review"}:::gate
+    G2_6{"G2.6 · human"}:::gate
+    DONE(["complete"]):::ship
+
+    plan --> ready
+    ready --> G2_5
+    G2_5 == "PROCEED" ==> announce
+    announce --> go
+    go --> G2_6
+    G2_6 == "PROCEED" ==> DONE
+
+    G2_5 -- "REVISE (max 3)" --> plan
+    G2_6 -- "REVISE (max 3)" --> plan
+```
+
+<!-- loop:release:end -->
+
 ### `operate` — a shipped service through detection and learning
 
 Instrument, write the runbook, communicate the incident, then feed the postmortem's runbook deltas straight back into the runbook. The one loop whose failures are live.
@@ -235,6 +271,7 @@ Skills for the SDLC steps around the code itself — turning raw requirements in
 | [`release-notes`](skills/release-notes/SKILL.md) | Turn git history between two refs (default: last tag → HEAD) into two artifacts: customer-facing release notes rewritten in reader benefits — no commit-speak, no ticket IDs, no "various improvements" — and an internal Keep-a-Changelog version with a commit hash on every line. Breaking changes hoisted to the top of both with an "Action required" line (detected via `!:` markers, removed public API, migration files, major bumps); internal noise (refactors, CI, deps) never leaks into customer notes; vague commits land in a "Needs review" list instead of being guessed at. |
 | [`bug-triage`](skills/bug-triage/SKILL.md) | Turn a vague bug report ("it's broken on mobile sometimes") into a ticket an engineer can start without contacting the reporter: searchable symptom-plus-condition title, numbered repro steps from a clean state (or an explicit "no repro yet" with the exact diagnostics to collect), expected-vs-actual with the verbatim error string, every claim tagged `[reported]` / `[verified]` / `[assumption]`, severity and priority judged independently (S4/P1 is a legitimate combination), ≤3 hypotheses each with a 5-minute check, and duplicate-search hints. One bug per ticket — multi-symptom reports get split. |
 | [`migration-plan`](skills/migration-plan/SKILL.md) | Phased migration/rollout plan (schema change with live backfill, API version, datastore/auth/platform swap) built on the parallel-change pattern: expand → migrate → contract. One change per phase (a failed phase implicates exactly one thing); every phase carries an observable gate with bake time, a tested rollback with an explicit data story, and a blast radius; at most one **named point of no return**; backfill specified idempotent + resumable + rate-limited with 3-depth parity checks; dual-write requires a named reconciler; the contract phase gets a date and an owner so "we'll remove the old path later" actually happens. |
+| [`launch-readiness`](skills/launch-readiness/SKILL.md) | Go/no-go readiness report for a merged change before it reaches users. It lists the change's own failure modes first, then judges seven checks in order: rollback, detection, response, measured NFR targets, data & privacy, comms, staged exposure. Each row is met / not met / n/a-with-reason, with an evidence link and an owner role, and a row with no evidence is `not met`. The verdict (PROCEED / PROCEED WITH CONDITIONS / REVISE / BLOCKED) follows mechanically from the rows, and a missing rollback blocks on its own. Gaps go to `migration-plan`, `observability-plan` or `runbook-generator` instead of being drafted inline. The `ready` stage of the `release` loop. |
 
 ### Product strategy
 
@@ -388,17 +425,18 @@ Why not have an LLM pick the model live on every call? Because that pays tokens
 
 ## Skill packs — install a role's toolkit in one command
 
-Categories (above) say what a skill *is*; packs say *who needs it*. [`packs.json`](packs.json) defines six role-based bundles — packs overlap where a skill serves several roles, and every skill belongs to at least one:
+Categories (above) say what a skill *is*; packs say *who needs it*. [`packs.json`](packs.json) gives every skill and every loop **exactly one home** ([RFC-0033](docs/rfcs/0033-core-pack-and-single-home-skills.md)). Skills every role uses live in **`core`**, and each role pack `requires` it, so installing a role pack installs `core` with it in the same command:
 
-| Pack | Skills | For |
-|---|---|---|
-| `solution-architect` | 17 | Design-phase artifacts: diagrams, ADRs, design docs, contracts, schemas, threat models, and the reviews that gate them |
-| `dev-team` | 14 | Build-and-ship loop: implementation with adversarial review, test plans, triage, migrations, release notes, quality gates, pre-ship hygiene |
-| `product-manager` | 13 | Direction to requirements: PR/FAQs, strategy frameworks, OKRs, PRDs, journey maps, story splitting, success measurement |
-| `ai-engineering` | 12 | Build and run AI systems: agent loop design, subagent orchestration, spend budgets, eval harnesses, usage reporting, data contracts |
-| `stakeholder-comms` | 9 | Non-technical audiences: audience profiling, deck outlines and real `.pptx` decks, exec summaries, decision logs, guides |
-| `sre-oncall` | 5 | Operate the service: runbooks, observability design, incident comms, postmortems, capacity/cost models |
-| `claude-api` | 4 | Build on the Anthropic API: prompt caching strategy, token budgeting, eval generation for skills, tool-use schema writing |
+| Pack | Skills | Loops | For |
+|---|---|---|---|
+| `core` | 4 | `ship-a-draft` | Every role: structured intake, document critique, the review council, output hygiene. Comes with every role pack |
+| `dev-team` | 14 + core | `build`, `release` | Build-and-ship: story splitting, implementation with adversarial review, test plans, triage, migrations, launch readiness, release notes, quality gates |
+| `solution-architect` | 11 + core | `design` | Design-phase artifacts: diagrams, ADRs, design docs, contracts, schemas, threat models |
+| `ai-engineering` | 11 + core | — | Adopt and build AI systems: readiness, use-case triage, rollout and policy, agent loop design, subagents, spend budgets, agent threat models, evals, usage reporting |
+| `product-manager` | 8 + core | `discover` | Direction to requirements: PR/FAQs, strategy frameworks, OKRs, business cases, interviews, PRDs, journey maps, success measurement |
+| `stakeholder-comms` | 6 + core | — | Non-technical audiences: audience profiling, deck outlines and real `.pptx` decks, exec summaries, decision logs, guides |
+| `sre-oncall` | 5 + core | `operate` | Operate the service: runbooks, observability design, incident comms, postmortems, capacity/cost models |
+| `claude-api` | 4 | — | Build on the Anthropic API: prompt caching strategy, token budgeting, eval generation for skills, tool-use schema writing. A specialist add-on; it does not bring core |
 
 ```bash
 python3 pack.py                                  # list packs
@@ -408,7 +446,7 @@ python3 pack.py product-manager --install --project      # into .claude/skills/
 python3 pack.py product-manager --install --dest .cursor/skills   # any dir, for non-Claude IDEs
 ```
 
-For non-Claude IDEs, `--dest` drops the folders where your tool expects them; the per-IDE wiring steps below still apply. Packs are metadata only — skills stay in flat `skills/<name>` folders, so per-skill `cp -R` installs keep working unchanged ([RFC-0001](docs/rfcs/0001-skill-packs.md) records the design decision).
+For non-Claude IDEs, `--dest` drops the folders where your tool expects them; the per-IDE wiring steps below still apply. Packs are metadata only — skills stay in flat `skills/<name>` folders, so per-skill `cp -R` installs keep working unchanged ([RFC-0001](docs/rfcs/0001-skill-packs.md) records the original decision; [RFC-0033](docs/rfcs/0033-core-pack-and-single-home-skills.md) replaced its overlapping packs with `core` and one home per skill).
 
 ## Outcomes — browse by why you're here
 
@@ -442,13 +480,13 @@ npx skilldrop-cli install --pack dev-team --project     # .claude/skills — als
 npx skilldrop-cli install prfaq --ide cursor            # + writes .cursor/rules/prfaq.mdc
 npx skilldrop-cli install --pack sre-oncall --ide kiro  # .kiro/skills — Kiro IDE + Kiro CLI, discovered natively
 npx skilldrop-cli install adr-generator --dest .agents/skills   # Codex + Copilot CLI (see below)
-npx skilldrop-cli loops                                 # the five loops, their stages and gates
+npx skilldrop-cli loops                                 # the six loops, their stages and gates
 npx skilldrop-cli install --loop build                  # a loop + every stage skill it sequences (RFC-0028)
 npx skilldrop-cli install --loop --pack sre-oncall      # every loop that pack declares
 npx skilldrop-cli agents                                # the reviewer subagents
 npx skilldrop-cli install --agent devils-advocate       # -> ~/.claude/agents/ (RFC-0012)
 npx skilldrop-cli install --panel review                # the whole review fleet: 3 subagents + the pre-merge-review orchestrator (RFC-0020)
-npx skilldrop-cli outdated && npx skilldrop-cli update  # skills improve; cp -R never tells you
+npx skilldrop-cli outdated && npx skilldrop-cli update  # skills improve; files you edited are kept, new copy as <file>.upstream
 npx skilldrop-cli list | skilldrop info <skill> | skilldrop packs | skilldrop uninstall <skill>
 npx skilldrop-cli list --json                            # machine-readable: list/info/packs/agents/outdated (RFC-0021)
 ```
@@ -466,18 +504,20 @@ skilldrop is also a **Claude Code plugin marketplace** — one marketplace, seve
 Then take the whole catalogue, or just your role's pack:
 
 ```text
-/plugin install skilldrop@skilldrop             # all 62 skills + 3 reviewer subagents
-/plugin install solution-architect@skilldrop    # 17 skills
-/plugin install dev-team@skilldrop              # 14 skills + the 3 reviewer subagents
-/plugin install product-manager@skilldrop       # 13 skills
-/plugin install ai-engineering@skilldrop        # 12 skills
-/plugin install stakeholder-comms@skilldrop     # 9 skills
-/plugin install sre-oncall@skilldrop            # 5 skills
+/plugin install skilldrop@skilldrop             # all 63 skills + 3 reviewer subagents
+/plugin install dev-team@skilldrop              # 18 skills (incl. core) + the 3 reviewer subagents
+/plugin install solution-architect@skilldrop    # 15 skills (incl. core)
+/plugin install ai-engineering@skilldrop        # 15 skills (incl. core)
+/plugin install product-manager@skilldrop       # 12 skills (incl. core)
+/plugin install stakeholder-comms@skilldrop     # 10 skills (incl. core)
+/plugin install sre-oncall@skilldrop            # 9 skills (incl. core)
+/plugin install claude-api@skilldrop            # 4 skills
+/plugin install core@skilldrop                  # 4 skills, on their own
 ```
 
 Every skill then invokes as `/<plugin>:<name>` (e.g. `/skilldrop:prfaq`). The whole-catalogue plugin ships the flat `skills/` and `agents/` trees at the repo root unchanged — same copy-install premise, expressed in Claude's own plugin format.
 
-The six **pack plugins** work differently, because a plugin's skills have to sit in a `skills/` folder inside the plugin. Rather than duplicate every skill into six directories on `main` — physical packs, which [RFC-0001](docs/rfcs/0001-skill-packs.md) rejected — the marketplace entries use Claude's `git-subdir` source to point at `packs/<name>/` on a generated [`plugins`](https://github.com/sananthanarayan/skilldrop/tree/plugins) branch, rebuilt by CI on every push to main. Nothing moves in the source tree, and you still only ever type the one `marketplace add`. A pack carries the reviewer subagents its own skills delegate to, so `dev-team` brings the review panel and `sre-oncall` does not.
+The eight **pack plugins** work differently, because a plugin's skills have to sit in a `skills/` folder inside the plugin. Rather than duplicate every skill into eight directories on `main` — physical packs, which [RFC-0001](docs/rfcs/0001-skill-packs.md) rejected — the marketplace entries use Claude's `git-subdir` source to point at `packs/<name>/` on a generated [`plugins`](https://github.com/sananthanarayan/skilldrop/tree/plugins) branch, rebuilt by CI on every push to main. Nothing moves in the source tree, and you still only ever type the one `marketplace add`. Each role pack's plugin also carries `core`'s skills and loops, since a plugin installs on its own. A pack carries the reviewer subagents its own skills delegate to, so `dev-team` brings the review panel and `sre-oncall` does not.
 
 `.claude-plugin/{marketplace,plugin}.json` are generated from `package.json` + `packs.json` by [`build_marketplace.py`](build_marketplace.py) (`--check` guards drift in CI; `--dist` renders the branch). Use the CLI above when you want per-skill granularity, another IDE, or hooks; use the marketplace when you're in Claude Code. Rationale: [RFC-0027](docs/rfcs/0027-retire-agentbundle-export.md).
 

package/bin/skilldrop.js

@@ -13,6 +13,7 @@ const fs = require("fs");
 const path = require("path");
 const os = require("os");
 const { execFileSync } = require("child_process");
+const crypto = require("crypto");
 
 const ROOT = path.resolve(__dirname, "..");
 const LEDGER = ".skilldrop.json";
@@ -48,7 +49,9 @@ Usage:
                                           (--no-skills for the loop alone) (RFC-0028)
   skilldrop install --panel review        install the review panel — the 3 reviewer subagents +
                                           the pre-merge-review orchestrator that fires them (RFC-0020)
-  skilldrop update                        re-copy installed skills whose version changed
+  skilldrop update [--force]              re-copy installed skills whose version changed; files
+                                          you edited are kept and the new copy lands beside them
+                                          as <file>.upstream (--force overwrites) (RFC-0032)
   skilldrop outdated                      show installed vs current versions, change nothing
   skilldrop uninstall <skill...>          remove skills (and wiring files this tool wrote)
   skilldrop uninstall --agent <name...>   remove subagents
@@ -264,6 +267,15 @@ function packsOf(cat) {
   const p = path.join(cat.dir, "packs.json");
   return fs.existsSync(p) ? readJSON(p).packs : null;
 }
+/* RFC-0033: a pack installs together with the packs it `requires` (in practice, core), so
+   one --pack still delivers a role's whole toolkit now that shared skills have one home. */
+function packMembers(ps, name, key) {
+  const req = (ps[name].requires || []).filter((r) => ps[r]);
+  const out = [];
+  for (const n of [...req, name]) for (const x of ps[n][key] || []) if (!out.includes(x)) out.push(x);
+  if (req.length) console.log(`pack '${name}' includes ${req.join(", ")}`);
+  return out;
+}
 function profilesOf(cat) {
   const p = path.join(cat.dir, "profiles.json");
   return fs.existsSync(p) ? readJSON(p).profiles : null;
@@ -709,7 +721,7 @@ function expandNames(args, cat) {
     if (!ps) die(`catalog '${cat.source}' has no packs.json — install skills by name`);
     const p = ps[args.flags.pack];
     if (!p) die(`unknown pack '${args.flags.pack}' in catalog '${cat.source}'`);
-    return p.skills.slice();
+    return packMembers(ps, args.flags.pack, "skills");
   }
   if (!args._.length) die("nothing to install — pass skill names, --pack <name>, or --all");
   for (const s of args._) if (!skillExists(cat, s)) die(`unknown skill '${s}' in catalog '${cat.source}'`);
@@ -721,10 +733,64 @@ function copyOne(cat, s, dest, ide, l, notes) {
   fs.cpSync(skillDir(cat, s), path.join(dest, s), { recursive: true });
   const note = writeWiring(ide, dest, s, m.description);
   if (note && notes) notes.push(note);
-  l.data[s] = { version: m.version, source: cat.source };
+  l.data[s] = { version: m.version, source: cat.source, files: fileHashes(skillDir(cat, s)) };
   return m;
 }
 
+/* RFC-0032: per-file SHA-256 of a skill as the catalog shipped it, recorded in the ledger at
+   copy time. It is the baseline `update` compares against, so a file the user edited is never
+   overwritten. Paths are forward-slash relative; *.upstream files are this tool's output. */
+function sha256(buf) { return crypto.createHash("sha256").update(buf).digest("hex"); }
+function fileHashes(dir) {
+  const out = {};
+  (function walk(d, rel) {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(path.join(d, e.name), r);
+      else if (e.isFile() && !e.name.endsWith(".upstream")) out[r] = sha256(fs.readFileSync(path.join(d, e.name)));
+    }
+  })(dir, "");
+  return out;
+}
+
+/* Update one skill file by file against the ledger baseline (RFC-0032):
+     upstream unchanged            -> leave the local file alone, edited or not
+     local untouched, or new file  -> take the new version
+     local edited, upstream moved  -> keep the local file, write the new one as <file>.upstream
+   A file the catalog dropped is removed only if the user never touched it. The new baseline is
+   what the catalog ships now, so a kept edit stays "edited" until the user merges it. */
+function mergeOne(cat, s, dest, ide, l, notes) {
+  const m = manifestOf(cat, s);
+  const src = skillDir(cat, s), dst = path.join(dest, s);
+  const base = l.data[s].files, next = fileHashes(src);
+  const kept = [], orphaned = [];
+  const at = (root, rel) => path.join(root, ...rel.split("/"));
+  const localHash = (rel) => { try { return sha256(fs.readFileSync(at(dst, rel))); } catch (e) { return null; } };
+  for (const [rel, h] of Object.entries(next)) {
+    const mine = localHash(rel), to = at(dst, rel);
+    if (mine === h) { fs.rmSync(to + ".upstream", { force: true }); continue; }
+    if (h === base[rel]) continue;
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    if (mine === null ? !(rel in base) : mine === base[rel]) {
+      fs.copyFileSync(at(src, rel), to);
+      fs.rmSync(to + ".upstream", { force: true });
+    } else {
+      fs.copyFileSync(at(src, rel), to + ".upstream");
+      kept.push(rel);
+    }
+  }
+  for (const rel of Object.keys(base)) {
+    if (rel in next) continue;
+    const mine = localHash(rel);
+    if (mine === base[rel]) fs.rmSync(at(dst, rel), { force: true });
+    else if (mine !== null) orphaned.push(rel);
+  }
+  const note = writeWiring(ide, dest, s, m.description);
+  if (note && notes) notes.push(note);
+  l.data[s] = { version: m.version, source: cat.source, files: next };
+  return { m, kept, orphaned };
+}
+
 /* Install a whole review panel — the reviewer subagents + the orchestrator skill — in one
    command (RFC-0020). Needs a target with BOTH a subagent and a skill format, so it accepts
    the default (Claude Code), --project, --ide kiro, or --dest; other IDEs install the halves
@@ -874,18 +940,30 @@ function installedRows(flags) {
 function update(args) {
   const { dest, ide, l, rows } = installedRows(args.flags);
   if (!rows.length) return console.log(`nothing installed at ${dest}`);
-  let n = 0;
+  let n = 0, conflicts = 0;
   for (const r of rows) {
     if (!r.current) { console.log(`skip ${r.s}: source '${r.src}' unreachable or skill gone from it`); continue; }
     if (r.current === r.installed) continue;
     const problems = checkSkill(r.cat, r.s);
     if (problems.length) { console.log(`skip ${r.s}: fails structural check in '${r.src}' (${problems[0]})`); continue; }
-    copyOne(r.cat, r.s, dest, ide, l);
-    console.log(`updated ${r.s} ${r.installed} -> ${r.current} (${r.src})`);
+    // No baseline (installed before RFC-0032) or --force: overwrite as before, and record one.
+    const entry = l.data[r.s];
+    if (args.flags.force || typeof entry !== "object" || !entry.files) {
+      copyOne(r.cat, r.s, dest, ide, l);
+      console.log(`updated ${r.s} ${r.installed} -> ${r.current} (${r.src})`);
+    } else {
+      const { kept, orphaned } = mergeOne(r.cat, r.s, dest, ide, l);
+      console.log(`updated ${r.s} ${r.installed} -> ${r.current} (${r.src})`);
+      for (const f of kept) console.log(`  kept your edits in ${f} — new version at ${f}.upstream`);
+      for (const f of orphaned) console.log(`  kept ${f} — dropped upstream, but you edited it`);
+      conflicts += kept.length;
+    }
     n++;
   }
   saveLedger(l);
   console.log(n ? `\n${n} skill(s) updated.` : "everything up to date.");
+  if (conflicts)
+    console.log(`${conflicts} file(s) kept your edits. Merge each <file>.upstream into its file, then delete it — or rerun with --force to take every new version.`);
 }
 
 function outdated(args) {
@@ -1013,7 +1091,7 @@ function installLoops(args) {
     if (!ps) die(`catalog '${cat.source}' has no packs.json`);
     const pk = ps[args.flags.pack];
     if (!pk) die(`unknown pack '${args.flags.pack}' in catalog '${cat.source}'`);
-    names = (pk.loops || []).slice();
+    names = packMembers(ps, args.flags.pack, "loops");
     if (!names.length) die(`pack '${args.flags.pack}' declares no loops`);
   }
   if (!names.length && args.flags.all) names = available.slice();
@@ -1182,13 +1260,13 @@ function listPacks(args) {
       catalog: cat.source,
       count: ps ? Object.keys(ps).length : 0,
       packs: Object.entries(ps || {}).map(([name, p]) => ({
-        name, description: p.description || null, skills: p.skills || [],
+        name, description: p.description || null, skills: p.skills || [], requires: p.requires || [],
       })),
     });
   if (!ps) return console.log(`catalog '${cat.source}' defines no packs.`);
   const w = Math.max(...Object.keys(ps).map((n) => n.length));
   for (const [n, p] of Object.entries(ps))
-    console.log(`${n.padEnd(w)}  (${p.skills.length} skills)  ${p.description}`);
+    console.log(`${n.padEnd(w)}  (${p.skills.length} skills${(p.requires || []).length ? ` + ${p.requires.join(", ")}` : ""})  ${p.description}`);
   console.log("\nInstall one: skilldrop install --pack <name>");
 }
 

package/contracts/pack.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/sananthanarayan/skilldrop/contracts/pack.schema.json",
   "title": "skilldrop packs.json",
-  "$comment": "RFC-0001 / RFC-0026 / RFC-0029. Packs and outcomes are METADATA ONLY — skills never move out of flat skills/<name> folders. Packs answer WHO needs a skill; outcomes answer WHY someone opened the catalogue. Both get the same two-way membership check in validate.py.",
+  "$comment": "RFC-0001 / RFC-0026 / RFC-0029 / RFC-0033. Packs and outcomes are METADATA ONLY — skills never move out of flat skills/<name> folders. RFC-0033: each skill and loop sits in exactly one pack; shared skills live in `core`, which other packs pull in via `requires`. Packs answer WHO needs a skill; outcomes answer WHY someone opened the catalogue. Both get the same two-way membership check in validate.py.",
   "type": "object",
   "additionalProperties": false,
   "required": ["version", "packs", "outcomes"],
@@ -20,7 +20,14 @@
           "description": { "type": "string", "description": "One line — who this pack is for." },
           "skills": { "type": "array", "items": { "type": "string" }, "minItems": 1,
                       "description": "Real skill folders. Every skill must appear in at least one pack." },
-          "loops": { "type": "array", "items": { "type": "string" },
+          "requires": {
+      "type": "array",
+      "items": {
+       "type": "string"
+      },
+      "description": "RFC-0033. Packs installed together with this one (in practice, `core`). One level only: a required pack may not itself require."
+     },
+     "loops": { "type": "array", "items": { "type": "string" },
                      "description": "RFC-0028. Real loops/ folders. Every loop must appear in at least one pack." }
         }
       }

package/loops/release/LOOP.md

@@ -0,0 +1,76 @@
+---
+name: release
+description: Take merged code to live users through a planned, reversible rollout — plan the phases and the rollback, judge readiness on evidence, draft the release notes, then a human makes the go/no-go call. Use when the user has merged a change and asks how to roll it out, whether they are ready to launch, or for a go/no-go decision.
+---
+
+# release
+
+This loop covers the step between `build`, which ends when a human merges, and `operate`,
+which assumes the service is already live. A merge can be undone with a revert. A launch that
+has touched users or data often cannot be undone, so this loop gets its own gates instead of
+being folded into either neighbour.
+
+## Stages
+
+| # | Stage | Type | Skills | Gate |
+|---|---|---|---|---|
+| 1 | `plan` | generate | [`migration-plan`](../../skills/migration-plan/SKILL.md) | — |
+| 2 | `ready` | verify | [`launch-readiness`](../../skills/launch-readiness/SKILL.md) | **G2.5** review |
+| 3 | `announce` | generate | [`release-notes`](../../skills/release-notes/SKILL.md) | — |
+| 4 | `go` | gate | [`council-review`](../../skills/council-review/SKILL.md) | **G2.6** human |
+
+## How to run this loop
+
+1. **Plan the rollout and the way back.** `migration-plan` sets out the phases, a tested
+   rollback for each one, and at most one named point of no return. For a code-only change
+   behind a flag, the plan can be short: the flag, the stages and how to turn it off. It still
+   has to exist.
+2. **Judge readiness at G2.5.** `launch-readiness` lists the change's own failure modes, then
+   checks rollback, detection, response, measured targets, data and privacy, comms and
+   exposure, each with evidence. `REVISE` returns to `plan`, and the report names which gap to
+   close and which skill closes it. A missing rollback is `BLOCKED` on its own.
+3. **Announce only once it is ready.** `release-notes` drafts the customer-facing and
+   internal notes from the git range. Writing them before G2.5 risks announcing a launch that
+   then does not happen.
+4. **A human decides at G2.6.** The release owner decides whether to ship *now*, given
+   timing, freeze windows and on-call coverage. When that decision is contested, use
+   `council-review`. `RECONSIDER` means it is ready but this is the wrong time, and the work
+   waits instead of going back to `plan`.
+
+After `PROCEED`, the change is live and the work moves to `operate`. Gaps that G2.5 sent to
+`observability-plan` or `runbook-generator` are the first things `operate` picks up.
+
+## Verdicts
+
+Defined in [`contracts/terminals.json`](../../contracts/terminals.json). G2.5 emits `PROCEED`,
+`PROCEED WITH CONDITIONS`, `REVISE` or `BLOCKED`. G2.6 adds `RECONSIDER`. `PROCEED WITH
+CONDITIONS` at G2.5 is allowed only when the open rows are comms or exposure. A detection or
+response gap is always `REVISE`.
+
+## Non-interactive runs
+
+Never invent evidence such as rehearsal logs, load-test numbers, dashboards or sign-offs.
+When the change being released cannot be identified, emit `BLOCKED: need <the PR, tag, or
+feature name>`. G2.6 is a human gate. A headless run stops after `announce` and reports the
+G2.5 verdict for a person to act on.
+
+## When a stage's skill is not installed
+
+Name the missing skill and skilldrop as its source, do the minimal inline version of that
+stage, and record the stage as degraded. For `ready`, the minimal version is the seven checks
+written as a list, each marked met, not met or n/a with a reason. Skipping it is never the
+minimal version.
+
+## Quality bar
+
+- **Rollback exists before readiness is judged.** A plan with no way back is the one thing that cannot be fixed after launch.
+- **Readiness rests on evidence.** Every check links to something; "we're good" is `not met`.
+- **Can and should are separate gates.** G2.5 says whether it can ship; G2.6 says whether it should ship now.
+- **Detection gaps leave this loop as hand-offs.** `operate` picks them up first, rather than discovering them during the first incident.
+
+## Anti-patterns to avoid
+
+- ❌ **Jumping from merge to "instrument a running service".** That skips this loop entirely, which is the gap it exists to close.
+- ❌ **Announcing before G2.5.** Customers hear about a launch that is then pulled.
+- ❌ **Treating flag-off as a rollback without a data story.** If dual-write or a backfill has run, turning the flag off does not undo the data.
+- ❌ **Letting G2.6 overrule a G2.5 `BLOCKED`.** A human can delay a ready launch; they cannot make an unready one ready by deciding to go.

package/loops/release/loop.json

@@ -0,0 +1,47 @@
+{
+  "$comment": "RFC-0031. Covers the step between build (ends at merge, G2.1) and operate (starts at instrument). The gate ids sit between G2 and G3 to match where the loop sits in the lifecycle.",
+  "name": "release",
+  "version": "0.1.0",
+  "description": "Take merged code to live users through a planned, reversible rollout — plan the phases and the rollback, judge readiness on evidence, draft the release notes, then a human makes the go/no-go call. Use when the user has merged a change and asks how to roll it out, whether they are ready to launch, or for a go/no-go decision.",
+  "entrypoint": "LOOP.md",
+  "kind": "loop",
+  "cap": 3,
+  "stages": [
+    {
+      "id": "plan",
+      "type": "generate",
+      "intent": "Decide the rollout phases, the rollback for each, and the one point of no return, before anything reaches users.",
+      "skills": ["migration-plan"]
+    },
+    {
+      "id": "ready",
+      "type": "verify",
+      "intent": "Judge on evidence whether the change can go live: rollback, detection, response, measured targets, data, comms, exposure.",
+      "skills": ["launch-readiness"],
+      "gate": {
+        "id": "G2.5",
+        "kind": "review",
+        "verdicts": ["PROCEED", "PROCEED WITH CONDITIONS", "REVISE", "BLOCKED"],
+        "revise_to": "plan"
+      }
+    },
+    {
+      "id": "announce",
+      "type": "generate",
+      "intent": "Write what users and the team are told. Only after readiness, so nobody announces a launch that then fails the check.",
+      "skills": ["release-notes"]
+    },
+    {
+      "id": "go",
+      "type": "gate",
+      "intent": "A human decides whether it should ship now. Readiness says it can; this decides timing, freeze windows, and who is on call.",
+      "skills": ["council-review"],
+      "gate": {
+        "id": "G2.6",
+        "kind": "human",
+        "verdicts": ["PROCEED", "PROCEED WITH CONDITIONS", "REVISE", "RECONSIDER", "BLOCKED"],
+        "revise_to": "plan"
+      }
+    }
+  ]
+}

package/model-routing.json

@@ -146,6 +146,10 @@
       "tier": "standard",
       "rationale": "Extracts architecture from code/IaC. Escalate to heavy on large codebases where cross-file inference is heavy."
     },
+    "launch-readiness": {
+      "tier": "standard",
+      "rationale": "Checks evidence against a fixed checklist. Bounded synthesis, not adversarial review."
+    },
     "runbook-generator": {
       "tier": "standard",
       "rationale": "Operational doc from service facts. Bounded synthesis."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "description": "Portable AI-agent skills for the deliverables knowledge workers ship \u2014 diagrams, ADRs, PRDs, runbooks, decks, reviews \u2014 installable into Claude Code, Cursor, Kiro, and any IDE that takes custom instructions. One command per skill or per role-based pack.",
   "author": {
     "name": "Sanjay Ananthanarayan",

package/packs.json

@@ -1,12 +1,22 @@
 {
-  "$comment": "Virtual skill packs — role-based bundles for one-command install. Packs are METADATA ONLY: skills stay in flat skills/<name> folders (golden rule: skills are discovered by path), a skill may belong to several packs, and every skill must belong to at least one (validate.py enforces both directions). Install a pack with `python3 pack.py <pack> --install`; see README. Rationale: docs/rfcs/0001-skill-packs.md. `outcomes` (RFC-0026) is the second browse axis: packs say WHO needs a skill, outcomes say WHY someone opens the catalogue. It is the README's nine categories restated as seven outcomes and made machine-readable so the site cannot drift from them. Outcomes are a browse aid only — not an install unit — and validate.py enforces the same two-way check packs get.",
-  "version": "0.1.0",
+  "$comment": "Virtual skill packs — role-based bundles for one-command install. Packs are METADATA ONLY: skills stay in flat skills/<name> folders (golden rule: skills are discovered by path), every skill and every loop belongs to exactly one pack (RFC-0033 — the shape a later physical packs/<name>/ layout needs), and a pack may `requires` the `core` pack, which every installer then installs with it. validate.py enforces all of this. Install a pack with `python3 pack.py <pack> --install`; see README. Rationale: docs/rfcs/0001-skill-packs.md. `outcomes` (RFC-0026) is the second browse axis: packs say WHO needs a skill, outcomes say WHY someone opens the catalogue. It is the README's nine categories restated as seven outcomes and made machine-readable so the site cannot drift from them. Outcomes are a browse aid only — not an install unit — and validate.py enforces the same two-way check packs get.",
+  "version": "0.2.0",
   "packs": {
+    "core": {
+      "description": "The cross-role toolkit every pack builds on: structured intake, document critique, the review council, and output hygiene, plus the ship-a-draft wrapper. Installed automatically with every role pack.",
+      "loops": ["ship-a-draft"],
+      "skills": [
+        "brief-intake",
+        "doc-critique",
+        "output-hygiene",
+        "council-review"
+      ]
+    },
     "solution-architect": {
       "description": "Design-phase artifacts: diagrams, decision records, design docs, contracts, schemas, threat models, and the reviews that gate them.",
-      "loops": ["design", "ship-a-draft"],
+      "requires": ["core"],
+      "loops": ["design"],
       "skills": [
-        "brief-intake",
         "architecture-diagrams",
         "reverse-architecture",
         "figma-diagrams",
@@ -14,22 +24,17 @@
         "design-doc",
         "tech-comparison-matrix",
         "threat-model",
-        "agent-threat-model",
-        "agents-md-generator",
         "api-contract-draft",
         "data-contract",
         "db-schema-design",
-        "nfr-spec",
-        "capacity-cost-model",
-        "council-review",
-        "doc-critique"
+        "nfr-spec"
       ]
     },
     "product-manager": {
-      "description": "Direction to requirements: PR/FAQs, strategy frameworks, OKRs, PRDs, journey maps, story splitting, and success measurement.",
-      "loops": ["discover", "ship-a-draft"],
+      "description": "Direction to requirements: PR/FAQs, strategy frameworks, OKRs, business cases, interviews, PRDs, journey maps, and success measurement.",
+      "requires": ["core"],
+      "loops": ["discover"],
       "skills": [
-        "brief-intake",
         "prfaq",
         "strategy-analysis",
         "okr-cascade",
@@ -37,23 +42,19 @@
         "requirements-interview",
         "prd-draft",
         "user-journey-map",
-        "user-story-splitter",
-        "success-metrics",
-        "exec-summary",
-        "doc-critique",
-        "ai-use-case-triage"
+        "success-metrics"
       ]
     },
     "dev-team": {
-      "description": "Build-and-ship loop: story implementation with adversarial review, test plans, triage, migrations, release notes, agent-policy files, and code-quality gates.",
-      "loops": ["build", "ship-a-draft"],
+      "description": "Build-and-ship: story splitting, implementation with adversarial review, test plans, triage, migrations, launch readiness, release notes, agent-policy files, and code-quality gates.",
+      "requires": ["core"],
+      "loops": ["build", "release"],
       "skills": [
         "agents-md-generator",
         "user-story-splitter",
         "feature-implement-loop",
         "pre-merge-review",
         "devils-advocate",
-        "council-review",
         "test-plan-generator",
         "bug-triage",
         "migration-plan",
@@ -61,12 +62,13 @@
         "sonar-onboard",
         "sonar-review",
         "accessibility-audit",
-        "output-hygiene",
-        "contribution-wizard"
+        "contribution-wizard",
+        "launch-readiness"
       ]
     },
     "sre-oncall": {
       "description": "Operate the service: runbooks, observability design, incident communications, postmortems, and capacity/cost models.",
+      "requires": ["core"],
       "loops": ["operate"],
       "skills": [
         "runbook-generator",
@@ -78,22 +80,21 @@
     },
     "stakeholder-comms": {
       "description": "Non-technical audiences: audience profiling, deck outlines and real .pptx decks, exec summaries, decision logs, and guides.",
-      "loops": ["ship-a-draft"],
+      "requires": ["core"],
+      "loops": [],
       "skills": [
-        "brief-intake",
         "audience-profile",
         "slide-outliner",
         "deck-builder",
         "exec-summary",
         "decision-log",
-        "guide-builder",
-        "doc-critique",
-        "output-hygiene"
+        "guide-builder"
       ]
     },
     "ai-engineering": {
-      "description": "Adopt and build AI systems: readiness assessment, use-case triage, rollout and acceptable-use policy, plus agent loop design, subagent orchestration, spend budgets, agent security review, eval harnesses, AI-usage reporting, and the data contracts AI pipelines depend on.",
-      "loops": ["design", "build"],
+      "description": "Adopt and build AI systems: readiness assessment, use-case triage, rollout and acceptable-use policy, plus agent loop design, subagent orchestration, spend budgets, agent security review, eval harnesses, and AI-usage reporting.",
+      "requires": ["core"],
+      "loops": [],
       "skills": [
         "agent-loop-design",
         "subagent-design",
@@ -101,7 +102,6 @@
         "agent-threat-model",
         "llm-eval-harness",
         "ai-usage-report",
-        "data-contract",
         "ai-readiness-assessment",
         "ai-use-case-triage",
         "ai-adoption-rollout",
@@ -191,7 +191,8 @@
         "observability-plan",
         "release-notes",
         "incident-comms",
-        "postmortem-generator"
+        "postmortem-generator",
+        "launch-readiness"
       ]
     },
     "explain-it-to-decision-makers": {

package/skills/launch-readiness/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: launch-readiness
+description: Produce a go/no-go launch readiness report for a merged change before it goes live — one row per check (rollback path, alert and runbook per new failure mode, NFR targets measured, comms drafted, data/privacy sign-off), each with an owner, evidence link, and met / not met / n/a-because status, ending in a PROCEED / PROCEED WITH CONDITIONS / REVISE / BLOCKED verdict. Use when the user asks "are we ready to launch", "go/no-go", "production readiness review", "launch checklist", or "can we ship this to users".
+---
+
+# launch-readiness
+
+You judge whether a change that is already merged *can* go live, using evidence rather than
+reassurance. The output is a readiness report a release owner can act on in five minutes.
+Whether it *should* go live now (timing, freeze windows, who is on call) is a separate human
+decision. That belongs to `council-review` or the release owner, not to this report.
+
+## How to respond
+
+1. **Pin down what is launching.** You need: the change (a PR, a release tag, or a feature
+   name), who it reaches (internal, a percentage, everyone), and the release owner. If the
+   change itself is unknown, ask. You may ask at most 2 questions. A missing reach or owner
+   becomes an `[assumption]` to confirm. Everything else becomes a row that is `not met`
+   because evidence is missing.
+
+2. **List the new failure modes first.** Before any checklist, write 3–5 ways this specific
+   change could hurt users or data once it is live. Read them from the diff, the design doc or
+   the migration plan. Each later check is judged against this list. A generic checklist with
+   no failure modes is a ritual.
+
+3. **Fill [`templates/readiness-report.md`](templates/readiness-report.md).** It has one row
+   per check, and every row carries:
+   - **Status:** `met`, `not met`, or `n/a — <reason>`. `n/a` without a reason counts as `not met`.
+   - **Evidence:** a link, a command output, or a file path. A row with no evidence counts as
+     `not met`, however confident the user sounds. Evidence must cover the path the failure
+     mode touches; if it is unclear what it covered (which endpoint a load test hit), tag it
+     `[assumption]`.
+   - **Owner:** a role, not a person's name.
+
+4. **Apply the checks in this order.** The order matters: the first ones are the costliest to
+   discover after launch.
+   1. **Rollback.** It must be a tested path back, with its data story stated. If a data or
+      schema change is involved and no plan exists, hand off to `migration-plan`.
+   2. **Detection.** Each new failure mode needs an alert that fires before users complain. If
+      one is missing, hand off to `observability-plan`.
+   3. **Response.** Each such alert needs a runbook entry. If one is missing, hand off to
+      `runbook-generator`.
+   4. **Quality targets.** Every target in `nfr-spec` (latency, availability, scale) must be
+      *measured*, for example by a load test or canary result. A target that is only asserted
+      does not count.
+   5. **Data and privacy.** New personal data, retention changes or new processors need a
+      named sign-off, or `n/a — <reason>`.
+   6. **Comms.** User-facing notes are drafted (see `release-notes`), support is briefed, and
+      the status page owner is known if the launch is risky.
+   7. **Exposure.** The first exposure is staged (flag, percentage or cohort), or there is a
+      stated reason why all-at-once is safe.
+
+5. **Give the verdict.** It is the last line, with exactly one reason:
+   - `PROCEED`: every row is `met` or `n/a — <reason>`.
+   - `PROCEED WITH CONDITIONS`: only rows 6–7 are open, and each open row has an owner and a
+     date. The open rows travel with the release.
+   - `REVISE`: any row 2–5 is `not met`. Name the row and the hand-off that fixes it.
+   - `BLOCKED`: rollback is `not met`, or the change or its reach is unknown. A missing
+     rollback blocks on its own, whatever else passes.
+
+**Non-interactive runs** (CI, subagent, headless): never invent evidence such as test results,
+dashboards or sign-offs. Tag a guessed fact `[assumption]` and list it first. If the change
+being launched cannot be identified, emit `BLOCKED: need <the PR, tag, or feature name>`.
+
+## Useful references in this skill
+
+- [`templates/readiness-report.md`](templates/readiness-report.md) — the report skeleton, one row per check.
+- [`examples/schema-change-revise.md`](examples/schema-change-revise.md) — a worked report for a schema change that comes out `REVISE`.
+
+## Quality bar
+
+- **Every row has evidence or is `not met`.** Readiness asserted is not readiness.
+- **The failure modes are specific to this change.** "The service could go down" is true of everything and checks nothing.
+- **Rollback is judged first and can block alone.** Every other gap can be fixed while live; an irreversible launch with no way back cannot.
+- **The verdict follows mechanically from the rows.** Two reviewers given the same rows reach the same verdict.
+- **Owners are roles.** "Payments on-call", not a person who will change teams.
+
+## When to use this skill
+
+- ✅ A merged change is about to reach users and someone asks "are we ready?"
+- ✅ A production readiness review needs a written go/no-go record.
+- ✅ The `ready` stage of the `release` loop.
+
+## When NOT to use this skill
+
+- ❌ Deciding whether to *merge*. That is `pre-merge-review`'s gate, which happens earlier.
+- ❌ Planning the rollout phases themselves. That is `migration-plan`; this skill checks that the plan exists and has been rehearsed.
+- ❌ Choosing *when* to launch. Timing and freeze windows are the release owner's call, or `council-review`'s if they are contested.
+
+## Anti-patterns to avoid
+
+- ❌ **A generic checklist with every box ticked.** If no row is `not met` on a non-trivial launch, the evidence was not checked.
+- ❌ **`n/a` as a way out.** Data and privacy marked `n/a` with no reason is the most common way a launch skips a review it needed.
+- ❌ **Letting a strong row offset a missing rollback.** Great dashboards do not make an irreversible launch safe.
+- ❌ **Writing the runbook or the alert inside this report.** Name the gap and hand it off; a readiness report that also drafts fixes becomes too long to read.

package/skills/launch-readiness/evals/eval_queries.json

@@ -0,0 +1,10 @@
+[
+  { "query": "Are we ready to launch this to users on Monday?", "should_trigger": true },
+  { "query": "Run a go/no-go check on the checkout redesign before we turn it on", "should_trigger": true },
+  { "query": "Do a production readiness review for the new search service", "should_trigger": true },
+  { "query": "Give me a launch checklist for this release and tell me what's missing", "should_trigger": true },
+  { "query": "Is this PR safe to merge?", "should_trigger": false },
+  { "query": "Plan the phased rollout and backfill for moving users to the new auth provider", "should_trigger": false },
+  { "query": "Write the release notes for everything since v2.3", "should_trigger": false },
+  { "query": "Write the runbook for the payments service", "should_trigger": false }
+]

package/skills/launch-readiness/evals/evals.json

@@ -0,0 +1,19 @@
+{
+  "skill_name": "launch-readiness",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Are we ready to launch? PR #412 adds a `loyalty_points` column to `customers`, backfills it from order history, and shows points on the checkout page. Going to 100% of users Thursday. Load test hit p99 180ms against a 250ms target (link: grafana/d/lt-412). We have a dashboard but haven't added alerts yet. Support hasn't been told.",
+      "assertions": [
+        "Lists 3-5 failure modes specific to this change (e.g. backfill load on customers, wrong point totals shown at checkout) before the checklist",
+        "Every check row has a status of met, not met, or n/a with a reason, plus an evidence column and an owner expressed as a role",
+        "Rollback is the first row and is not met, because no tested rollback or data story was supplied",
+        "Detection is not met because no alerts exist, and the report hands off to observability-plan rather than drafting the alert inline",
+        "The quality-targets row is met and cites the supplied load-test link as evidence",
+        "Exposure is flagged because a 100% launch is not staged and no reason is given for why all-at-once is safe",
+        "The verdict is BLOCKED, and the reason given is the missing rollback",
+        "No dashboards, test results, or sign-offs are invented beyond what the prompt supplied"
+      ]
+    }
+  ]
+}

package/skills/launch-readiness/examples/schema-change-revise.md

@@ -0,0 +1,54 @@
+# Worked example — schema change that comes out REVISE
+
+## Input given to the skill
+
+> Go/no-go for release `orders-v4.2`. It splits `orders.address` into `shipping_address_id`
+> pointing at a new `addresses` table. We followed the migration plan
+> (docs/migrations/orders-address.md): expand and backfill are done in staging, and dual-write
+> is behind the flag `orders.address_split`. Rollback is "turn the flag off". It was rehearsed
+> in staging on 2026-09-28 (log: ci/run/88213). The p99 target for order reads is 120ms, and
+> the canary at 5% shows 96ms (grafana/d/orders-canary). The existing `orders-5xx` alert
+> covers this. Release notes are drafted in PR #977. Plan is 5% → 50% → 100% over three days.
+
+---
+
+# Launch readiness — orders-v4.2 (address split)
+
+**Change:** release `orders-v4.2` · **Reach:** 5% → 50% → 100% over 3 days · **Release owner:** Orders tech lead
+**Assessed:** 2026-10-01 · **Inputs:** migration plan, staging rollback log, canary dashboard, PR #977
+
+## New failure modes
+
+| # | Failure mode | Who is hurt | Reversible? |
+|---|---|---|---|
+| F1 | Dual-write diverges: an order is saved with an `addresses` row that doesn't match `orders.address` | Customers shipped to the wrong address | Partly. Data can be fixed, parcels already sent cannot |
+| F2 | The read path picks the new column before the backfill is complete for that tenant | Customers who see a blank address at checkout | Yes, by turning the flag off |
+| F3 | The extra join pushes order reads past p99 under full load | All checkout users | Yes, by turning the flag off |
+
+## Checks
+
+| # | Check | Covers | Status | Evidence | Owner |
+|---|---|---|---|---|---|
+| 1 | Rollback | all | met | Flag-off rehearsed in staging, ci/run/88213. While the old column is still written, flag-off loses no data | Orders on-call |
+| 2 | Detection | F1–F3 | **not met** | `orders-5xx` catches F3 errors only. Nothing detects F1 divergence or F2 blank reads, because both return 200 | Orders on-call |
+| 3 | Response | F1–F3 | **not met** | There is no runbook entry for divergence. `orders-5xx` has a runbook entry, but it does not mention the flag | Orders on-call |
+| 4 | Quality targets | F3 | met | Canary p99 96ms against a 120ms target at 5%, grafana/d/orders-canary | Orders tech lead |
+| 5 | Data & privacy | — | n/a — no new personal data. Address data moves between tables, and retention and processors are unchanged | Migration plan §2 | Data protection lead |
+| 6 | Comms | — | met | Release notes drafted in PR #977. No customer-visible change | Orders tech lead |
+| 7 | Exposure | — | met | Staged 5% → 50% → 100% behind `orders.address_split` | Release owner |
+
+## Open items
+
+- Row 2: add a reconciliation metric for dual-write divergence, and an alert on any non-zero count, plus an alert on blank-address reads. Orders on-call, before the 5% → 50% step. Hand off to `observability-plan`.
+- Row 3: add a runbook entry for "divergence alert fires" (flag off, then run the reconciler), and add the flag to the `orders-5xx` entry. Orders on-call, same deadline. Hand off to `runbook-generator`.
+
+## Verdict
+
+**REVISE.** Row 2 is not met: the two failure modes that do lasting damage (F1, F2) return 200, so nothing would detect them. Fix rows 2 and 3, then run readiness again.
+
+---
+
+**Why this is a good output:** the rollback is genuinely in place, so the verdict is REVISE and
+not BLOCKED. The report notices that an existing alert covering the change only catches the
+failure that is easiest to undo. It does not draft the alert or runbook itself; it names the
+gap, the owner and the hand-off.

package/skills/launch-readiness/manifest.json

@@ -0,0 +1,24 @@
+{
+  "name": "launch-readiness",
+  "version": "0.1.0",
+  "description": "Produce a go/no-go launch readiness report for a merged change before it goes live — one row per check (rollback path, alert and runbook per new failure mode, NFR targets measured, comms drafted, data/privacy sign-off), each with an owner, evidence link, and met / not met / n/a-because status, ending in a PROCEED / PROCEED WITH CONDITIONS / REVISE / BLOCKED verdict. Use when the user asks \"are we ready to launch\", \"go/no-go\", \"production readiness review\", \"launch checklist\", or \"can we ship this to users\".",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": [
+    "migration-plan",
+    "observability-plan",
+    "runbook-generator",
+    "nfr-spec",
+    "release-notes",
+    "council-review",
+    "pre-merge-review"
+  ],
+  "handoff": [
+    { "to": "migration-plan", "when": "the change has no tested rollback path", "purpose": "Plan the phases and the rollback, and name the point of no return, before readiness is judged again.", "fallback": "If migration-plan is absent, write the rollback as numbered steps with its data story inline, and mark the row not met until someone has rehearsed it." },
+    { "to": "observability-plan", "when": "a new failure mode has no alert", "purpose": "Define the SLI and the burn-rate alert that would detect it.", "fallback": "If observability-plan is absent, name the symptom, the metric that shows it, and a threshold inline, tagged [assumption] for the owner to confirm." },
+    { "to": "runbook-generator", "when": "an alert exists but has no runbook entry", "purpose": "Write the procedure the on-call follows when that alert fires.", "fallback": "If runbook-generator is absent, write recognise / mitigate / escalate as three lines under the row, and keep the row not met until the on-call owner has reviewed them." }
+  ],
+  "tags": ["launch", "release", "readiness", "go-no-go", "production-readiness"],
+  "model": { "tier": "standard", "rationale": "Checks evidence against a fixed checklist. Bounded synthesis, not adversarial review." }
+}

package/skills/launch-readiness/templates/readiness-report.md

@@ -0,0 +1,41 @@
+# Launch readiness — {change name}
+
+**Change:** {PR / tag / feature} · **Reach:** {internal / N% / cohort / everyone} · **Release owner:** {role}
+**Assessed:** {YYYY-MM-DD} · **Inputs:** {what was read — diff, design doc, migration plan, dashboards}
+
+> **Assumptions to confirm first** (omit if none)
+> - `[assumption]` {fact guessed rather than given}
+
+## New failure modes
+
+What this change, specifically, could do to users or data once live.
+
+| # | Failure mode | Who is hurt | Reversible? |
+|---|---|---|---|
+| F1 | {e.g. backfill locks `orders` table under peak write load} | {checkout users} | {yes / no / partly} |
+| F2 | | | |
+| F3 | | | |
+
+## Checks
+
+Status is `met`, `not met`, or `n/a — <reason>`. No evidence means `not met`.
+
+| # | Check | Covers | Status | Evidence | Owner |
+|---|---|---|---|---|---|
+| 1 | **Rollback** — tested path back, data story stated | all | | {link / command output} | {role} |
+| 2 | **Detection** — an alert per failure mode, fires before users complain | F1–F3 | | | |
+| 3 | **Response** — a runbook entry per alert in row 2 | F1–F3 | | | |
+| 4 | **Quality targets** — each NFR target measured, not asserted | | | | |
+| 5 | **Data & privacy** — sign-off for new personal data, retention, or processors | | | | |
+| 6 | **Comms** — release notes drafted, support briefed, status-page owner known | | | | |
+| 7 | **Exposure** — first exposure staged, or why all-at-once is safe | | | | |
+
+## Open items
+
+One line per `not met` row: what closes it, who, by when, and the hand-off if any.
+
+- Row {n}: {what closes it} — {owner role}, {date} → {`migration-plan` / `observability-plan` / `runbook-generator` / none}
+
+## Verdict
+
+**{PROCEED | PROCEED WITH CONDITIONS | REVISE | BLOCKED}** — {the one reason, naming the row}.