crewforth 0.0.1 → 3.0.0-rc.2

package/kit/skills/db-migration/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: db-migration
+description: |
+  Apply schema migrations safely: detect the tool, classify the change by risk, gate destructive ones behind
+  approval, back up in prod, preview-apply-verify, roll back on failure.
+  Use when a schema change is about to be applied to any environment.
+---
+
+# Database Migration
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "migration", "schema change", "update database", "add column", "create table", "alter table", "add a column to", "adding a column to", "drop a column", "rename the table", "change the column type", "backfill"
+
+A migration is very often a **one-way gate**: once applied, going back is expensive or impossible
+unless it was planned for. That is why the heart of the flow is not running a command, but **classifying
+the change by risk class before it passes through the gate** — let the safe one flow through, stop and
+get approval for the destructive one, and keep a rollback path ready in every case. The skill works with
+all common ORM/migration tools.
+
+> **Crewforth adaptation (local, .claude/):** Engine and tool come from `CLAUDE.md ## Stack` or repo detection
+> (`backend-architecture`). `crew-database-expert` applies it; **a destructive migration requires explicit approval (§4.5)**, commit/push with explicit approval (§4.4). Authorization/IDOR
+> impact → **crew-security-expert**; personal-data retention → **crew-privacy-agent**. §4 Prohibitions apply.
+
+## Checklist
+- [ ] Tool detected, pending migrations listed
+- [ ] Every change classified (additive / destructive / ambiguous)
+- [ ] Destructive/ambiguous changes approved by the user
+- [ ] Backup taken (mandatory in prod, verified)
+- [ ] Preview (dry-run) shown and approved
+- [ ] Applied, schema verified post-apply
+- [ ] Rollback path (tool or backup) ready
+
+---
+
+## 1. Detect the tool
+
+Determine the tool from the file trace; if none is found, fall back to **raw SQL mode** (below); if several are found, ask the user.
+
+| Trace | Tool |
+|---|---|
+| `prisma/schema.prisma` | Prisma |
+| `knexfile.{js,ts}` | Knex |
+| `.sequelizerc` / `config/config.json` + `models/` | Sequelize |
+| `data-source.ts` (typeorm) / `ormconfig.ts` | TypeORM |
+| `drizzle.config.ts` | Drizzle |
+| `alembic.ini` / `alembic/` | Alembic |
+| `manage.py` + `django` dependency | Django |
+| `db/migrate/` + `rails` in Gemfile | Rails |
+| `Microsoft.EntityFrameworkCore` in `*.csproj` + `Migrations/` | EF Core |
+
+---
+
+## 2. Classify the change — the heart of the flow
+
+Extract the SQL to be applied (the "Preview" column in the matrix below) and place it into one of three classes:
+
+| Class | Example operations | How it is handled |
+|---|---|---|
+| **Additive** (safe) | `CREATE TABLE`, nullable/defaulted `ADD COLUMN`, `CREATE INDEX`, non-destructive `ADD CONSTRAINT`, seed `INSERT` | Proceed in the normal flow |
+| **Destructive** (dangerous) | `DROP TABLE/COLUMN/INDEX/CONSTRAINT`, `ALTER COLUMN … TYPE`, `TRUNCATE`, `DELETE` without WHERE, `RENAME` (breaks references) | **Always the approval gate** (below) |
+| **Ambiguous** (human judgment) | `ALTER COLUMN`, `ADD COLUMN NOT NULL` without a default (blows up on a populated table), `UPDATE`, mixed migration | **Treat as destructive**, warn and ask |
+
+**Approval gate (destructive/ambiguous):** list the operations one by one, show the environment and the target, wait for explicit approval. Even if "run" was said in the general flow, this gate requires separate approval.
+```
+WARNING — this migration contains a destructive operation:
+  · DROP COLUMN "legacy_email" (table: users)
+  · ALTER COLUMN "status" TYPE integer (table: orders)
+CANNOT BE UNDONE without a backup.  Target: production (myapp_db @ db.example.com)
+Continue? (yes / no)
+```
+If rejected, stop immediately and propose a safer path (e.g. a new column + background copy instead of changing the type).
+
+---
+
+## 3. Backup (mandatory in prod)
+
+Back up before any migration; it cannot be skipped in prod, and can be skipped in dev with approval. Then verify
+**the backup was created and is not empty** — otherwise abort:
+```bash
+[ -s "$BACKUP_FILE" ] || { echo "ERROR: Backup empty/not created — migration aborted."; exit 1; }
+```
+Backup + restore + post-apply verify commands **per engine** (PostgreSQL · MySQL · SQLite):
+**`references/backup-restore.md`** — read the one for your database, not all three.
+
+---
+
+## 4. Tool × life-cycle matrix
+
+Once classification and backup are complete: **Preview → (approval) → Apply → Verify**.
+
+Per-tool commands for those four steps and for rollback — Prisma, Knex, Sequelize, TypeORM, Drizzle, Alembic, Django, Rails, EF Core: **`references/tool-matrix.md`**. Look up the one the project uses.
+
+**Rules:** **Always** show the preview before applying and get it approved (if the tool does not support a dry-run, treat the migration file itself as the preview). A destructive migration is not applied without passing the approval gate (§2). Show the full apply output; if there is an error, roll back.
+
+**Additional post-apply verification** — compare against the expected schema using your engine's inspect command (`references/backup-restore.md`).
+
+---
+
+## 5. Rollback
+
+First the tool-specific rollback (last column of the matrix); if that fails, restore from the backup (per-engine
+restore command in **`references/backup-restore.md`**); then re-verify. If neither works, warn the user with the full error detail.
+
+---
+
+## No tool — raw SQL mode
+
+If no tool is detected, manage numbered up/down files (every `up` has a `down`, each SQL inside `BEGIN`/`COMMIT`)
+with a `_migrations` tracking table. Full pattern + example + the apply loop: **`references/raw-sql.md`**.
+
+---
+
+## Invariant rules
+1. **Classify first** — additive/destructive/ambiguous; treat the ambiguous as destructive.
+2. **Destructive = human approval** — a separate gate even in an automated flow.
+3. **Prod backup mandatory** — no apply without a verified backup.
+4. **Preview on by default** — opting out requires an explicit request.
+5. **Always verify after applying.**
+6. **Rollback path always ready** — tool or backup.
+7. **Show the target** — DB name/host/environment, before applying.

