@lifeaitools/rdc-skills 0.13.5 → 0.13.7

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "rdc",
-  "version": "0.13.5",
+  "version": "0.13.6",
   "description": "RDC typed-agent dispatch skill suite for Claude Code — plan, build, review, overnight unattended builds with work-item tracking and TDD enforcement.",
   "author": {
     "name": "LIFEAI",
@@ -297,7 +297,7 @@
       "name": "deploy",
       "slash": "rdc:deploy",
       "category": "deploy",
-      "usage": "rdc:deploy <slug> [new|diagnose|audit] [--fix]",
+      "usage": "rdc:deploy <slug> [new|diagnose|audit|promote] [--fix|--hotfix <sha>]",
       "args": {
         "positional": [
           {
@@ -310,7 +310,7 @@
             "name": "action",
             "required": false,
             "description": "Operation kind",
-            "accepts": "new | diagnose | audit | (omit for default deploy)"
+            "accepts": "new | diagnose | audit | promote | (omit for default deploy)"
           }
         ],
         "flags": [
@@ -319,6 +319,12 @@
             "type": "bool",
             "default": false,
             "description": "Apply remediation during diagnose/audit"
+          },
+          {
+            "name": "--hotfix",
+            "type": "string",
+            "default": null,
+            "description": "With promote: cherry-pick this specific commit sha to main instead of the app-path develop delta"
           }
         ]
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifeaitools/rdc-skills",
-  "version": "0.13.5",
+  "version": "0.13.7",
   "description": "RDC typed-agent dispatch skill suite for Claude Code - plan, build, review, overnight builds",
   "keywords": [
     "claude-code",

package/skills/deploy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rdc:deploy
-description: "Usage `rdc:deploy <slug> [new|diagnose|audit] [--fix]` — Deploy an app to Coolify (production) or PM2 (staging), add a new Coolify app, diagnose a failed deploy, or audit watch paths. Handles DNS, health checks, and post-deploy verification."
+description: "Usage `rdc:deploy <slug> [new|diagnose|audit|promote] [--fix|--hotfix <sha>]` — Deploy an app to Coolify (production) or PM2 (staging), promote a verified dev change to production (one-command cherry-pick → PR → admin-merge → explicit Coolify trigger → verify), add a new Coolify app, diagnose a failed deploy, or audit watch paths. Handles DNS, branch protection, health checks, and post-deploy verification."
 ---
 
 > **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
@@ -15,10 +15,11 @@ No raw MCP dumps. No UUIDs unless asked.
 
 > **Sandbox contract:** This skill honors `RDC_TEST=1` per `guides/agent-bootstrap.md` § RDC_TEST Sandbox Contract. Destructive external calls short-circuit under the flag.
 >
-> *Under `$RDC_TEST=1`:* Modes 1 (deploy) and 2 (new) are **entirely skipped** — echo `[RDC_TEST] skipping Coolify deploy/create` and mark every `[ ]` line in those checklists as `[~]`. Modes 3 (diagnose) and 4 (audit without `--fix`) are **read-only and run normally**. Mode 4 with `--fix` skips all remediation — echo `[RDC_TEST] skipping audit --fix remediation` and report findings only. Registry SELECTs, Coolify status reads, HTTP gate probes, TLS checks, and DNS lookups are NOT destructive and run normally. Anything that writes (create app, set watch_paths, deploy trigger, env var write, DNS write, CF cache purge, registry UPDATE/INSERT) is gated.
+> *Under `$RDC_TEST=1`:* Modes 1 (deploy), 2 (new), and 5 (promote) are **entirely skipped** — echo `[RDC_TEST] skipping Coolify deploy/create/promote` and mark every `[ ]` line in those checklists as `[~]`. Modes 3 (diagnose) and 4 (audit without `--fix`) are **read-only and run normally**. Mode 4 with `--fix` skips all remediation — echo `[RDC_TEST] skipping audit --fix remediation` and report findings only. Registry SELECTs, Coolify status reads, HTTP gate probes, TLS checks, and DNS lookups are NOT destructive and run normally. Anything that writes (create app, set watch_paths, deploy trigger, **PR/admin-merge to main**, env var write, DNS write, CF cache purge, registry UPDATE/INSERT) is gated.
 
 ## When to Use
 - Project lead says "deploy", "ship it", "push to production", "update the server"
+- Project lead says "promote", "patch prod", "hotfix production", "push this fix live" — use `rdc:deploy <slug> promote`
 - A new app needs to be registered and deployed for the first time (`rdc:deploy new`)
 - A deployed app is behaving unexpectedly and needs diagnosis (`rdc:deploy diagnose`)
 - Running a compliance/health audit of all deployed apps (`rdc:deploy audit`)
@@ -27,6 +28,8 @@ No raw MCP dumps. No UUIDs unless asked.
 
 - `rdc:deploy <slug>` — deploy existing app (latest commit on its watched branch)
 - `rdc:deploy <slug> <build-id>` — deploy specific commit/tag
+- `rdc:deploy <slug> promote` — promote the verified `develop` change for this app to production (Mode 5)
+- `rdc:deploy <slug> promote --hotfix <sha>` — promote a specific commit (cherry-pick just that sha to `main`)
 - `rdc:deploy new <slug>` — create a new Coolify app from registry
 - `rdc:deploy diagnose <slug>` — debug why an app is broken
 - `rdc:deploy audit` — fleet-wide scan for missed failures
@@ -53,6 +56,7 @@ rdc:deploy: <slug> → <domain>
 [ ] Gate: TLS valid (no SSL cipher mismatch)
 [ ] Gate: cache headers correct on HTML
 [ ] Gate: container running on declared port
+[ ] Gate: metadata audit (see § Metadata Audit below) — warn on gaps, do not block deploy
 [ ] Cloudflare cache purged (if proxied)
 [ ] artifact_registry INSERT per PUBLISH.md surface (if PUBLISH.md present)
 [ ] deployment_registry updated (last_deploy_at, status)
@@ -138,6 +142,96 @@ Severity rules:
 
 `--fix` auto-remediates only: missing watch_paths, registry row updates, CF cache purges. Never touches env vars, DNS, or container config without explicit confirmation.
 
+### Mode 5 — promote <slug> [--hotfix <sha>]
+
+Promote a **verified `develop` change** for one app to production. This is the sanctioned production-patch fast path — one command instead of fighting branch protection, the main-push hook, and a flaky Coolify webhook by hand.
+
+**Authorization:** production promote requires explicit user go-ahead ("promote", "patch prod", "push live", "go"). A dev deploy does NOT. If the user has not given it for THIS promote, stop and ask first.
+
+```
+rdc:deploy promote: <slug> → <prod-domain>
+[ ] Registry lookup: PROD row (uuid, prod branch=main, watch_paths, url)
+[ ] PUBLISH.md status gate: status=active AND prod in environments (block if not)
+[ ] Scope resolved: --hotfix <sha> → that commit; else the app-path commits on develop not on main
+[ ] Scope guard: promote ONLY this app's paths. NEVER merge develop→main wholesale (drags unrelated WIP to prod)
+[ ] Clean worktree off origin/main (never switch the dirty working tree)
+[ ] Apply change: cherry-pick <sha> (or `git checkout <develop-sha> -- <app-paths>`); confirm diff = expected files only
+[ ] Mandatory pre-promote code-review (pr-review-toolkit:code-reviewer on the promote diff). Block on critical/high.
+[ ] Commit on promote branch; push branch (NOT main directly — the main-push hook blocks raw main pushes)
+[ ] Open PR base=main; merge with admin override (`gh pr merge --squash --admin --delete-branch`) — branch protection needs --admin
+[ ] EXPLICITLY trigger Coolify deploy — NEVER rely on the GitHub→Coolify webhook (it silently no-ops on some merges even with auto-deploy ON)
+[ ] Deployment reached "finished" state (poll coolify_events / deployment status)
+[ ] Gate: HTTP 200 on prod domain
+[ ] Gate: content-level check — assert the actual changed string is live (200 alone is NOT proof; origin may serve stale)
+[ ] Gate: TLS valid
+[ ] Gate: metadata audit (see § Metadata Audit below) — BLOCK promote on any missing required item
+[ ] Cloudflare cache purged (if proxied)
+[ ] deployment_registry updated (last_deploy_at, last_deploy_commit, status)
+✅ rdc:deploy promote: <slug> live in prod — <changed-string> verified
+```
+
+**The explicit Coolify trigger (the whole point — do not skip):**
+```bash
+_COOLIFY=$(curl -s http://127.0.0.1:52437/v/coolify-api)
+# Correct endpoint is GET /api/v1/deploy?uuid= — NOT POST /applications/<uuid>/deploy (that 404s)
+curl -s -H "Authorization: Bearer $_COOLIFY" \
+  "$DEPLOY_API_BASE/api/v1/deploy?uuid=<PROD_UUID>&force=true"
+# → {"deployments":[{"deployment_uuid":"...","message":"...deployment queued."}]}
+```
+
+**Why each guard exists (lessons from 2026-06-05 EF Hooper promote):**
+- `main` branch protection rejects PR merge without `--admin`; a raw `git push …:main` is blocked by the main-push hook → must go branch → PR → admin-merge.
+- Coolify auto-deploy was **ON** for the app yet the merge did **not** auto-deploy — a webhook-delivery flake. A promote must ALWAYS trigger the deploy explicitly and verify; never hope the webhook fired.
+- `develop` was 87 commits ahead of `main` (unrelated apps' WIP). Promoting must be surgical (this app's paths / one sha), never a develop→main merge.
+- HTTP 200 was returned by the stale origin the whole time — only a content-level assertion (`curl … | grep '<new string>'`) proves the promote landed.
+
+## Metadata Audit
+
+After a successful deploy or promote, audit the live site's `<head>` metadata. Run this against the deployed URL (not a local file).
+
+**Check list** (curl the deployed URL, parse the HTML `<head>`):
+
+| # | Item | How to check | Required | Severity |
+|---|------|-------------|----------|----------|
+| 1 | `<title>` | grep `<title>` — non-empty, not default/placeholder | yes | block |
+| 2 | `<meta name="description">` | content attr ≥ 50 chars, ≤ 160 chars | yes | block on promote; warn on deploy |
+| 3 | `<link rel="canonical">` | href present, starts with `https://`, matches the deployed domain | yes | block on promote; warn on deploy |
+| 4 | `og:title` | `<meta property="og:title">` present | yes | block on promote; warn on deploy |
+| 5 | `og:description` | `<meta property="og:description">` present, ≥ 50 chars | yes | block on promote; warn on deploy |
+| 6 | `og:image` | `<meta property="og:image">` present, URL returns HTTP 200 | yes | block on promote; warn on deploy |
+| 7 | `og:url` | present, matches canonical | recommended | warn |
+| 8 | `twitter:card` | `summary_large_image` or `summary` | recommended | warn |
+| 9 | `twitter:image` | present, URL returns HTTP 200 | recommended | warn |
+| 10 | Favicon | `<link rel="icon">` present, href returns HTTP 200 | yes | block on promote; warn on deploy |
+| 11 | `sitemap.xml` | `<domain>/sitemap.xml` returns HTTP 200 | recommended | warn |
+| 12 | `robots.txt` | `<domain>/robots.txt` returns HTTP 200 | recommended | warn |
+| 13 | Version | `<meta name="version">` or visible version string in page | yes (project rule) | warn |
+
+**Behavior by mode:**
+- **Mode 1 (deploy):** run the audit after HTTP/TLS gates. Print a table of results. **Warn** on gaps but do NOT block the deploy — dev deploys are iterative.
+- **Mode 5 (promote):** run the audit after content-level check. **Block the promote** if any item marked "block on promote" is missing. Print the table and require the metadata to be fixed before re-attempting.
+- **Mode 4 (audit):** include the metadata sweep in the fleet scan (one row per app per missing item in the findings table).
+
+**Implementation — one-liner per check:**
+```bash
+URL="https://<domain>"
+HEAD=$(curl -s "$URL" | sed -n '/<head/,/<\/head>/p')
+echo "$HEAD" | grep -ioE '<title>[^<]+</title>'
+echo "$HEAD" | grep -ioE 'name="description"[^>]*content="[^"]*"'
+echo "$HEAD" | grep -ioE 'rel="canonical"[^>]*href="[^"]*"'
+echo "$HEAD" | grep -ioE 'property="og:title"[^>]*content="[^"]*"'
+echo "$HEAD" | grep -ioE 'property="og:image"[^>]*content="[^"]*"'
+echo "$HEAD" | grep -ioE 'name="twitter:card"[^>]*content="[^"]*"'
+echo "$HEAD" | grep -ioE 'rel="icon"[^>]*href="[^"]*"'
+echo "$HEAD" | grep -ioE 'name="version"[^>]*content="[^"]*"'
+curl -s -o /dev/null -w "%{http_code}" "$URL/sitemap.xml"
+curl -s -o /dev/null -w "%{http_code}" "$URL/robots.txt"
+OG_IMG=$(echo "$HEAD" | grep -ioE 'property="og:image"[^>]*content="([^"]*)"' | grep -ioE 'https://[^"]*')
+[ -n "$OG_IMG" ] && curl -s -o /dev/null -w "%{http_code}" "$OG_IMG"
+```
+
+**Why this exists (2026-06-05):** life.ai deployed to production with zero social/SEO metadata — no description, no OG, no favicon, no sitemap. HTTP 200 + TLS + content passed; metadata was invisible to the existing gates. This audit catches that class of defect.
+
 ## PUBLISH.md Integration
 
 Every deploy reads `PUBLISH.md` from the app's source root to derive `watch_paths` and to register surfaces in Studio `artifact_registry`.
@@ -225,9 +319,10 @@ curl -s -H "Authorization: Bearer $_COOLIFY" \
 curl -s -H "Authorization: Bearer $_COOLIFY" \
   "$DEPLOY_API_BASE/api/v1/applications/<uuid>"
 
-# Deploy (trigger)
-curl -s -X POST -H "Authorization: Bearer $_COOLIFY" \
-  "$DEPLOY_API_BASE/api/v1/applications/<uuid>/deploy"
+# Deploy (trigger) — correct endpoint is GET /api/v1/deploy?uuid=
+# (POST /applications/<uuid>/deploy returns {"message":"Not found."})
+curl -s -H "Authorization: Bearer $_COOLIFY" \
+  "$DEPLOY_API_BASE/api/v1/deploy?uuid=<uuid>&force=true"
 
 # Get deployment logs
 curl -s -H "Authorization: Bearer $_COOLIFY" \