create-sdd-project 0.18.0 → 0.18.2

package/lib/adapt-agents.js

@@ -91,6 +91,13 @@ const WORKFLOW_CORE_PROJECT_TYPE_RULES = {
       [/### UI Changes \(if applicable\)\n\n\[Components to add\/modify\. Reference `docs\/specs\/ui-components\.md`\.\]\n\n/, ''],
       [' / `ui-components.md`', ''],
     ],
+    // v0.18.2 (Codex R1 finding C4): pr-template.md is project-type adapted —
+    // moved from inline replaceInFileFn to this table so smart-diff fallback
+    // compare via adaptWorkflowCoreContentForProjectType produces a matching
+    // pristine target on backend/frontend installs (no false-preserve).
+    'skills/development-workflow/references/pr-template.md': [
+      [' / ui-components.md', ''],
+    ],
   },
   frontend: {
     'skills/development-workflow/SKILL.md': [
@@ -101,6 +108,9 @@ const WORKFLOW_CORE_PROJECT_TYPE_RULES = {
       [/### API Changes \(if applicable\)\n\n\[Endpoints to add\/modify\. Reference[^\]]*\]\n\n/, ''],
       ['`api-spec.yaml` / ', ''],
     ],
+    'skills/development-workflow/references/pr-template.md': [
+      ['api-spec.yaml / ', ''],
+    ],
   },
 };
 
@@ -243,25 +253,16 @@ function adaptAgentContentForProjectType(dest, config, replaceInFileFn) {
     replaceInFileFn(path.join(dest, 'AGENTS.md'), [
       [', `ui-ux-designer`', ''],
     ]);
-    for (const dir of toolDirs) {
-      // pr-template: remove ui-components from checklist (out of scope for
-      // v0.17.1 — see dev/ROADMAP.md "Known follow-ups" item 2)
-      replaceInFileFn(path.join(dest, dir, 'skills', 'development-workflow', 'references', 'pr-template.md'), [
-        [' / ui-components.md', ''],
-      ]);
-    }
+    // v0.18.2 (Codex R1 C4): pr-template.md rules moved to WORKFLOW_CORE_PROJECT_TYPE_RULES
+    // (handled by the wfRules loop above) so smart-diff fallback compare can
+    // produce a pristine adapted target via adaptWorkflowCoreContentForProjectType.
     // base-standards.mdc: remove ui-ux-designer table row (shared table above)
     replaceInFileFn(
       path.join(dest, 'ai-specs', 'specs', 'base-standards.mdc'),
       BASE_STANDARDS_PROJECT_TYPE_RULES.backend
     );
-  } else if (config.projectType === 'frontend') {
-    for (const dir of toolDirs) {
-      replaceInFileFn(path.join(dest, dir, 'skills', 'development-workflow', 'references', 'pr-template.md'), [
-        ['api-spec.yaml / ', ''],
-      ]);
-    }
   }
+  // v0.18.2: frontend pr-template rule also moved to WORKFLOW_CORE_PROJECT_TYPE_RULES.
 }
 
 module.exports = {

package/lib/meta.js

@@ -273,14 +273,79 @@ function expectedSmartDiffTrackedPaths(aiTools, projectType) {
   paths.add('ai-specs/specs/documentation-standards.mdc');
 
   // v0.17.1: development-workflow skill core files — filtered by aiTools.
-  // bug-workflow, health-check, pm-orchestrator, project-memory are OUT OF
-  // SCOPE for v0.17.1 (deferred — see dev/ROADMAP.md "Known follow-ups" item 2).
   for (const dir of toolDirs) {
     paths.add(`${dir}/skills/development-workflow/SKILL.md`);
     paths.add(`${dir}/skills/development-workflow/references/ticket-template.md`);
     paths.add(`${dir}/skills/development-workflow/references/merge-checklist.md`);
   }
 
+  // v0.18.2: extend smart-diff coverage to remaining SKILL.md entry points +
+  // 11 reference files (closes ROADMAP "Known follow-ups" item 1 — long-deferred
+  // since v0.17.1). Universal per aiTools (no project-type filtering — skills
+  // and reference templates are stack-agnostic except pr-template.md, which
+  // has project-type rules in WORKFLOW_CORE_PROJECT_TYPE_RULES so the
+  // fallback compare in upgrade-generator.js produces a pristine adapted
+  // target).
+  for (const dir of toolDirs) {
+    // 4 SKILL.md entry points
+    paths.add(`${dir}/skills/bug-workflow/SKILL.md`);
+    paths.add(`${dir}/skills/health-check/SKILL.md`);
+    paths.add(`${dir}/skills/pm-orchestrator/SKILL.md`);
+    paths.add(`${dir}/skills/project-memory/SKILL.md`);
+    // 7 development-workflow references
+    paths.add(`${dir}/skills/development-workflow/references/pr-template.md`);
+    paths.add(`${dir}/skills/development-workflow/references/branching-strategy.md`);
+    paths.add(`${dir}/skills/development-workflow/references/failure-handling.md`);
+    paths.add(`${dir}/skills/development-workflow/references/workflow-example.md`);
+    paths.add(`${dir}/skills/development-workflow/references/complexity-guide.md`);
+    paths.add(`${dir}/skills/development-workflow/references/add-feature-template.md`);
+    paths.add(`${dir}/skills/development-workflow/references/cross-model-review.md`);
+    // 1 pm-orchestrator reference
+    paths.add(`${dir}/skills/pm-orchestrator/references/pm-session-template.md`);
+    // 3 project-memory references
+    paths.add(`${dir}/skills/project-memory/references/bugs_template.md`);
+    paths.add(`${dir}/skills/project-memory/references/decisions_template.md`);
+    paths.add(`${dir}/skills/project-memory/references/key_facts_template.md`);
+  }
+
+  // v0.18.1: shipped slash-commands — preserve user customizations across
+  // upgrades. Closes v0.18.0 known limitation where audit-merge.md was
+  // wholesale-overwritten (notable since teams may tune drift recipes for
+  // their PR/ticket conventions). Same hash decision tree as agents +
+  // standards: missing/force → write, hash match → replace, hash mismatch
+  // → preserve + .new backup, no hash → fallback content compare.
+  const COMMAND_FILES_CLAUDE = [
+    'audit-merge.md',
+    'context-prompt.md',
+    'review-plan.md',
+    'review-project.md',
+    'review-spec.md',
+  ];
+  const COMMAND_FILES_GEMINI = [
+    // Each Claude command has a Gemini twin: a thin TOML wrapper + a body
+    // -instructions.md. Both must be tracked since users may edit either.
+    'audit-merge.toml',
+    'audit-merge-instructions.md',
+    'context-prompt.toml',
+    'context-prompt-instructions.md',
+    'review-plan.toml',
+    'review-plan-instructions.md',
+    'review-project.toml',
+    'review-project-instructions.md',
+    'review-spec.toml',
+    'review-spec-instructions.md',
+  ];
+  if (aiTools !== 'gemini') {
+    for (const cmd of COMMAND_FILES_CLAUDE) {
+      paths.add(`.claude/commands/${cmd}`);
+    }
+  }
+  if (aiTools !== 'claude') {
+    for (const cmd of COMMAND_FILES_GEMINI) {
+      paths.add(`.gemini/commands/${cmd}`);
+    }
+  }
+
   return paths;
 }
 

package/lib/upgrade-generator.js

@@ -305,21 +305,45 @@ function generateUpgrade(config) {
   const filesToAdapt = new Set();
 
   // v0.17.1: before the skills/ wholesale delete-and-copy, save the content
-  // of the 6 workflow-core files so we can restore them if their hash tells
+  // of the workflow-core files so we can restore them if their hash tells
   // us they were customized. Map keyed by absolute path, value = string or
   // null (null = file didn't exist before upgrade).
+  // v0.18.2: extended from 6 paths to 21 paths × tool dirs (max 42 for
+  // fullstack-both). Adds 4 SKILL.md entry points + 11 reference files,
+  // closing ROADMAP "Known follow-ups" item 1.
   const workflowCoreBackup = new Map();
   const workflowCorePosixPaths = [];
   {
     const dirsForBackup = [];
     if (aiTools !== 'gemini') dirsForBackup.push('.claude');
     if (aiTools !== 'claude') dirsForBackup.push('.gemini');
+    const WORKFLOW_CORE_RELATIVE_PATHS = [
+      // v0.17.1 (3 files)
+      'skills/development-workflow/SKILL.md',
+      'skills/development-workflow/references/ticket-template.md',
+      'skills/development-workflow/references/merge-checklist.md',
+      // v0.18.2: 4 SKILL.md entry points
+      'skills/bug-workflow/SKILL.md',
+      'skills/health-check/SKILL.md',
+      'skills/pm-orchestrator/SKILL.md',
+      'skills/project-memory/SKILL.md',
+      // v0.18.2: 7 development-workflow references
+      'skills/development-workflow/references/pr-template.md',
+      'skills/development-workflow/references/branching-strategy.md',
+      'skills/development-workflow/references/failure-handling.md',
+      'skills/development-workflow/references/workflow-example.md',
+      'skills/development-workflow/references/complexity-guide.md',
+      'skills/development-workflow/references/add-feature-template.md',
+      'skills/development-workflow/references/cross-model-review.md',
+      // v0.18.2: 1 pm-orchestrator reference
+      'skills/pm-orchestrator/references/pm-session-template.md',
+      // v0.18.2: 3 project-memory references
+      'skills/project-memory/references/bugs_template.md',
+      'skills/project-memory/references/decisions_template.md',
+      'skills/project-memory/references/key_facts_template.md',
+    ];
     for (const dir of dirsForBackup) {
-      for (const relSub of [
-        'skills/development-workflow/SKILL.md',
-        'skills/development-workflow/references/ticket-template.md',
-        'skills/development-workflow/references/merge-checklist.md',
-      ]) {
+      for (const relSub of WORKFLOW_CORE_RELATIVE_PATHS) {
         const posix = `${dir}/${relSub}`;
         const abs = path.join(dest, ...posix.split('/'));
         workflowCorePosixPaths.push({ posix, abs });
@@ -370,13 +394,13 @@ function generateUpgrade(config) {
         fs.rmSync(subDir, { recursive: true, force: true });
       }
     }
-    // For .gemini, also remove commands (SDD-owned — Gemini TOML commands)
-    if (dir === '.gemini') {
-      const cmdDir = path.join(base, 'commands');
-      if (fs.existsSync(cmdDir)) {
-        fs.rmSync(cmdDir, { recursive: true, force: true });
-      }
-    }
+    // v0.18.2: do NOT wholesale-delete .gemini/commands. The smart-diff loop
+    // below iterates template command files individually and preserves user
+    // customizations of tracked paths (e.g. audit-merge.toml) — closing the
+    // v0.18.1 plumbing gap where these files were silently overwritten on
+    // every upgrade despite being tracked in expectedSmartDiffTrackedPaths.
+    // Custom Gemini commands (files NOT in the template) are left in place,
+    // mirroring the agent strategy from v0.16.10.
 
     // Copy fresh from template
     const templateToolDir = path.join(templateDir, dir);
@@ -522,16 +546,117 @@ function generateUpgrade(config) {
           continue;
         }
 
-        // For .claude/commands, merge: overwrite SDD template commands, preserve user's custom commands
-        if (dir === '.claude' && sub === 'commands') {
+        // v0.18.2: smart-diff loop for commands (closes v0.18.1 plumbing gap).
+        //
+        // Pre-v0.18.2: .claude/commands wholesale cpSync'd every file (line 525-531)
+        // and .gemini/commands wholesale rmSync'd + recursive cpSync'd (lines 374-378
+        // and the fallback at 532-533). Both branches overwrote user customizations
+        // silently despite the paths being added to expectedSmartDiffTrackedPaths in
+        // v0.18.1 (lib/meta.js:284-320).
+        //
+        // Now: iterate template command files individually. For each file:
+        //   - If posix path is tracked → smart-diff decision tree (preserve customizations)
+        //   - Else → unconditional overwrite (SDD-owned wrappers, e.g. add-feature.toml)
+        // Custom commands (files NOT in template) are NOT touched, mirroring the
+        // agent strategy from v0.16.10.
+        //
+        // Commands have NO project-type or stack adaptations — adapted target == raw template.
+        if (sub === 'commands') {
           fs.mkdirSync(destSub, { recursive: true });
-          for (const file of fs.readdirSync(srcSub)) {
-            // Always overwrite template-owned files (they may have been updated)
-            fs.cpSync(path.join(srcSub, file), path.join(destSub, file));
+          const trackedSet = expectedSmartDiffTrackedPaths(aiTools, projectType);
+          const templateCmdFiles = fs
+            .readdirSync(srcSub, { withFileTypes: true })
+            .filter((e) => e.isFile())
+            .map((e) => e.name);
+
+          for (const file of templateCmdFiles) {
+            const templateCmdPath = path.join(srcSub, file);
+            const existingCmdPath = path.join(destSub, file);
+            const relativePath = path.relative(dest, existingCmdPath);
+            const posixPath = toPosix(relativePath);
+            const rawTemplate = fs.readFileSync(templateCmdPath, 'utf8');
+
+            if (!trackedSet.has(posixPath)) {
+              // SDD-owned (e.g. add-feature.toml, fix-bug.toml, next-task.toml,
+              // show-progress.toml, start-task.toml) — unconditional overwrite.
+              if (fs.existsSync(existingCmdPath)) {
+                backupBeforeReplace(dest, relativePath, backupTimestamp);
+              }
+              fs.writeFileSync(existingCmdPath, rawTemplate, 'utf8');
+              replaced++;
+              continue;
+            }
+
+            // --- v0.18.2 commands smart-diff decision tree (mirror of agents) ---
+            if (!fs.existsSync(existingCmdPath)) {
+              fs.writeFileSync(existingCmdPath, rawTemplate, 'utf8');
+              filesToAdapt.add(posixPath);
+              replaced++;
+              continue;
+            }
+
+            if (config.forceTemplate) {
+              backupBeforeReplace(dest, relativePath, backupTimestamp);
+              fs.writeFileSync(existingCmdPath, rawTemplate, 'utf8');
+              filesToAdapt.add(posixPath);
+              replaced++;
+              continue;
+            }
+
+            const existingContent = fs.readFileSync(existingCmdPath, 'utf8');
+            const storedHash = meta && meta.hashes[posixPath];
+
+            const preserveCmd = () => {
+              backupBeforeReplace(dest, relativePath, backupTimestamp);
+              const newBackupPath = path.join(
+                dest,
+                '.sdd-backup',
+                backupTimestamp,
+                `${relativePath}.new`
+              );
+              try {
+                fs.mkdirSync(path.dirname(newBackupPath), { recursive: true });
+                fs.writeFileSync(newBackupPath, rawTemplate, 'utf8');
+              } catch (e) {
+                console.warn(
+                  `    ⚠ Failed to write .new backup for ${relativePath}: ${e.code || e.message}`
+                );
+              }
+              modifiedAgentsResults.push({ name: relativePath, modified: true });
+              preserved++;
+              // Codex M1 invariant: preserved files do NOT update newHashes.
+            };
+
+            if (storedHash) {
+              const currentHash = computeHash(existingContent);
+              if (currentHash === storedHash) {
+                // Pristine — replace + record new hash.
+                backupBeforeReplace(dest, relativePath, backupTimestamp);
+                fs.writeFileSync(existingCmdPath, rawTemplate, 'utf8');
+                filesToAdapt.add(posixPath);
+                replaced++;
+                continue;
+              }
+              // Hash mismatch → user customized → preserve.
+              preserveCmd();
+              continue;
+            }
+
+            // Fallback — no hash (e.g. pre-v0.18.1 install). Compare against
+            // raw template (commands have no adapters).
+            if (normalizedContentEquals(existingContent, rawTemplate)) {
+              backupBeforeReplace(dest, relativePath, backupTimestamp);
+              fs.writeFileSync(existingCmdPath, rawTemplate, 'utf8');
+              filesToAdapt.add(posixPath);
+              replaced++;
+              continue;
+            }
+            preserveCmd();
           }
-        } else {
-          fs.cpSync(srcSub, destSub, { recursive: true });
+          continue;
         }
+
+        fs.cpSync(srcSub, destSub, { recursive: true });
         replaced++;
       }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-sdd-project",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "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

@@ -55,14 +55,14 @@ Eleven empirically-validated drift patterns. Failures are NOT blockers for the c
 **12. P1 — PR body test count stale.** The PR body's "npm test" line should match the terminal test count in the ticket (AC / DoD / Completion Log last entry). Agents commonly open the PR at Step 4 and add tests during Step 5 review — the PR body number becomes stale.
 ```bash
 PR_BODY=$(gh pr view --json body -q .body)
-PR_TESTS=$(echo "$PR_BODY" | grep -iE "(npm test|tests?.*(pass|green))" | grep -oE "[0-9]+/[0-9]+" | head -1)
-TICKET_TESTS=$(grep -iE "(npm test|tests?.*(pass|green))" "$TICKET" | grep -oE "[0-9]+/[0-9]+" | tail -1)
+PR_TESTS=$(echo "$PR_BODY" | grep -iE "(npm test|tests?[^|]*[0-9]|[*: ]tests?[*: ]+[0-9])" | grep -oE "[0-9]+/[0-9]+" | head -1)
+TICKET_TESTS=$(grep -iE "(npm test|tests?[^|]*[0-9]|[*: ]tests?[*: ]+[0-9])" "$TICKET" | grep -oE "[0-9]+/[0-9]+" | tail -1)
 [ -n "$PR_TESTS" ] && [ -n "$TICKET_TESTS" ] && [ "$PR_TESTS" != "$TICKET_TESTS" ] && flag "P1 drift: PR body $PR_TESTS vs ticket $TICKET_TESTS"
 ```
 
 **13. P2 — Merge Checklist Evidence rows aspirational.** Rows marked `[x]` with future-tense Evidence ("will land", "to be created", "pending", "next commit", "TBD") — the row claims done but the work hasn't happened yet.
 ```bash
-awk '/^## Merge Checklist Evidence/,/^## /' "$TICKET" \
+awk '/^## Merge Checklist Evidence/{flag=1; next} /^## /{flag=0} flag' "$TICKET" \
   | grep -E '^\|.*\[x\].*(to be |will |pending|TBD|Will be |to be created|next commit|aspirational)' \
   && flag "P2 drift: aspirational row(s) found"
 ```
@@ -82,7 +82,7 @@ done < /tmp/pm_items.txt
 
 **15. P4 — Remote branch orphan after "deleted".** Workflow Step 6 claims `[x] branch deleted` but origin still has the branch.
 ```bash
-BRANCH=$(grep -E "^\*\*[Bb]ranch:\*\*" "$TICKET" | head -1 | sed -E 's/^\*\*[Bb]ranch:\*\*[[:space:]]*([^[:space:]|]+).*/\1/')
+BRANCH=$(grep -oE '\*\*[Bb]ranch:\*\*[[:space:]]*[^[:space:]|()]+' "$TICKET" | head -1 | sed -E 's/^\*\*[Bb]ranch:\*\*[[:space:]]*//')
 git fetch origin --prune --quiet
 git ls-remote --heads origin "$BRANCH" 2>/dev/null | grep -q refs/heads && flag "P4 drift: remote branch $BRANCH still exists (run: git push origin --delete $BRANCH)"
 ```
@@ -91,7 +91,10 @@ git ls-remote --heads origin "$BRANCH" 2>/dev/null | grep -q refs/heads && flag
 ```bash
 FROZEN_COUNT=0
 for t in docs/tickets/*.md; do
-  status=$(grep -E "^\*\*Status:\*\*" "$t" | head -1 | sed -E 's/^\*\*Status:\*\*[[:space:]]*([A-Za-z ]+)[[:space:]]*\|.*/\1/' | sed -E 's/[[:space:]]+$//')
+  status=$(grep -E "^\*\*Status:\*\*" "$t" | head -1 \
+    | sed -E 's/^\*\*Status:\*\*[[:space:]]*\*?\*?//' \
+    | sed -E 's/[[:space:]]*\*?\*?[[:space:]]*\|.*//' \
+    | sed -E 's/[[:space:]]+$//')
   [ "$status" = "Done" ] && continue
   ticket_id=$(basename "$t" .md | sed -E 's/-[a-z].*//')
   git log --all --oneline --grep="$ticket_id" | grep -q . && FROZEN_COUNT=$((FROZEN_COUNT+1))
@@ -126,15 +129,15 @@ COMPLETION=$(awk '/^## Completion Log/,/^## Merge Checklist/' "$TICKET")
 CHECKED_STEPS=$(echo "$WORKFLOW" | grep -E "^- \[x\] Step [0-9]+:" | sed -E 's/^- \[x\] Step ([0-9]+):.*/\1/' | sort -u)
 while read -r step_num; do
   [ -z "$step_num" ] && continue
-  echo "$COMPLETION" | grep -qE "Step[[:space:]]+$step_num([^0-9]|$)" || flag "P8 drift: Step $step_num [x] but no Completion Log entry"
+  echo "$COMPLETION" | grep -qE "^\|[^|]*\|[[:space:]]*Step[[:space:]]+$step_num([^0-9]|$)" || flag "P8 drift: Step $step_num [x] but no dedicated Completion Log entry"
 done <<< "$CHECKED_STEPS"
 ```
 
 **20. P9 — Tracker header "Last Updated" stale.** The `**Last Updated:**` header and the `**Active Feature:**` detail should agree on step number (e.g., both say 5/6). Mismatch suggests the header wasn't refreshed after state transitions.
 ```bash
 TRACKER=docs/project_notes/product-tracker.md
-HEADER_STEP=$(grep -oE 'Step [0-9]+/6' "$TRACKER" | head -1)
-DETAIL_STEP=$(grep -A 1 '^\*\*Active Feature:\*\*' "$TRACKER" | grep -oE 'Step [0-9]+/6' | head -1)
+HEADER_STEP=$(grep '^\*\*Last Updated:\*\*' "$TRACKER" | grep -oE '(Step )?[0-9]+/6' | head -1 | sed -E 's/^Step //')
+DETAIL_STEP=$(grep -A 1 '^\*\*Active Feature:\*\*' "$TRACKER" | grep -oE '(Step )?[0-9]+/6' | head -1 | sed -E 's/^Step //')
 [ -n "$HEADER_STEP" ] && [ -n "$DETAIL_STEP" ] && [ "$HEADER_STEP" != "$DETAIL_STEP" ] \
   && flag "P9 drift: tracker header says $HEADER_STEP, Active Feature says $DETAIL_STEP"
 ```
@@ -151,7 +154,10 @@ awk -F'|' '/^\| [0-9]{4}-[0-9]{2}-[0-9]{2}/ {
 
 **22. P11 — Tracker Features table status vs ticket Status mismatch.** Ticket Status=Ready for Merge / Review → tracker expects `in-progress`. Ticket Status=Done → tracker expects `done`. Mismatch means one side wasn't updated after the state change.
 ```bash
-TICKET_STATUS=$(grep -E "^\*\*Status:\*\*" "$TICKET" | head -1 | sed -E 's/^\*\*Status:\*\*[[:space:]]*([A-Za-z ]+)[[:space:]]*\|.*/\1/' | sed -E 's/[[:space:]]+$//')
+TICKET_STATUS=$(grep -E "^\*\*Status:\*\*" "$TICKET" | head -1 \
+    | sed -E 's/^\*\*Status:\*\*[[:space:]]*\*?\*?//' \
+    | sed -E 's/[[:space:]]*\*?\*?[[: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
@@ -163,6 +169,40 @@ esac
   && 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.
+```bash
+TRACKER=docs/project_notes/product-tracker.md
+if [ -f "$TRACKER" ]; then
+  ACTUAL_HEAD=$(git rev-parse HEAD 2>/dev/null || true)
+  if [ -n "$ACTUAL_HEAD" ]; then
+    ACTUAL_SHORT=$(printf '%s' "$ACTUAL_HEAD" | cut -c1-7)
+    TRACKER_HEADS=$(grep -E '^\*\*(Last Updated|Active Feature):\*\*' "$TRACKER" 2>/dev/null \
+      | grep -oE 'HEAD[[:space:]:]+`?[a-f0-9]{7,40}`?' \
+      | grep -oE '[a-f0-9]{7,40}' \
+      | sort -u || true)
+    for sha in $TRACKER_HEADS; do
+      case "$ACTUAL_HEAD" in "$sha"*) continue ;; esac
+      case "$sha" in "$ACTUAL_SHORT"*) continue ;; esac
+      flag "P12 drift: tracker HEAD reference $sha does not match git rev-parse HEAD ($ACTUAL_HEAD); refresh tracker"
+    done
+  fi
+fi
+```
+
+### Execution discipline (added v0.18.1)
+
+For each of the 12 drift checks (P1–P12), if you declare PASS, **include the literal command output** (or its absence — explicit "no rows matched", "extracted: feature/foo", "FROZEN_COUNT=0") as evidence in your report. A bare "PASS" without supporting output is treated as **NOT EXECUTED** by the auditor — re-run with output captured.
+
+Recommended pattern:
+
+```
+P1 PR body test count stale | PASS | PR_TESTS=4110/4110, TICKET_TESTS=4110/4110 (matched)
+P2 Aspirational rows | PASS | awk … | grep … (no rows matched)
+P5 Frozen ticket Status | PASS | FROZEN_COUNT=0
+```
+
+This prevents two failure modes empirically observed during the v0.18.1 origin audit (fx F-H9 + F-H10): (a) the agent abbreviates execution and reports CLEAN by inference from MEMORY/design knowledge; (b) buggy recipes return empty output silently and the agent treats empty as PASS without verifying the recipe ran. Both are caught when literal output is required.
+
 ### Output Format
 
 Report two tables — one for **structural (blocking)** compliance, one for **drift (advisory)**. Emit two verdicts plus a combined summary line.
@@ -188,7 +228,7 @@ Report two tables — one for **structural (blocking)** compliance, one for **dr
 
 **STRUCTURAL: READY FOR MERGE** (or **STRUCTURAL: NEEDS FIX — N blockers**)
 
-### Drift (12-22) — advisory, refresh before user authorization
+### Drift (12-23) — advisory, refresh before user authorization
 
 | # | Pattern | Status | Detail |
 |---|---------|:------:|--------|
@@ -203,6 +243,7 @@ Report two tables — one for **structural (blocking)** compliance, one for **dr
 | 20 | P9 Tracker header stale | PASS | header = detail |
 | 21 | P10 Duplicate log rows | PASS | no duplicates |
 | 22 | P11 Tracker status mismatch | PASS | in-progress for Ready for Merge |
+| 23 | P12 Tracker HEAD reference | PASS | tracker HEAD = git HEAD |
 
 **DRIFT: CLEAN** (or **DRIFT: N advisories — refresh before merge**)
 
@@ -234,6 +275,7 @@ Fix them directly:
 - **P9 (Tracker header stale)** → update `**Last Updated:**` line step reference to match Active Feature detail
 - **P10 (Duplicate log rows)** → remove duplicate rows
 - **P11 (Tracker status mismatch)** → sync tracker Features row status to ticket header Status
+- **P12 (Tracker HEAD reference stale)** → update `**Last Updated:**` and `**Active Feature:**` `HEAD: <sha>` tokens to match `git rev-parse HEAD`. Use `git rev-parse --short HEAD` for the 7-char form.
 
 After fixing, re-run the audit to confirm all checks pass.
 

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

@@ -55,48 +55,52 @@ Eleven empirically-validated drift patterns. Failures are NOT blockers for the c
 **12. P1 — PR body test count stale.** Ratio must co-occur with test/pass/green marker to avoid AC/DoD ratios (14/14, 7/7).
 ```bash
 PR_BODY=$(gh pr view --json body -q .body)
-PR_TESTS=$(echo "$PR_BODY" | grep -iE "(npm test|tests?.*(pass|green))" | grep -oE "[0-9]+/[0-9]+" | head -1)
-TICKET_TESTS=$(grep -iE "(npm test|tests?.*(pass|green))" "$TICKET" | grep -oE "[0-9]+/[0-9]+" | tail -1)
-[ -n "$PR_TESTS" ] && [ -n "$TICKET_TESTS" ] && [ "$PR_TESTS" != "$TICKET_TESTS" ] && flag "P1: PR body $PR_TESTS vs ticket $TICKET_TESTS"
+PR_TESTS=$(echo "$PR_BODY" | grep -iE "(npm test|tests?[^|]*[0-9]|[*: ]tests?[*: ]+[0-9])" | grep -oE "[0-9]+/[0-9]+" | head -1)
+TICKET_TESTS=$(grep -iE "(npm test|tests?[^|]*[0-9]|[*: ]tests?[*: ]+[0-9])" "$TICKET" | grep -oE "[0-9]+/[0-9]+" | tail -1)
+[ -n "$PR_TESTS" ] && [ -n "$TICKET_TESTS" ] && [ "$PR_TESTS" != "$TICKET_TESTS" ] && flag "P1 drift: PR body $PR_TESTS vs ticket $TICKET_TESTS"
 ```
 
 **13. P2 — Merge Checklist Evidence aspirational.** `[x]` rows with future-tense text.
 ```bash
-awk '/^## Merge Checklist Evidence/,/^## /' "$TICKET" \
+awk '/^## Merge Checklist Evidence/{flag=1; next} /^## /{flag=0} flag' "$TICKET" \
   | grep -E '^\|.*\[x\].*(to be |will |pending|TBD|Will be |to be created|next commit|aspirational)' \
-  && flag "P2: aspirational row(s)"
+  && flag "P2 drift: aspirational row(s) found"
 ```
 
 **14. P3 — Post-merge actions not logged** (post-merge only).
 ```bash
+# Strip checkbox prefix before comparison; use grep -Fq fixed-string match.
 grep -E "^- \[ \].*(post-merge|operator|prod rollout|pending verification)" "$TICKET" \
   | sed -E 's/^- \[ \] //' > /tmp/pm_items.txt
 COMPLETION=$(awk '/^## Completion Log/,/^## Merge Checklist/' "$TICKET")
 while IFS= read -r item; do
   [ -z "$item" ] && continue
   KEY=$(echo "$item" | cut -c1-40)
-  echo "$COMPLETION" | grep -Fq "$KEY" || flag "P3: '$item' not logged"
+  echo "$COMPLETION" | grep -Fq "$KEY" || flag "P3 drift: post-merge '$item' not in Completion Log"
 done < /tmp/pm_items.txt
 ```
 
 **15. P4 — Remote branch orphan.**
 ```bash
-BRANCH=$(grep -E "^\*\*[Bb]ranch:\*\*" "$TICKET" | head -1 | sed -E 's/^\*\*[Bb]ranch:\*\*[[:space:]]*([^[:space:]|]+).*/\1/')
+BRANCH=$(grep -oE '\*\*[Bb]ranch:\*\*[[:space:]]*[^[:space:]|()]+' "$TICKET" | head -1 | sed -E 's/^\*\*[Bb]ranch:\*\*[[:space:]]*//')
 git fetch origin --prune --quiet
-git ls-remote --heads origin "$BRANCH" 2>/dev/null | grep -q refs/heads && flag "P4: branch $BRANCH still on origin"
+git ls-remote --heads origin "$BRANCH" 2>/dev/null | grep -q refs/heads && flag "P4 drift: remote branch $BRANCH still exists (run: git push origin --delete $BRANCH)"
 ```
 
 **16. P5 — Frozen ticket Status post-merge.** Multi-word status via sed char class, not `\w+`.
 ```bash
 FROZEN_COUNT=0
 for t in docs/tickets/*.md; do
-  status=$(grep -E "^\*\*Status:\*\*" "$t" | head -1 | sed -E 's/^\*\*Status:\*\*[[:space:]]*([A-Za-z ]+)[[:space:]]*\|.*/\1/' | sed -E 's/[[:space:]]+$//')
+  status=$(grep -E "^\*\*Status:\*\*" "$t" | head -1 \
+    | sed -E 's/^\*\*Status:\*\*[[:space:]]*\*?\*?//' \
+    | sed -E 's/[[:space:]]*\*?\*?[[:space:]]*\|.*//' \
+    | sed -E 's/[[:space:]]+$//')
   [ "$status" = "Done" ] && continue
   ticket_id=$(basename "$t" .md | sed -E 's/-[a-z].*//')
   git log --all --oneline --grep="$ticket_id" | grep -q . && FROZEN_COUNT=$((FROZEN_COUNT+1))
 done
-[ "$FROZEN_COUNT" -ge 2 ] && flag "P5 SYSTEMIC: $FROZEN_COUNT frozen tickets"
-[ "$FROZEN_COUNT" -eq 1 ] && flag "P5: 1 frozen ticket"
+[ "$FROZEN_COUNT" -ge 2 ] && flag "P5 drift (SYSTEMIC): $FROZEN_COUNT frozen tickets — Status not updated post-merge"
+[ "$FROZEN_COUNT" -eq 1 ] && flag "P5 drift: 1 frozen ticket"
 ```
 
 **17. P6 — AC count off-by-N.**
@@ -104,7 +108,7 @@ done
 ACTUAL=$(awk '/^## Acceptance Criteria/,/^## Definition of Done/' "$TICKET" | grep -cE "^- \[[x ]\]")
 CLAIMED=$(grep -oE 'all [0-9]+ marked|AC: [0-9]+/[0-9]+' "$TICKET" | head -1 | grep -oE "[0-9]+" | head -1)
 [ -n "$CLAIMED" ] && [ "$CLAIMED" != "$ACTUAL" ] && [ $((ACTUAL - CLAIMED)) -ge 2 -o $((CLAIMED - ACTUAL)) -ge 2 ] \
-  && flag "P6: claim $CLAIMED vs actual $ACTUAL"
+  && flag "P6 drift: claim '$CLAIMED' vs actual AC count $ACTUAL"
 ```
 
 **18. P7 — Test count drift within ticket (final-sections only).**
@@ -112,8 +116,9 @@ CLAIMED=$(grep -oE 'all [0-9]+ marked|AC: [0-9]+/[0-9]+' "$TICKET" | head -1 | g
 TERMINAL=$(awk '/^## Completion Log/,/^## Merge Checklist/' "$TICKET" | grep -iE "(test|pass|green)" | grep -oE "[0-9]+/[0-9]+" | tail -1)
 AC=$(awk '/^## Acceptance Criteria/,/^## Definition of Done/' "$TICKET")
 DOD=$(awk '/^## Definition of Done/,/^## Workflow Checklist/' "$TICKET")
-for n in $(printf '%s\n%s\n' "$AC" "$DOD" | grep -iE "(test|pass|green)" | grep -oE "[0-9]+/[0-9]+" | sort -u); do
-  [ -n "$TERMINAL" ] && [ "$n" != "$TERMINAL" ] && flag "P7: final $n vs terminal $TERMINAL"
+FINAL_NUMS=$(printf '%s\n%s\n' "$AC" "$DOD" | grep -iE "(test|pass|green)" | grep -oE "[0-9]+/[0-9]+" | sort -u)
+for n in $FINAL_NUMS; do
+  [ -n "$TERMINAL" ] && [ "$n" != "$TERMINAL" ] && flag "P7 drift: final-section count $n vs terminal $TERMINAL"
 done
 ```
 
@@ -124,17 +129,17 @@ COMPLETION=$(awk '/^## Completion Log/,/^## Merge Checklist/' "$TICKET")
 CHECKED_STEPS=$(echo "$WORKFLOW" | grep -E "^- \[x\] Step [0-9]+:" | sed -E 's/^- \[x\] Step ([0-9]+):.*/\1/' | sort -u)
 while read -r step_num; do
   [ -z "$step_num" ] && continue
-  echo "$COMPLETION" | grep -qE "Step[[:space:]]+$step_num([^0-9]|$)" || flag "P8: Step $step_num [x] but no log entry"
+  echo "$COMPLETION" | grep -qE "^\|[^|]*\|[[:space:]]*Step[[:space:]]+$step_num([^0-9]|$)" || flag "P8 drift: Step $step_num [x] but no dedicated Completion Log entry"
 done <<< "$CHECKED_STEPS"
 ```
 
 **20. P9 — Tracker header stale.**
 ```bash
 TRACKER=docs/project_notes/product-tracker.md
-HEADER_STEP=$(grep -oE 'Step [0-9]+/6' "$TRACKER" | head -1)
-DETAIL_STEP=$(grep -A 1 '^\*\*Active Feature:\*\*' "$TRACKER" | grep -oE 'Step [0-9]+/6' | head -1)
+HEADER_STEP=$(grep '^\*\*Last Updated:\*\*' "$TRACKER" | grep -oE '(Step )?[0-9]+/6' | head -1 | sed -E 's/^Step //')
+DETAIL_STEP=$(grep -A 1 '^\*\*Active Feature:\*\*' "$TRACKER" | grep -oE '(Step )?[0-9]+/6' | head -1 | sed -E 's/^Step //')
 [ -n "$HEADER_STEP" ] && [ -n "$DETAIL_STEP" ] && [ "$HEADER_STEP" != "$DETAIL_STEP" ] \
-  && flag "P9: header $HEADER_STEP vs detail $DETAIL_STEP"
+  && flag "P9 drift: tracker header says $HEADER_STEP, Active Feature says $DETAIL_STEP"
 ```
 
 **21. P10 — Duplicate Completion Log rows.**
@@ -143,12 +148,16 @@ awk -F'|' '/^\| [0-9]{4}-[0-9]{2}-[0-9]{2}/ {
   key = $2 "|" $3 "|" substr($4, 1, 80)
   gsub(/^[[:space:]]+|[[:space:]]+$/, "", key)
   print key
-}' "$TICKET" | sort | uniq -d | while read -r dup; do flag "P10: duplicate row: $dup"; done
+}' "$TICKET" | sort | uniq -d \
+  | while read -r dup; do flag "P10 drift: duplicate Completion Log row: $dup"; done
 ```
 
 **22. P11 — Tracker Features table status vs ticket Status mismatch.**
 ```bash
-TICKET_STATUS=$(grep -E "^\*\*Status:\*\*" "$TICKET" | head -1 | sed -E 's/^\*\*Status:\*\*[[:space:]]*([A-Za-z ]+)[[:space:]]*\|.*/\1/' | sed -E 's/[[:space:]]+$//')
+TICKET_STATUS=$(grep -E "^\*\*Status:\*\*" "$TICKET" | head -1 \
+    | sed -E 's/^\*\*Status:\*\*[[:space:]]*\*?\*?//' \
+    | sed -E 's/[[:space:]]*\*?\*?[[: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
@@ -157,9 +166,43 @@ case "$TICKET_STATUS" in
   *) EXPECTED="" ;;
 esac
 [ -n "$EXPECTED" ] && [ -n "$TRACKER_STATUS" ] && [ "$TRACKER_STATUS" != "$EXPECTED" ] \
-  && flag "P11: Status='$TICKET_STATUS' expects tracker='$EXPECTED' but tracker='$TRACKER_STATUS'"
+  && 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.
+```bash
+TRACKER=docs/project_notes/product-tracker.md
+if [ -f "$TRACKER" ]; then
+  ACTUAL_HEAD=$(git rev-parse HEAD 2>/dev/null || true)
+  if [ -n "$ACTUAL_HEAD" ]; then
+    ACTUAL_SHORT=$(printf '%s' "$ACTUAL_HEAD" | cut -c1-7)
+    TRACKER_HEADS=$(grep -E '^\*\*(Last Updated|Active Feature):\*\*' "$TRACKER" 2>/dev/null \
+      | grep -oE 'HEAD[[:space:]:]+`?[a-f0-9]{7,40}`?' \
+      | grep -oE '[a-f0-9]{7,40}' \
+      | sort -u || true)
+    for sha in $TRACKER_HEADS; do
+      case "$ACTUAL_HEAD" in "$sha"*) continue ;; esac
+      case "$sha" in "$ACTUAL_SHORT"*) continue ;; esac
+      flag "P12 drift: tracker HEAD reference $sha does not match git rev-parse HEAD ($ACTUAL_HEAD); refresh tracker"
+    done
+  fi
+fi
+```
+
+### Execution discipline (added v0.18.1)
+
+For each of the 12 drift checks (P1–P12), if you declare PASS, **include the literal command output** (or its absence — explicit "no rows matched", "extracted: feature/foo", "FROZEN_COUNT=0") as evidence in your report. A bare "PASS" without supporting output is treated as **NOT EXECUTED** by the auditor — re-run with output captured.
+
+Recommended pattern:
+
+```
+P1 PR body test count stale | PASS | PR_TESTS=4110/4110, TICKET_TESTS=4110/4110 (matched)
+P2 Aspirational rows | PASS | awk … | grep … (no rows matched)
+P5 Frozen ticket Status | PASS | FROZEN_COUNT=0
+```
+
+This prevents two failure modes empirically observed during the v0.18.1 origin audit (fx F-H9 + F-H10): (a) the agent abbreviates execution and reports CLEAN by inference from MEMORY/design knowledge; (b) buggy recipes return empty output silently and the agent treats empty as PASS without verifying the recipe ran. Both are caught when literal output is required.
+
 ### Output Format
 
 Report two tables — one for **structural (blocking)** compliance, one for **drift (advisory)**. Emit two verdicts plus a combined summary line.
@@ -185,7 +228,7 @@ Report two tables — one for **structural (blocking)** compliance, one for **dr
 
 **STRUCTURAL: READY FOR MERGE** (or **STRUCTURAL: NEEDS FIX — N blockers**)
 
-### Drift (12-22) — advisory, refresh before user authorization
+### Drift (12-23) — advisory, refresh before user authorization
 
 | # | Pattern | Status | Detail |
 |---|---------|:------:|--------|
@@ -200,6 +243,7 @@ Report two tables — one for **structural (blocking)** compliance, one for **dr
 | 20 | P9 Tracker header stale | PASS | header = detail |
 | 21 | P10 Duplicate log rows | PASS | no duplicates |
 | 22 | P11 Tracker status mismatch | PASS | status consistent |
+| 23 | P12 Tracker HEAD reference | PASS | tracker HEAD = git HEAD |
 
 **DRIFT: CLEAN** (or **DRIFT: N advisories — refresh before merge**)
 
@@ -231,6 +275,7 @@ Fix them directly:
 - **P9** → refresh `**Last Updated:**` step reference
 - **P10** → remove duplicate rows
 - **P11** → sync tracker Features row status to ticket header Status
+- **P12 (Tracker HEAD reference stale)** → update `**Last Updated:**` and `**Active Feature:**` `HEAD: <sha>` tokens to match `git rev-parse HEAD`. Use `git rev-parse --short HEAD` for the 7-char form.
 
 After fixing, re-run the audit to confirm all checks pass.