create-sdd-project 0.17.2 → 0.18.0

package/lib/adapt-agents.js

@@ -227,7 +227,8 @@ function adaptAgentContentForProjectType(dest, config, replaceInFileFn) {
   // WORKFLOW_CORE_PROJECT_TYPE_RULES table above so upgrade-generator.js
   // can apply the same rules in-memory (smart-diff fallback comparison).
   // pr-template.md + AGENTS.md + base-standards.mdc remain inline because
-  // they're not workflow-core files (pr-template is v0.17.2 scope).
+  // they're not workflow-core files (pr-template is out of scope for v0.17.1 —
+  // see dev/ROADMAP.md "Known follow-ups" item 2).
   const wfRules = WORKFLOW_CORE_PROJECT_TYPE_RULES[config.projectType];
   if (wfRules) {
     for (const dir of toolDirs) {
@@ -243,7 +244,8 @@ function adaptAgentContentForProjectType(dest, config, replaceInFileFn) {
       [', `ui-ux-designer`', ''],
     ]);
     for (const dir of toolDirs) {
-      // pr-template: remove ui-components from checklist (v0.17.2 scope)
+      // 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', ''],
       ]);

package/lib/init-generator.js

@@ -232,10 +232,32 @@ function generateInit(config) {
   console.log('    These files were generated from project analysis. Adjust patterns');
   console.log('    and conventions to match your team\'s actual practices.');
 
-  // Test coverage note
-  if (scan.tests.estimatedCoverage === 'none' || scan.tests.estimatedCoverage === 'low') {
+  // Test coverage note — v0.17.3: broaden signal detection across root,
+  // backend, and frontend tests (covers E2E-only setups and monorepos
+  // with workspace-level tests). Only show the note when NO test signal
+  // exists anywhere.
+  const hasAnyTestSignal =
+    scan.tests.framework !== 'none' ||
+    scan.backendTests.framework !== 'none' ||
+    scan.frontendTests.framework !== 'none' ||
+    scan.tests.e2eFramework !== null ||
+    scan.tests.testFiles > 0 ||
+    scan.backendTests.testFiles > 0 ||
+    scan.frontendTests.testFiles > 0;
+  const maxCoverageRank = (c) =>
+    c === 'high' ? 3 : c === 'medium' ? 2 : c === 'low' ? 1 : 0;
+  const bestCoverage = Math.max(
+    maxCoverageRank(scan.tests.estimatedCoverage),
+    maxCoverageRank(scan.backendTests.estimatedCoverage),
+    maxCoverageRank(scan.frontendTests.estimatedCoverage),
+  );
+  if (!hasAnyTestSignal || bestCoverage <= 1 /* none or low */) {
     console.log('');
-    const fileCount = scan.tests.testFiles;
+    const fileCount = Math.max(
+      scan.tests.testFiles,
+      scan.backendTests.testFiles,
+      scan.frontendTests.testFiles,
+    );
     if (fileCount === 0) {
       console.log('  📝 No test files detected.');
     } else {
@@ -458,8 +480,11 @@ function adaptBackendStandards(template, scan) {
   const db = scan.backend.db;
   const lang = scan.language === 'typescript' ? 'TypeScript' : 'JavaScript';
 
-  const testFramework = scan.tests.framework !== 'none'
-    ? capitalizeFramework(scan.tests.framework)
+  // v0.17.3: consume backendTests instead of tests so that monorepos with
+  // workspace-only test frameworks (e.g., fx: vitest in packages/api) emit
+  // the correct Testing line. Single-package: backendTests === tests.
+  const testFramework = scan.backendTests.framework !== 'none'
+    ? capitalizeFramework(scan.backendTests.framework)
     : 'Not configured';
 
   let stackLines = [
@@ -570,9 +595,14 @@ function adaptFrontendStandards(template, scan) {
   const state = scan.frontend.state ? `, ${scan.frontend.state}` : '';
   const lang = scan.language === 'typescript' ? 'TypeScript' : 'JavaScript';
 
+  // v0.17.3: consume frontendTests (see backend equivalent above).
+  const frontendTestFramework = scan.frontendTests.framework !== 'none'
+    ? capitalizeFramework(scan.frontendTests.framework)
+    : 'Not configured';
+
   content = content.replace(
     /## Technology Stack\n\n[\s\S]*?(?=\n## Project Structure)/,
-    `## Technology Stack\n\n- **Framework**: ${framework}\n- **Language**: ${lang}\n- **Styling**: ${styling}${components ? `\n- **Components**: ${components.slice(2)}` : ''}${state ? `\n- **State Management**: ${state.slice(2)}` : ''}\n- **Testing**: ${scan.tests.framework !== 'none' ? capitalizeFramework(scan.tests.framework) : 'Not configured'}\n\n`
+    `## Technology Stack\n\n- **Framework**: ${framework}\n- **Language**: ${lang}\n- **Styling**: ${styling}${components ? `\n- **Components**: ${components.slice(2)}` : ''}${state ? `\n- **State Management**: ${state.slice(2)}` : ''}\n- **Testing**: ${frontendTestFramework}\n\n`
   );
 
   // Update Project Structure
@@ -848,8 +878,29 @@ function configureProductTracker(template, scan) {
     content = content.replace('| backend | pending', `| ${featureType} | pending`);
   }
 
-  // Add retrofit testing as first feature if coverage is low
-  if (scan.tests.estimatedCoverage === 'none' || scan.tests.estimatedCoverage === 'low') {
+  // Add retrofit testing as first feature if coverage is low — v0.17.3
+  // broaden the gate: consider backend and frontend test coverage, not just
+  // root-level. Avoids false F001 recommendation on monorepos that have
+  // extensive tests in workspaces. Per Gemini round-3 CRITICAL: also gate
+  // on the broader "any test signal" disjunction so E2E-only setups
+  // (Playwright/Cypress at root, no unit tests anywhere) don't trigger
+  // F001 either — symmetric with the console-warning gate above.
+  const rankCoverage = (c) =>
+    c === 'high' ? 3 : c === 'medium' ? 2 : c === 'low' ? 1 : 0;
+  const bestCov = Math.max(
+    rankCoverage(scan.tests.estimatedCoverage),
+    rankCoverage(scan.backendTests.estimatedCoverage),
+    rankCoverage(scan.frontendTests.estimatedCoverage),
+  );
+  const hasAnyTestSignal =
+    scan.tests.framework !== 'none' ||
+    scan.backendTests.framework !== 'none' ||
+    scan.frontendTests.framework !== 'none' ||
+    scan.tests.e2eFramework !== null ||
+    scan.tests.testFiles > 0 ||
+    scan.backendTests.testFiles > 0 ||
+    scan.frontendTests.testFiles > 0;
+  if (!hasAnyTestSignal || bestCov <= 1 /* none or low */) {
     // Use regex to match the F001 placeholder row resiliently (handles column changes)
     content = content.replace(
       /\| F001 \|[^\n]*\n/,

package/lib/init-wizard.js

@@ -41,8 +41,23 @@ function formatScanSummary(scanResult) {
   };
   lines.push(`    Architecture:  ${patternLabels[scanResult.srcStructure.pattern] || 'Unknown'}`);
 
-  if (scanResult.tests.framework !== 'none') {
-    lines.push(`    Tests:         ${scanResult.tests.framework} (${scanResult.tests.testFiles} test files)`);
+  // v0.17.3: collect distinct non-'none' frameworks across root, backend,
+  // and frontend tests. For mixed monorepos (e.g., fx: vitest in api, jest
+  // in web), display joined (e.g., "vitest + jest") so the summary reflects
+  // what adapt-functions will actually write. Avoids the v1.1 UX issue
+  // where OR-precedence picked root-hoisted jest over workspace vitest.
+  const uniqueFrameworks = Array.from(new Set([
+    scanResult.tests.framework,
+    scanResult.backendTests.framework,
+    scanResult.frontendTests.framework,
+  ].filter((f) => f !== 'none')));
+  if (uniqueFrameworks.length > 0) {
+    const totalFiles = Math.max(
+      scanResult.tests.testFiles,
+      scanResult.backendTests.testFiles,
+      scanResult.frontendTests.testFiles,
+    );
+    lines.push(`    Tests:         ${uniqueFrameworks.join(' + ')} (${totalFiles} test files)`);
   } else {
     lines.push('    Tests:         None detected');
   }

package/lib/meta.js

@@ -236,9 +236,10 @@ function writeMeta(dest, hashes) {
  * - 6 workflow-core files (development-workflow SKILL.md + ticket-template.md
  *   + merge-checklist.md, × 2 tools) — filtered by aiTools
  *
- * Out of scope for v0.17.1 (deferred to v0.17.2): bug-workflow/SKILL.md,
- * health-check/SKILL.md, pm-orchestrator/SKILL.md, project-memory/SKILL.md,
- * and all references/ files except the 3 development-workflow ones above.
+ * Out of scope for v0.17.1 (deferred — see dev/ROADMAP.md "Known follow-ups"
+ * item 2): bug-workflow/SKILL.md, health-check/SKILL.md, pm-orchestrator/SKILL.md,
+ * project-memory/SKILL.md, and all references/ files except the 3
+ * development-workflow ones above. Did not land in the v0.17.2 scanner hotfix.
  */
 function expectedSmartDiffTrackedPaths(aiTools, projectType) {
   const paths = new Set();
@@ -273,7 +274,7 @@ function expectedSmartDiffTrackedPaths(aiTools, projectType) {
 
   // 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 to v0.17.2).
+  // 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`);

package/lib/scanner.js

@@ -46,62 +46,187 @@ function scan(projectDir) {
   const frontend = detectFrontend(projectDir, pkg);
   const isMonorepo = detectMonorepo(projectDir, pkg);
 
-  // v0.17.2 monorepo fallback: promote to workspace when root lacks a
-  // framework, even if root partial detection set `detected: true`.
-  if (isMonorepo && (!backend.framework || !frontend.framework)) {
+  let language = detectLanguage(projectDir);
+  let srcStructure = detectArchitecture(projectDir, pkg);
+  const rootTests = detectTests(projectDir, pkg);
+  let backendTests = rootTests;
+  let frontendTests = rootTests;
+
+  // v0.17.3: single-pass monorepo enumeration.
+  //
+  // Combines v0.17.2's framework promotion (runs only when root lacks a
+  // framework, gated by `!backend.framework` / `!frontend.framework`) with
+  // v0.17.3's auxiliary-field promotion (language, architecture, tests,
+  // frontend styling/components/state) into a single loop that always runs
+  // in monorepos.
+  //
+  // Rationale for always-enumerate: `workspaceSource` is only set when
+  // v0.17.2 actually promoted a framework from a workspace (root lacked it).
+  // If root has the framework hoisted (e.g., `"next": "^14.2.29"` at root in
+  // a Next.js monorepo), v0.17.2's loop never runs → `workspaceSource` is
+  // null → auxiliary detection has no workspace handle. v0.17.3 solves this
+  // by tracking `primaryBackendWs` / `primaryFrontendWs` independently:
+  // always populated for monorepos with a detectable backend/frontend
+  // workspace, regardless of where the framework came from. See
+  // dev/v0.17.3-plan.md D5 for full rationale + round-1/round-2 review trail.
+  let primaryBackendWs = null;
+  let primaryFrontendWs = null;
+  if (isMonorepo) {
     const workspaces = enumerateWorkspaces(projectDir, pkg);
     for (const wsRel of workspaces) {
       const wsAbs = path.join(projectDir, ...wsRel.split('/'));
       const wsPkg = readPackageJson(wsAbs);
-      if (!backend.framework) {
+
+      if (!primaryBackendWs) {
         const wsBackend = detectBackend(wsAbs, wsPkg);
         if (wsBackend.framework) {
-          // Field-merge: prefer workspace values for fields it detected,
-          // preserve root values for fields the workspace didn't (e.g.,
-          // a root .env's DATABASE_URL → root.db, which packages/api
-          // might not repeat in its own .env). Iterate `Object.keys` so
-          // future additions to `detectBackend` are forwarded without
-          // requiring a dual-update here (Gemini round-4 finding 1).
-          // `workspaceSource` records the winning workspace for diagnostics.
-          for (const field of Object.keys(wsBackend)) {
-            if (wsBackend[field] !== null && wsBackend[field] !== undefined) {
-              backend[field] = wsBackend[field];
+          primaryBackendWs = wsRel;
+          // v0.17.2 promotion — only when root lacked framework. Preserves
+          // v0.17.2 semantics byte-equivalent.
+          if (!backend.framework) {
+            for (const field of Object.keys(wsBackend)) {
+              if (wsBackend[field] !== null && wsBackend[field] !== undefined) {
+                backend[field] = wsBackend[field];
+              }
             }
+            backend.workspaceSource = wsRel;
           }
-          backend.workspaceSource = wsRel;
         }
       }
-      if (!frontend.framework) {
+
+      if (!primaryFrontendWs) {
         const wsFrontend = detectFrontend(wsAbs, wsPkg);
         if (wsFrontend.framework) {
-          for (const field of Object.keys(wsFrontend)) {
-            if (wsFrontend[field] !== null && wsFrontend[field] !== undefined) {
-              frontend[field] = wsFrontend[field];
+          primaryFrontendWs = wsRel;
+          if (!frontend.framework) {
+            for (const field of Object.keys(wsFrontend)) {
+              if (wsFrontend[field] !== null && wsFrontend[field] !== undefined) {
+                frontend[field] = wsFrontend[field];
+              }
             }
+            frontend.workspaceSource = wsRel;
           }
-          frontend.workspaceSource = wsRel;
         }
       }
-      if (backend.framework && frontend.framework) break;
+
+      if (primaryBackendWs && primaryFrontendWs) break;
     }
+
+    // v0.17.3 auxiliary detection — runs whenever a primary workspace was
+    // identified, independent of v0.17.2 promotion.
+    if (primaryBackendWs) {
+      const wsAbs = path.join(projectDir, ...primaryBackendWs.split('/'));
+      const wsPkg = readPackageJson(wsAbs);
+      // D1: scalar language merge — TypeScript wins over JavaScript, never
+      // demote. 'javascript' is detectLanguage's default; if the workspace
+      // returns 'typescript', promote.
+      if (detectLanguage(wsAbs) === 'typescript') language = 'typescript';
+      // D2: architecture per-field merge.
+      // - pattern: workspace wins if it detected ANY known pattern (any
+      //   non-'unknown' value). Strict non-demotion: workspace 'unknown'
+      //   never demotes a known root pattern. Workspace known-vs-known
+      //   resolves to workspace because the workspace is the authoritative
+      //   source for the primary backend's organization (root pattern in
+      //   monorepos is often a false signal from the listing fallback when
+      //   no src/ exists).
+      // - dirs: workspace wins when it has any dirs (root's empty []
+      //   carries no info, and root in monorepos lists workspace dirs not
+      //   source dirs which is misleading).
+      // - boolean hasX flags: OR-merge (true wins, never demoted from true).
+      const wsArch = detectArchitecture(wsAbs, wsPkg);
+      if (wsArch.pattern !== 'unknown') srcStructure.pattern = wsArch.pattern;
+      if (wsArch.dirs && wsArch.dirs.length > 0) srcStructure.dirs = wsArch.dirs;
+      for (const field of [
+        'hasControllers',
+        'hasRoutes',
+        'hasModels',
+        'hasServices',
+        'hasDomain',
+        'hasMiddleware',
+        'hasFeatures',
+        'hasHandlers',
+      ]) {
+        if (wsArch[field] === true) srcStructure[field] = true;
+      }
+      // D3: backend tests per-field merge (preserves root-level E2E).
+      backendTests = mergeWorkspaceTests(rootTests, detectTests(wsAbs, wsPkg));
+    }
+
+    if (primaryFrontendWs) {
+      const wsAbs = path.join(projectDir, ...primaryFrontendWs.split('/'));
+      const wsPkg = readPackageJson(wsAbs);
+      // D4 (revised): promote auxiliary frontend fields (styling,
+      // components, state) from the primary frontend workspace,
+      // independent of whether the framework was promoted at root.
+      const wsFrontendAux = detectFrontend(wsAbs, wsPkg);
+      for (const field of ['styling', 'components', 'state']) {
+        if (wsFrontendAux[field] !== null && wsFrontendAux[field] !== undefined) {
+          frontend[field] = wsFrontendAux[field];
+        }
+      }
+      frontendTests = mergeWorkspaceTests(rootTests, detectTests(wsAbs, wsPkg));
+    }
+
+    // D5 observability: export primary workspace identifiers for diagnostics
+    // and smoke-test assertions. `workspaceSource` (v0.17.2) remains set only
+    // when promotion happened; `primaryWorkspace` (v0.17.3) is set whenever a
+    // workspace was used for aux detection.
+    if (primaryBackendWs) backend.primaryWorkspace = primaryBackendWs;
+    if (primaryFrontendWs) frontend.primaryWorkspace = primaryFrontendWs;
   }
 
   return {
     projectName: pkg.name || path.basename(projectDir),
     description: pkg.description || '',
-    language: detectLanguage(projectDir),
+    language,
     backend,
     frontend,
     isMonorepo,
     rootDirs: listRootDirs(projectDir),
-    srcStructure: detectArchitecture(projectDir, pkg),
-    tests: detectTests(projectDir, pkg),
+    srcStructure,
+    tests: rootTests,
+    backendTests,
+    frontendTests,
     existingDocs: detectExistingDocs(projectDir),
     gitBranch: detectGitBranch(projectDir),
     hasGit: fs.existsSync(path.join(projectDir, '.git')),
   };
 }
 
+/**
+ * v0.17.3: per-field merge of workspace test detection results into a
+ * new object based on root-level test detection.
+ *
+ * Preserves root-level signals the workspace doesn't see:
+ *   - e2eFramework (Playwright/Cypress typically installed once at root)
+ *   - framework (if workspace found no unit framework, keep root's default
+ *     or hoisted value)
+ *
+ * Promotes workspace signals that override root:
+ *   - framework: workspace wins if it detected a non-'none' unit framework
+ *   - hasConfig: logical OR (either source)
+ *   - testFiles / testDirs / estimatedCoverage: workspace authoritative when
+ *     it saw any test files. (Note: `countFilesRecursive` walks from
+ *     projectDir up to depth 6 traversing into packages/*, so rootTests
+ *     already aggregates workspace counts. A comparison like
+ *     `wsTests.testFiles > rootTests.testFiles` would be dead code — see
+ *     dev/v0.17.3-plan.md D3 v1.2 revision.)
+ */
+function mergeWorkspaceTests(rootTests, wsTests) {
+  const merged = { ...rootTests };
+  if (wsTests.framework !== 'none') {
+    merged.framework = wsTests.framework;
+    merged.hasConfig = wsTests.hasConfig || rootTests.hasConfig;
+  }
+  if (wsTests.testFiles > 0) {
+    merged.testFiles = wsTests.testFiles;
+    merged.testDirs = wsTests.testDirs;
+    merged.estimatedCoverage = wsTests.estimatedCoverage;
+  }
+  if (wsTests.e2eFramework) merged.e2eFramework = wsTests.e2eFramework;
+  return merged;
+}
+
 /**
  * v0.17.1: enumerate workspace paths declared in `pkg.workspaces`.
  *
@@ -112,7 +237,8 @@ function scan(projectDir) {
  *  - Single-wildcard patterns: `"packages/*"` (expand immediate subdirs)
  *
  * Does NOT support: `**` recursive patterns, `!exclude` negation, or
- * `pnpm-workspace.yaml` — all deferred to v0.17.2.
+ * `pnpm-workspace.yaml` — all deferred (see dev/ROADMAP.md "Known follow-ups"
+ * item 3). Did not land in the v0.17.2 scanner hotfix.
  *
  * Returns a deterministic, deduplicated array of POSIX-style relative
  * workspace paths. Ordering: outer = declaration order of patterns; inner

package/package.json

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

@@ -48,13 +48,130 @@ If DIVERGED, flag as FAIL with instruction to merge target branch first.
 
 Run only if `git diff origin/<target-branch>..HEAD --name-only` shows `.json` files in seed-data or fixtures directories.
 
+### Drift Checks (added v0.18.0) — ADVISORY, not blocking
+
+Eleven empirically-validated drift patterns. Failures are NOT blockers for the compliance verdict, but MUST be refreshed before requesting user authorization (the user will otherwise catch them during audit and send the PR back). Each check has a concrete shell recipe — use BSD-grep-compatible regex (no `\K`).
+
+**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)
+[ -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" \
+  | grep -E '^\|.*\[x\].*(to be |will |pending|TBD|Will be |to be created|next commit|aspirational)' \
+  && flag "P2 drift: aspirational row(s) found"
+```
+
+**14. P3 — Post-merge actions not logged** (only fires if PR is MERGED and ticket Status is Done). Items marked as post-merge operator actions (AC / DoD / Test plan unchecked with post-merge keywords) should have a Completion Log row documenting execution.
+```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 drift: post-merge '$item' not in Completion Log"
+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/')
+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)"
+```
+
+**16. P5 — Frozen ticket Status post-merge.** Scan all tickets in `docs/tickets/`; flag any with Status ≠ Done whose ticket-ID appears in `git log --all --grep`. Multi-word Status values like "Ready for Merge" must be handled (use `sed -E` 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" = "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 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.** Merge Checklist Evidence row 1 claim ("all N marked" / "AC: X/Y") diverges from actual count of `[x]` + `[ ]` in `## Acceptance Criteria`.
+```bash
+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 drift: claim '$CLAIMED' vs actual AC count $ACTUAL"
+```
+
+**18. P7 — Test count drift within ticket (final-sections only).** Only flag AC / DoD / tracker Active-Session numbers diverging from Completion Log terminal. Intermediate rows are legitimate.
+```bash
+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")
+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
+```
+
+**19. P8 — Completion Log gap vs Workflow Checklist.** Each `[x]` Step N in Workflow should have ≥1 Completion Log row mentioning "Step N". Use `while-read` on unique step numbers (not `for-in` which splits on whitespace).
+```bash
+WORKFLOW=$(awk '/^## Workflow Checklist/,/^## Completion Log/' "$TICKET")
+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"
+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)
+[ -n "$HEADER_STEP" ] && [ -n "$DETAIL_STEP" ] && [ "$HEADER_STEP" != "$DETAIL_STEP" ] \
+  && flag "P9 drift: tracker header says $HEADER_STEP, Active Feature says $DETAIL_STEP"
+```
+
+**21. P10 — Duplicate Completion Log rows.** Hash `date | action | first-80-of-notes`. Duplicates suggest copy-paste error during editing.
+```bash
+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 drift: duplicate Completion Log row: $dup"; done
+```
+
+**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:]]+$//')
+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="" ;;
+esac
+[ -n "$EXPECTED" ] && [ -n "$TRACKER_STATUS" ] && [ "$TRACKER_STATUS" != "$EXPECTED" ] \
+  && flag "P11 drift: ticket Status='$TICKET_STATUS' expects tracker='$EXPECTED' but tracker='$TRACKER_STATUS'"
+```
+
 ### Output Format
 
-Report as a compliance table:
+Report two tables — one for **structural (blocking)** compliance, one for **drift (advisory)**. Emit two verdicts plus a combined summary line.
 
 ```
 ## Merge Compliance Audit — [FEATURE-ID]
 
+### Structural (1-11) — blocking merge gate
+
 | # | Check | Status | Detail |
 |---|-------|:------:|--------|
 | 1 | Ticket Status | PASS | "Ready for Merge" |
@@ -69,7 +186,31 @@ Report as a compliance table:
 | 10 | Working Tree | PASS | Clean |
 | 11 | Data Files | PASS | N/A — no JSON seed files |
 
-**Verdict: READY FOR MERGE** (or **NEEDS FIX — N issues**)
+**STRUCTURAL: READY FOR MERGE** (or **STRUCTURAL: NEEDS FIX — N blockers**)
+
+### Drift (12-22) — advisory, refresh before user authorization
+
+| # | Pattern | Status | Detail |
+|---|---------|:------:|--------|
+| 12 | P1 PR body test count stale | PASS | matches ticket terminal |
+| 13 | P2 Aspirational Evidence rows | PASS | all rows past-tense |
+| 14 | P3 Post-merge actions logged | PASS | N/A pre-merge |
+| 15 | P4 Remote branch orphan | PASS | not checked pre-merge |
+| 16 | P5 Frozen ticket Status | PASS | 0 frozen |
+| 17 | P6 AC count off-by-N | PASS | claim matches actual |
+| 18 | P7 Intra-ticket test drift | PASS | final sections = terminal |
+| 19 | P8 Completion Log gap | PASS | every [x] step has narrative |
+| 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 |
+
+**DRIFT: CLEAN** (or **DRIFT: N advisories — refresh before merge**)
+
+### Combined verdict
+
+- Both PASS → **READY FOR MERGE** (compliance 11/11, drift clean)
+- Structural fail → **NEEDS FIX — N structural blockers** (any drift noted separately)
+- Structural pass + drift advisories → **READY FOR MERGE PENDING DRIFT CLEANUP — N advisories**
 ```
 
 ### If issues are found
@@ -81,6 +222,19 @@ Fix them directly:
 - Merge base diverged → `git merge origin/<target-branch>` and resolve conflicts
 - Data file issues → fix the data
 
+**Drift advisories (12-22) fixes:**
+- **P1 (PR body test count stale)** → edit PR body "Quality Gates" / "npm test" line to match ticket terminal count; add "(+N new tests)" delta note
+- **P2 (Aspirational Evidence)** → rewrite `[x]` rows with past-tense text + commit SHA + concrete numbers
+- **P3 (Post-merge action unlogged)** → add a Completion Log row documenting the post-merge execution with date + action + empirical result
+- **P4 (Remote branch orphan)** → `git push origin --delete <branch>` after confirming merge succeeded
+- **P5 (Frozen ticket Status)** → update each ticket's `**Status:**` field from "In Progress"/"Ready for Merge" to `Done`; this often belongs in a docs-only tracker-sync PR if the cycle is retroactive
+- **P6 (AC count off-by-N)** → recount AC items; update the Merge Checklist Evidence row 1 claim to match actual
+- **P7 (Intra-ticket test drift)** → refresh AC / DoD / tracker numbers to match the Completion Log terminal entry
+- **P8 (Completion Log gap)** → add a Completion Log row per missing Step with agent verdict + commit SHA
+- **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
+
 After fixing, re-run the audit to confirm all checks pass.
 
 ## Notes

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

@@ -48,13 +48,127 @@ If DIVERGED, flag as FAIL with instruction to merge target branch first.
 
 Run only if `git diff origin/<target-branch>..HEAD --name-only` shows `.json` files in seed-data or fixtures directories.
 
+### Drift Checks (added v0.18.0) — ADVISORY, not blocking
+
+Eleven empirically-validated drift patterns. Failures are NOT blockers for the compliance verdict, but MUST be refreshed before requesting user authorization. Use BSD-grep-compatible regex (no `\K`).
+
+**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"
+```
+
+**13. P2 — Merge Checklist Evidence aspirational.** `[x]` rows with future-tense text.
+```bash
+awk '/^## Merge Checklist Evidence/,/^## /' "$TICKET" \
+  | grep -E '^\|.*\[x\].*(to be |will |pending|TBD|Will be |to be created|next commit|aspirational)' \
+  && flag "P2: aspirational row(s)"
+```
+
+**14. P3 — Post-merge actions not logged** (post-merge only).
+```bash
+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"
+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/')
+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"
+```
+
+**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" = "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"
+```
+
+**17. P6 — AC count off-by-N.**
+```bash
+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"
+```
+
+**18. P7 — Test count drift within ticket (final-sections only).**
+```bash
+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"
+done
+```
+
+**19. P8 — Completion Log gap vs Workflow Checklist.**
+```bash
+WORKFLOW=$(awk '/^## Workflow Checklist/,/^## Completion Log/' "$TICKET")
+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"
+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)
+[ -n "$HEADER_STEP" ] && [ -n "$DETAIL_STEP" ] && [ "$HEADER_STEP" != "$DETAIL_STEP" ] \
+  && flag "P9: header $HEADER_STEP vs detail $DETAIL_STEP"
+```
+
+**21. P10 — Duplicate Completion Log rows.**
+```bash
+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
+```
+
+**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:]]+$//')
+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="" ;;
+esac
+[ -n "$EXPECTED" ] && [ -n "$TRACKER_STATUS" ] && [ "$TRACKER_STATUS" != "$EXPECTED" ] \
+  && flag "P11: Status='$TICKET_STATUS' expects tracker='$EXPECTED' but tracker='$TRACKER_STATUS'"
+```
+
 ### Output Format
 
-Report as a compliance table:
+Report two tables — one for **structural (blocking)** compliance, one for **drift (advisory)**. Emit two verdicts plus a combined summary line.
 
 ```
 ## Merge Compliance Audit — [FEATURE-ID]
 
+### Structural (1-11) — blocking merge gate
+
 | # | Check | Status | Detail |
 |---|-------|:------:|--------|
 | 1 | Ticket Status | PASS | "Ready for Merge" |
@@ -69,7 +183,31 @@ Report as a compliance table:
 | 10 | Working Tree | PASS | Clean |
 | 11 | Data Files | PASS | N/A — no JSON seed files |
 
-**Verdict: READY FOR MERGE** (or **NEEDS FIX — N issues**)
+**STRUCTURAL: READY FOR MERGE** (or **STRUCTURAL: NEEDS FIX — N blockers**)
+
+### Drift (12-22) — advisory, refresh before user authorization
+
+| # | Pattern | Status | Detail |
+|---|---------|:------:|--------|
+| 12 | P1 PR body test count stale | PASS | matches ticket terminal |
+| 13 | P2 Aspirational Evidence rows | PASS | all past-tense |
+| 14 | P3 Post-merge actions logged | PASS | N/A pre-merge |
+| 15 | P4 Remote branch orphan | PASS | not checked pre-merge |
+| 16 | P5 Frozen ticket Status | PASS | 0 frozen |
+| 17 | P6 AC count off-by-N | PASS | claim matches actual |
+| 18 | P7 Intra-ticket test drift | PASS | final = terminal |
+| 19 | P8 Completion Log gap | PASS | every [x] step has narrative |
+| 20 | P9 Tracker header stale | PASS | header = detail |
+| 21 | P10 Duplicate log rows | PASS | no duplicates |
+| 22 | P11 Tracker status mismatch | PASS | status consistent |
+
+**DRIFT: CLEAN** (or **DRIFT: N advisories — refresh before merge**)
+
+### Combined verdict
+
+- Both PASS → **READY FOR MERGE**
+- Structural fail → **NEEDS FIX — N blockers**
+- Structural pass + drift advisories → **READY FOR MERGE PENDING DRIFT CLEANUP — N advisories**
 ```
 
 ### If issues are found
@@ -81,6 +219,19 @@ Fix them directly:
 - Merge base diverged → `git merge origin/<target-branch>` and resolve conflicts
 - Data file issues → fix the data
 
+**Drift advisories (12-22) fixes:**
+- **P1** → edit PR body npm test line to match ticket terminal count
+- **P2** → rewrite `[x]` rows with past-tense + commit SHA
+- **P3** → add Completion Log row for each post-merge execution
+- **P4** → `git push origin --delete <branch>` after merge
+- **P5** → update ticket Status from "In Progress"/"Ready for Merge" to `Done`
+- **P6** → recount ACs and update Merge Checklist row 1 claim
+- **P7** → sync AC/DoD/tracker numbers to Completion Log terminal
+- **P8** → add Completion Log row per missing Step with agent verdict + commit SHA
+- **P9** → refresh `**Last Updated:**` step reference
+- **P10** → remove duplicate rows
+- **P11** → sync tracker Features row status to ticket header Status
+
 After fixing, re-run the audit to confirm all checks pass.
 
 ## Notes