package/kit/skills/db-migration/references/backup-restore.md

@@ -0,0 +1,33 @@
+# Backup & restore — per engine
+
+Take the backup **before** any migration (mandatory in prod; dev may skip with approval), then verify it is
+non-empty or abort. Rollback order: the tool-specific rollback first (matrix, last column) → if it fails, restore
+from this backup → re-verify. Read **only the section for your database**.
+
+## PostgreSQL
+```bash
+# backup — compressed full dump
+pg_dump -h $DB_HOST -U $DB_USER -d $DB_NAME -F c -f backup_$(date +%Y%m%d_%H%M%S).dump
+# restore (rollback)
+pg_restore -h $DB_HOST -U $DB_USER -d $DB_NAME --clean --if-exists $BACKUP_FILE
+# post-apply verify
+psql -h $DB_HOST -U $DB_USER -d $DB_NAME -c "\d $TABLE"
+```
+
+## MySQL
+```bash
+# backup
+mysqldump -h $DB_HOST -u $DB_USER -p$DB_PASS $DB_NAME > backup_$(date +%Y%m%d_%H%M%S).sql
+# restore (rollback)
+mysql -h $DB_HOST -u $DB_USER -p$DB_PASS $DB_NAME < $BACKUP_FILE
+# post-apply verify
+mysql -h $DB_HOST -u $DB_USER -p$DB_PASS $DB_NAME -e "DESCRIBE $TABLE;"
+```
+
+## SQLite
+```bash
+# backup
+sqlite3 $DB_PATH ".backup 'backup_$(date +%Y%m%d_%H%M%S).db'"
+# restore (rollback)
+cp $BACKUP_FILE $DB_PATH
+```

