create-sdd-project 0.18.3 → 0.18.4

package/lib/meta.js

@@ -12,13 +12,27 @@
  * warnings on cross-version upgrades — the Codex P1 finding from the
  * v0.16.10 cross-model review).
  *
- * Core invariant (Codex M1 from plan v1.0 review): a hash in this file
- * represents "the last time the tool wrote this file, the content hashed
- * to X". Hashes are ONLY written/updated when the tool actually wrote
- * canonical output to a file in the current run (replaced, new, or
- * --force-template paths). Preserved files leave their hash entry
- * untouched — otherwise the user's customized content would be hashed and
- * silently overwritten on the next upgrade.
+ * Core invariant (Codex M1 from plan v1.0 review, refined v0.18.4 G1):
+ * a hash in this file represents the canonical TEMPLATE output the tool
+ * last attempted to install for this path. Hashes are written/updated in
+ * three situations:
+ *
+ *   1. The tool wrote canonical output (replaced, new file, or
+ *      --force-template paths) — record the new template hash.
+ *   2. v0.18.4 G1 — Case 3c fallback preserve writes the template hash to
+ *      bootstrap a previously-untracked path into the hash-based decision
+ *      tree for future upgrades. The file on disk is NOT modified (user's
+ *      customization is preserved + .new is written); only the meta entry
+ *      is recorded so the next upgrade can enter Case 2 instead of falling
+ *      through Case 3 again. Records what we "attempted to install", which
+ *      is the correct anchor for both: (a) the user later accepting .new
+ *      → user_current == stored → Case 2a clean replace, and (b) the user
+ *      keeping their customization → user_current != stored → Case 2b
+ *      preserve (situation (3) below then applies).
+ *   3. NEVER on Case 2b preserve — when a stored hash already exists and
+ *      the current file diverges from it, the prior baseline is kept
+ *      untouched. Otherwise the user's customized content would be hashed
+ *      and silently overwritten on the next upgrade.
  *
  * File format (schemaVersion: 1):
  *   {

package/lib/upgrade-generator.js

@@ -540,8 +540,21 @@ function generateUpgrade(config) {
               continue;
             }
 
-            // Content mismatch → preserve. Same rule: no hash update.
+            // Content mismatch → preserve.
+            //
+            // v0.18.4 G1: bootstrap hash AFTER preserve so next upgrade enters
+            // the hash-based path (Case 2) instead of falling through Case 3c
+            // again. Recording the TEMPLATE hash (not the user's hash) is the
+            // correct semantic anchor:
+            //   - If user later accepts .new → user_current == stored → Case 2a
+            //     clean replace.
+            //   - If user keeps customization → user_current != stored → Case 2b
+            //     preserve (Codex M1 invariant then applies — no further hash
+            //     updates).
+            // This is opt-in at the CALL SITE, not inside preserveFile, so
+            // Case 2b callers above remain governed by the M1 invariant.
             preserveFile(adaptedFullTargetFallback);
+            newHashes[posixPath] = computeHash(adaptedFullTargetFallback);
           }
           continue;
         }
@@ -651,7 +664,9 @@ function generateUpgrade(config) {
               replaced++;
               continue;
             }
+            // v0.18.4 G1: Case 3c bootstrap (see agents site for full rationale).
             preserveCmd();
+            newHashes[posixPath] = computeHash(rawTemplate);
           }
           continue;
         }
@@ -836,6 +851,8 @@ function generateUpgrade(config) {
     }
     modifiedAgentsResults.push({ name: relativePath, modified: true });
     preserved++;
+    // v0.18.4 G1: Case 3c bootstrap (see agents site for full rationale).
+    newHashes[posix] = computeHash(adaptedTarget);
   }
 
   // --- d) Handle standards (smart diff) ---
@@ -979,7 +996,9 @@ function generateUpgrade(config) {
       replaced++;
       continue;
     }
+    // v0.18.4 G1: Case 3c bootstrap (see agents site for full rationale).
     preserveStandard();
+    newHashes[spec.posix] = computeHash(freshAdapted);
   }
 
   step('Updated standards files');
