@lifeaitools/rdc-skills 0.25.9 → 0.26.0

package/commands/deploy.md

@@ -1,152 +1,177 @@
----
-name: rdc:deploy
-description: >-
-  Coolify ops. Usage `rdc:deploy <slug> [build-id]` or `rdc:deploy new <slug>` or `rdc:deploy diagnose <slug>` or `rdc:deploy audit [--fix]` — type checklists, DNS decision tree, mandatory post-deploy gate. Checklist-only output.
----
-
-> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
-> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
-> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
-
-
-# rdc:deploy — Coolify Operations
-
-**READ FIRST:** `guides/output-contract.md`. Checklist-only output. No narration.
-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.
-
-## Arguments
-
-- `rdc:deploy <slug>` — deploy existing app (latest commit on its watched branch)
-- `rdc:deploy <slug> <build-id>` — deploy specific commit/tag
-- `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
-- `rdc:deploy audit --fix` — fleet scan + auto-remediate safe issues
-- `rdc:deploy` (no args) — print mode menu, ask which
-
-## Modes
-
-### Mode 1 — deploy <slug> [build-id]
-
-```
-rdc:deploy: <slug> → <domain>
-[ ] Registry lookup (slug, uuid, branch, type, env_vars_needed)
-[ ] Git state verified (branch matches Coolify, commit pushed)
-[ ] Build-id resolved (default: HEAD of watched branch)
-[ ] Env vars present in Coolify (compare to registry)
-[ ] Type-specific preflight (see docs/runbooks/coolify-deploy-checklist.md)
-[ ] Deploy triggered
-[ ] Deployment reached "finished" state
-[ ] Gate: HTTP 200
-[ ] Gate: TLS valid (no SSL cipher mismatch)
-[ ] Gate: cache headers correct on HTML
-[ ] Gate: container running on declared port
-[ ] Cloudflare cache purged (if proxied)
-[ ] deployment_registry updated (last_deploy_at, status)
-✅ rdc:deploy: <slug> deployed in Nm Ns
-```
-
-### Mode 2 — new <slug>
-
-```
-rdc:deploy new: <slug>
-[ ] Registry entry loaded (or interactive create)
+---
+name: rdc:deploy
+description: >-
+  Coolify ops. Usage `rdc:deploy <slug> [build-id]`, `rdc:deploy new <slug>`, `rdc:deploy maintenance <service>`, `rdc:deploy diagnose <slug>`, or `rdc:deploy audit [--fix]` — typed checklists, private-service controls, DNS decision tree, and mandatory post-deploy gates. Checklist-only output.
+---
+
+> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
+> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
+> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
+
+
+# rdc:deploy — Coolify Operations
+
+**READ FIRST:** `guides/output-contract.md`. Checklist-only output. No narration.
+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.
+
+## Arguments
+
+- `rdc:deploy <slug>` — deploy existing app (latest commit on its watched branch)
+- `rdc:deploy <slug> <build-id>` — deploy specific commit/tag
+- `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
+- `rdc:deploy audit --fix` — fleet scan + auto-remediate safe issues
+- `rdc:deploy maintenance <service>` — create, update, or verify a template-declared private service; no public domain or host port
+- `rdc:deploy` (no args) — print mode menu, ask which
+
+## Modes
+
+### Mode 1 — deploy <slug> [build-id]
+
+```
+rdc:deploy: <slug> → <domain>
+[ ] Registry lookup (slug, uuid, branch, type, env_vars_needed)
+[ ] Git state verified (branch matches Coolify, commit pushed)
+[ ] Build-id resolved (default: HEAD of watched branch)
+[ ] Env vars present in Coolify (compare to registry)
+[ ] Type-specific preflight (see docs/runbooks/coolify-deploy-checklist.md)
+[ ] Deploy triggered
+[ ] Deployment reached "finished" state
+[ ] Gate: HTTP 200
+[ ] Gate: TLS valid (no SSL cipher mismatch)
+[ ] Gate: cache headers correct on HTML
+[ ] Gate: container running on declared port
+[ ] Cloudflare cache purged (if proxied)
+[ ] deployment_registry updated (last_deploy_at, status)
+✅ rdc:deploy: <slug> deployed in Nm Ns
+```
+
+### Mode 2 — new <slug>
+
+```
+rdc:deploy new: <slug>
+[ ] Registry entry loaded (or interactive create)
 [ ] DNS path chosen (A: staging wildcard  B: apex  C: other zone)