package/kit/skills/db-migration/references/raw-sql.md

@@ -0,0 +1,30 @@
+# No tool — raw SQL mode
+
+If no migration tool is detected, manage numbered up/down files; every `up` has a `down`, and every SQL runs
+inside `BEGIN`/`COMMIT`.
+```
+migrations/001_create_users.up.sql   +   001_create_users.down.sql
+```
+```sql
+-- 001_create_users.up.sql
+BEGIN;
+CREATE TABLE IF NOT EXISTS users (
+  id SERIAL PRIMARY KEY,
+  email VARCHAR(255) NOT NULL UNIQUE,
+  created_at TIMESTAMP NOT NULL DEFAULT NOW()
+);
+COMMIT;
+-- 001_create_users.down.sql
+BEGIN;
+DROP TABLE IF EXISTS users;
+COMMIT;
+```
+Keep the applied ones in a tracking table; run only those with no record:
+```bash
+psql … -c "CREATE TABLE IF NOT EXISTS _migrations(id SERIAL PRIMARY KEY, name TEXT UNIQUE, applied_at TIMESTAMP DEFAULT NOW())"
+for f in migrations/*.up.sql; do
+  n=$(basename "$f" .up.sql)
+  [ "$(psql … -tAc "SELECT count(*) FROM _migrations WHERE name='$n'")" = 0 ] || continue
+  psql … -f "$f" && psql … -c "INSERT INTO _migrations(name) VALUES('$n')"
+done
+```

package/kit/skills/db-migration/references/tool-matrix.md

@@ -0,0 +1,35 @@
+# Tool × life-cycle commands
+
+Find your tool's row and use it. A project has one migration tool; the other eight rows are noise at the
+moment you are running a migration, which is why they are here rather than in `SKILL.md`.
+
+The sequence itself — **Preview → (approval) → Apply → Verify** — and the rule that a destructive migration
+never skips the approval gate live in `SKILL.md`. This file only says which command spells each step.
+
+| Tool | Status | Preview (dry-run) | Apply | Verify | Roll back |
+|---|---|---|---|---|---|
+| Prisma | `migrate status` | `migrate diff … --script` | `migrate deploy` | `migrate status` | `migrate resolve --rolled-back` + backup |
+| Knex | `migrate:status` | `migrate:latest --dry-run` | `migrate:latest` | `migrate:status` | `migrate:rollback` |
+| Sequelize | `db:migrate:status` | read the migration file | `db:migrate` | `db:migrate:status` | `db:migrate:undo` |
+| TypeORM | `migration:show` | read the pending file | `migration:run` | `migration:show` | `migration:revert` |
+| Drizzle | `drizzle-kit status` | `generate` → inspect SQL | `drizzle-kit push` | `drizzle-kit status` | `drizzle-kit drop` (prefer backup) |
+| Alembic | `current` + `history` | `upgrade head --sql` | `upgrade head` | `current` (=head) | `downgrade -1` |
+| Django | `showmigrations` | `sqlmigrate <app> <name>` | `migrate` | `showmigrations` ([X]) | `migrate <app> <previous>` |
+| Rails | `db:migrate:status` | read the migration file | `db:migrate` | `db:migrate:status` (up) | `db:rollback STEP=1` |
+| EF Core | `migrations list` | `migrations script` | `database update` | `migrations list` | `database update <previous>` |
+
+Invocation prefix: `npx …` for the Node tools, the project's Python environment for Alembic and Django,
+`dotnet ef …` for EF Core.
+
+## Where a preview does not exist
+
+Sequelize, TypeORM and Rails have no true dry-run. **Treat the migration file itself as the preview** — read
+it out and get it approved before applying. "The tool cannot preview" is not a reason to skip the gate; it is
+a reason the preview is manual.
+
+## Rollback is not a substitute for the backup
+
+Every `Roll back` command above reverses *schema* intent. None of them restores data a destructive migration
+already dropped. That is what the mandatory production backup is for — see `references/backup-restore.md`.
+Drizzle's entry says "prefer backup" for exactly this reason, and the same caution applies to the others
+whenever the migration touched data rather than only structure.