@@ -1055,7 +1074,9 @@ function generateUpgrade(config) {
       newHashes[AGENTS_MD_POSIX] = computeHash(adaptedAgentsMd);
       replaced++;
     } else {
+      // v0.18.4 G1: Case 3c bootstrap (see agents site for full rationale).
       preserveAgentsMd();
+      newHashes[AGENTS_MD_POSIX] = computeHash(adaptedAgentsMd);
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-sdd-project",
-  "version": "0.18.3",
+  "version": "0.18.4",
   "description": "Create a new SDD DevFlow project with AI-assisted development workflow",
   "bin": {
     "create-sdd-project": "bin/cli.js"

package/template/.claude/commands/audit-merge.md

@@ -186,15 +186,33 @@ TICKET_STATUS=$(grep -E "^\*\*Status:\*\*" "$TICKET" | head -1 \
     | sed -E 's/[[:space:]]+(\(.*\)|—.*|–.*|-.*)$//' \
     | sed -E 's/\*\*[[:space:]]*$//' \
     | sed -E 's/[[:space:]]+$//')
-FEATURE_ID=$(basename "$TICKET" .md | sed -E 's/-[a-z].*//')
-TRACKER_STATUS=$(grep -F "$FEATURE_ID" docs/project_notes/product-tracker.md | grep -oE "\| (in-progress|done|pending|blocked) \|" | head -1 | sed -E 's/\| ([a-z-]+) \|/\1/')
-case "$TICKET_STATUS" in
-  "Ready for Merge"|"Review"|"In Progress"|"Planning"|"Spec") EXPECTED="in-progress" ;;
-  "Done") EXPECTED="done" ;;
-  *) EXPECTED="" ;;
+TICKET_BASENAME=$(basename "$TICKET" .md)
+# v0.18.4 P11-B: sub-scope tickets (-lite / -FU / -FU[0-9]*) close a partial
+# scope of a parent feature; the parent tracker row stays at its parent status
+# (typically `pending` or `in-progress`) while the sub-scope ticket reaches
+# `Done`. P11 must NOT enforce status mapping across this boundary. Pattern
+# scope: empirically derived from fx convention (uppercase -FU + -lite). If
+# future projects introduce -spike / -mini / -aux variants, expand here.
+case "$TICKET_BASENAME" in
+  *-lite|*-lite-*|*-FU|*-FU-*|*-FU[0-9]*)
+    echo "P11 N/A: $TICKET_BASENAME is a sub-scope ticket — parent tracker row status independent" >&2
+    ;;
+  *)
+    FEATURE_ID=$(echo "$TICKET_BASENAME" | sed -E 's/-[a-z].*//')
+    # v0.18.4 P11-B drive-by hardening: anchor tracker lookup to pipe-table row
+    # (FEATURE_ID as first cell). Mirrors v0.18.3 P16 idiom — prevents narrative
+    # mentions earlier in the tracker from silencing or false-firing the check.
+    TRACKER_STATUS=$(grep -E "^\|[[:space:]]*$FEATURE_ID[[:space:]]*\|" docs/project_notes/product-tracker.md \
+        | grep -oE "\| (in-progress|done|pending|blocked) \|" | head -1 | sed -E 's/\| ([a-z-]+) \|/\1/')
+    case "$TICKET_STATUS" in
+      "Ready for Merge"|"Review"|"In Progress"|"Planning"|"Spec") EXPECTED="in-progress" ;;
+      "Done") EXPECTED="done" ;;
+      *) EXPECTED="" ;;
+    esac
+    [ -n "$EXPECTED" ] && [ -n "$TRACKER_STATUS" ] && [ "$TRACKER_STATUS" != "$EXPECTED" ] \
+      && flag "P11 drift: ticket Status='$TICKET_STATUS' expects tracker='$EXPECTED' but tracker='$TRACKER_STATUS'"
+    ;;
 esac
