From e81f629ac85b092952857fac60f6cff11098c14d Mon Sep 17 00:00:00 2001 From: Bastien Chanot Date: Sat, 27 Jun 2026 02:23:16 +0200 Subject: [PATCH] =?UTF-8?q?fix(init-project):=20doc-sync=20+=20doc-commit?= =?UTF-8?q?=20before=20FINISH=20=E2=80=94=20fixes=20docs=20stranded=20outs?= =?UTF-8?q?ide=20PR?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reorder: SYNC README moves from STEP 12 (post-FINISH) to STEP 10c (after 10b capitalize, before 11 FINISH) and gains lib/doc-commit.md; GSD 13 → 12. Final order: 10b capitalize -> 10c doc-sync -> 11 FINISH -> 12 GSD — both artifact-commits (memory, docs) land before FINISH, so they reach the merge/PR (twin of the ship-feature fix, BDR-034). Partial-fix note added: scaffold + STEP 5b bootstrap-README commit gap (BLK-010) and GSD-post-FINISH ROADMAP (BLK-011) are deliberately out of scope — separate chantiers. Ref-coherence (the swap flips STEP 12's meaning SYNC-README -> GSD and removes 13, so refs by number must move, not just a vanishing number): PROGRESS PROTOCOL 13-step -> 12-step + STEP /13 -> /12. USAGE.md: 5 refs corrected (table 12-13 -> 11-12 steps; pipeline illustration reworked so sync README shows BEFORE finish; 3 GSD-as-STEP-13 refs -> STEP 12). Each USAGE ref read individually post-swap — all were correct at 13, correct at 12 after fix, none accidentally-true/silently-false. Latent-bug check: init-project had NO stale ref from the capitalize chantier (STEP 10b was a non-shifting letter insertion, not a swap). Historical records (BDR-017 '13 steps', CHANGELOG STEP 13 GSD, BLK-011) left as-is — append-only; closing entry documents the renumber. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01Ho5EQCFTSvYamuRtVZpp2d --- USAGE.md | 15 ++++++++------- skills/init-project/SKILL.md | 29 +++++++++++++++++++++++------ 2 files changed, 31 insertions(+), 13 deletions(-) diff --git a/USAGE.md b/USAGE.md index b788ce9..a01b74d 100644 --- a/USAGE.md +++ b/USAGE.md @@ -123,7 +123,7 @@ Tu veux... | Commande | Quand | Notes | |---|---|---| -| `/init-project` | Nouveau projet from scratch | 12-13 steps, deux gates obligatoires | +| `/init-project` | Nouveau projet from scratch | 11-12 steps, deux gates obligatoires | | `/ship-feature` | Feature sur projet existant | Pipeline 9 steps, une gate | | `/feat` | Petite feature (1-5 fichiers) | Léger, pas d'orchestration lourde | | `/bugfix` | Bug avec investigation root cause | Hypothèses, diagnostic, fix minimal | @@ -192,9 +192,10 @@ Hotfix/quick fix → tout OFF sauf superpowers # → STEP 1 : interview (skip si prompt complet) # → STEP 4 : ★ GATE — valider l'architecture # → STEP 7 : ★ GATE — valider le plan d'implémentation -# → STEP 8-11: implémentation TDD + review + finish -# → STEP 12 : sync README -# → STEP 13 : propose GSD v2 si multi-session détecté +# → STEP 8-10 : implémentation TDD + review +# → STEP 10b-c: capitalize mémoire + sync README (avant finish) +# → STEP 11 : finish (merge / commit initial) +# → STEP 12 : propose GSD v2 si multi-session détecté # 3. Features suivantes /ship-feature "description de la feature" @@ -203,7 +204,7 @@ Hotfix/quick fix → tout OFF sauf superpowers ### Pattern B — Projet long (multi-session, plusieurs jours) · ~1500-2500t/session CC ``` -# Même départ que Pattern A, mais au STEP 13 : +# Même départ que Pattern A, mais au STEP 12 : # → Répondre "yes" à "Initialize GSD v2?" # → ROADMAP.md est créé avec les milestones @@ -399,7 +400,7 @@ Verify : npx expo export --platform web --output-dir /tmp/expo-check --clear **Si le projet devient long (plusieurs features sur semaines) :** ``` -# STEP 13 propose GSD v2 : répondre "yes" +# STEP 12 propose GSD v2 : répondre "yes" # Puis dans terminal : gsd /gsd auto @@ -500,7 +501,7 @@ Convention: snake_case Python, camelCase TypeScript." **Workflow long avec GSD v2 :** ``` -# Après /init-project (STEP 13 → "yes") +# Après /init-project (STEP 12 → "yes") # Le ROADMAP.md généré contient : # Milestone 1: Boutique in-app + Stripe # Milestone 2: PvP + matchmaking diff --git a/skills/init-project/SKILL.md b/skills/init-project/SKILL.md index e6e646c..3c66ddc 100644 --- a/skills/init-project/SKILL.md +++ b/skills/init-project/SKILL.md @@ -15,10 +15,10 @@ $ARGUMENTS ## PROGRESS PROTOCOL Every STEP must announce itself with a header BEFORE its work block, so the -user always sees where they are in the 13-step pipeline: +user always sees where they are in the 12-step pipeline: ``` -━━━ STEP /13 — ━━━ (~<estimated minutes>) +━━━ STEP <N>/12 — <TITLE> ━━━ (~<estimated minutes>) why: <one sentence — what's at risk if this step is skipped> ``` @@ -212,13 +212,30 @@ surgically commits the approved founding decisions (`.claude/memory` + STEP 11 FINISH so the memory is integrated with the branch, not stranded. If nothing was capitalized, the helper no-ops — no commit. +## STEP 10c — DOC SYNC +Run BEFORE STEP 11 FINISH (moved here from post-FINISH). doc-syncer PATCHES public docs but +does NOT commit them, and `finishing-a-development-branch` integrates only COMMITTED history +— so a patch left uncommitted never reaches the merge/PR. Same PR-stranding class as the +STEP 10b capitalize fix (BDR-034). + +Load `$HOME/.claude/agents/doc-syncer.md` (AUTO MODE, scope: files changed this session). +Detect drift, update cmds/vars/structure, add recent changes entry. + +**Then commit the docs** — follow `$HOME/.claude/lib/doc-commit.md`: it surgically commits +ONLY the files doc-syncer patched (its `PATCHED_FILES` output, one path per line → one argv +arg each), never `git add -A`, never `.claude/`/`CLAUDE.md`, and no-ops if nothing was +patched. Report per its rc table — rc 4 = a LOUD upstream BDR-022 anomaly, not a silent skip. + +> **Partial fix (conscious).** This commits the docs doc-sync patched, so they reach the +> merge/PR. It does NOT fix the scaffold (STEP 5) + bootstrap-README (STEP 5b) commit gap +> (BLK-010: no deterministic commit owner; `git worktree add -b` on an unborn HEAD) — a +> separate chantier. After this, init-project's doc-sync is fixed but the scaffold/bootstrap +> commit gap stays open; GSD STEP 12 still creates ROADMAP.md post-FINISH (BLK-011) — also separate. + ## STEP 11 — FINISH Invoke `superpowers:finishing-a-development-branch`. Tests pass, build clean, no placeholders, initial commit ready. -## STEP 12 — SYNC README -Load `$HOME/.claude/agents/doc-syncer.md` (AUTO MODE, scope: files changed this session). Detect drift, update cmds/vars/structure, add recent changes entry. - -## STEP 13 — GSD v2 INIT (optional) +## STEP 12 — GSD v2 INIT (optional) If `multi-session` signal was detected in STEP 0 OR the project has >3 planned milestones: Ask: "Initialize GSD v2 for multi-session management? (yes / skip)" - `yes` →