package/kit/skills/dependency-audit/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: dependency-audit
+description: |
+  Dependency risk assessment, read-only: known CVEs, deprecated packages, licence compliance, maintenance
+  status, lockfile integrity, and a justification for every new dependency. Acting on it is dependency-upgrade.
+---
+
+# Dependency Audit
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "dependency audit", "npm audit", "package security", "CVE", "license", "deprecated package", "still maintained", "no longer maintained", "unmaintained", "third party library", "supply chain"
+
+**This skill only reports.** It changes no manifest and no lockfile — bringing dependencies current is
+[[dependency-upgrade]], which classifies each move by risk and verifies the build. Keeping the two apart keeps
+this one safe to run any time, on any branch, including one you are only inspecting.
+
+## Audit axes
+1. **Known vulnerabilities (CVE):** audit appropriate to the ecosystem
+   ```bash
+   npm audit --production           # Node
+   dotnet list package --vulnerable # .NET  (cannot be combined with --deprecated/--outdated)
+   pip-audit                        # Python
+   ```
+2. **License compliance:** flag licenses incompatible with the project such as copyleft/GPL (a risk in commercial closed source).
+3. **Maintenance status:** abandoned / long-unmaintained / single-maintainer packages, and packages the registry
+   itself marks **deprecated** — `dotnet list package --deprecated`, `npm view <pkg> deprecated`. A deprecated
+   package is not a version problem: no bump fixes it, it needs a replacement.
+4. **Transitive dependencies:** also scan vulnerabilities in indirect dependencies.
+5. **Lockfile integrity:** lockfile committed and consistent with the manifest; versions pinned.
+6. **Justification for new dependencies:** is it actually needed? Don't add a heavy package for a single small function (supply-chain surface).
+7. **Install-time execution:** does any dependency run code during installation — `preinstall`/`install`/
+   `postinstall` scripts — and `prepare`, which runs only for a git, link or folder dependency and never for a
+   registry tarball — a build hook, or a setup step that fetches at install time? This is the mechanism the recent
+   registry compromises actually used: the malicious version does not have to be imported, only installed, so a
+   CVE feed and a code review both miss it. Ask two things: which packages declare such a script, and whether
+   the project can install without them at all (`npm ci --ignore-scripts`; for Python the control is refusing source
+   distributions, `pip install --only-binary=:all:`, optionally with `--require-hashes` — a wheel has no install
+   hook, an sdist does; or a vendored, pre-built artefact). A package that cannot install without running code is not disqualified —
+   it is a package whose publisher you are trusting with arbitrary execution on every machine and every runner,
+   which is a decision, not a default.
+8. **Publisher concentration — read it from the registry, not from the repository.** "Many contributors" on a
+   forge says who can open a pull request; it does not say who can publish. The number that matters is who holds
+   the publish right on the registry (`npm owner ls <pkg>` · for PyPI the package JSON's `ownership.roles`,
+   NOT the self-reported `info.maintainer` field · the equivalent ACL for the ecosystem in use) — and whether the
+   PUBLISH PATH itself is challenged, which is not the same as "the account has 2FA": npm's `auth-only` 2FA mode
+   does not gate `npm publish`, and a granular token with bypass-2FA publishes with no second factor, while on
+   PyPI 2FA has been mandatory for every account since 2024 so the real question there is Trusted Publisher
+   versus a long-lived API token. A widely-used
+   package whose registry ACL is one unprotected account is a single compromised credential away from every
+   build that installs it, whatever the contributor graph looks like.
+
+## Output
+Severity-sorted list: `package · version · issue (CVE/license/maintenance) · upgrade path`.
+
+## DoD
+- 0 known HIGH/CRITICAL vulnerabilities; licenses compliant; lockfile consistent; every new package justified.
+- **Every axis resolves to one of three states, and the third is a real answer:** *assessed-clean*,
+  *assessed-flagged*, or *not assessable here — and why*. An axis that was skipped because the tool is missing,
+  the registry was unreachable, or the ecosystem has no equivalent is reported as unassessed, never folded into
+  the clean count. A report that cannot tell "nothing found" from "nobody looked" is the failure this skill
+  exists to prevent, and the sibling `security-scan` already holds the same rule.