-[ ] DNS record verified or wildcard confirmed
-[ ] Cloudflare proxy setting correct for DNS path
-[ ] server_uuid, project_uuid, environment_uuid, github_app_uuid resolved
-[ ] Build type chosen (Next.js / Vite / static / standalone)
-[ ] Type-specific fields filled (ports, build cmd, install cmd, start cmd)
-[ ] Application created via /applications/private-github-app
-[ ] watch_paths set and verified
-[ ] Env vars set in Coolify
-[ ] First deploy triggered
-[ ] Gate passed (5 checks)
-[ ] deployment_registry row inserted
-✅ rdc:deploy new: <slug> live at <domain>
-```
-
-### Mode 3 — diagnose <slug>
-
-```
-rdc:deploy diagnose: <slug>
-[ ] App located (uuid, domain, last deploy)
-[ ] Container state (running / restarting / stopped)
-[ ] Last 100 log lines scanned for known error patterns
-[ ] Port mismatch check (declared vs actual)
-[ ] Env var drift check (registry vs Coolify)
-[ ] watch_paths sanity check
-[ ] HTTP / TLS reachability
-[ ] Cloudflare proxy state check
-[ ] Disk space on server
-[ ] Branch mismatch check (Coolify git_branch vs expected)
-⚠️ rdc:deploy diagnose: <root cause in one sentence> — fix: <one command>
-```
-
-### Mode 4 — audit
-
-```
-rdc:deploy audit: fleet scan
-[ ] Inventory join: Coolify apps ⋈ deployment_registry
-[ ] Orphans (in one but not the other)
-[ ] Monorepo apps missing watch_paths
-[ ] Stale deploys (>14 days since last success)
-[ ] Registry rows with status='broken'
-[ ] Failed deployments in last 7 days
-[ ] HTTP gate sweep (non-200 per domain)
-[ ] TLS cert expiry <30 days
-[ ] Port mismatches (ports_exposes vs actual container port)
-[ ] Env var drift (registry.env_vars_needed vs Coolify env)
-[ ] Branch mismatches (Coolify git_branch ≠ expected)
-[ ] Disk space on 64.237.54.189
+[ ] DNS record verified or wildcard confirmed
+[ ] Cloudflare proxy setting correct for DNS path
+[ ] server_uuid, project_uuid, environment_uuid, github_app_uuid resolved
+[ ] Build type chosen (Next.js / Vite / static / standalone)
+[ ] Type-specific fields filled (ports, build cmd, install cmd, start cmd)
+[ ] Application created via /applications/private-github-app
+[ ] watch_paths set and verified
+[ ] Env vars set in Coolify
+[ ] First deploy triggered
+[ ] Gate passed (5 checks)
+[ ] deployment_registry row inserted
+✅ rdc:deploy new: <slug> live at <domain>
+```
+
+### Mode 3 — diagnose <slug>
+
+```
+rdc:deploy diagnose: <slug>
+[ ] App located (uuid, domain, last deploy)
+[ ] Container state (running / restarting / stopped)
+[ ] Last 100 log lines scanned for known error patterns
+[ ] Port mismatch check (declared vs actual)
+[ ] Env var drift check (registry vs Coolify)
+[ ] watch_paths sanity check
+[ ] HTTP / TLS reachability
+[ ] Cloudflare proxy state check
+[ ] Disk space on server
+[ ] Branch mismatch check (Coolify git_branch vs expected)
+⚠️ rdc:deploy diagnose: <root cause in one sentence> — fix: <one command>
+```
+
+### Mode 4 — audit
+
+```
+rdc:deploy audit: fleet scan
+[ ] Inventory join: Coolify apps ⋈ deployment_registry
+[ ] Orphans (in one but not the other)
+[ ] Monorepo apps missing watch_paths
+[ ] Stale deploys (>14 days since last success)
+[ ] Registry rows with status='broken'
+[ ] Failed deployments in last 7 days
+[ ] HTTP gate sweep (non-200 per domain)
+[ ] TLS cert expiry <30 days
+[ ] Port mismatches (ports_exposes vs actual container port)
+[ ] Env var drift (registry.env_vars_needed vs Coolify env)
+[ ] Branch mismatches (Coolify git_branch ≠ expected)
+[ ] Disk space on 64.237.54.189
 [ ] DNS/proxy misconfigs on configured staging wildcard
