feat(1d): G3 — custom install-steps hook + graceful-generic (DG5) + DG3 N/A-skip demo

tests/custom-html-tiny/install_steps.sh seeds content into the volume pre-deploy. Proof: install
FAILS without the hook (404, graceful-generic), PASSES with it. Same run shows backup/restore=skip
(custom-html-tiny non-backup-capable) — DG3 N/A-skip. deploy-count=1. recipe_meta shortens timeouts.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

machine-docs/BACKLOG-1d.md

@@ -27,9 +27,11 @@
 - [x] Override proven (all 4 tiers ran cc-ci overlays); extend-by-composition (reuse generic helpers);
       no redeploy (deploy-count=1); precedence repo-local>cc-ci>generic via tests/unit/test_discovery.py (5/5).
 
-### G3 — Custom install-steps hook + graceful-generic (DG5)
-- [ ] install_steps.sh hook run during install tier (after app new+env, before deploy).
-- [ ] Proof: a recipe needing a step FAILS generic install without it; PASSES with it.
+### G3 — Custom install-steps hook + graceful-generic (DG5) — CLAIMED, awaiting Adversary
+- [x] install_steps.sh hook run during install tier (after app new+env, before deploy) — wired in
+      deploy_app via discovery.install_steps.
+- [x] Proof on custom-html-tiny: install FAILS without the hook (404, graceful), PASSES with it.
+- [x] DG3 N/A-skip run-demo: custom-html-tiny non-backup-capable -> backup/restore = skip (Run B).
 
 ### G4 — !testme e2e + per-op reporting + docs + cold verify (DG6, DG7, DG8)
 - [ ] !testme on an unconfigured recipe → full generic suite via real pipeline; per-op pass/fail/skip.

machine-docs/JOURNAL-1d.md

@@ -177,3 +177,24 @@ Two more real bugs fixed en route (both via live runs): `_app_container` now bou
 container to reappear (backup-bot cycles it); the custom-html backup/restore overlay reads the marker
 via `exec_in_app` (volume-direct), not http (which raced the serving layer post-backup, served '').
 Re-claiming G1 (DG2+DG3) and claiming G2 (DG4+DG4.1).
+
+## 2026-05-28 — G3 GREEN (DG5 hook + graceful-generic) + DG3 N/A-skip run-demo
+
+Custom install-steps hook = `tests/<recipe>/install_steps.sh` (or repo-local `tests/install_steps.sh`),
+run by deploy_app AFTER `abra app new`+env, BEFORE `abra app deploy`, env CCCI_APP_DOMAIN/CCCI_RECIPE/
+CCCI_APP_ENV. Proof on **custom-html-tiny** (static-web-server serving an empty `content` volume → 404
+zero-config; non-backup-capable), final code on cc-ci:
+```
+RUN A: hook ABSENT  -> deploy/readiness failed: ... not healthy over HTTPS / (last status 404)
+                       deploy-count=1   install : fail          # graceful-generic: needs a step, fails, reported
+RUN B: hook PRESENT -> install-steps hook (cc-ci): .../tests/custom-html-tiny/install_steps.sh
+                       install : pass   upgrade : pass           # hook seeded index.html -> serves 200
+                       backup  : skip   restore : skip           # non-backup-capable -> N/A (DG3 N/A run-demo)
+                       deploy-count = 1
+```
+So DG5 is proven BOTH ways on the SAME recipe (fail-without / pass-with), and the SAME run demonstrates
+DG3's N/A-skip half (backup/restore cleanly skipped, not failed, on a serving non-backup recipe). The
+hook writes index.html straight to the swarm volume's mountpoint (no container/image pull → no Docker
+Hub rate-limit risk); deploy-count stays 1 (the pre-created volume is not a deploy). recipe_meta for
+custom-html-tiny shortens timeouts (fast static app). lint PASS (shellcheck+shfmt+ruff+yamllint).
+Claiming G3.

machine-docs/STATUS-1d.md

@@ -18,8 +18,9 @@ per-recipe overlay authoring is Phase 2.
 - [~] **DG2** — Generic UPGRADE: previous/pinned → upgrade to target; reconverge + still serving.
       **Green on hedgedoc (3.0.9→3.0.10); CLAIMED (G1).**
 - [~] **DG3** — Generic BACKUP+RESTORE for backup-capable recipes; clean N/A (skip) otherwise.
-      **Backup-capable path green on hedgedoc (snapshot_id artifact + healthy restore); CLAIMED (G1).**
-      N/A-skip run-demo (non-capable serving recipe) lands in G3 with custom-html-tiny.
+      **Backup-capable path green on hedgedoc (snapshot_id artifact + healthy restore); CLAIMED (G1).
+      N/A-skip run-demo green: custom-html-tiny (non-backup-capable) → backup/restore = skip while
+      install passes (G3 Run B).**
 - [~] **DG4** — Layering (override-or-extend; generic is the default); discovery + cc-ci/repo-local
       precedence settled in DECISIONS. Invariant: no overlay for an op ⇒ generic runs.
       **CLAIMED (G2): custom-html overlays override+extend the generic, all 4 tiers green; discovery
@@ -27,7 +28,9 @@ per-recipe overlay authoring is Phase 2.
 - [~] **DG4.1** — Overlays reuse the deployment: ONE deploy + ONE teardown per run; no extra
       new/deploy/undeploy (assert via deploy-count). **CLAIMED (G2): deploy-count=1 across the full
       overlay lifecycle.**