package/kit/skills/dependency-upgrade/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: dependency-upgrade
+description: |
+  Bring dependencies current without breaking the build: find what is vulnerable, deprecated or behind,
+  classify each target version by risk, apply what is safe, verify, and roll back what is not.
+---
+
+# Dependency Upgrade
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "upgrade dependencies", "outdated packages", "bump versions", "update packages", "keep dependencies current"
+
+## When
+Staying on current versions as an ongoing practice, or reacting to a CVE. [[dependency-audit]] tells you what is
+wrong; this decides what to do about it and does it. It **mutates the manifest and the lockfile**, so it carries
+the same shape as [[db-migration]]: detect the tool, classify by risk, gate the dangerous class behind approval,
+apply, verify, roll back on red.
+
+## 1 — Ask the three separate questions
+They are three different problems with three different answers, and the tooling keeps them separate too.
+
+| Question | Node | .NET | Python |
+|---|---|---|---|
+| What has a **known CVE**? | `npm audit --json` | `dotnet list package --vulnerable` | `pip-audit` |
+| What is **deprecated**? | `npm view <pkg> deprecated` | `dotnet list package --deprecated` | registry / project notes |
+| What is simply **behind**? | `npm outdated --json` | `dotnet list package --outdated` | `pip list --outdated` |
+
+> The three `dotnet list package` flags **cannot be combined** — it is three separate runs, not one.
+
+**Deprecated is not an upgrade.** No version bump fixes it; the package needs a replacement, which is a design
+change with its own review — never fold it into a routine bump.
+
+## 2 — Classify every target version before touching anything
+The risk is not "how old is it", it is "how far does the jump go".
+
+| Class | Rule | Approval |
+|---|---|---|
+| **Security patch** | fixes a known CVE, within the current major | Do it first, on its own commit — it is the one upgrade whose delay has a cost |
+| **Patch** (`x.y.Z`) | bugfix only | Apply, batched |
+| **Minor** (`x.Y.z`) | additive, backward compatible **by promise** | Apply, batched, only if the suite is green afterwards |
+| **Major** (`X.y.z`) | breaking by definition | **Never automatic.** Read the changelog/migration guide, one package per commit, and say what breaks |
+| **Pinned / transitive-only** | pinned deliberately, or not a direct dependency | Leave it. Find out *why* it is pinned before unpinning |
+
+Semver is a promise, not a guarantee: a minor that breaks you is a bug in the package, and your suite is the
+only thing that will tell you. That is why the verify step below is not optional.
+
+## 3 — Apply
+- **Group by class, one commit per group** — a patch batch and a major are not the same change and must not
+  share a commit. A single commit mixing forty bumps is unreviewable and unrevertable.
+- **Preview first.** `npm audit fix --dry-run` before `npm audit fix`. Never reach for `npm audit fix --force`
+  without saying so out loud: it installs **semver-major** upgrades, which is precisely how this task breaks a
+  build while claiming to be a security fix.
+- **The lockfile is part of the change.** Commit it with the manifest; a manifest bump without its lockfile is
+  a change nobody else reproduces ([[dependency-audit]] axis 5).
+- Never hand-edit a lockfile. Let the tool regenerate it.
+
+## 4 — Verify, then decide
+Nothing counts as upgraded until it is observed working — install, build, full test suite, and the project's
+quality gate. Run the app's real entry path if the change touches runtime, not just unit tests ([[testing]]).
+
+- Green → keep it.
+- Red → **roll back this group** (`git checkout -- <manifest> <lockfile>` then reinstall), then either pin, split
+  the batch to find the culprit, or move that package to its own major-upgrade task. Do not "fix forward" a
+  routine bump; that turns maintenance into an unplanned feature.
+- Re-run [[dependency-audit]] afterwards: an upgrade can introduce a new transitive CVE.
+
+## 5 — Continuous, without an autonomous loop
+"Always current" is a **cadence**, not an agent that runs by itself — Crewforth has no timed or self-triggering
+loops, because every mutation here needs an approval a loop cannot give. Continuity comes from somewhere that
+already has a human gate at the end:
+- A scheduled CI job running the step-1 commands and failing on HIGH/CRITICAL ([[ci-pipeline]]).
+- Or a bot (Renovate / Dependabot) opening one PR per group — Crewforth does not reimplement it; the value added
+  is the policy above deciding which PRs merge on green and which need a human to read a changelog.
+- Either way the PR passes through the ordinary gates: build, tests, [[security-scan]], review, approval.
+
+## DoD
+- Vulnerable, deprecated and outdated were asked as three separate questions, with the command output shown.
+- Every applied upgrade is classed patch / minor / major, and no major went in automatically or unexplained.
+- Security fixes landed first and separately.
+- Manifest and lockfile moved together; no lockfile was hand-edited.
+- Build + full suite were observed green after the change, or the group was rolled back and named.
+- Deprecated packages are reported as replacement work, not silently bumped.

