diff --git a/docs/specs/2026-06-27-deploy-skill-design.md b/docs/specs/2026-06-27-deploy-skill-design.md index a8bc964..2b875f5 100644 --- a/docs/specs/2026-06-27-deploy-skill-design.md +++ b/docs/specs/2026-06-27-deploy-skill-design.md @@ -35,7 +35,7 @@ Treated as settled corollaries: user executes out-of-band; a **new** `lib/deploy PROCEDURE.md reference runbook — fixed shell + `# @delta:` annotated steps (edited IN-PLACE) INCIDENTS.md DEP-NNN incident ledger: date, step, error verbatim, root cause, fix (APPEND-ONLY; resolution = introducing commit, derive via git) - STATE deployed SHA + timestamp + outcome — the diff oracle (overwritten each deploy) + STATE.json deployed SHA + timestamp + outcome — the diff oracle (overwritten each deploy) NEXT.sh instantiated runbook — EPHEMERAL, not committed ; run STEP-BY-STEP (checklist, manual # VERIFY: gates) — never `bash NEXT.sh` unattended @@ -56,9 +56,9 @@ All three facts re-run live before writing this spec; observed output recorded, **First-deploy detection = STATE-absent, deterministic. `describe` is off the detection path.** ``` -[ -f .claude/deploy/STATE ] => exit 1 (absent = first deploy) <- THE detector +[ -f .claude/deploy/STATE.json ] => exit 1 (absent = first deploy) <- THE detector git describe --tags --match 'deploy/*' => fatal: No names found ; exit 128 <- only the reason NOT to use describe -[ -f .claude/deploy/STATE ] => exit 0 (present = delta path) +[ -f .claude/deploy/STATE.json ] => exit 0 (present = delta path) ``` **Delta = `git diff --name-only HEAD`** (two explicit endpoints; no dots, so it cannot be misread as three-dot). diff --git a/lib/deploy-commit.sh b/lib/deploy-commit.sh index b1922df..bdee296 100644 --- a/lib/deploy-commit.sh +++ b/lib/deploy-commit.sh @@ -23,6 +23,8 @@ _out_of_scope() { # 0 = forbidden, 1 = in scope _scope_violations() { local p; for p in "$@"; do _out_of_scope "$p" && printf '%s\n' "$p"; done; } +_ignored() { git check-ignore -q "$1"; } # rc 0 = ignored + _changed_only() { # echo passed files that actually have changes local p; for p in "$@"; do [ -n "$(git status --porcelain -- "$p" 2>/dev/null)" ] && printf '%s\n' "$p"; done @@ -52,6 +54,12 @@ case "$cmd" in echo "deploy-commit: NOTHING committed. Caller must pass only .claude/deploy/ files."; } >&2 exit 4 fi + mapfile -t ignored_paths < <(for p in "$@"; do _ignored "$p" && printf '%s\n' "$p"; done) + if [ "${#ignored_paths[@]}" -gt 0 ]; then + { echo "deploy-commit: REFUSED — path(s) are git-ignored and will NOT persist; \`.claude/deploy/\` must be committable in this project:"; + printf ' - %s\n' "${ignored_paths[@]}"; } >&2 + exit 5 + fi _unsafe_state && { echo "deploy-commit: unsafe git state (detached/merge/rebase) — not committing" >&2; exit 3; } mapfile -t changed < <(_changed_only "$@") [ "${#changed[@]}" -gt 0 ] || exit 1 diff --git a/lib/tests/deploy-commit.test.sh b/lib/tests/deploy-commit.test.sh index 915df03..f100509 100644 --- a/lib/tests/deploy-commit.test.sh +++ b/lib/tests/deploy-commit.test.sh @@ -45,4 +45,9 @@ check T7-three-files "$(git -C "$d" show --name-only --format= HEAD | grep -c de d=$(mkrepo); printf 'b\n' >"$d/src.txt" ( cd "$d" && bash "$H" pending src.txt ) >/dev/null 2>&1; check T8-pending-out-of-scope-rc "$?" 4 +d=$(mkrepo); printf '.claude/\n' >"$d/.gitignore" +printf 'run\n' >"$d/.claude/deploy/PROCEDURE.md" +( cd "$d" && bash "$H" commit "docs(deploy): t" .claude/deploy/PROCEDURE.md ) >/dev/null 2>&1 +check T9-ignored-rc "$?" 5 + printf 'PASS=%s FAIL=%s\n' "$pass" "$fail"; [ "$fail" -eq 0 ] diff --git a/skills/deploy/SKILL.md b/skills/deploy/SKILL.md index b84b129..9e0d73b 100644 --- a/skills/deploy/SKILL.md +++ b/skills/deploy/SKILL.md @@ -121,9 +121,10 @@ Read `.claude/deploy/PENDING.json` **first** (it is the only memory between runs "A deploy started `` is awaiting your report (target ``)." **Do not** recompute the delta, re-read HEAD, or re-instantiate from scratch — the bridge is authoritative. - - *Staleness guard:* if `runbook_rev` ≠ the live runbook commit - (`git log -1 --format=%h -- .claude/deploy/PROCEDURE.md`), the on-disk - `NEXT.sh` is stale (a patch landed) — regenerate it from `step_reached` + - *Staleness guard:* if `NEXT.sh` is absent **OR** `runbook_rev` ≠ the live + runbook commit (`git log -1 --format=%H -- .claude/deploy/PROCEDURE.md`), + the on-disk `NEXT.sh` is stale or missing (a patch landed, or a cold + resume without regeneration) — regenerate it from `step_reached` (STEP 2's expansion) before reacting. - **`PENDING.json` absent + `PROCEDURE.md` absent → BOOTSTRAP.** No runbook yet: interview the project and scaffold an annotated `PROCEDURE.md` (or adopt one @@ -164,7 +165,7 @@ Author a runbook, seed the incident ledger, commit both, then proceed to STEP 1. - Migration steps (`psql -f`, `migrate up`, `supabase migration`) → `# @delta:migrations glob=supabase/migrations/*.sql:list` - Build/restart steps (`docker compose`, `make build`, image push) → - `# @delta:rebuild when=docker-compose*.yml,Dockerfile,*.dockerfile` + `# @delta:rebuild when=docker-compose*.yml,Dockerfile,Dockerfile.*` - Dep-install steps (`npm ci`, `pip install -r`, `bundle install`) → `# @delta:deps when=package.json,*lock*,requirements.txt,pyproject.toml` 4. Present the annotated draft; invite corrections before the gate. @@ -217,14 +218,24 @@ Present the full draft `PROCEDURE.md`. 1. Write `.claude/deploy/PROCEDURE.md` (Write tool — the approved draft). 2. Seed `.claude/deploy/INCIDENTS.md` from `templates/deploy/INCIDENTS.md` (Write tool). -3. Commit both via the allowlist helper: +3. Ensure the target project's `.gitignore` contains `.claude/deploy/NEXT.sh` and + `.claude/deploy/PENDING.json` (append both if missing — these are the transient + artifacts that must not be committed). +4. Check that `.claude/deploy/` is NOT git-ignored: `git check-ignore -q .claude/deploy/PROCEDURE.md` + (rc 0 = ignored). If ignored — e.g. the project has `.claude/` in its `.gitignore` wholesale — + **ABORT bootstrap**: warn the user that the runbook/oracle/ledger cannot be committed, + and tell them to un-ignore `.claude/deploy/` (e.g. add `!.claude/deploy/` after the + `.claude/` rule). Do NOT commit anything further. +5. Commit via the allowlist helper: ```bash bash lib/deploy-commit.sh commit \ "feat(deploy): bootstrap runbook" \ .claude/deploy/PROCEDURE.md .claude/deploy/INCIDENTS.md ``` Return codes: **0** committed · **1** no-op (investigate — both files should be new) · - **3** unsafe git state (STOP, tell user) · **4** out-of-scope path · **2** usage error. + **3** unsafe git state (STOP, tell user) · **4** out-of-scope path · + **5** a passed path is git-ignored (won't persist) — STOP, fix the target's `.gitignore` · + **2** usage error OR not a git repo. **On rc=0: continue to STEP 1.** `STATE.json` absent → first deploy → STEP 1 sets `base_sha: null` and the full runbook fires (every fixed step and @@ -275,7 +286,7 @@ Set the base, compute the changed-file list, capture the target. { "base_sha": "", "target_sha": "", "delta": [], "step_reached": "awaiting-user", "started_at": "", - "runbook_rev": "" } + "runbook_rev": "" } ``` **Then HAND BACK** (AskUserQuestion): *"Run NEXT.sh step by step against prod. Report back: **Deployed OK** / **Failed at step X: ** / **Not yet**."* Then @@ -319,7 +330,9 @@ bash lib/deploy-commit.sh commit \ Return codes: **0** committed (short-hash on stdout) · **1** nothing staged — you wrote neither file · **3** unsafe git state (detached/merge/rebase — STOP, tell the user) · **4** out-of-scope path (you passed a non-`.claude/deploy/` path — fix -the call) · **2** usage error. The helper commits whatever subset actually changed; +the call) · **5** a passed path is git-ignored (won't persist) — STOP, fix the +target's `.gitignore` · **2** usage error OR not a git repo. The helper commits +whatever subset actually changed; patch+incident coupling is **Claude-discipline, not helper-enforced**. **This commit IS the resolution** — the commit that introduces `DEP-NNN` is its @@ -327,7 +340,7 @@ fix (patch + incident committed atomically). Recover later via `git log -S '' -- .claude/deploy/INCIDENTS.md`. No backfill needed. Then: -1. Bump `PENDING.json.runbook_rev` to that commit's sha; keep `step_reached` = `X`. +1. Bump `PENDING.json.runbook_rev` to `git rev-parse HEAD` (full sha — not the helper's short-hash stdout); keep `step_reached` = `X`. 2. **Regenerate `NEXT.sh` from `step_reached` against the PATCHED runbook** (steps X…end — X+1…end never ran). This is NOT replaying one step: the bumped `runbook_rev` is exactly the staleness trigger — runbook changed ⇒ prior