-[ -n "$EXPECTED" ] && [ -n "$TRACKER_STATUS" ] && [ "$TRACKER_STATUS" != "$EXPECTED" ] \
-  && flag "P11 drift: ticket Status='$TICKET_STATUS' expects tracker='$EXPECTED' but tracker='$TRACKER_STATUS'"
 ```
 
 **23. P12 — Tracker HEAD references stale (added v0.18.2).** The `**Last Updated:**` and `**Active Feature:**` lines may embed `HEAD <sha>` or `HEAD: <sha>` references that were correct when written but went stale as further commits landed (empirically observed in fx F-WEB-MENU-VISION-001 audit cycle 2026-05-06: tracker said `HEAD: fd752e4` while `git rev-parse HEAD` was `6fa801e` after the agent's own self-edit commit). Compare each extracted SHA against the active branch HEAD. Bidirectional prefix tolerance: a 7-char tracker SHA matches the full 40-char actual HEAD if it's a prefix; a full 40-char tracker SHA matches if its first 7 chars equal the actual short form. Scoped strictly to the two header lines so narrative SHAs in "Last Completed" prose never false-positive-fire.

package/template/.claude/skills/development-workflow/references/merge-checklist.md

@@ -74,6 +74,14 @@ In the ticket, fill the `## Merge Checklist Evidence` table. For each action (0
 
 **Canonical form for the AC count claim:** write `AC: <marked>/<total>` — `marked` is the count of `[x]` Acceptance Criteria, `total` is the count of all AC items including any intentionally deferred `[ ]`. When all are checked use the matching form `AC: N/N` (or the shorthand `all N marked`). The `/audit-merge` P6 drift check parses both forms.
 
+**Sub-scope ticket naming convention (recognized by `/audit-merge` P11 since v0.18.4):** when a feature is too large to close in one ticket, split it into sub-scope tickets using one of these suffixes on the basename:
+
+- `<FEATURE_ID>-lite-<descriptor>.md` — minimal viable closure of a partial scope (e.g. `F116-lite-ci-hardening.md`)
+- `<FEATURE_ID>-FU.md` — single follow-up closing a deferred piece
+- `<FEATURE_ID>-FU<N>.md` — numbered follow-ups (e.g. `F-H7-FU1.md`, `F-H10-FU2.md`)
+
+Sub-scope tickets reach `Status: Done` independently while the parent feature's tracker row stays at its parent status (typically `pending` or `in-progress`) until ALL sub-scopes close. `/audit-merge` P11 detects the suffix and emits `P11 N/A` instead of flagging the parent/sub-scope status divergence as drift.
+
 ## Action 9: Run compliance audit
 
 Run `/audit-merge` to verify all compliance checks pass automatically. If any check fails, fix it and re-run until all pass.

package/template/.gemini/commands/audit-merge-instructions.md

@@ -186,15 +186,33 @@ TICKET_STATUS=$(grep -E "^\*\*Status:\*\*" "$TICKET" | head -1 \
     | sed -E 's/[[:space:]]+(\(.*\)|—.*|–.*|-.*)$//' \
     | sed -E 's/\*\*[[:space:]]*$//' \
     | sed -E 's/[[:space:]]+$//')