package/kit/skills/deploy/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: deploy
+description: |
+  Ship a build reversibly — to a host you manage or a platform that manages it. Pick the topology first, keep
+  the previous version reachable, gate on health, roll back without rebuilding. Use when shipping anywhere
+  users can reach.
+---
+
+# Deploy
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "deploy", "push to the server", "to the server", "onto the server", "build on the server", "install on the VPS", "ship it to the server", "go to production", "to production", "go live"
+
+A deploy has a single idea, and it does not depend on where you are deploying: **make the new version live in a
+way you can undo.** Keep the previous version reachable until the new one has proved itself; if it fails the
+health gate, go back to the old one and nobody notices.
+
+**Two topologies implement that idea differently, and mixing them is where deploys go wrong.** On a host you
+manage, "reversible" means the previous release still sits on disk and the swap is a pointer you can move back.
+On a platform that manages the host for you, "reversible" means the previous *artefact* is still addressable and
+you re-point the environment at it — you do not rebuild it. Phase 0 picks the branch; everything after follows.
+
+> **Crewforth adaptation (local, .claude/):** Any backend runtime (Docker recommended). **Deploy requires explicit
+> approval (§4.4)**; a backup before every swap and a health gate after are mandatory. If `.deploy.yml` carries server
+> credentials it goes into `.gitignore`. §4 Prohibitions apply.
+
+## Phase 0 — Which topology
+Answer before anything else, because the rest of the skill forks here. Ask if it is not obvious; do not infer it
+from the language or the framework.
+
+| | **A · Self-managed host** | **B · Managed platform** |
+|---|---|---|
+| You have | SSH to a machine you own or rent | an API/CLI, and no shell on the box |
+| A release is | a directory on that host | an immutable artefact (image digest, build id, bundle) |
+| "Deploy" means | put the files in place and restart | promote an existing artefact to an environment |
+| Rollback means | move the pointer back to the previous directory | re-point the environment at the previous artefact |
+| Owned by | **`references/topology-a.md`** (phases 1–5) | **`references/topology-b.md`** (phases B1–B4) |
+
+Signals for B: the platform builds from a push, or the runtime is described as containers/functions/dynos/pods
+that you do not administer. Signals for A: you are given a host, a user and a port. A Kubernetes cluster is B
+when a controller reconciles it from a manifest, and A only if you are genuinely hand-placing files on nodes.
+
+**If both are in play** — a managed platform in front, a self-managed worker behind — run the branches
+separately and gate each on its own health check. One approval does not cover two topologies.
+
+## Checklist (A · self-managed host)
+- [ ] Topology decided (Phase 0)
+- [ ] Runtime + deploy method determined
+- [ ] Config taken from `.deploy.yml`/the user, SSH verified
+- [ ] Reverse proxy + (if there is a domain) SSL in place
+- [ ] Running version backed up to `releases/`
+- [ ] User approved the deploy, new version deployed
+- [ ] Health gate passed (otherwise automatic rollback performed)
+- [ ] If requested, single-command scripts (`deploy.sh` / `adopt.sh`) generated
+
+## Checklist (B · managed platform)
+- [ ] Topology decided (Phase 0)
+- [ ] Artefact built once and addressed immutably (digest / build id, not a moving tag)
+- [ ] Which artefact is in which environment is recorded
+- [ ] Config and secrets injected per environment, not baked into the artefact
+- [ ] User approved the promotion to this environment
+- [ ] Health gate passed from OUTSIDE — not the platform's own status
+- [ ] Previous artefact still addressable, and the migration question settled before the deploy
+
+---
+
+## The phases — read ONE branch
+
+Phase 0 picked it; loading both is the mistake this skill opens with.
+
+- **A · self-managed host** → **`references/topology-a.md`**: runtime/method detection, `.deploy.yml` + SSH,
+  reverse proxy and SSL, the backup-then-swap for Docker and bare-metal, the health gate, the rollback.
+- **B · managed platform** → **`references/topology-b.md`**: build once and address it immutably, promote
+  without rebuilding, health-gate from outside the platform, roll back by re-pointing.
+
+The invariant rules at the end of this file hold on both, and they are the half that must not be read from a
+reference file: they are what an approval is checked against.
+
+## Single-command scripts (optional)
+
+After a successful deploy, **ask** whether to generate project-specific `deploy.sh` / `adopt.sh` (single-command
+deploy/update). Derive the steps from the real project (package.json / Dockerfile / Makefile / compose), never a
+generic template. Full guidance + what each script contains: **`references/scripts.md`**.
+
+---
+
+## Invariant rules
+These hold on BOTH branches; where the mechanism differs, the rule does not.
+0. **The topology is decided, not assumed** — Phase 0, once, out loud. Everything downstream depends on it.
+1. **No deploy without approval** — show the method/host/domain/port plan, wait for approval.
+2. **Always back up before the swap** — timestamped into `releases/`; if the backup fails, abort.
+3. **Always a health gate after the swap** — HTTP + process; if it doesn't pass, automatic rollback.
+4. **Keep the last 3 versions** — don't delete them all.
+5. **Don't deploy to prod without knowing the target** — host/deploy_path/domain must be approved.
+6. **Verify SSH first** — if you can't connect, fail fast.
+7. **Don't expose the port directly** — the app binds to `127.0.0.1`, outward only through the proxy.
+8. **SSL is mandatory when there's a domain** — always set it up unless `ssl` is explicitly `false`.
+9. **Never rebuild to roll back** (B) — promote the previous artefact. A rebuild is a different artefact.
+10. **The platform's own status is not the health gate** (B) — verify from where a user stands.
+11. **Rolling back code does not roll back a migration** — settle the schema question before the deploy.

