@launchsecure/launch-kit 0.0.33 → 0.0.34

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

@@ -1,144 +1,151 @@
 ---
-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.
+description: Production-readiness check for the current branch — branch freshness, typecheck, lint, build, schema/migration drift, migration safety, env coverage, and recent LS comms. Stack-agnostic: detects the project's toolchain (Node/Python/Go/Rust/Ruby/JVM/.NET/PHP) and migrations tooling at runtime, runs the detected command per check, and skips with a reason where a stack has no equivalent. Read-only; reports a go/no-go punch list. 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.
+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 (default: `master`/`main`). Reports a punch list with ✓ / ⚠ / ✗ per check and a single go/no-go verdict.
+
+This skill ships with `launch-kit init` into **any** project, so it makes **no stack assumptions**. Preflight step 5 detects the toolchain and the migrations tooling once; every check below runs the *detected* command, and any check with no equivalent on this stack is **skipped with a visible reason** rather than failing or running a tool the repo doesn't have.
 
 Parse `$ARGUMENTS`:
-- (empty) — full check on the current branch vs `master` (or repo's default).
+- (empty) — full check on the current branch vs the default branch.
 - **--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.
+- **--quick** — skip the build (the slowest check). Still runs the rest.
 - **--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`
+- `/kit:deploy-check --target=staging --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.
+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`/`main`).
+3. Print the scope upfront: `"deploy-check: <current-branch> → <target-branch>"`.
+4. Stash check — if `git status --porcelain` shows uncommitted changes, surface a `⚠ uncommitted changes in working tree` row at the top. Don't refuse; some workflows want uncommitted work included.
+5. **Detect the project stack** (this is what makes the skill portable — resolve once, reuse below). Identify the project family from its manifest, then resolve the per-check command. **Always prefer an explicit script/target the repo defines** (a `package.json` script, a `Makefile` target like `build`/`lint`/`test`, a `justfile` recipe) over the language default — a defined script encodes the project's real intent.
+
+   | Family | Marker | typecheck | lint | build | env-ref grep |
+   |---|---|---|---|---|---|
+   | Node | `package.json` (PM from lockfile: pnpm/yarn/bun/npm; `RUN=<pm> run`) | `<RUN> typecheck` else `npx tsc --noEmit` **only if `tsconfig.json`**; else skip | `<RUN> lint` if defined | `<RUN> build` if defined | `process\.env\.[A-Z_]+` in `*.ts,*.tsx,*.js,*.mjs,*.cjs` |
+   | Python | `pyproject.toml`/`requirements.txt`/`setup.py` | `mypy`/`pyright` if configured, else skip | `ruff check`/`flake8` if configured | build script if defined (often none) | `os\.environ\[`, `os\.getenv\(`, `getenv\(` in `*.py` |
+   | Go | `go.mod` | `go vet ./...` | `golangci-lint run` if present | `go build ./...` | `os\.Getenv\(` in `*.go` |
+   | Rust | `Cargo.toml` | `cargo check` | `cargo clippy` | `cargo build --release` | `env::var\(`, `std::env::var` in `*.rs` |
+   | Ruby | `Gemfile` | `srb tc` if sorbet, else skip | `rubocop` if present | build script if defined | `ENV\[` in `*.rb` |
+   | JVM | `pom.xml`/`build.gradle(.kts)` | (compile = build) | checkstyle/ktlint if configured | `mvn -q package` / `gradle build` | `System\.getenv\(` in `*.java,*.kt` |
+   | .NET | `*.csproj`/`*.sln` | (compile = build) | `dotnet format --verify-no-changes` if present | `dotnet build -c Release` | `Environment\.GetEnvironmentVariable\(` in `*.cs` |
+   | PHP | `composer.json` | `phpstan`/`psalm` if present | `php-cs-fixer`/`phpcs` if present | build script if defined | `getenv\(`, `\$_ENV\[` in `*.php` |
+   | unknown | — | skip | skip | skip (look for a `Makefile`/`justfile` `build` target first) | skip env_coverage |
+
+   Also resolve, reusing the same detection `/kit:ship` uses:
+   - **`MIGRATIONS_DIR`** — `prisma/migrations/` · `supabase/migrations/` · `drizzle/` (or a dir with `drizzle/meta/`) · `db/migrate/` (Rails) · `alembic/versions/` · a Django app's `*/migrations/` · `src/main/resources/db/migration/` (Flyway) · a knex/TypeORM/Sequelize dir, or **`none`**. A config-declared `migrationsPath` wins.
+   - **`MIGRATION_TOOL`** — prisma / supabase / drizzle / rails / alembic / django / flyway / knex / typeorm / sequelize / `none`. Drives whether a *drift* command exists (check 5).
+   - **`ENV_EXAMPLE`** — `.env.testing` if it exists, else `.env.example`, else `none`.
+
+   Record the resolved command set and print a one-line `stack: <family> · pm=<pm> · migrations=<tool|none>` so the user can see what was detected.
 
 ## 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> }`.
+Run independent checks (typecheck/lint/build) in PARALLEL. Each returns `{ name, status: "ok"|"warn"|"fail"|"skip", detail: <one-line>, artifact?: <path|url> }`. **A check with no detected command is `skip` with a reason — never `fail`.**
 
 ### 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).
-
+Run `TYPECHECK_CMD` from Preflight. If none for this stack, `⚠ typecheck skipped — no typecheck configured for <family>`.
 - ✓ `0 errors`
-- ✗ `<N> errors` (sample first 3 file:line:message)
+- ✗ `<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`
+Run `LINT_CMD`. If none defined, `⚠ lint skipped — no lint script/linter detected`.
+- ✓ `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`.
+Run `BUILD_CMD` (the project's real build, so the check matches CI). Skip if `--quick` or `--skip=build`. If no build command exists for this stack (common for libraries / scripting projects), `⚠ build skipped — no build step detected`.
+- ✓ `built in <durationMs>ms` · ✗ `build failed` (last 20 lines of stderr as artifact)
 
-- ✓ `built in <durationMs>ms`
-- ✗ `build failed` (last 20 lines of stderr as artifact)
+**DB-safety guard (only when the build touches a DB).** If the detected `BUILD_CMD` runs migrations as part of the build (e.g. a Node build script that chains `prisma migrate deploy`, or any build that applies `MIGRATION_TOOL` migrations — detect by scanning the build script / target), then a prod DB connection string must NOT be used. If the relevant connection env (`DATABASE_URL`, `DB_URL`, etc.) looks production-y (matches `neon.tech`, `rds.amazonaws.com`, `supabase.co`, a `vercel.app` proxy host, etc.), refuse the build step: `⚠ build skipped — build applies migrations and DATABASE_URL looks production-y (<host>); re-run with a dev DB or pass --skip=build`. If the build does NOT touch a DB (most stacks), skip this guard.
 
-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. schema_drift (only when MIGRATION_TOOL supports it)
 
-### 5. prisma_drift
+Schema-vs-migrations consistency, using the tool's own drift command:
+- **prisma** — `npx prisma migrate diff --from-schema-datasource prisma/schema.prisma --to-migrations prisma/migrations --shadow-database-url <DEV_SHADOW_URL>`. The diff should be EMPTY (this project hand-authors migrations — see CLAUDE.md). Non-empty = a model change without a migration.
+- **drizzle** — `npx drizzle-kit check` (reports schema/migration mismatch).
+- **rails** — `bin/rails db:abort_if_pending_migrations` against a dev DB (pending = drift).
+- **alembic/django** — `alembic check` / `python manage.py makemigrations --check --dry-run` (a would-be-generated migration = drift).
+- **other / none** — `⚠ schema_drift skipped — no drift command for <tool>` (or skip silently when `MIGRATION_TOOL=none`).
 
-Schema vs migrations consistency:
+- ✓ `schema matches migrations` · ✗ `<N> drift detected` (surface the diff as an artifact; suggest authoring a migration).
+- If a drift command needs a shadow/dev DB and none is available: `⚠ schema_drift skipped — no shadow/dev DB URL`.
 
-```
-npx prisma migrate diff --from-schema-datasource prisma/schema.prisma --to-migrations prisma/migrations --shadow-database-url <DEV_SHADOW_URL>
-```
+### 6. migration_safety (only when MIGRATIONS_DIR ≠ none)
 
-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:
+If `MIGRATIONS_DIR=none`, skip entirely. Otherwise scan every migration added since divergence:
 
 ```
-git diff --name-only <target>...HEAD -- prisma/migrations/
+git diff --name-only <target>...HEAD -- <MIGRATIONS_DIR>
 ```
 
-For each new migration, scan the SQL for risk patterns (per project CLAUDE.md migration safety rules):
+For **SQL-based** migrations (prisma/supabase/flyway/rails-SQL/alembic-SQL), scan the SQL for risk patterns (per the project's migration-safety discipline):
+- ✓ no destructive ops (`DROP COLUMN`, `DROP TABLE`, `ALTER COLUMN ... DROP`, `DELETE FROM` without a backup-matching `WHERE`).
+- ⚠ destructive ops present BUT a sidecar `CREATE TABLE _backup_*` AND an orphan-check (`RAISE EXCEPTION ... orphans remain`) are present in the same file.
+- ✗ destructive ops without backup OR without orphan-check OR expand+contract mixed in one migration.
 
-- ✓ 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.
+For **non-SQL** migration DSLs (Rails Ruby DSL, Django/Alembic Python ops, Drizzle TS), best-effort scan for the tool's destructive ops (`remove_column`, `drop_table`, `op.drop_column`, `.dropColumn`, etc.) and note `partial coverage — non-SQL migration, pattern scan only`.
 
 Each failure cites the exact migration filename + line numbers.
 
-### 7. env_coverage
+### 7. env_coverage (only when ENV_EXAMPLE ≠ none and an env-ref pattern exists)
 
-Compare `.env.example` (or `.env.testing` if it exists) keys against `process.env.*` references in the new code since divergence:
+Compare documented keys in `ENV_EXAMPLE` against env references in new code since divergence, using the stack's `env-ref grep`:
 
 ```
-git diff <target>...HEAD -- '*.ts' '*.tsx' | grep -oE 'process\.env\.[A-Z_][A-Z0-9_]+'
+git diff <target>...HEAD -- <stack source globs> | grep -oE '<ENV_REF_PATTERN>'
 ```
-
-- ✓ 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)
+- ✓ every referenced env var is documented in `ENV_EXAMPLE`
+- ⚠ `<N> new env vars used but missing from <ENV_EXAMPLE>` (list them)
+- env docs are advisory — this is never a hard ✗. If `ENV_EXAMPLE=none`, `⚠ env_coverage skipped — no env example file`.
 
 ### 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.
+Pull the last 10 comments tagged `release` or `daily_update` via `mcp__launch-secure__communication_read`; surface `"<N> release/standup comments in last 7 days — latest: <title> (<author>, <age>)"`. Informational. Skip with `⚠ launch-secure MCP not wired` if unavailable.
 
 ### 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)`
+`mcp__launch-recall__recall_status` — confirms the shadow-git backup is alive so a rollback path exists. Informational.
+- ✓ `recall alive — last snap <X ago>` · ⚠ `recall dead — restart before deploy`. Skip if the MCP isn't wired.
 
 ## Report
 
-Render a punch list (plain text, monospace; not markdown table):
+Render a punch list (plain text, monospace; not a markdown table):
 
 ```
 deploy-check: implementation → master
+stack: node · pm=npm · migrations=prisma
 
   ✓ 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
+  ✓ schema_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)
+                           → prisma/migrations/2026_05_25_drop_legacy/migration.sql:14 (DROP COLUMN, 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)
+  ✓ recent_comms           1 release comment in last 7 days — "channels rollout" (prajyot, 2d ago)
   ✓ recall_health          alive — last snap 4m ago
 
 verdict: NO-GO — 1 hard fail (migration_safety).
@@ -147,14 +154,16 @@ next: author a backup table + orphan check in the listed migration, then re-run
 
 Verdict rules:
 - Any ✗ → NO-GO with the failing check(s) listed.
-- All ✓ + ⚠ only → GO WITH CAVEATS, list the warnings.
+- All ✓ + ⚠/skip only → GO WITH CAVEATS, list the warnings + skips.
 - All ✓ → GO.
+- **Skips never fail the gate** — but if every code-quality check (typecheck+lint+build) skipped, add a `⚠ note: no typecheck/lint/build ran for this stack — gate is weak` so a green verdict isn't mistaken for thorough.
 
 ## 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 stack assumptions.** Every tool-specific command is resolved by detection in Preflight step 5. If detection comes up empty for a check, skip it with a reason — never run a tool the repo doesn't have, never hard-fail for its absence.
+- **Parallel checks.** Run independent checks concurrently — sequential bloats the wait 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.
+- **DB-safe.** The build DB-safety guard only triggers when the detected build actually applies migrations; when it does, refuse a production-looking connection string.
+- **Honest about scope.** This check is what a human would do manually; it is NOT a guarantee. Surface: `"This check doesn't run e2e tests, doesn't validate runtime config, doesn't sniff for secrets in commits — those are separate skills."`
+- **launch-chart is optional context only** (e.g. blast radius of a migration), never part of the gate. The gate is git + the detected toolchain + the migrations tool + MCP-LS.

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

@@ -0,0 +1,132 @@
+---
+description: Refresh the HANDOFF Brief (doc/handoff/HANDOFF.md) from current session state and regenerate the next-session kickoff prompt. Current-state only — per-ship history lives in doc/shipping-logs/ (written by /kit:ship). Does NOT commit or push; run /kit:handoff first, then /kit:ship so the HANDOFF edit rides the ship payload.
+---
+
+# /kit:handoff
+
+Wrap a session: keep `doc/handoff/HANDOFF.md` an accurate **current-state snapshot**, and produce a kickoff prompt the next session can paste in cold.
+
+`doc/handoff/HANDOFF.md` is a **current-state Brief** — it does NOT accumulate per-session "what shipped" writeups. That history lives in `doc/shipping-logs/` (written by `/kit:ship`). Keep HANDOFF lean — if it grows past ~150 lines, the wrong thing is going into it (a cumulative feature list belongs in a roadmap doc; per-ship detail belongs in `doc/shipping-logs/`).
+
+This skill does **NOT commit and does NOT push**. `/kit:ship` does that. The intended order is `/kit:handoff` → `/kit:ship`, so the HANDOFF edit lands inside the slice's ship payload and publishes with it. For a session that won't run `/kit:ship`, see **Edge cases**.
+
+Parse `$ARGUMENTS`:
+
+- (empty) — refresh `doc/handoff/HANDOFF.md` against the current session and regenerate the kickoff prompt.
+- **--dry-run** — build the refreshed HANDOFF + kickoff in a fenced preview block, but do NOT write the file. Useful for "what would the handoff look like right now?".
+- **--next=<text>** — name what's next explicitly (e.g. `--next="F12 webhook retries"`) instead of inferring it from the session. Drives the kickoff prompt's title + context.
+
+## Preflight
+
+1. `git rev-parse --is-inside-work-tree` — abort if not a git repo.
+2. Resolve the **base branch** to diff the session against:
+   - `git symbolic-ref refs/remotes/origin/HEAD --short` (strip `origin/`) → the repo's default branch. Fall back to `origin/main` / `origin/master` if unset.
+   - Use `git log <base>..HEAD` as "what this session/branch added."
+3. Confirm `doc/handoff/` exists. If not, this is the first handoff — create `doc/handoff/HANDOFF.md` from the skeleton in **Step 2** rather than editing.
+
+## Step 1 — Inventory what happened
+
+Survey the session — gather, don't show yet:
+
+- `git log <base>..HEAD --oneline` — what's committed locally this branch.
+- `git status --porcelain` + `git diff --stat` — uncommitted work.
+- Recent `TaskList` (if present) — completed vs deferred.
+- From the conversation: decisions made, scope cuts, schema/migration changes, new env vars, external-service touchpoints, anything paused mid-flight.
+
+Produce a short internal summary (slice/title · what changed · schema/env deltas · deferred items · open threads). This feeds Steps 2–3; do not print it.
+
+## Step 2 — Refresh `doc/handoff/HANDOFF.md`
+
+Update **only** these sections — nothing else belongs in this file:
+
+1. **Intro line** — keep the "refreshed at each `/kit:handoff`" note + the `docs/archive/` pointer (see Archiving).
+2. **Where we are** — the one-block current-state status: what's now feature-complete, what's paused, any new external dependency. Tight.
+3. **What's next** — the next 1–3 things in priority order. If priorities shifted this session, reflect it.
+4. **Open threads** — the short list of genuinely-open items needing attention soon. **Prune anything resolved this session.** Long-horizon "maybe someday" items belong in a deferrals doc, not here.
+5. **Kickoff prompt** — Step 3.
+
+Do NOT add: a "What shipped this session" section (→ `doc/shipping-logs/`), a past-sessions log, or a cumulative feature list (→ a roadmap doc).
+
+First-handoff skeleton (when the file doesn't exist yet):
+
+```markdown
+---
+title: Handoff — Current State
+---
+
+# <Project> — Handoff
+
+_Current-state snapshot, refreshed at each session's `/kit:handoff`. Per-ship "what shipped" history lives in `doc/shipping-logs/`. Older handoff content is archived at `docs/archive/`._
+
+## Where we are
+
+<one-block current state>
+
+## What's next
+
+1. <next thing>
+2. <…>
+
+## Open threads
+
+- <genuinely-open item>
+
+## Kickoff prompt for the next session
+
+> <generated in Step 3>
+```
+
+## Step 3 — Regenerate the kickoff prompt
+
+Replace the "Kickoff prompt for the next session" section at the bottom of `HANDOFF.md`. It must be **specific to whatever's next** (use `--next=` if given), not generic:
+
+```markdown
+## Kickoff prompt for the next session
+
+> Starting **<work item / FNN — Title>**. Read `CLAUDE.md`, then `doc/handoff/HANDOFF.md` and the relevant Briefs under `doc/`. {One-paragraph context: what this work is, why now, what infra is already in place.}
+>
+> Before any code, confirm the design shape:
+>
+> 1. **Surface.** {Where does this live? Closest precedent in the codebase?}
+> 2. **Fields / inputs.** {What does the user/agent provide?}
+> 3. **Eligibility.** {When is the action available? State guards?}
+> 4. **Data path.** {What writes happen, in what order? What events/logs are emitted?}
+> 5. **{Feature-specific question.}**
+> 6. **Out of scope / deferrals.** {What are we explicitly NOT building? Trigger to revisit?}
+>
+> Scope the slice, confirm deferrals, then branch off the default branch. Run `/kit:handoff` then `/kit:ship` at session end.
+```
+
+If `What's next` lists multiple candidates, write the kickoff for the most-likely-next and add a one-line note about the alternative.
+
+## Step 4 — Tell the user
+
+Single short message:
+
+1. **Confirm `HANDOFF.md` is updated** — brief recap of the new current-state + what's-next.
+2. **Show the kickoff prompt** — copy-paste ready, in a fenced block.
+3. **Remind:** start a **new** session for the next slice (one session per feature/branch) and paste the kickoff as the first message.
+4. **Suggest `/kit:ship` next** if there's uncommitted work — there will be, at minimum the HANDOFF edit — so the refresh publishes with the slice.
+
+Do NOT commit. Do NOT push. `/kit:ship` does that.
+
+## Archiving (keep HANDOFF lean)
+
+If `HANDOFF.md` exceeds ~150 lines or the "Where we are" block has accumulated many fully-shipped-and-stable bullets:
+
+- Move the stale, no-longer-active content to `docs/archive/HANDOFF-thru-<YYYY-MM>.md` (append to it if it exists).
+- Leave a one-line pointer in the intro line.
+- The live HANDOFF should read in under a minute. History is recoverable from the archive + `doc/shipping-logs/`; it does not need to live in the active snapshot.
+
+## Edge cases
+
+- **Session shipped code** — `/kit:ship` runs after this and commits the HANDOFF edit along with the slice. The normal path.
+- **Design / planning / process session, no `/kit:ship`** — still refresh HANDOFF (decisions made, deferrals identified, new open threads) and the kickoff. Since no ship will run, either make a small `docs:` commit of the HANDOFF change yourself, or tell the user it's uncommitted and unpublished. Do not silently leave it dangling.
+- **No changes since base** (pure conversation, no code, no decisions) — don't fabricate updates. Refresh only the kickoff prompt and say "no current-state changes; here's the prompt for next session."
+- **Session spanned multiple slices** (rare — violates one-session-per-feature) — each slice already has its own `doc/shipping-logs/` entry from `/kit:ship`; just ensure HANDOFF's current-state reflects all of them.
+
+## Notes for the assistant
+
+- HANDOFF is **current-state only**. The single most common failure is letting it grow into a session journal — that's what `doc/shipping-logs/` is for. When in doubt, cut.
+- This skill never pushes; it respects the same unauthorized-push rules as `/kit:ship`. The HANDOFF edit becomes team-visible only when `/kit:ship` pushes it.
+- If the repo registers a `handoff` doc category in its file-content-sync config (mapping `doc/handoff/**` to the discussion handler, the same mechanism `/kit:ship` uses for `doc/shipping-logs/**`), the HANDOFF Brief materializes as a Comm Hub comment on push. If not, HANDOFF still works as a local cold-start doc — it just isn't mirrored to the Comm Hub. That category registration is a one-time repo/server config, not this skill's job.