-FEATURE_ID=$(basename "$TICKET" .md | sed -E 's/-[a-z].*//')
-TRACKER_STATUS=$(grep -F "$FEATURE_ID" docs/project_notes/product-tracker.md | grep -oE "\| (in-progress|done|pending|blocked) \|" | head -1 | sed -E 's/\| ([a-z-]+) \|/\1/')
-case "$TICKET_STATUS" in
-  "Ready for Merge"|"Review"|"In Progress"|"Planning"|"Spec") EXPECTED="in-progress" ;;
-  "Done") EXPECTED="done" ;;
-  *) EXPECTED="" ;;
+TICKET_BASENAME=$(basename "$TICKET" .md)
+# v0.18.4 P11-B: sub-scope tickets (-lite / -FU / -FU[0-9]*) close a partial
+# scope of a parent feature; the parent tracker row stays at its parent status
+# (typically `pending` or `in-progress`) while the sub-scope ticket reaches
+# `Done`. P11 must NOT enforce status mapping across this boundary. Pattern
+# scope: empirically derived from fx convention (uppercase -FU + -lite). If
+# future projects introduce -spike / -mini / -aux variants, expand here.
+case "$TICKET_BASENAME" in
+  *-lite|*-lite-*|*-FU|*-FU-*|*-FU[0-9]*)
+    echo "P11 N/A: $TICKET_BASENAME is a sub-scope ticket — parent tracker row status independent" >&2
+    ;;
+  *)
+    FEATURE_ID=$(echo "$TICKET_BASENAME" | sed -E 's/-[a-z].*//')
+    # v0.18.4 P11-B drive-by hardening: anchor tracker lookup to pipe-table row
+    # (FEATURE_ID as first cell). Mirrors v0.18.3 P16 idiom — prevents narrative
+    # mentions earlier in the tracker from silencing or false-firing the check.
+    TRACKER_STATUS=$(grep -E "^\|[[:space:]]*$FEATURE_ID[[:space:]]*\|" docs/project_notes/product-tracker.md \
+        | grep -oE "\| (in-progress|done|pending|blocked) \|" | head -1 | sed -E 's/\| ([a-z-]+) \|/\1/')
+    case "$TICKET_STATUS" in
+      "Ready for Merge"|"Review"|"In Progress"|"Planning"|"Spec") EXPECTED="in-progress" ;;
+      "Done") EXPECTED="done" ;;
+      *) EXPECTED="" ;;
+    esac
+    [ -n "$EXPECTED" ] && [ -n "$TRACKER_STATUS" ] && [ "$TRACKER_STATUS" != "$EXPECTED" ] \
+      && flag "P11 drift: ticket Status='$TICKET_STATUS' expects tracker='$EXPECTED' but tracker='$TRACKER_STATUS'"
+    ;;
 esac
-[ -n "$EXPECTED" ] && [ -n "$TRACKER_STATUS" ] && [ "$TRACKER_STATUS" != "$EXPECTED" ] \
-  && flag "P11 drift: ticket Status='$TICKET_STATUS' expects tracker='$EXPECTED' but tracker='$TRACKER_STATUS'"
 ```
 
 **23. P12 — Tracker HEAD references stale (added v0.18.2).** The `**Last Updated:**` and `**Active Feature:**` lines may embed `HEAD <sha>` or `HEAD: <sha>` references that were correct when written but went stale as further commits landed (empirically observed in fx F-WEB-MENU-VISION-001 audit cycle 2026-05-06: tracker said `HEAD: fd752e4` while `git rev-parse HEAD` was `6fa801e` after the agent's own self-edit commit). Compare each extracted SHA against the active branch HEAD. Bidirectional prefix tolerance: a 7-char tracker SHA matches the full 40-char actual HEAD if it's a prefix; a full 40-char tracker SHA matches if its first 7 chars equal the actual short form. Scoped strictly to the two header lines so narrative SHAs in "Last Completed" prose never false-positive-fire.

package/template/.gemini/skills/development-workflow/references/merge-checklist.md

@@ -74,6 +74,14 @@ In the ticket, fill the `## Merge Checklist Evidence` table. For each action (0
 
 **Canonical form for the AC count claim:** write `AC: <marked>/<total>` — `marked` is the count of `[x]` Acceptance Criteria, `total` is the count of all AC items including any intentionally deferred `[ ]`. When all are checked use the matching form `AC: N/N` (or the shorthand `all N marked`). The `/audit-merge` P6 drift check parses both forms.
 
+**Sub-scope ticket naming convention (recognized by `/audit-merge` P11 since v0.18.4):** when a feature is too large to close in one ticket, split it into sub-scope tickets using one of these suffixes on the basename:
+
+- `<FEATURE_ID>-lite-<descriptor>.md` — minimal viable closure of a partial scope (e.g. `F116-lite-ci-hardening.md`)
+- `<FEATURE_ID>-FU.md` — single follow-up closing a deferred piece
+- `<FEATURE_ID>-FU<N>.md` — numbered follow-ups (e.g. `F-H7-FU1.md`, `F-H10-FU2.md`)
+
+Sub-scope tickets reach `Status: Done` independently while the parent feature's tracker row stays at its parent status (typically `pending` or `in-progress`) until ALL sub-scopes close. `/audit-merge` P11 detects the suffix and emits `P11 N/A` instead of flagging the parent/sub-scope status divergence as drift.
+
 ## Action 9: Run compliance audit
 
 Run `/audit-merge` to verify all compliance checks pass automatically. If any check fails, fix it and re-run until all pass.