package/kit/skills/deploy/references/proxy-ssl.md

@@ -0,0 +1,56 @@
+# Reverse proxy and SSL — the file contents
+
+Read the half you need. A deploy uses Nginx **or** Caddy, never both, and the two paths differ most exactly
+where it matters: Caddy obtains and renews the certificate itself, Nginx needs Certbot wired up separately.
+
+The decision — which proxy is installed, whether SSL applies at all, and that the app binds only to
+`127.0.0.1` — stays in `SKILL.md`. This file is what to write once that is settled.
+
+## Nginx
+
+Site config:
+
+```nginx
+server {
+  listen 80;
+  server_name DOMAIN;
+  location / {
+    proxy_pass http://127.0.0.1:APP_PORT;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection 'upgrade';
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+  }
+}
+```
+
+Link it into `sites-enabled` with `ln -s`, then `nginx -t && systemctl reload nginx`. Run `nginx -t` before
+the reload every time — a reload on a broken config takes the site down, and the test costs nothing.
+
+### SSL on the Nginx path
+
+Skip entirely when `ssl: false` or there is no domain. **Never attempt SSL on a bare IP** — a certificate
+authority cannot issue for one, and the attempt burns rate-limited quota on the domain you will use later.
+
+Verify DNS resolves to this host *first*, or Certbot's challenge fails in a way that looks like a proxy fault:
+
+```bash
+dig +short $DOMAIN        # must equal $HOST
+certbot --nginx -d $DOMAIN --non-interactive --agree-tos -m admin@$DOMAIN
+systemctl enable certbot.timer   # automatic renewal — without this the site breaks in 90 days
+```
+
+## Caddy
+
+```
+DOMAIN {
+  reverse_proxy 127.0.0.1:APP_PORT
+}
+```
+
+`systemctl reload caddy`. Caddy handles the certificate and its renewal on its own — no Certbot, no timer, no
+separate SSL step. If the domain does not yet resolve, Caddy will retry rather than fail loudly, so check
+`journalctl -u caddy` when a fresh domain serves plain HTTP longer than expected.

