@boyingliu01/xp-gate 0.35.0 → 0.35.2

package/lib/rework.js

@@ -0,0 +1,262 @@
+/**
+ * `xp-gate rework` — what the gate journal says about rework (#651).
+ *
+ * `xp-gate retro` already answers "how much did we ship". This answers the
+ * narrower and more actionable question: how often does a round of work clear
+ * the gates on the first attempt, and which rule stops it most.
+ *
+ * The reason this needs a dedicated command rather than a `retro` line: before
+ * #651 the journal contained NO failure records at all, so a naive rework rate
+ * computed from it returned 100% every time. A metric that reads "perfect" when
+ * it is actually unmeasured is worse than no metric -- it manufactures
+ * confidence. So `measurable: false` is a first-class outcome here.
+ *
+ * No runtime dependencies: this ships inside the zero-install package.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const AUDIT_DIR = '.xp-gate';
+const AUDIT_FILE = 'audit.jsonl';
+const PENDING_FILE = 'audit.pending.jsonl';
+
+/** Bucket name for failures the journal cannot attribute to a rule. */
+const UNATTRIBUTED = 'unattributed';
+
+/**
+ * Read every journal record under `repoRoot`, oldest first.
+ *
+ * Malformed lines are skipped rather than thrown on: the journal is append-only
+ * and a single truncated write must not take the whole report down.
+ *
+ * @param {string} [repoRoot]
+ * @returns {Array<object>}
+ */
+function readJournal(repoRoot = process.cwd()) {
+  const dir = path.join(repoRoot, AUDIT_DIR);
+  const entries = [];
+  for (const file of [AUDIT_FILE, PENDING_FILE]) {
+    const full = path.join(dir, file);
+    let raw;
+    try {
+      raw = fs.readFileSync(full, 'utf8');
+    } catch {
+      continue;
+    }
+    for (const line of raw.split('\n')) {
+      if (!line.trim()) continue;
+      try {
+        const parsed = JSON.parse(line);
+        if (parsed && typeof parsed === 'object') entries.push(parsed);
+      } catch {
+        /* truncated/garbled line -- skip, do not fail the report */
+      }
+    }
+  }
+  return entries;
+}
+
+/** Median of a numeric array (0 for an empty array). */
+function median(values) {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+
+/** Mean of a numeric array (0 for an empty array). */
+function mean(values) {
+  if (values.length === 0) return 0;
+  return values.reduce((a, b) => a + b, 0) / values.length;
+}
+
+/**
+ * Group a flat record list into rework rounds.
+ *
+ * The journal is a flat stream of gate executions with no round identifier, so a
+ * round is reconstructed the only way the data allows: a run of FAIL records
+ * terminated by the next PASS. That is exactly "how many attempts before this
+ * landed", which is the definition rework needs. A trailing run of failures with
+ * no resolving pass is a round that has not landed yet, and is counted as
+ * `unresolved` rather than being dropped.
+ *
+ * @param {Array<object>} entries
+ */
+function groupRounds(entries) {
+  const rounds = [];
+  let current = 0;
+  for (const entry of entries) {
+    if (entry.passed) {
+      if (current > 0) rounds.push(current);
+      current = 0;
+      continue;
+    }
+    current += 1;
+  }
+  return { resolved: rounds, unresolved: current };
+}
+
+/**
+ * Aggregate the journal into rework metrics.
+ *
+ * @param {Array<object>} entries journal records
+ * @returns {object} see AC-670-59..62
+ */
+function computeReworkStats(entries) {
+  const list = Array.isArray(entries) ? entries : [];
+  const totals = list.length;
+  const failures = list.filter((e) => e.passed === false).length;
+  const passes = totals - failures;
+
+  // ── Failures by reason ────────────────────────────────────────────────────
+  // Unlabelled failures are bucketed, never dropped: dropping them would lower
+  // the failure count and push the first-pass rate UP, which is the optimistic
+  // direction and therefore the dangerous one.
+  const byReason = new Map();
+  for (const entry of list) {
+    if (entry.passed !== false) continue;
+    const raw = typeof entry.failure_reason === 'string' ? entry.failure_reason.trim() : '';
+    const key = raw === '' ? UNATTRIBUTED : raw;
+    byReason.set(key, (byReason.get(key) || 0) + 1);
+  }
+  const topFailures = [...byReason.entries()]
+    .map(([reason, count]) => ({ reason, count }))
+    .sort((a, b) => b.count - a.count || a.reason.localeCompare(b.reason));
+
+  // ── Durations ─────────────────────────────────────────────────────────────
+  // Two independent guards, because the flag alone is not enough:
+  //
+  //  1. honour `duration_anomaly` -- the writer's own verdict;
+  //  2. reject implausible magnitudes. Measured on the real journal: 391 records
+  //     carry the flag, but 6 MORE epoch-sized values (up to 1.78e12) do not,
+  //     so trusting the flag alone left the mean at 1.3e9 ms -- the very
+  //     "average 430 million seconds" artifact this is supposed to kill.
+  //
+  // The ceiling is deliberately generous (1 hour): a real gate run that long is
+  // pathological but conceivable, while an epoch stamp is ~1.78e12 and cannot be
+  // mistaken for anything else.
+  const MAX_PLAUSIBLE_DURATION_MS = 60 * 60 * 1000;
+  const isPlausible = (e) => typeof e.duration_ms === 'number'
+    && Number.isFinite(e.duration_ms)
+    && e.duration_ms >= 0
+    && e.duration_ms <= MAX_PLAUSIBLE_DURATION_MS
+    && e.duration_anomaly !== true;
+  const sane = list.filter(isPlausible);
+  const duration = sane.length > 0
+    ? {
+      medianMs: median(sane.map((e) => e.duration_ms)),
+      meanMs: Math.round(mean(sane.map((e) => e.duration_ms))),
+      samples: sane.length,
+      // Every record that did NOT contribute -- flagged or implausible. Reporting
+      // only the flagged count would understate the exclusion and make the
+      // sample size look closer to the record count than it is.
+      excludedAnomalies: list.filter((e) => typeof e.duration_ms === 'number' && !isPlausible(e)).length,
+    }
+    : null;
+
+  // ── Rounds ────────────────────────────────────────────────────────────────
+  const rounds = groupRounds(list);
+  const reworkRounds = rounds.resolved;
+
+  // ── First-pass rate ───────────────────────────────────────────────────────
+  // Undefined without failures. A rate over an empty failure set is not 100%.
+  const measurable = failures > 0;
+  const firstPassRate = measurable ? Math.round((passes / totals) * 1000) / 10 : null;
+
+  return {
+    measurable,
+    reason: measurable ? null : 'no failure records in the journal -- first-pass rate is not measurable (pre-#651 journals only recorded passes)',
+    totalRecords: totals,
+    passes,
+    failures,
+    firstPassRate,
+    rounds: {
+      resolved: reworkRounds.length,
+      unresolved: rounds.unresolved > 0,
+      medianRework: median(reworkRounds),
+      meanRework: Math.round(mean(reworkRounds) * 100) / 100,
+      worstRework: reworkRounds.length > 0 ? Math.max(...reworkRounds) : 0,
+    },
+    topFailures,
+    duration,
+  };
+}
+
+/** Render a stats object for the terminal. */
+function formatReworkReport(stats, { limit = 10 } = {}) {
+  const lines = [];
+  lines.push('');
+  lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  lines.push('   REWORK REPORT');
+  lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  lines.push('');
+  lines.push(`  Journal records: ${stats.totalRecords}  (${stats.passes} pass, ${stats.failures} fail)`);
+
+  if (!stats.measurable) {
+    // Say WHY, and say it loudly: a silent 100% would be a lie.
+    lines.push('');
+    lines.push('  ⚠️  First-pass rate: NOT MEASURABLE');
+    lines.push(`     ${stats.reason}`);
+  } else {
+    lines.push(`  First-pass rate: ${stats.firstPassRate}%`);
+  }
+
+  if (stats.rounds.resolved > 0) {
+    lines.push('');
+    lines.push(`  Rework rounds (failures before a landing): ${stats.rounds.resolved}`);
+    lines.push(`     median ${stats.rounds.medianRework} / mean ${stats.rounds.meanRework} / worst ${stats.rounds.worstRework}`);
+    if (stats.rounds.unresolved) {
+      lines.push('     (a trailing run of failures has not landed yet)');
+    }
+  }
+
+  if (stats.topFailures.length > 0) {
+    lines.push('');
+    lines.push(`  Top ${limit} blocking reasons:`);
+    for (const { reason, count } of stats.topFailures.slice(0, limit)) {
+      lines.push(`     ${String(count).padStart(5)}  ${reason}`);
+    }
+  }
+
+  if (stats.duration) {
+    lines.push('');
+    lines.push(`  Gate duration: median ${stats.duration.medianMs} ms / mean ${stats.duration.meanMs} ms (${stats.duration.samples} samples`);
+    lines.push(`                 ${stats.duration.excludedAnomalies} anomaly record(s) excluded)`);
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * CLI entry.
+ * @param {string[]} argv args after `rework`
+ */
+function main(argv = []) {
+  const repoRootIdx = argv.indexOf('--dir');
+  const repoRoot = repoRootIdx !== -1 && argv[repoRootIdx + 1] ? argv[repoRootIdx + 1] : process.cwd();
+  const limitIdx = argv.indexOf('--top');
+  const limit = limitIdx !== -1 && argv[limitIdx + 1] ? parseInt(argv[limitIdx + 1], 10) : 10;
+
+  const stats = computeReworkStats(readJournal(repoRoot));
+  if (argv.includes('--json')) {
+    process.stdout.write(`${JSON.stringify(stats, null, 2)}\n`);
+    return 0;
+  }
+  process.stdout.write(`${formatReworkReport(stats, { limit })}\n`);
+  return 0;
+}
+
+module.exports = {
+  readJournal,
+  computeReworkStats,
+  formatReworkReport,
+  main,
+  UNATTRIBUTED,
+};
+
+if (require.main === module) {
+  process.exitCode = main(process.argv.slice(2));
+}

package/lib/test-alignment.ts

@@ -670,13 +670,32 @@ export function calculateScore(
 // Step 5: writeReport()
 // ============================================================================
 
-export function writeReport(report: TestAlignmentReportFile, outputPath: string): void {
-  const dir = path.dirname(outputPath);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
+/**
+ * Write the alignment report, recording (not throwing) a write failure.
+ *
+ * This is the LAST step of runFullAlignment — after the spec is parsed and every
+ * test file is scanned. Letting a write error escape discards all of that work
+ * and turns a reportable condition (disk full, read-only mount, permission
+ * denied) into a crashed command with no report at all. The report schema
+ * already carries an `errors` array for exactly this kind of condition.
+ *
+ * @returns true when the file was written, false when the failure was recorded.
+ */
+export function writeReport(report: TestAlignmentReportFile, outputPath: string): boolean {
+  try {
+    const dir = path.dirname(outputPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(outputPath, JSON.stringify(report, null, 2), 'utf8');
+    return true;
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    report.errors.push(`Failed to write report to ${outputPath}: ${reason}`);
+    process.stderr.write(`⚠️  Failed to write alignment report to ${outputPath}: ${reason}
+`);
+    return false;
   }
-
-  fs.writeFileSync(outputPath, JSON.stringify(report, null, 2), 'utf8');
 }
 
 // ============================================================================
@@ -756,7 +775,8 @@ export function runFullAlignment(options: AlignmentOptions): TestAlignmentReport
     errors: [],
   };
 
-  // Step 5: Write output
+  // Step 5: Write output. A failure is recorded on `report.errors` by writeReport
+  // rather than thrown — the caller still gets the analysis it just paid for.
   if (outputPath) {
     writeReport(report, outputPath);
   }

package/mock-policy/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MOCK-POLICY KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** c8a73b2a
+**Commit:** 0a400e4c
 **Branch:** main
-**Version:** 0.35.0.0
+**Version:** 0.35.2.0
 
 ## OVERVIEW
 Mock layering policy enforcement — Gate M3 of pre-push hook. Ensures integration tests use real implementations for internal dependencies, mock external dependencies, and annotate pending mocks with removal plans. Combines project scope scanning, mock decision engine, and per-file validation into a single pipeline.

package/mutation/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MUTATION KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** c8a73b2a
+**Commit:** 0a400e4c
 **Branch:** main
-**Version:** 0.35.0.0
+**Version:** 0.35.2.0
 
 ## OVERVIEW
 **Gate M** (incremental mutation testing) + **Gate M2** helpers (test-layer detection used by `src/mock-policy/`). Pre-push quality gate. TypeScript-only; uses Stryker.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/xp-gate",
-  "version": "0.35.0",
+  "version": "0.35.2",
   "description": "AI-driven development workflow: 6 quality gates + Delphi review + Sprint Flow",
   "bin": {
     "xp-gate": "bin/xp-gate.js"

package/plugins/claude-code/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "xp-gate",
-  "version": "0.35.0",
+  "version": "0.35.2",
   "displayName": "XP-Gate",
   "description": "Extreme Programming quality gates + AI workflow skills for Claude Code. Includes 12 pre-commit gates (Gate 0-11), 8 pre-push gates, Sprint Flow (6 phases), and Delphi multi-expert review (>=90% consensus).",
   "author": {

package/plugins/claude-code/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** c8a73b2a
+**Commit:** 0a400e4c
 **Branch:** main
-**Version:** 0.35.0.0
+**Version:** 0.35.2.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, exactly 3 experts with distinct executable model IDs). Supports design, requirements, and code-walkthrough modes.

package/plugins/claude-code/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** c8a73b2a
+**Commit:** 0a400e4c
 **Branch:** main
-**Version:** 0.35.0.0
+**Version:** 0.35.2.0
 
 ## OVERVIEW
 **6-phase** development pipeline (v2.0 compact redesign, Issue #290): PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE. Phase 3/6 BUILD default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE between DESIGN (2/6) and BUILD (3/6): design must pass Delphi review (≥90% consensus) before any coding.

package/plugins/claude-code/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** c8a73b2a
+**Commit:** 0a400e4c
 **Branch:** main
-**Version:** 0.35.0.0
+**Version:** 0.35.2.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/plugins/dsh/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/dsh-plugin-xp-gate",
-  "version": "0.35.0",
+  "version": "0.35.2",
   "description": "XP-Gate deterministic quality gates + AI workflow skills as a DeepSeek Harness (DSH) native plugin: gate-check / gate-principles / gate-arch tools + 12 SKILL.md skills",
   "type": "module",
   "main": "./lib/index.js",

package/plugins/dsh/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** c8a73b2a
+**Commit:** 0a400e4c
 **Branch:** main
-**Version:** 0.35.0.0
+**Version:** 0.35.2.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, exactly 3 experts with distinct executable model IDs). Supports design, requirements, and code-walkthrough modes.

package/plugins/dsh/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** c8a73b2a
+**Commit:** 0a400e4c
 **Branch:** main
-**Version:** 0.35.0.0
+**Version:** 0.35.2.0
 
 ## OVERVIEW
 **6-phase** development pipeline (v2.0 compact redesign, Issue #290): PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE. Phase 3/6 BUILD default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE between DESIGN (2/6) and BUILD (3/6): design must pass Delphi review (≥90% consensus) before any coding.

package/plugins/dsh/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** c8a73b2a
+**Commit:** 0a400e4c
 **Branch:** main
-**Version:** 0.35.0.0
+**Version:** 0.35.2.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/plugins/opencode/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/opencode-plugin",
-  "version": "0.35.0",
+  "version": "0.35.2",
   "type": "module",
   "main": "index.ts",
   "description": "XP-Gate quality gates + AI workflow skills + Sprint Flow TUI sidebar for OpenCode",

package/plugins/opencode/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** c8a73b2a
+**Commit:** 0a400e4c
 **Branch:** main
-**Version:** 0.35.0.0
+**Version:** 0.35.2.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, exactly 3 experts with distinct executable model IDs). Supports design, requirements, and code-walkthrough modes.

package/plugins/opencode/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** c8a73b2a
+**Commit:** 0a400e4c
 **Branch:** main
-**Version:** 0.35.0.0
+**Version:** 0.35.2.0
 
 ## OVERVIEW
 **6-phase** development pipeline (v2.0 compact redesign, Issue #290): PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE. Phase 3/6 BUILD default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE between DESIGN (2/6) and BUILD (3/6): design must pass Delphi review (≥90% consensus) before any coding.

package/plugins/opencode/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** c8a73b2a
+**Commit:** 0a400e4c
 **Branch:** main
-**Version:** 0.35.0.0
+**Version:** 0.35.2.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/plugins/qoder/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "xp-gate",
-  "version": "0.35.0",
+  "version": "0.35.2",
   "displayName": "XP-Gate",
   "description": "Extreme Programming quality gates + AI workflow skills for Qoder. Includes 12 pre-commit gates (Gate 0-11), 8 pre-push gates, Sprint Flow (6 phases), and Delphi multi-expert review (>=90% consensus).",
   "author": {

package/plugins/qoder/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** c8a73b2a
+**Commit:** 0a400e4c
 **Branch:** main
-**Version:** 0.35.0.0
+**Version:** 0.35.2.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, exactly 3 experts with distinct executable model IDs). Supports design, requirements, and code-walkthrough modes.

package/plugins/qoder/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** c8a73b2a
+**Commit:** 0a400e4c
 **Branch:** main
-**Version:** 0.35.0.0
+**Version:** 0.35.2.0
 
 ## OVERVIEW
 **6-phase** development pipeline (v2.0 compact redesign, Issue #290): PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE. Phase 3/6 BUILD default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE between DESIGN (2/6) and BUILD (3/6): design must pass Delphi review (≥90% consensus) before any coding.

package/plugins/qoder/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** c8a73b2a
+**Commit:** 0a400e4c
 **Branch:** main
-**Version:** 0.35.0.0
+**Version:** 0.35.2.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/principles/AGENTS.md

@@ -1,9 +1,9 @@
 # PRINCIPLES CHECKER MODULE
 
 **Generated:** 2026-10-30
-**Commit:** c8a73b2a
+**Commit:** 0a400e4c
 **Branch:** main
-**Version:** 0.35.0.0
+**Version:** 0.35.2.0
 
 ## OVERVIEW
 Clean Code & SOLID principles checker — **Gate 4** of pre-commit. 14 rules × 9 language adapters, SARIF 2.1.0 output. Houses the **Boy Scout Rule** enforcement engine (Gate 6) and warning-baseline storage.

package/scripts/__tests__/sync-package-content-isolation.test.js

@@ -0,0 +1,73 @@
+/**
+ * @test REQ-645
+ * @intent `sync-package-content.test.js` used the REAL repository root as the
+ *        spawn cwd:
+ *
+ *          const WORKTREE_PATH = path.resolve(__dirname, '..', '..', '..', '..');
+ *
+ *        Four levels up from `src/npm-package/scripts/__tests__/` is the repo
+ *        root, not a temp dir. The tests then ran the real sync script with
+ *        `cwd: WORKTREE_PATH`, so the script's writes landed in the repository
+ *        instead of a sandbox. CI's Gate 5 failed at `vitest-worktree-guard`:
+ *
+ *          Work tree polluted by the test run — 1 path(s) the run introduced:
+ *              M src/npm-package/mock-policy/gate-m3.ts
+ *
+ *        The reason this is easy to miss: the pollution is CONDITIONAL. The
+ *        script's writes are idempotent, so when the mirror already matches the
+ *        source nothing changes and the run looks clean. It only dirties the tree
+ *        when the checked-out commit happens to carry a stale mirror — which is
+ *        exactly when CI is checking out a commit that the fix was supposed to
+ *        validate. So it presents as "flaky, just re-run it", and re-running
+ *        hides the cause while leaving the latent defect in place.
+ *
+ *        The guard catching it is good, but it catches the CONSEQUENCE. This file
+ *        pins the CAUSE: a test may not write into the repository.
+ * @covers AC-670-54, AC-670-55
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..', '..');
+const TEST_FILE = path.join(
+  REPO_ROOT, 'src', 'npm-package', 'scripts', '__tests__', 'sync-package-content.test.js',
+);
+
+function readSuite() {
+  return fs.readFileSync(TEST_FILE, 'utf8');
+}
+
+describe('sync-package-content tests must not write into the repository (#645)', () => {
+  it('AC-670-54: no test uses the repo root as a spawn cwd', () => {
+    const source = readSuite();
+    // The exact offending expression. `path.resolve(__dirname, '..' x4)` from the
+    // test file IS the repo root -- there is no temp dir anywhere in that chain.
+    const offenders = source
+      .split('\n')
+      .map((line, i) => ({ line: line.trim(), n: i + 1 }))
+      .filter((x) => /WORKTREE_PATH\s*=\s*path\.resolve\(__dirname/.test(x.line));
+    expect(
+      offenders,
+      `tests still anchor on the real repo root:\n${offenders.map((o) => `  :${o.n} ${o.line}`).join('\n')}`,
+    ).toEqual([]);
+  });
+
+  it('AC-670-55: the sync tests run against a temp worktree, not the checkout', () => {
+    const source = readSuite();
+    // Whatever the variable is called, the cwd handed to a spawned sync must be
+    // one the test CREATED. mkdtemp is the only way to guarantee that: a path
+    // built from __dirname is by construction inside the repository.
+    expect(source, 'suite must create a throwaway worktree').toMatch(/mkdtemp/);
+    // Every spawnSync `cwd:` must point at that temp root, never at the checkout.
+    const cwdLines = source
+      .split('\n')
+      .filter((line) => /^\s*cwd:\s*/.test(line))
+      .map((line) => line.trim());
+    expect(cwdLines.length, 'expected at least one spawn cwd').toBeGreaterThan(0);
+    for (const line of cwdLines) {
+      expect(line, `spawn cwd escapes the sandbox: ${line}`).not.toMatch(/cwd:\s*REPO_ROOT/);
+    }
+  });
+});