-[ ] Duplicate apps (same repo, multiple UUIDs)
-
-Findings:
-| Severity | App | Issue | Fix |
-|----------|-----|-------|-----|
-| HIGH     | ... | ...   | ... |
-⚠️ rdc:deploy audit: N HIGH · M MED · K LOW — run `rdc:deploy audit --fix` to auto-remediate safe issues
-```
-
-Severity rules:
-- **HIGH** — user-facing down (HTTP non-200, TLS invalid, container not running)
-- **MED** — degraded or drifting (watch_paths missing, env var drift, stale deploy, branch mismatch)
-- **LOW** — cleanup (orphans, duplicates, registry status stale)
-
-`--fix` auto-remediates only: missing watch_paths, registry row updates, CF cache purges. Never touches env vars, DNS, or container config without explicit confirmation.
-
-## Coolify Access — clauth + REST API
-
-All Coolify operations use the clauth daemon and the Coolify REST API directly.
-There is no Coolify MCP server — do not reference `@masonator/coolify-mcp`.
-
-```bash
-_COOLIFY=$(curl -s http://127.0.0.1:52437/v/coolify-api)
+[ ] Duplicate apps (same repo, multiple UUIDs)
+
+Findings:
+| Severity | App | Issue | Fix |
+|----------|-----|-------|-----|
+| HIGH     | ... | ...   | ... |
+⚠️ rdc:deploy audit: N HIGH · M MED · K LOW — run `rdc:deploy audit --fix` to auto-remediate safe issues
+```
+
+Severity rules:
+- **HIGH** — user-facing down (HTTP non-200, TLS invalid, container not running)
+- **MED** — degraded or drifting (watch_paths missing, env var drift, stale deploy, branch mismatch)
+- **LOW** — cleanup (orphans, duplicates, registry status stale)
+
+`--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 7 — maintenance <service> (private infrastructure)
+
+Use maintenance only for a service declared in the `private-service` template.
+It creates, updates, or verifies a Coolify-network service with no public
+domain, no DNS route, and no host-port publication. Secret checks use key names
+only; values are never retrieved or emitted. Retiring a service is outside this
+mode and requires separate explicit approval.
+
+```
+rdc:deploy maintenance: <service>
+[ ] Template and source/branch/Dockerfile/internal-port/health-path resolved
+[ ] Private-only contract: domains empty, host port absent, network alias declared
+[ ] Required secret keys confirmed by name only
+[ ] Explicit deploy completed
+[ ] Health gate passes inside the container
+[ ] Existing Coolify-network workload reaches the alias and health path
+[ ] No public domain, TLS route, DNS record, or host endpoint is present
+✅ rdc:deploy maintenance: <service> healthy on the private network
+```
+
+For `clauth`, require `CLAUTH_MACHINE_ID` and `CLAUTH_MASTER_PASSWORD`, port
+`52437`, and `/ping`. The container may bind `0.0.0.0` internally only;
+consumers must use its Coolify network alias rather than `localhost`.
+
+## Coolify Access — clauth + REST API
+
+All Coolify operations use the clauth daemon and the Coolify REST API directly.
+There is no Coolify MCP server — do not reference `@masonator/coolify-mcp`.
+
+```bash
+_COOLIFY=$(curl -s http://127.0.0.1:52437/v/coolify-api)
 curl -s -H "Authorization: Bearer $_COOLIFY" "$DEPLOY_API_BASE/api/v1/applications"
-```
-
-If clauth daemon is not responding:
-```
-BLOCKED: clauth daemon not responding. Run scripts\restart-clauth.bat, unlock at http://127.0.0.1:52437
-```
-
-## References
-
-- Type-specific checklists + DNS tree + gate commands: `docs/runbooks/coolify-deploy-checklist.md`
-- Rules / registry RPCs / hard limits: `.claude/rules/coolify-deployment.md`
-- Infrastructure constants:
-  ```
-  Server UUID:     ih386anenvvvn6fy1umtyow0
-  Server IP:       64.237.54.189
+```
+
+If clauth daemon is not responding:
+```
+BLOCKED: clauth daemon not responding. Run scripts\restart-clauth.bat, unlock at http://127.0.0.1:52437
+```
+
+## References
+
+- Type-specific checklists + DNS tree + gate commands: `docs/runbooks/coolify-deploy-checklist.md`
+- Rules / registry RPCs / hard limits: `.claude/rules/coolify-deployment.md`
+- Infrastructure constants:
+  ```
+  Server UUID:     ih386anenvvvn6fy1umtyow0
+  Server IP:       64.237.54.189
   Dashboard:       <deployment-dashboard-url>
-  GitHub App UUID: xdmcy60putp5h9j7k4kwg9c3
-  ```
-
-## Supersedes
-
-`coolify-deploy` standalone skill (kept for back-compat; new work uses `rdc:deploy`).
+  GitHub App UUID: xdmcy60putp5h9j7k4kwg9c3
+  ```
+
+## Supersedes
+
+`coolify-deploy` standalone skill (kept for back-compat; new work uses `rdc:deploy`).

package/commands/fixit.md

@@ -1,150 +1,150 @@
----
-name: rdc:fixit
-description: >-
-  Usage `rdc:fixit <description>` — sanctioned bypass for quick fixes under 5 files / 30 min. Creates minimal work item, makes fix, commits, DELIVERS it to where it is consumed (publish/deploy/land) and verifies, then closes. The ONLY alternative to rdc:build. For typos, config patches, hotfixes, dep bumps.
----
-
-> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
-> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
-> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
-
-> If dispatching subagents or running as a subagent: read `{PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md` first (fallback: `{PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md`).
-
-> **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.
-
-
-# rdc:fixit — Sanctioned Quick Fix
-
-## When to Use
-- Typo or single-line text correction
-- Config value change (env vars, constants, feature flags)
-- Emergency hotfix that cannot wait for a full build cycle
-- Dependency version bump
-- CSS/styling tweak on a single component
-- Broken import or export fix
-- Single-file logic correction
-
-## When NOT to Use — escalate to rdc:build instead
-- New feature of any size
-- Refactor touching >5 files
-- Anything requiring architecture decisions
-- Work that will take longer than 30 minutes
-- Schema changes or migrations
-
-## Arguments
-- `rdc:fixit <description>` — fix the described issue
-
-## Procedure
-
-### 1. Scope check (mandatory — do this before touching any file)
-
-Will this fix touch more than **5 files** or take more than **30 minutes**?
-
-- **YES** → Stop. Use `/rdc:build` instead. Explain to the user why.
-- **NO** → Continue.
-
-### 2. Create a minimal work item (before touching any code)
-
-```sql
-SELECT insert_work_item(
-  p_title     := 'fixit: <description>',
-  p_item_type := 'bug',
-  p_priority  := 'urgent',
-  p_status    := 'in_progress',
-  p_source    := 'fixit'
-);
-```
-
-Note the returned `id`.
-
-### 3. Write the fixit session marker
-
-Write to `{USER_HOME}/.claude/fixit.marker`:
-```
-<work_item_id>
-<ISO timestamp>
-<description>
-```
-
-This signals the Stop hook that fixit is handling its own documentation.
-
-### 4. Make the fix
-
-Do the minimal work. Scope creep rule: if you discover the fix requires more than originally scoped, **stop immediately**:
-1. Close the work item: `update_work_item_status('<id>', 'blocked', '["Escalated — scope exceeded fixit threshold"]')`
-2. Delete the marker file
-3. Tell the user to use `/rdc:build` instead
-
-### 5. Commit
-
-```bash
-git add <specific files only — never git add -A for a fixit>
-git commit -m "fix(<scope>): <description>"
-if [ "$RDC_TEST" != "1" ]; then
-  git push origin {development-branch}
-else
-  echo "[RDC_TEST] skipping git push origin {development-branch}"
-fi
-```
-
-### 5.5 Deliver to done (MANDATORY — a fixit is not done until the change is LIVE)
-
-⛔ **"Committed and pushed" is NOT done.** Editing code and walking away is the exact
-failure this step exists to prevent. Carry the change to where it is consumed and verify it:
-
-| Target shape | "Done" = delivered means | How + structural proof |
-|---|---|---|
-| Published package (npm / PyPI) | new version live on the registry | `npm publish --access public` (or repo release path); verify `npm view <pkg> version` == new version |
-| Deployed app (`apps/*`, sites) | change live on the running host | `/rdc:deploy <slug>` (dev) / `promote` (prod); verify HTTP 200 + content probe |
-| Shared lib consumed in-repo | landed on the integration branch | `node scripts/land.mjs`; verify branch contains the SHA |
-| Standalone repo | its own release ritual completed | repo release script/tag; verify the artifact/tag exists |
-| Pure doc / internal-only change, NO consumer | committed + landed | no deploy; the ONLY case where commit == done |
-
-- **A version bump obligates a release.** A bumped-but-unshipped version is an unfinished fixit.
-- **Verify structurally** (registry version, HTTP status, tag presence), never by assumption.
-- **If delivery can't complete in-session** (missing OTP/secret, human approval, denied
-  command, manual prod promotion): set the work item `blocked` with the exact remaining
-  command + reason and tell the user the one step to run — do NOT mark `done`.
-
-Under `RDC_TEST=1`: echo `[RDC_TEST] skipping delivery (publish/deploy)` and proceed.
-
-### 6. Report, review, close, and clean up
-
-**Precondition: Step 5.5 delivery is verified.** If delivery is blocked, set `blocked` (not
-`done`) with the remaining step — never mark an undelivered change `done`.
-
-```sql
-SELECT submit_implementation_report('<id>'::uuid,
-  '{"tldr":"<one sentence>","assumptions":[],"deviations":[],"uncertainty":[],"detail":"<what was fixed>","flags":[],"transactional":false,"memory_records":[],"codeflow_post":{"agent_session_id":"<agent-session-id>","summary":"<what changed and why>","files_changed":["<path>"],"verification":["<command/evidence>"],"commit":"<hash optional>"}}'::jsonb
-);
-
-SELECT update_work_item_status('<id>'::uuid, 'review',
-  '["Fixed via rdc:fixit; ready for validation"]'::jsonb,
-  '<agent-session-id>',
-  'agent'
-);
-
-SELECT update_work_item_status('<id>'::uuid, 'done',
-  '["Validator verified rdc:fixit report, CodeFlow post, and checklist evidence"]'::jsonb,
-  '<validator-session-id>',
-  'validator'
-);
-```
-
-```bash
-rm {USER_HOME}/.claude/fixit.marker
-```
-
-### 7. Confirm to user
-
-Report: what was fixed, file(s) changed, commit hash. One sentence.
-
-## Rules
-- Work item created BEFORE any code change — never after
-- `git add` specific files only — never `-A` or `.` for a fixit
-- Branch: development branch always
-- Never run `pnpm build` — not needed for a fixit
-- If scope expands mid-fix: stop, escalate to rdc:build, don't finish under fixit
-- Marker file must be cleaned up whether fix succeeds or escalates
-- **Done = delivered, not committed.** Live where consumed (published/deployed/landed) +
-  verified. A version bump obligates a publish. Can't deliver in-session → `blocked`, never `done`.
+---
+name: rdc:fixit
+description: >-
+  Usage `rdc:fixit <description>` — sanctioned bypass for quick fixes under 5 files / 30 min. Creates minimal work item, makes fix, commits, DELIVERS it to where it is consumed (publish/deploy/land) and verifies, then closes. The ONLY alternative to rdc:build. For typos, config patches, hotfixes, dep bumps.
+---
+
+> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
+> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
+> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
+
+> If dispatching subagents or running as a subagent: read `{PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md` first (fallback: `{PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md`).
+
+> **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.
+
+
+# rdc:fixit — Sanctioned Quick Fix
+
+## When to Use
+- Typo or single-line text correction
+- Config value change (env vars, constants, feature flags)
+- Emergency hotfix that cannot wait for a full build cycle
+- Dependency version bump
+- CSS/styling tweak on a single component
+- Broken import or export fix
+- Single-file logic correction
+
+## When NOT to Use — escalate to rdc:build instead
+- New feature of any size
+- Refactor touching >5 files
+- Anything requiring architecture decisions
+- Work that will take longer than 30 minutes
+- Schema changes or migrations
+
+## Arguments
+- `rdc:fixit <description>` — fix the described issue
+
+## Procedure
+
+### 1. Scope check (mandatory — do this before touching any file)
+
+Will this fix touch more than **5 files** or take more than **30 minutes**?
+
+- **YES** → Stop. Use `/rdc:build` instead. Explain to the user why.
+- **NO** → Continue.
+
+### 2. Create a minimal work item (before touching any code)
+
+```sql
+SELECT insert_work_item(
+  p_title     := 'fixit: <description>',
+  p_item_type := 'bug',
+  p_priority  := 'urgent',
+  p_status    := 'in_progress',
+  p_source    := 'fixit'
+);
+```
+
+Note the returned `id`.
+
+### 3. Write the fixit session marker
+
+Write to `{USER_HOME}/.claude/fixit.marker`:
+```
+<work_item_id>
+<ISO timestamp>
+<description>
+```
+
+This signals the Stop hook that fixit is handling its own documentation.
+
+### 4. Make the fix
+
+Do the minimal work. Scope creep rule: if you discover the fix requires more than originally scoped, **stop immediately**:
+1. Close the work item: `update_work_item_status('<id>', 'blocked', '["Escalated — scope exceeded fixit threshold"]')`
+2. Delete the marker file
+3. Tell the user to use `/rdc:build` instead
+
+### 5. Commit
+
+```bash
+git add <specific files only — never git add -A for a fixit>
+git commit -m "fix(<scope>): <description>"
+if [ "$RDC_TEST" != "1" ]; then
+  git push origin {development-branch}
+else
+  echo "[RDC_TEST] skipping git push origin {development-branch}"
+fi
+```
+
+### 5.5 Deliver to done (MANDATORY — a fixit is not done until the change is LIVE)
+
+⛔ **"Committed and pushed" is NOT done.** Editing code and walking away is the exact
+failure this step exists to prevent. Carry the change to where it is consumed and verify it:
+
+| Target shape | "Done" = delivered means | How + structural proof |
+|---|---|---|
+| Published package (npm / PyPI) | new version live on the registry | `npm publish --access public` (or repo release path); verify `npm view <pkg> version` == new version |
+| Deployed app (`apps/*`, sites) | change live on the running host | `/rdc:deploy <slug>` (dev) / `promote` (prod); verify HTTP 200 + content probe |
+| Shared lib consumed in-repo | landed on the integration branch | `node scripts/land.mjs`; verify branch contains the SHA |
+| Standalone repo | its own release ritual completed | repo release script/tag; verify the artifact/tag exists |
+| Pure doc / internal-only change, NO consumer | committed + landed | no deploy; the ONLY case where commit == done |
+
+- **A version bump obligates a release.** A bumped-but-unshipped version is an unfinished fixit.
+- **Verify structurally** (registry version, HTTP status, tag presence), never by assumption.
+- **If delivery can't complete in-session** (missing OTP/secret, human approval, denied
+  command, manual prod promotion): set the work item `blocked` with the exact remaining
+  command + reason and tell the user the one step to run — do NOT mark `done`.
+
+Under `RDC_TEST=1`: echo `[RDC_TEST] skipping delivery (publish/deploy)` and proceed.
+
+### 6. Report, review, close, and clean up
+
+**Precondition: Step 5.5 delivery is verified.** If delivery is blocked, set `blocked` (not
+`done`) with the remaining step — never mark an undelivered change `done`.
+
+```sql
+SELECT submit_implementation_report('<id>'::uuid,
+  '{"tldr":"<one sentence>","assumptions":[],"deviations":[],"uncertainty":[],"detail":"<what was fixed>","flags":[],"transactional":false,"memory_records":[],"codeflow_post":{"agent_session_id":"<agent-session-id>","summary":"<what changed and why>","files_changed":["<path>"],"verification":["<command/evidence>"],"commit":"<hash optional>"}}'::jsonb
+);
+
+SELECT update_work_item_status('<id>'::uuid, 'review',
+  '["Fixed via rdc:fixit; ready for validation"]'::jsonb,
+  '<agent-session-id>',
+  'agent'
+);
+
+SELECT update_work_item_status('<id>'::uuid, 'done',
+  '["Validator verified rdc:fixit report, CodeFlow post, and checklist evidence"]'::jsonb,
+  '<validator-session-id>',
+  'validator'
+);
+```
+
+```bash
+rm {USER_HOME}/.claude/fixit.marker
+```
+
+### 7. Confirm to user
+
+Report: what was fixed, file(s) changed, commit hash. One sentence.
+
+## Rules
+- Work item created BEFORE any code change — never after
+- `git add` specific files only — never `-A` or `.` for a fixit
+- Branch: development branch always
+- Never run `pnpm build` — not needed for a fixit
+- If scope expands mid-fix: stop, escalate to rdc:build, don't finish under fixit
+- Marker file must be cleaned up whether fix succeeds or escalates
+- **Done = delivered, not committed.** Live where consumed (published/deployed/landed) +
+  verified. A version bump obligates a publish. Can't deliver in-session → `blocked`, never `done`.