fix(deploy): drop resolved-by — resolution = introducing atomic commit (derive via git)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ho5EQCFTSvYamuRtVZpp2d
This commit is contained in:
Bastien Chanot
parent
3f11b61ab0
commit
a10635aa36
@ -36,7 +36,7 @@
|
||||
|
||||
**§8 item 1 — tag push:** annotated tag `git tag -a deploy/<YYYY-MM-DD> <target_sha> -m "<summary>"` laid in MARK (success). **Project knob `# @config push_deploy_tags=true|false`** in the `PROCEDURE.md` header (default `false`): when true, MARK runs `git push origin deploy/<date>` — always **best-effort/non-fatal** (the push never blocks the deploy; tag is a bookmark, STATE.json is the oracle). Same-day re-deploy → suffix `-N`.
|
||||
|
||||
**§8 item 2 — INCIDENTS ID/name:** `.claude/deploy/INCIDENTS.md`, append-only, entries `DEP-NNN` (next = `grep '^## DEP-' | max+1`), fields mirror `blockers.md`: date, step, error (verbatim), root cause, fix, → resolving commit sha. Name confirmed `INCIDENTS.md` (not `ERRORS-LEARNED.md`).
|
||||
**§8 item 2 — INCIDENTS ID/name:** `.claude/deploy/INCIDENTS.md`, append-only, entries `DEP-NNN` (next = `grep '^## DEP-' | max+1`), fields mirror `blockers.md`: date, step, error (verbatim), root cause, fix. Resolution derivable from git: the commit that adds the entry IS the fix (atomic patch+incident); recover via `git log -S 'DEP-NNN' -- .claude/deploy/INCIDENTS.md`. Name confirmed `INCIDENTS.md` (not `ERRORS-LEARNED.md`).
|
||||
|
||||
**§8 item 3 — `@delta:` grammar:** directives on a runbook step's preceding comment line, patterns matched against the delta file list. `glob=` carries TWO required semantics (a single "checklist-only" reading was REJECTED — it breaks the game example, where step 3 runs `psql -f 0033` THEN `psql -f 0034` = one command PER file):
|
||||
- `# @delta:<name> glob=<pat>:each` — **repeat**: emit the step's command once per delta file matching `<pat>` (e.g. `psql -f <each>`).
|
||||
@ -269,13 +269,13 @@ curl -fsS https://$DEPLOY_HOST/health
|
||||
# Deploy incidents (append-only) — DEP-NNN
|
||||
|
||||
<!-- One entry per incident. Next ID = grep '^## DEP-' | max+1. Mirrors blockers.md. -->
|
||||
<!-- Resolution = the commit that adds this entry (atomic patch+incident). Recover: git log -S 'DEP-NNN' -- .claude/deploy/INCIDENTS.md -->
|
||||
<!-- ## DEP-NNN — <step> failed
|
||||
- date: YYYY-MM-DD
|
||||
- step: <runbook step + label>
|
||||
- error: `<verbatim error>`
|
||||
- cause: <root cause>
|
||||
- fix: <what changed in PROCEDURE.md>
|
||||
- resolved-by: <commit sha> -->
|
||||
- fix: <what changed in PROCEDURE.md> -->
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Record the JSON schemas** (no parsing in shell — Claude reads them in skill steps)
|
||||
@ -332,7 +332,7 @@ git commit -m "feat(deploy): runbook/ledger templates + bridge schemas + gitigno
|
||||
- "Deployed OK" → STEP 5.
|
||||
- "Failed at step X: <err>" → STEP 4.
|
||||
- "Not yet" → re-state pending, stop.
|
||||
- [ ] **STEP 4 — LEARN + [GATE] + ATOMIC COMMIT.** Diagnose. Draft: (a) in-place `PROCEDURE.md` patch to step X; (b) `INCIDENTS.md` append `DEP-NNN` (error verbatim). **[GATE]** `all / pick / edit / skip-all` (significant edit). On approve: write both, then **one atomic** `bash lib/deploy-commit.sh commit "docs(deploy): patch <step> — recovered from <err>" .claude/deploy/PROCEDURE.md .claude/deploy/INCIDENTS.md`. Set `resolved-by` to the returned sha. Then bump `PENDING.json.runbook_rev` to the new `PROCEDURE.md` commit sha (keep `step_reached` at X). **Resume = REGENERATE `NEXT.sh` from `step_reached` against the PATCHED runbook** (steps X…end — X+1…end never ran), NOT replay a single step. The bumped `runbook_rev` is exactly the trigger: runbook changed ⇒ prior `NEXT.sh` is stale ⇒ regenerate. Re-present via STEP 2's hand-back.
|
||||
- [ ] **STEP 4 — LEARN + [GATE] + ATOMIC COMMIT.** Diagnose. Draft: (a) in-place `PROCEDURE.md` patch to step X; (b) `INCIDENTS.md` append `DEP-NNN` (error verbatim). **[GATE]** `all / pick / edit / skip-all` (significant edit). On approve: write both, then **one atomic** `bash lib/deploy-commit.sh commit "docs(deploy): patch <step> — recovered from <err>" .claude/deploy/PROCEDURE.md .claude/deploy/INCIDENTS.md`. The commit that adds `DEP-NNN` IS its resolution (derive via git later). Then bump `PENDING.json.runbook_rev` to the new `PROCEDURE.md` commit sha (keep `step_reached` at X). **Resume = REGENERATE `NEXT.sh` from `step_reached` against the PATCHED runbook** (steps X…end — X+1…end never ran), NOT replay a single step. The bumped `runbook_rev` is exactly the trigger: runbook changed ⇒ prior `NEXT.sh` is stale ⇒ regenerate. Re-present via STEP 2's hand-back.
|
||||
- [ ] **STEP 5 — MARK (success).** Write `STATE.json` (`deployed_sha = PENDING.target_sha`, outcome ok, tag). `git tag -a deploy/<date> <target> -m "<summary>"`; **if `@config push_deploy_tags=true`** then `git push origin deploy/<date>` (best-effort, non-fatal). `bash lib/deploy-commit.sh commit "chore(deploy): mark <date> @ <short>" .claude/deploy/STATE.json`. **Delete `PENDING.json`** (+ `NEXT.sh`). Report.
|
||||
|
||||
- [ ] **Verification scenarios** (dry-run walkthroughs, no prod):
|
||||
|
||||
@ -34,7 +34,7 @@ Treated as settled corollaries: user executes out-of-band; a **new** `lib/deploy
|
||||
.claude/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, -> resolving commit hash (APPEND-ONLY)
|
||||
fix (APPEND-ONLY; resolution = introducing commit, derive via git)
|
||||
STATE 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
|
||||
|
||||
@ -197,7 +197,7 @@ Diagnose the root cause of the step-X failure, then draft a **coupled pair**:
|
||||
repeat the failure;
|
||||
- **(b)** an append to `INCIDENTS.md` — a new `DEP-NNN`
|
||||
(`next = grep '^## DEP-' INCIDENTS.md | max+1`) with date, step, **error
|
||||
verbatim**, root cause, fix, and `resolved-by` (filled after commit).
|
||||
verbatim**, root cause, and fix.
|
||||
|
||||
**[GATE] — `all / pick <IDs> / edit <ID> / skip-all`** (significant edit — it
|
||||
changes a prod path).
|
||||
@ -217,16 +217,17 @@ changed — investigate, you should have written both) · **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.
|
||||
|
||||
**This commit IS the resolution** — the commit that introduces `DEP-NNN` is its
|
||||
fix (patch + incident committed atomically). Recover later via
|
||||
`git log -S '<DEP-NNN>' -- .claude/deploy/INCIDENTS.md`. No backfill needed.
|
||||
|
||||
Then:
|
||||
1. Set the new `DEP-NNN`'s `resolved-by:` to the returned short-hash. (This is a
|
||||
metadata-only line; it rides along on the next `INCIDENTS.md` commit — do not
|
||||
churn a second commit for it.)
|
||||
2. Bump `PENDING.json.runbook_rev` to that commit's sha; keep `step_reached` = `X`.
|
||||
3. **Regenerate `NEXT.sh` from `step_reached` against the PATCHED runbook**
|
||||
1. Bump `PENDING.json.runbook_rev` to that commit's sha; 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
|
||||
`NEXT.sh` is stale ⇒ regenerate.
|
||||
4. Re-present via **STEP 2's [GATE] + hand-back** (the regenerated `NEXT.sh`;
|
||||
3. Re-present via **STEP 2's [GATE] + hand-back** (the regenerated `NEXT.sh`;
|
||||
`PENDING.json` keeps `base/target/delta`, `step_reached` back to
|
||||
`awaiting-user`).
|
||||
|
||||
|
||||
@ -1,10 +1,10 @@
|
||||
# Deploy incidents (append-only) — DEP-NNN
|
||||
|
||||
<!-- One entry per incident. Next ID = grep '^## DEP-' | max+1. Mirrors blockers.md. -->
|
||||
<!-- Resolution = the commit that adds this entry (atomic patch+incident). Recover: git log -S 'DEP-NNN' -- .claude/deploy/INCIDENTS.md -->
|
||||
<!-- ## DEP-NNN — <step> failed
|
||||
- date: YYYY-MM-DD
|
||||
- step: <runbook step + label>
|
||||
- error: `<verbatim error>`
|
||||
- cause: <root cause>
|
||||
- fix: <what changed in PROCEDURE.md>
|
||||
- resolved-by: <commit sha> -->
|
||||
- fix: <what changed in PROCEDURE.md> -->
|
||||
|
||||
Loading…
Reference in New Issue
Block a user