@launchsecure/launch-kit 0.0.29 → 0.0.31

package/scaffolds/ls-marketplace/plugins/kit/skills/blast-radius/SKILL.md

@@ -0,0 +1,117 @@
+---
+description: Build a blast radius for a file/table/endpoint via launch-chart and push it to launch-deck as an interactive radial graph. Use to assess "what breaks if I change X" before refactors, schema migrations, or API contract changes. Chart-first; on chart gaps (no nodes, missing layer, empty edges) files a feedback comment to LaunchSecure so the gap is monitored.
+when_to_use: |
+  Auto-fire when the user wants to VISUALISE the reverse-dependency blast radius for a specific node (file / table / endpoint / hook) before a refactor, migration, or contract change. Trigger phrases: "what breaks if I change X", "blast radius for X", "impact of refactoring X", "who's affected if I rename / drop / remove X", "scope this migration", "ripple effect of changing X", "is X safe to remove". Deck is required because the deliverable is an interactive radial graph — a flat list of dependents in the terminal misses ring/layer structure. Do NOT auto-fire for: simple "who imports X" or "where is X used" (use /kit:analyse), reading the structure of one file (use chart read_graph directly), planning the change itself (separate step that runs after blast-radius), plain-text dependency summaries the user can read in the terminal, or any request without a clear named target node.
+allowed-tools:
+  - mcp__launch-deck__server_status
+  - mcp__launch-deck__start_server
+  - mcp__launch-deck__deck
+  - mcp__launch-chart__chart_server_status
+  - mcp__launch-chart__detect_project_stack
+  - mcp__launch-chart__blast_points
+  - mcp__launch-chart__read_graph
+  - mcp__launch-secure__kit_feedback_submit
+  - Bash
+---
+
+# /kit:blast-radius
+
+Calculate the reverse-dependency blast radius for a target node and visualise it as an interactive radial graph in launch-deck. The graph centres on the target and rings out by hop distance across all project layers (db / api / ui / static / etc.).
+
+Parse `$ARGUMENTS`:
+- **target** (required) — a node id from the project graph (file path like `lib/permissions/types.ts`, table name like `User`, endpoint id like `POST /api/work-items`). If absent, ask the user.
+- **hops=N** — max traversal depth. Default 2.
+- **layer=<id>** — restrict to one layer when the same name exists in multiple layers (e.g. `layer=db`).
+- **--session=<id>** — deck session name. Default `blast-<target-slug>`.
+- **--mode=feature** — render with feature rings (modify / create / ripple) instead of the default structural rings (hop1 / hop2). Use when the radius represents planned change scope rather than pure structural reachability.
+
+Examples:
+- `/kit:blast-radius lib/permissions/types.ts`
+- `/kit:blast-radius User layer=db hops=3`
+- `/kit:blast-radius POST /api/work-items --mode=feature`
+
+## Preflight
+
+1. Confirm both MCPs are wired — `mcp__launch-chart__chart_server_status` and `mcp__launch-deck__server_status`. If either is missing, stop and tell the user to run `npx @launchsecure/launch-kit refresh` (or `npx launch-deck` for the deck server).
+2. Run `mcp__launch-chart__detect_project_stack` once. Cache the returned `layers` for the bug-report fallback below.
+
+## 1. Compute the blast points
+
+Call `mcp__launch-chart__blast_points` with `node_id: <target>`, `hops: <hops>`, `direction: "reverse"`, and `layer` if supplied. The tool returns affected nodes (with hop, type, layer, module) plus a summary.
+
+**Chart-gap detection** — if any of these are true, file a feedback comment per the shared `chart-gap` protocol below before stopping:
+- `error` is set
+- `nodes` is empty AND the user explicitly named a node id that exists on disk (verify by `Read`-ing the path)
+- `summary.byLayer` covers fewer layers than `detect_project_stack` reported as available
+
+## 2. Build the manifest
+
+Translate the blast_points result into the deck `blast-radius` block manifest shape. Reuse layer ids/icons/colors from `detect_project_stack` so the visual matches the project's conventions; fall back to:
+- db → `database`, `#172554`
+- api → `server`, `#1e3a5f`
+- ui → `layout-dashboard`, `#0c4a6e`
+- static → `file-text`, `#374151`
+- shared → `puzzle`, `#4338ca`
+- middleware → `shield`, `#1f2937`
+- config → `cog`, `#52525b`
+
+Rings:
+- structural mode (default): `[{id:"hop1",name:"Direct",color:"#f97316"},{id:"hop2",name:"Indirect",color:"#eab308"}]`
+- feature mode: `[{id:"modify",name:"Modify",color:"#f97316"},{id:"create",name:"Create",color:"#22c55e"},{id:"ripple",name:"Ripple",color:"#eab308"}]`
+
+Centre node: `{ name: <target>, description: "<N> direct, <M> indirect (<hops> hops)" }`.
+
+Nodes: map each blast result row to `{ id, name, layer, ring: hop===1 ? "hop1" : "hop2", path, type }`.
+
+Edges: connect the centre to every hop=1 node; connect each hop=2 node to one hop=1 ancestor from its dependency chain (read from `blast_points` `via` field if present, otherwise pick any hop=1 node in the same layer).
+
+## 3. Push to deck
+
+Call `mcp__launch-deck__deck` with `session: <session>`, `mode: "show"`, `blocks: [{ type: "blast-radius", label: <target>, manifest: <built-manifest> }]`.
+
+If the deck server isn't running, call `mcp__launch-deck__start_server` first, then retry.
+
+## 4. Open in browser
+
+After the push, open the per-session URL so the user lands directly on this blast-radius:
+
+```
+open "<deck-url>/#<session>"          # macOS
+xdg-open "<deck-url>/#<session>"      # Linux
+```
+
+`<deck-url>` is the `url` returned by `mcp__launch-deck__server_status` (typically `http://localhost:52829`). The `#<session>` hash deep-links to this exact session.
+
+## Output
+
+After the push, print a terse summary:
+
+```
+blast-radius for <target> — <N> direct, <M> indirect (<hops> hops)
+  by layer: db 4, api 7, ui 12
+  pushed to deck session "<session>" — <deck-url>/#<session>
+```
+
+## Chart-gap protocol (shared)
+
+When the chart MCP returns less data than expected, file ONE report via `mcp__launch-secure__kit_feedback_submit` (the kit-self feedback channel — NOT `communication_write`, which would land in the user's own project Comm Hub instead of the launch-kit project) before stopping:
+
+```
+title: "launch-chart gap: <one-line>"
+source: "kit:blast-radius"
+body: |
+  Skill: /kit:blast-radius
+  Tool:  blast_points(node_id=<id>, hops=<n>, layer=<layer?>)
+  Returned: <nodes_count> nodes, layers=<layers_seen>
+  Expected: <what-was-expected, e.g. "node exists at <path>" or "layer X should appear">
+  Project stack: <one-line summary from detect_project_stack>
+```
+
+Do NOT spam — file at most one report per skill invocation. After filing, tell the user "Filed chart-gap report to launch-kit project. Falling back to read_graph + Read." and continue with a degraded path: try `mcp__launch-chart__read_graph` with `search: <target>` to confirm the node exists in any layer; if so, do the blast-radius math from `include_edges: true` results manually; otherwise stop and surface the gap to the user.
+
+## Constraints
+
+- **MCP-first.** Never grep the filesystem to build the manifest — use `blast_points` and `read_graph`.
+- **Idempotent on re-run.** Re-pushing to the same session overwrites the previous render — that's fine, just tell the user.
+- **Single bug-file per run.** Don't file a comment for every gap; bundle into one report.
+- **Plain text output.** No markdown tables, no fenced blocks in the human-facing summary.

package/scaffolds/ls-marketplace/plugins/kit/skills/brief/SKILL.md

@@ -0,0 +1,112 @@
+---
+description: Create or update a repo-backed Brief in the LaunchSecure Comm Hub per the LS Briefs framework — Discovery-plane document (docCategory=features) authored as a comment that's also synced to a markdown file in the repo. Use to capture an idea before promoting it to an Epic.
+---
+
+# /kit:brief
+
+A **Brief** is an LS Discovery-plane artefact: a long-form description of a problem/opportunity, authored as a comment in the project's Comm Hub AND backed by a markdown file in the repo (`docs/requirements/features/<slug>.md` by convention). It's the structured alternative to a free-form Discussion when the idea has enough shape to write down. Briefs get promoted to Epics on the Roadmap once they're DECIDED.
+
+Parse `$ARGUMENTS`:
+- **subcommand** (required) — `new` | `update` | `list` | `show`.
+- For **new**: `<title>` (required), `--from=discussion:<id>` to seed body from an existing discussion thread, `--module=<slug>` to tag.
+- For **update**: `<brief-id-or-slug>` and either a body description (re-generates body) or `--append=<text>` to add a section.
+- For **list**: `[--module=<slug>] [--status=open|decided|declined]`.
+- For **show**: `<brief-id-or-slug>`.
+
+Examples:
+- `/kit:brief new "Channels for Comm Hub" --module=communication`
+- `/kit:brief new "Roadmap nav" --from=discussion:cmt_abc123`
+- `/kit:brief list --status=open`
+- `/kit:brief show channels-for-comms`
+- `/kit:brief update channels-for-comms --append="Resolved: use the Slack metaphor not Teams."`
+
+## Preflight
+
+1. Confirm `mcp__launch-secure__ping` works (the cloud LS MCP must be wired). If only `mcp__local-launch-secure__*` is wired, ask the user whether to post to local or cloud — default per project memory is CLOUD.
+2. For `new`, sanity-check that no existing brief with the same slug already exists — call `mcp__launch-secure__communication_read` filtered by `resourceType=comment` and search the title. If a match is found, ask whether to update instead.
+
+## The Brief shape
+
+Per the LS Briefs framework (`docs/requirements/work-items/roadmap-and-hierarchy.md`):
+
+- **resourceType**: `comment` (Briefs are comments)
+- **docCategory**: `features` (this is what file-backed sync watches)
+- **title**: the human-friendly name; the slug is derived
+- **body**: the long-form markdown — sections below
+- **file_links**: not used here; the FileBackedEntity link is created by LS server-side on first save
+- **tags**: optional module tag, plus a `brief` tag for filtering
+
+### Body template
+
+When generating a NEW brief, use this skeleton (markdown body):
+
+```markdown
+# <Title>
+
+**Status**: PROPOSED  
+**Owner**: <user-mention or "unassigned">  
+**Module**: <module slug or "-">
+
+## Problem
+
+<1-2 paragraphs — what's broken or missing, who feels it, why now>
+
+## Proposed direction
+
+<1-3 paragraphs — the shape of the solution, not the implementation>
+
+## Out of scope
+
+- <bullets — what this brief deliberately does NOT cover>
+
+## Open questions
+
+- [ ] <bullets — what we still need to decide before this can become an Epic>
+
+## Success looks like
+
+<1-2 sentences — observable outcome, not "ship X">
+
+## References
+
+- <link to existing code via launch-chart node id (use mcp__launch-chart__read_graph to find the right nodes; cite them as `lib/foo/bar.ts:42`)>
+- <related comments by id>
+```
+
+The body is plain markdown — Comm Hub renders it. Use launch-chart to add real code references (don't invent file paths).
+
+## Write paths
+
+### new
+
+1. Build the body from the template + the user's description (or the `--from=discussion:<id>` seed — fetch via `communication_read` and weave the relevant points into the Problem/Proposed-direction sections).
+2. Call `mcp__launch-secure__communication_write` with:
+   - `title: <user-supplied>`
+   - `body: <generated-markdown>`
+   - `resource_type: "comment"`
+   - `fields: { docCategory: "features", briefStatus: "PROPOSED" }`
+   - `tag_ids: <module tag id + "brief" tag id>` (call `mcp__launch-secure__tags_list` first to resolve names → ids; if either tag doesn't exist, surface the missing tag(s) and proceed without)
+3. Print the returned comment id + URL.
+4. Tell the user: "LS server-side file-backed sync will materialize `docs/requirements/features/<slug>.md` on the next default-branch push that includes this brief — pull the branch to see it locally."
+
+### update
+
+1. Resolve `<brief-id-or-slug>` via `communication_read(resourceType: "comment", search: <slug>)`. If multiple match, list them and stop.
+2. If `--append=<text>`, fetch the current body, append the text under a `## Update <ISO-date>` heading, and call `mcp__launch-secure__communication_update` with the new body.
+3. If a fresh description was passed, regenerate the body from the template + new description, ask the user to confirm (show the diff briefly), then update.
+
+### list
+
+`mcp__launch-secure__communication_read` filtered by `resourceType=comment`, narrow on `docCategory=features` if the API supports it (otherwise pull a wider set and filter client-side by tag/status). Render one line per brief: `id  status  title  module  updated`.
+
+### show
+
+Fetch via `communication_read` and print the body as-is, no transformation.
+
+## Constraints
+
+- **Plain markdown body.** Per project memory `feedback_comms_plain_text.md`, comms posts are plain — no HTML, no emojis unless the user wrote them.
+- **One brief, one comment.** Don't fragment a brief across multiple comments — append via `--append` to keep the document continuous.
+- **Cloud LS by default.** Per memory `feedback_post_to_cloud_ls_default.md`. Local LS only when the user explicitly says "local".
+- **Cite real code.** Use launch-chart node ids in the References section — don't invent file paths.
+- **Don't auto-promote to Epic.** A Brief → Epic is a deliberate human action (project memory: bucket transitions are deliberate, not derived). Surface a hint at the end: "When DECIDED, run `/work-items create epic --from-brief=<id>` to promote."

package/scaffolds/ls-marketplace/plugins/kit/skills/course/SKILL.md

@@ -0,0 +1,84 @@
+---
+description: Show the currently active LaunchSecure course (server profile) and list the others available in .launch-secure.cred.config. Surfaces which serverUrl/org/project this Claude session is talking to so the user doesn't post local LS comms to prod, or vice versa. Read-only by default; switch is opt-in.
+---
+
+# /kit:course
+
+A "course" is a named LaunchSecure destination — `serverUrl + PAT + orgSlug + projectSlug` — stored under `profiles` in `.launch-secure.cred.config`. The active course drives every MCP call and every `npx launch-pod` invocation. This skill answers two questions: *which course am I on right now*, and *what others are available* — without changing anything unless explicitly told to.
+
+Parse `$ARGUMENTS` — first token is the subcommand:
+
+- (empty) or **status** — one-line: which course is active.
+- **list** — table of every course, active marked with `★`.
+- **switch <name>** — change the active course (rewrites `.launch-secure.cred.config` AND `.mcp.json`'s launch-secure URL). Asks for confirmation.
+- **diff** — show the deltas between two courses (`--a=<name> --b=<name>`).
+
+Examples:
+- `/kit:course`            → "active: prod (acme/launchsecure-v2 @ launchsecure-v2.vercel.app)"
+- `/kit:course list`       → table
+- `/kit:course switch local`
+- `/kit:course diff --a=local --b=prod`
+
+## Preflight
+
+Confirm `.launch-secure.cred.config` exists in the cwd (or in the nearest parent up to 3 levels — `cred-shape.ts`'s lookup convention). If missing, tell the user: `"No .launch-secure.cred.config here. Run \`npx @launchsecure/launch-kit init\` first."`
+
+Read the cred file directly (it's gitignored, lives at the repo root, JSON shape with `active` + `profiles`). Never call out to launch-course CLI from inside the skill for read operations — read the file. Use `launch-course` (Bash) only for `switch` (it owns the MCP rewrite invariant).
+
+## Per-subcommand behavior
+
+### status (default)
+
+Read the cred file. Print one line:
+
+```
+active: <name> (<orgSlug>/<projectSlug> @ <serverUrl>)
+```
+
+If the file is in legacy flat shape (single profile at the top), say so explicitly: `"active: (legacy single-profile shape — no name; first multi-profile op auto-migrates)"`.
+
+### list
+
+```
+courses (3):
+    name        serverUrl                              org/project
+  ★ prod        https://launchsecure-v2.vercel.app     acme/launchsecure-v2
+    staging     https://staging.launchsecure-v2.app    acme/launchsecure-v2
+    local       http://localhost:3000                  acme/launchsecure-v2
+```
+
+Sort: active first, then alphabetical. Column-align with monospace.
+
+### switch
+
+1. Sanity-check `<name>` exists in `profiles`. If not, list available names and stop.
+2. Print the BEFORE → AFTER one-liner:
+   ```
+   switching: prod (acme/launchsecure-v2 @ launchsecure-v2.vercel.app)
+             → local (acme/launchsecure-v2 @ localhost:3000)
+   ```
+3. Ask: `"Continue? (yes / no)"` — wait for `yes`. Per project memory, destructive/sticky changes require explicit confirmation.
+4. On `yes`, run `npx launch-course set <name>` via Bash. This rewrites both `.launch-secure.cred.config` (active pointer) AND `.mcp.json` (the launch-secure URL). Surface the CLI output verbatim.
+5. After switch, remind: `"Restart Claude Code to pick up the new MCP URL (or use \`/mcp reload\` if available)."`
+
+### diff
+
+Resolve `--a` and `--b` from `profiles`. Print a compact diff:
+
+```
+local         →  prod
+serverUrl     http://localhost:3000              →  https://launchsecure-v2.vercel.app
+org           acme                               →  acme
+project       launchsecure-v2                    →  launchsecure-v2
+pat           sha256:abc1…ef                     →  sha256:def0…12
+```
+
+PAT values are hashed (sha256 first 8 of each, last 2 — purely for the user to confirm they differ; never print full PATs). Same row for unchanged values.
+
+## Constraints
+
+- **Read-only by default.** Only `switch` writes; status/list/diff never mutate.
+- **Switch requires confirmation.** Per project memory, never destructive without `yes`.
+- **No PAT exfiltration.** Never print the full PAT value; show short hashes for diff identification only.
+- **Don't bypass launch-course CLI.** The `switch` MCP-rewrite logic is its responsibility — call the CLI; don't reimplement the .mcp.json mutation inside the skill (drift risk).
+- **Surface the active course on every run.** Even on `list`/`diff`, the first or last line shows which course is active so the user is never confused about session scope.

package/scaffolds/ls-marketplace/plugins/kit/skills/debug/SKILL.md

@@ -0,0 +1,85 @@
+---
+description: Investigate a bug, error message, or unexpected behavior using launch-chart first (structural + variable queries), falling back to grep/Read only when the chart can't answer. When the chart gap is the reason for the fallback, files a feedback comment to LaunchSecure so the gap is monitored and fixed.
+---
+
+# /kit:debug
+
+A guided investigation workflow that defaults to chart-MCP queries and only reaches for grep/Read when the chart can't answer — and when that happens, files a one-line feedback comment in LS so the gap doesn't go unnoticed.
+
+Parse `$ARGUMENTS`:
+- **symptom** (required) — the error message, broken behavior, or question to investigate. Quoted is fine: `/kit:debug "tags don't render on the work-item drawer"`.
+- **--start=<node>** — start the investigation from a specific file/function/table id (skip the search step).
+- **--layer=<id>** — scope chart queries to one layer (ui / api / db / static).
+- **--no-grep-fallback** — refuse the grep fallback entirely (strict MCP-only).
+
+Examples:
+- `/kit:debug tags don't render on the work-item drawer`
+- `/kit:debug "TypeError: Cannot read property 'status' of undefined" --layer=ui`
+- `/kit:debug --start=src/server/comms/build-feed.ts`
+
+## Investigation loop
+
+Run this loop until the user has enough to act, OR until a fallback was filed (then surface the fallback):
+
+### Step 1 — locate the entry point
+
+If `--start` was given, jump to step 2. Otherwise, use chart to find candidate nodes:
+
+1. Extract key terms from the symptom (component name, identifier, error class). Skip noise words.
+2. Call `mcp__launch-chart__read_graph(search: <term>, type: <best-guess-type>, layer: <layer?>)`. If `type` is uncertain, omit it and filter the response by relevance.
+3. If `read_graph` returns 0 candidates, broaden: try without `type`, then without `layer`. Surface the top 3 candidates to the user as ranked options; if the user can pick, jump to step 2 with their pick.
+
+**Chart-gap detection (entry-point search):**
+- If `read_graph` returns 0 candidates AND a quick `grep` confirms the term exists somewhere in source → file a chart-gap report per the protocol below, then proceed via the grep fallback for this query only.
+- If `detect_project_stack` lists a layer (e.g. `api`) but `read_graph(layer:"api")` returns 0 nodes → file a chart-gap report (parser misconfig).
+
+### Step 2 — understand the node
+
+Once the entry point is known, query its structure and behavior:
+
+- **Structural** — `mcp__launch-chart__read_graph(node_id: <id>, hops: 1, include_edges: true)` for what it renders/imports and what depends on it.
+- **Variable / state** — `mcp__launch-chart__inspect_node(node_id: <id>, fields: ["stateVars"])` or `(filter: <key-term>)` for what state it holds, what conditions exist. Per project CLAUDE.md, ALWAYS start with `fields` or `filter` to keep the response small.
+
+Compose a hypothesis from these two reads. Example: "WorkItemDrawer fetches tags via `useWorkItemTags`, which calls `GET /api/work-items/:id/tags` — let's see what that returns."
+
+### Step 3 — follow the trail
+
+Walk the dependency edges toward the suspected cause (API endpoint, DB table, util fn, etc.). At each hop, use `read_graph(node_id, hops:1)` to find the next link. When you hit a leaf or run out of edges, narrate the chain back to the user with file:line refs from the node ids.
+
+### Step 4 — propose, don't fix
+
+End with a one-paragraph diagnosis + 2-3 candidate causes ranked by likelihood. Do NOT propose an edit unless the user asks for one — debug is investigation, not implementation. Suggest the next move: "Want me to read the route handler and confirm?" or "Want `/kit:diagram sequence`-ing the call chain?"
+
+## Grep fallback
+
+Only enter this path when:
+- the chart returned no results AND a chart-gap report was filed, OR
+- the symptom is about a non-TS asset (CSS string, env var, JSON value, comment) — the chart doesn't model these and the gap is expected.
+
+Then use `grep`/`Read` directly. Always tell the user explicitly: `"Chart returned nothing — falling back to grep (filed gap report id: …)"` or `"Symptom is in CSS/JSON, which chart doesn't model — using grep directly (no gap report needed)."`
+
+## Chart-gap protocol (shared)
+
+When the chart MCP returns less than the symptom suggests it should, file ONE report via `mcp__launch-secure__kit_feedback_submit` (the kit-self feedback channel — NOT `communication_write`, which would land in the user's own project Comm Hub instead of the launch-kit project):
+
+```
+title: "launch-chart gap: <one-line>"
+source: "kit:debug"
+body: |
+  Skill: /kit:debug
+  Symptom: <one-line symptom>
+  Tool:    read_graph(search="…", layer="…", type="…")
+  Returned: 0 nodes
+  Cross-check: grep "<term>" matched <N> files (sample: <path1>, <path2>)
+  Project stack: <detect_project_stack one-liner>
+```
+
+Then continue with the grep fallback for THIS query. Don't file again in the same invocation.
+
+## Constraints
+
+- **Chart-first.** Default to MCP queries; grep only when the chart cannot answer.
+- **One gap report per invocation.** Don't spam comments.
+- **No implementation.** This skill diagnoses; it does not edit. If the user wants the fix, they invoke `/fix:*` or hand the diagnosis back to you in chat.
+- **Cite by node id.** Every claim links to a chart node id (file:line via `inspect_node` lines) so the user can verify.
+- **Surface the fallback verbatim.** When grep is used, the message that grep was used (and why) must appear in the output — silent fallback hides the gap.

package/scaffolds/ls-marketplace/plugins/kit/skills/deploy-check/SKILL.md

@@ -0,0 +1,160 @@
+---
+description: Production-readiness check for the current branch — typecheck, lint, build, prisma drift, migration safety, env coverage, and recent LS comms. Read-only; reports a punch list of go/no-go signals before a deploy or merge to a deploy-tracked branch. Does NOT deploy.
+---
+
+# /kit:deploy-check
+
+Audit the current branch for production readiness. Bundles every signal a human would manually check before clicking "deploy" or merging to a deploy-tracked branch (per project convention: `master`). Reports a punch list with ✓ / ⚠ / ✗ per check and a single go/no-go verdict.
+
+Parse `$ARGUMENTS`:
+- (empty) — full check on the current branch vs `master` (or repo's default).
+- **--target=<branch>** — compare against a different deploy-tracked branch.
+- **--skip=<check,…>** — comma-separated checks to skip (e.g. `--skip=lint,build`). Use sparingly; surface skipped checks in the report.
+- **--quick** — skip the build (the slowest check). Still runs typecheck, lint, prisma, env, comms.
+- **--json** — emit a machine-readable report (per check: ok, detail, durationMs).
+
+Examples:
+- `/kit:deploy-check`
+- `/kit:deploy-check --quick`
+- `/kit:deploy-check --skip=lint`
+- `/kit:deploy-check --target=staging-mirror --json`
+
+## Preflight
+
+1. Confirm cwd is a git repo (`git rev-parse --is-inside-work-tree`).
+2. Resolve the target branch — `--target=` if given, else default branch (`git symbolic-ref refs/remotes/origin/HEAD --short` → strip `origin/`; fall back to `master`).
+3. Print the scope upfront: `"deploy-check: <current-branch> → <target-branch>"`. The user should never wonder which comparison this is.
+4. Stash check — if `git status --porcelain` shows uncommitted changes, surface this as a `⚠ uncommitted changes in working tree` row at the top of the report. Don't refuse; some workflows want the check to include uncommitted work.
+
+## Checks
+
+Run every check in PARALLEL when possible (typecheck/lint/build are independent and slow). Each check returns `{ name, status: "ok"|"warn"|"fail", detail: <one-line>, artifact?: <path or url> }`.
+
+### 1. branch_freshness
+
+How far behind the target branch is the current branch?
+
+```
+git fetch --quiet origin
+git rev-list --left-right --count <target>...HEAD
+```
+
+- ✓ `0 commits behind target` → fresh
+- ⚠ `1–10 behind`
+- ✗ `>10 behind` → suggest `git merge origin/<target>` or rebase
+
+### 2. typecheck
+
+`npx tsc --noEmit` (or the project's `npm run typecheck` if defined in `package.json` scripts — prefer the script).
+
+- ✓ `0 errors`
+- ✗ `<N> errors` (sample first 3 file:line:message)
+
+### 3. lint
+
+`npm run lint` if defined in `package.json` scripts; else skip with a `⚠ no lint script defined` row.
+
+- ✓ `0 errors`
+- ⚠ `<N> warnings`
+- ✗ `<N> errors`
+
+### 4. build
+
+`npm run build` (uses the project's actual build pipeline so the check matches what Vercel/CI would do). Skip if `--quick` or `--skip=build`.
+
+- ✓ `built in <durationMs>ms`
+- ✗ `build failed` (last 20 lines of stderr as artifact)
+
+Note: this runs the full prod build including prisma generate + migrate deploy. Make sure `DATABASE_URL` is set to a *safe* dev DB before running. If `DATABASE_URL` looks production-y (matches `vercel.app`, `neon.tech`, `rds.amazonaws.com`, etc.), refuse the build step and surface `⚠ build skipped — DATABASE_URL looks production-y (<host>); re-run with a dev DB or pass --skip=build`.
+
+### 5. prisma_drift
+
+Schema vs migrations consistency:
+
+```
+npx prisma migrate diff --from-schema-datasource prisma/schema.prisma --to-migrations prisma/migrations --shadow-database-url <DEV_SHADOW_URL>
+```
+
+The project authors migrations by hand (CLAUDE.md: never `prisma db push` or `migrate dev`). So this diff should be EMPTY — any non-empty result means a model field was added without a corresponding hand-written migration.
+
+- ✓ `schema matches migrations`
+- ✗ `<N> drift detected` — surface the diff body as an artifact; suggest authoring a migration per the project's hand-written SQL convention.
+
+If no `DEV_SHADOW_URL` is available, skip this check with `⚠ prisma_drift skipped — no shadow DB URL` and recommend setting one in `.env.local`.
+
+### 6. migration_safety
+
+Recent migrations on the branch — look at every migration file added since divergence from target:
+
+```
+git diff --name-only <target>...HEAD -- prisma/migrations/
+```
+
+For each new migration, scan the SQL for risk patterns (per project CLAUDE.md migration safety rules):
+
+- ✓ no destructive ops (`DROP COLUMN`, `DROP TABLE`, `ALTER COLUMN ... DROP`, `DELETE FROM` without `WHERE` matching backup) found.
+- ⚠ destructive ops present BUT a sidecar `CREATE TABLE _backup_*` exists in the same file AND an orphan-check (`RAISE EXCEPTION ... orphans remain`) is present.
+- ✗ destructive ops without backup OR without orphan-check OR mixing expand+contract in a single migration.
+
+Each failure cites the exact migration filename + line numbers.
+
+### 7. env_coverage
+
+Compare `.env.example` (or `.env.testing` if it exists) keys against `process.env.*` references in the new code since divergence:
+
+```
+git diff <target>...HEAD -- '*.ts' '*.tsx' | grep -oE 'process\.env\.[A-Z_][A-Z0-9_]+'
+```
+
+- ✓ every referenced env var is documented in `.env.example`
+- ⚠ `<N> new env vars used but missing from .env.example` (list them)
+- ✗ N/A (always a warn, never a hard fail — env docs are advisory)
+
+### 8. recent_comms (LS Comm Hub)
+
+Pull the last 10 comments tagged `release` or `daily_update` via `mcp__launch-secure__communication_read` and surface a one-line: `"<N> release/standup comments in last 7 days — latest: <title> (<author>, <age>)"`. This is informational — it helps the user know if a release note was already drafted or if the team flagged something to ship.
+
+Skip with a `⚠ launch-secure MCP not wired` row if the MCP isn't available; don't fail the whole check.
+
+### 9. recall_health
+
+`mcp__launch-recall__recall_status` — ensures the shadow-git backup is alive so a rollback path exists if the deploy goes sideways. Informational only.
+
+- ✓ `recall alive — last snap <X ago>`
+- ⚠ `recall dead — restart before deploy (\`/kit:recall doctor\` for detail)`
+
+## Report
+
+Render a punch list (plain text, monospace; not markdown table):
+
+```
+deploy-check: implementation → master
+
+  ✓ branch_freshness       0 commits behind master
+  ✓ typecheck              0 errors (3.2s)
+  ⚠ lint                   12 warnings (no errors)
+  ✓ build                  built in 47s
+  ✓ prisma_drift           schema matches migrations
+  ✗ migration_safety       1 destructive op without backup
+                           → prisma/migrations/2026_05_25_drop_legacy_thread/migration.sql:14 (DROP COLUMN legacyThreadId, no _backup_* sidecar)
+  ⚠ env_coverage           2 new env vars missing from .env.example: FEED_BACKEND_URL, FEED_TIMEOUT_MS
+  ✓ recent_comms           1 release comment in last 7 days — "Comm Hub channels rollout" (prajyot, 2d ago)
+  ✓ recall_health          alive — last snap 4m ago
+
+verdict: NO-GO — 1 hard fail (migration_safety).
+next: author a backup table + orphan check in the listed migration, then re-run /kit:deploy-check.
+```
+
+Verdict rules:
+- Any ✗ → NO-GO with the failing check(s) listed.
+- All ✓ + ⚠ only → GO WITH CAVEATS, list the warnings.
+- All ✓ → GO.
+
+## Constraints
+
+- **Read-only.** Never deploy, never push, never auto-fix.
+- **Parallel checks.** Run independent checks concurrently (Bash run_in_background) — sequential bloats the wait time past usefulness.
+- **No silent skips.** Every skipped check appears in the report with a reason.
+- **DB-safe.** Refuse to run `build` against a production-looking DATABASE_URL — the build runs `prisma migrate deploy` against it.
+- **Honest about scope.** This check is what a human would do manually; it is NOT a guarantee. Surface false-negatives readers: `"This check doesn't run e2e tests, doesn't validate runtime config, doesn't sniff for secrets in commits — those are separate skills."`
+- **Use launch-chart only for nice-to-have context (e.g. blast radius of a migration), not for the gate.** The gate is git+npm+prisma+MCP-LS; chart is optional.