package/kit/skills/deploy/references/rollback.md

@@ -0,0 +1,18 @@
+# Phase 5 — Rollback (run on health-gate failure)
+
+Undo the swap: put the most recent version in `releases/` back into `current`, restart the service, repeat the
+health gate (Phase 4).
+```bash
+LATEST=$(ssh -i $SSH_KEY $USER@$HOST "ls -dt $DEPLOY_PATH/releases/*/ 2>/dev/null | head -1")
+[ -z "$LATEST" ] && { echo "ERROR: no backup — rollback impossible"; exit 1; }
+ssh -i $SSH_KEY $USER@$HOST "
+  mkdir -p $DEPLOY_PATH/current
+  rsync -a --delete ${LATEST%/}/ $DEPLOY_PATH/current/   # atomic swap — no 'rm -rf' (guard-safe)
+  { docker rm -f $APP 2>/dev/null && docker run -d --name $APP --restart unless-stopped \
+      -p 127.0.0.1:$APP_PORT:$APP_PORT $APP:previous; } \
+    || systemctl restart $APP || pm2 restart $APP
+"
+```
+> **Note:** Rollback uses `rsync --delete` instead of `rm -rf` so `guard-bash` (the local `rm -rf` block) doesn't
+> block the automatic rollback. The deploy verbs (`ssh`/`rsync`/`docker`) pass through the approval gate via
+> `settings.json` `permissions.ask` — they run with approval, not silently.

package/kit/skills/deploy/references/scripts.md

@@ -0,0 +1,9 @@
+# Single-command scripts (optional)
+
+After a successful deploy, **ask:** "Shall I generate `deploy.sh` and `adopt.sh` so you can deploy/update with a single command in the future?"
+
+If you generate them, **don't use a generic template** — analyze the actual project (package.json scripts / Dockerfile / Makefile / docker-compose / `.env.example`) and derive the exact build+start steps. Two scripts:
+- **`deploy.sh`** — first-time setup + deploy: load config · verify SSH · proxy + SSL · back up to `releases/` · project-specific build · transfer · dependencies · start · health gate with retries · rollback on failure.
+- **`adopt.sh`** — quick update: config · backup · code sync · (if needed) build/dependencies · restart · health gate · rollback on failure.
+
+Rules: `chmod +x`; if `.deploy.yml` carries credentials, ask about `.gitignore`; don't overwrite an existing script without approval (show a diff); no hardcoded credentials — always read from `.deploy.yml`; comment and explain every project-specific decision.