-- [ ] **DG5** — Custom install-steps hook + graceful-generic rule; fail-without / pass-with proof.
+- [~] **DG5** — Custom install-steps hook + graceful-generic rule; fail-without / pass-with proof.
+      **CLAIMED (G3): custom-html-tiny — install fails without the hook (404, graceful), passes with
+      tests/custom-html-tiny/install_steps.sh seeding content.**
 - [ ] **DG6** — `!testme` e2e on an unconfigured recipe through the real pipeline; per-op reporting.
 - [ ] **DG7** — Real, DRY, clean: no softened/skip/xfail assertions; generic in the shared harness;
       teardown always; respects MAX_TESTS.
@@ -41,9 +44,10 @@ per-recipe overlay authoring is Phase 2.
 - **G4** — `!testme` e2e + per-op reporting + docs + cold verify. *Accept: DG6, DG7, DG8 → DONE.*
 
 ## In flight
-**G3 — custom install-steps hook + graceful-generic (next).** Implement the install_steps.sh hook
-proof on custom-html-tiny (needs content to serve → fails generic install without the hook, passes
-with it), which ALSO yields DG3's N/A-skip run-demo (custom-html-tiny is non-backup-capable).
+**G4 — !testme e2e + per-op reporting + docs + migrate remaining recipes (next).** Wire the full
+generic suite through a real `!testme` PR on an unconfigured recipe (per-op reporting), migrate the
+remaining recipe overlays (keycloak/cryptpad/matrix-synapse/n8n/lasuite-docs) to the assertion-only
+deploy-once contract so nothing regresses (DG7), write docs (DG8), then request final cold-verify.
 
 **F1d-1 — FIXED, awaiting Adversary close.** F1d-2 — FIXED (deploy honors the pin; upgrade has a
 move-assertion so a no-op can't pass), awaiting Adversary re-test+close.
@@ -65,6 +69,14 @@ generic) + the "no overlay ⇒ generic" invariant proven by `tests/unit/test_dis
 Reproduce (cold): `RECIPE=custom-html STAGES=install,upgrade,backup,restore CCCI_JANITOR_MAX_AGE=0 \
 cc-ci-run runner/run_recipe_ci.py` (TIER lines show `cc-ci:` overlays) + `cc-ci-run -m pytest tests/unit`.
 
+**Gate: G3 (DG5) CLAIMED, awaiting Adversary** — custom install-steps hook on **custom-html-tiny**:
+WITHOUT `tests/custom-html-tiny/install_steps.sh` the generic install FAILS (404, graceful-generic —
+reported per-op, not a crash); WITH it (seeds index.html into the content volume pre-deploy) install
+PASSES. The same Run B also demonstrates DG3's N/A-skip: custom-html-tiny is non-backup-capable, so
+backup/restore report **skip** while install/upgrade pass (deploy-count=1). Evidence in JOURNAL-1d.
+Reproduce (cold): run `RECIPE=custom-html-tiny STAGES=install …` with the hook absent (install:fail)
+then present (install:pass, backup/restore:skip).
+
 Design (DECISIONS.md Phase 1d): tier model with the lifecycle OP owned by the shared harness (test
 files = assertions only); override precedence repo-local > cc-ci > generic + extend-by-composition;
 deploy-once with a deploy-count guard; backup-capability auto-detect; install-steps shell hook.

tests/custom-html-tiny/install_steps.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Custom install-steps hook for custom-html-tiny (Phase 1d DG5).
+#
+# custom-html-tiny is a static-web-server that serves from an (otherwise EMPTY) `content` volume, so
+# the GENERIC install legitimately fails 404 with zero config — that is the correct, reported
+# graceful-generic outcome (a recipe needing a step fails the generic, you fix it by adding a step).
+# This hook is that step: it pre-seeds an index.html into the app's content volume BEFORE deploy, so
+# the app actually serves. With this hook present the generic install passes; remove it and the
+# generic install fails again — demonstrating the hook + the graceful-generic rule both real.
+#
+# Runs on cc-ci (root) after `abra app new` + env, before `abra app deploy`. Env: CCCI_APP_DOMAIN,
+# CCCI_RECIPE, CCCI_APP_ENV. Writes straight to the swarm volume's mountpoint (no container/image
+# pull). The volume is created here so it exists when the stack deploys (swarm reuses a named volume).
+set -euo pipefail
+
+stack="${CCCI_APP_DOMAIN//./_}"
+vol="${stack}_content"
+
+docker volume create "$vol" >/dev/null
+mountpoint="$(docker volume inspect "$vol" --format '{{.Mountpoint}}')"
+cat >"${mountpoint}/index.html" <<'HTML'
+<!doctype html>
+<html><body>
+<h1>cc-ci custom-html-tiny</h1>
+<p>content seeded by install_steps.sh (custom install-steps hook, DG5)</p>
+</body></html>
+HTML
+echo "install_steps: seeded index.html into volume ${vol} (${mountpoint})"

tests/custom-html-tiny/recipe_meta.py

@@ -0,0 +1,5 @@
+# Per-recipe config for custom-html-tiny (a fast static-web-server). Shorter timeouts than the
+# defaults: it converges + serves in seconds, so the generic install's fail-without-hook case
+# (DG5) is detected quickly instead of waiting the default 300s HTTP timeout.
+DEPLOY_TIMEOUT = 120
+HTTP_TIMEOUT = 90