@tekyzinc/gsd-t 3.27.10 → 3.29.10

package/CHANGELOG.md

@@ -2,6 +2,110 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [3.29.10] - 2026-05-27 10:09 PDT
+
+### Changed — Timestamp precision in progress.md (forward-only)
+
+Origin: GSD-T-Board (and humans reading progress.md mid-workday) need
+timestamp precision finer than a day. Many GSD-T phases run multiple
+times per day; date-only entries collapse the timeline. The Decision Log
+already used `YYYY-MM-DD HH:MM:`; this release extends that precision to
+the visible "Completed" / "Date" cells and frontmatter.
+
+- **`commands/gsd-t-complete-milestone.md`** — Completed Milestones table
+  rows now write the "Completed" cell as `YYYY-MM-DD HH:MM TZ` (e.g.
+  `2026-05-27 10:09 PDT`). Milestone archive `**Completed**:` line uses
+  the same format. The progress.md `## Date:` line is bumped on
+  milestone completion.
+- **`commands/gsd-t-init.md`** — initial `## Date:` line in seed
+  progress.md uses the new format.
+- **`templates/progress.md`** — Session Log "Date" cell + `## Date:`
+  frontmatter use the new format. Inline comments document the
+  forward-only convention (readers MUST accept both old date-only and
+  new date+time+TZ rows).
+- **`bin/gsd-t-time-format.cjs`** (new) — shared helpers:
+  - `localIsoWithOffset()` → `YYYY-MM-DDTHH:MM:SS±HH:MM` (replaces
+    `new Date().toISOString()` for `archive-meta.json::completedAt`)
+  - `localTimestampForProgress()` → `YYYY-MM-DD HH:MM TZ`
+- **`bin/orchestrator.js` + `scripts/gsd-t-design-review-server.js`** —
+  `completedAt` JSON fields now emit local-offset ISO instead of UTC `Z`,
+  via `localIsoWithOffset()`.
+- **`scripts/gsd-t-date-guard.js`** (PreToolUse hook):
+  - `stamped-iso` pattern extended to accept optional TZ abbreviation,
+    numeric offset (`±HH:MM` / `±HHMM`), or `Z` after the `HH:MM`.
+  - New `progress-table-cell` pattern validates `| YYYY-MM-DD HH:MM TZ |`
+    in table cells against ±5 min live-clock drift.
+- **`templates/CLAUDE-global.md` + `~/.claude/CLAUDE.md`** — Live Clock
+  Rule documents the new format requirements.
+
+### Forward-only — NOT a migration
+
+Pre-3.29.10 rows in existing `progress.md` files (date-only `YYYY-MM-DD`)
+**stay as-is**. No rewrite. The format change applies only to entries
+written from this version forward. Readers (status, dashboard,
+GSD-T-Board) handle both formats — the change is back-compat by design.
+
+### Falsifiable verification
+
+- 9 new unit tests in `test/m59-time-format.test.js` covering the
+  helper + both date-guard regexes + writer→guard round-trip.
+- Full suite: **2658/2658 pass** (baseline 2649 + 9 new, **zero
+  regressions**).
+- Date-guard regex tests confirm: ✅ `Date: 2024-05-27 10:15 PDT`,
+  ✅ `Date: 2024-05-27T10:15:00-07:00`, ✅ `| 2024-05-27 10:15 PDT |`
+  in table cells; ✅ pre-existing `| 2024-05-27 |` date-only cells
+  remain valid (not flagged).
+
+**Versioning**: minor bump 3.28.10 → **3.29.10** (additive capability,
+no breaking reader changes — every consumer already handled the
+opaque-string case).
+
+## [3.28.10] - 2026-05-27
+
+### Added — M58 Test Data Cleanup Gate
+
+Origin: GSD-T-Board v0.1.10 ran `gsd-t-verify`, the Playwright suite
+passed, the milestone was tagged VERIFIED — and 2442 `E2E_TEST_*` /
+`E2E_DRAG_*` ideas stayed live in the production data store. Root cause:
+GSD-T had no convention for tracking test data inserted during Verify and
+no purge step after the suite completes.
+
+- **`gsd-t test-data`** (`bin/gsd-t-test-data-ledger.cjs`) — append-only
+  JSONL ledger at `.gsd-t/test-data-ledger.jsonl` recording every test
+  insert as `{runId, kind, store, id, taggedPrefix, insertedAt}`. Public
+  API: `appendInsert`, `listInserts`, `purgeRunInserts`, `registerAdapter`.
+  CLI: `gsd-t test-data --list [--run <id>]` / `gsd-t test-data --purge
+  --run <id> [--dry-run]`. Exit 0 on success, 4 on adapter errors.
+- **Three built-in adapters** (`bin/gsd-t-test-data-adapters/`):
+  `localStorage-key-prefix` (Playwright page.evaluate-based), `file-json-array`
+  (atomic write-temp + rename), `sqlite-table-where` (parameterized DELETE
+  with tagged-prefix LIKE guard; dynamic `better-sqlite3` require). Every
+  adapter refuses to delete a record whose id doesn't start with the
+  ledger row's `taggedPrefix` — defense in depth.
+- **`withTestData()` Playwright fixture**
+  (`templates/test-helpers/test-data-fixture.ts`) — opt-in fixture exposing
+  `testData.tag(prefix)` and `testData.register({...})`. Tagging convention:
+  `{PREFIX}_{verifyRunId}_{counter}`. Reads `process.env.GSD_T_VERIFY_RUN_ID`
+  set by `gsd-t-verify`. Optional `purgePerTest` opt-in for long suites.
+- **`gsd-t-verify` Step 4.5** (new, FAIL-blocking) — runs
+  `gsd-t test-data --purge --run "$GSD_T_VERIFY_RUN_ID"` after the E2E
+  suite, before VERDICT. Any adapter error fails the gate (block-promotion
+  semantics, equivalent to a failing CI-Parity Gate). Verify report line:
+  `Test Data Cleanup: PASS — purged=N skipped=M errors=E` or `FAIL`.
+- **Contracts** — `test-data-ledger-contract.md` v1.0.0 STABLE +
+  `test-data-tagging-contract.md` v1.0.0 STABLE.
+
+**Falsifiable SC results** (all PASS):
+- SC1 ledger records 5 inserts from synthetic Playwright fixture ✅
+- SC2 `purgeRunInserts({runId})` removes those 5, reports `purged.length===5` ✅
+- SC3 verify FAILs when ledger entries can't be purged (planted adapter throw) ✅
+- SC4 successful E2E purges cleanly → verify report `purged=5 skipped=0 errors=0` ✅
+- SC5 zero regressions on `npm test` ✅
+- SC6 Red Team GRUDGING PASS ≥5 broken patches caught ✅
+- SC7 doc-ripple complete (verify.md + CLAUDE-global.md + README + help + 2 contracts) ✅
+
+**Versioning**: minor bump 3.27.10 → **3.28.10** (new feature, additive).
+
 ## [3.27.10] - 2026-05-19
 
 ### Added — M57 CI-Parity Verify Gate

package/README.md

@@ -121,6 +121,8 @@ gsd-t verify-gate --skip-track1 --json                  # Diagnostic: Track 2 on
 gsd-t verify-gate --max-concurrency 4 --json            # Override D3-map default
 gsd-t build-coverage --json                             # M57: new top-level paths must be a real CI build input (structural parse)
 gsd-t ci-parity --json                                  # M57: reproduce the project's actual CI build locally (auto docker build)
+gsd-t test-data --list [--run ID] [--json]              # M58: list test-data ledger entries
+gsd-t test-data --purge --run ID [--dry-run] [--json]   # M58: purge tagged test data after Verify (Step 4.5)
 ```
 
 `gsd-t parallel` consumes the M44 task-graph (D1) and applies three pre-spawn gates (D4 depgraph validation → D5 file-disjointness → D6 economics) followed by mode-aware headroom/split math. Extends — does not replace — the M40 orchestrator. Contract: `.gsd-t/contracts/wave-join-contract.md` v1.1.0.

package/bin/gsd-t-test-data-adapters/file-json-array.cjs

@@ -0,0 +1,56 @@
+/**
+ * Adapter: file-json-array
+ *
+ * Purges a record from a JSON file containing an array.
+ * `store` is the file path; `id` is the value of the `id` field on the matching row.
+ *
+ * Refuses to delete a record whose `id` does not start with `taggedPrefix`.
+ * Atomic rewrite (write-temp + rename).
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+
+const KIND = 'file-json-array';
+
+function purge({ store, id, taggedPrefix }) {
+  if (typeof store !== 'string' || store.length === 0) {
+    throw new Error('file-json-array: store must be a non-empty file path');
+  }
+  if (typeof id !== 'string' || id.length === 0) {
+    throw new Error('file-json-array: id must be a non-empty string');
+  }
+  if (typeof taggedPrefix === 'string' && taggedPrefix.length > 0 && !id.startsWith(taggedPrefix)) {
+    throw new Error(`file-json-array: tag prefix mismatch (id="${id}", taggedPrefix="${taggedPrefix}")`);
+  }
+
+  if (!fs.existsSync(store)) {
+    return 'absent';
+  }
+  let raw;
+  try {
+    raw = fs.readFileSync(store, 'utf8');
+  } catch (e) {
+    throw new Error(`file-json-array: read failed: ${e.message}`);
+  }
+  let arr;
+  try {
+    arr = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`file-json-array: parse failed: ${e.message}`);
+  }
+  if (!Array.isArray(arr)) {
+    throw new Error('file-json-array: store contents are not an array');
+  }
+  const before = arr.length;
+  const next = arr.filter((row) => !(row && typeof row === 'object' && row.id === id));
+  if (next.length === before) {
+    return 'absent';
+  }
+  // Atomic rewrite
+  const tmp = `${store}.tmp.${process.pid}.${Date.now()}`;
+  fs.writeFileSync(tmp, JSON.stringify(next, null, 2), 'utf8');
+  fs.renameSync(tmp, store);
+  return 'purged';
+}
+
+module.exports = { kind: KIND, purge };

package/bin/gsd-t-test-data-adapters/localstorage-key-prefix.cjs

@@ -0,0 +1,44 @@
+/**
+ * Adapter: localStorage-key-prefix
+ *
+ * Purges a key from browser localStorage. Designed to be called from
+ * Playwright host side via `page.evaluate`.
+ *
+ * Caller passes `page` via `purge({ page, store, id, taggedPrefix })`.
+ * `store` is the key prefix; `id` is the suffix. Final key = store + id.
+ *
+ * When `page` is omitted, the adapter returns 'absent' rather than throwing
+ * — this lets ledger.purgeRunInserts run cleanly when no live browser is
+ * present (e.g., after Playwright tears down). Verify-step semantics: if
+ * Playwright is gone, the data is gone too (unless persisted server-side,
+ * which other adapters handle).
+ */
+const KIND = 'localStorage-key-prefix';
+
+async function purge({ page, store, id, taggedPrefix }) {
+  if (typeof store !== 'string' || store.length === 0) {
+    throw new Error('localStorage-key-prefix: store must be a non-empty key prefix');
+  }
+  if (typeof id !== 'string' || id.length === 0) {
+    throw new Error('localStorage-key-prefix: id must be a non-empty string');
+  }
+  if (typeof taggedPrefix === 'string' && taggedPrefix.length > 0 && !id.startsWith(taggedPrefix)) {
+    throw new Error(`localStorage-key-prefix: tag prefix mismatch (id="${id}", taggedPrefix="${taggedPrefix}")`);
+  }
+
+  // Browser-side cleanup requires a live page. If absent, treat as 'absent'.
+  if (!page || typeof page.evaluate !== 'function') {
+    return 'absent';
+  }
+
+  const key = store + id;
+  const result = await page.evaluate((k) => {
+    if (typeof window === 'undefined' || !window.localStorage) return 'absent';
+    if (window.localStorage.getItem(k) === null) return 'absent';
+    window.localStorage.removeItem(k);
+    return 'purged';
+  }, key);
+  return result;
+}
+
+module.exports = { kind: KIND, purge };

package/bin/gsd-t-test-data-adapters/sqlite-table-where.cjs

@@ -0,0 +1,71 @@
+/**
+ * Adapter: sqlite-table-where
+ *
+ * Purges a row from a SQLite table by ID, with a tagged-prefix LIKE guard.
+ * `store` is `dbPath|table|idColumn` (three pipe-separated segments).
+ *
+ * `better-sqlite3` is dynamically required at adapter-use time — adapter
+ * still loads when the module isn't installed. Tests self-skip in that case.
+ */
+const fs = require('node:fs');
+
+const KIND = 'sqlite-table-where';
+
+const IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+function parseStore(store) {
+  if (typeof store !== 'string') {
+    throw new Error('sqlite-table-where: store must be "dbPath|table|idColumn"');
+  }
+  const parts = store.split('|');
+  if (parts.length !== 3) {
+    throw new Error('sqlite-table-where: store must be "dbPath|table|idColumn"');
+  }
+  const [dbPath, table, idColumn] = parts.map((s) => s.trim());
+  if (!dbPath || !table || !idColumn) {
+    throw new Error('sqlite-table-where: empty segment in store');
+  }
+  if (!IDENT_RE.test(table)) {
+    throw new Error(`sqlite-table-where: invalid table identifier "${table}"`);
+  }
+  if (!IDENT_RE.test(idColumn)) {
+    throw new Error(`sqlite-table-where: invalid idColumn identifier "${idColumn}"`);
+  }
+  return { dbPath, table, idColumn };
+}
+
+function purge({ store, id, taggedPrefix }) {
+  const { dbPath, table, idColumn } = parseStore(store);
+  if (typeof id !== 'string' || id.length === 0) {
+    throw new Error('sqlite-table-where: id must be a non-empty string');
+  }
+  if (typeof taggedPrefix !== 'string' || taggedPrefix.length === 0) {
+    throw new Error('sqlite-table-where: taggedPrefix is required for SQL safety');
+  }
+  if (!id.startsWith(taggedPrefix)) {
+    throw new Error(`sqlite-table-where: tag prefix mismatch (id="${id}", taggedPrefix="${taggedPrefix}")`);
+  }
+  if (!fs.existsSync(dbPath)) {
+    return 'absent';
+  }
+
+  let Database;
+  try {
+    Database = require('better-sqlite3');
+  } catch (e) {
+    throw new Error('sqlite-table-where: better-sqlite3 not installed; cannot purge');
+  }
+
+  const db = new Database(dbPath);
+  try {
+    // Identifiers are validated against IDENT_RE; values use bind parameters.
+    const sql = `DELETE FROM "${table}" WHERE "${idColumn}" = ? AND "${idColumn}" LIKE ?`;
+    const stmt = db.prepare(sql);
+    const info = stmt.run(id, taggedPrefix + '%');
+    return info.changes > 0 ? 'purged' : 'absent';
+  } finally {
+    db.close();
+  }
+}
+
+module.exports = { kind: KIND, purge };

package/bin/gsd-t-test-data-ledger.cjs

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+/**
+ * gsd-t-test-data-ledger — M58 D1
+ *
+ * Append-only JSONL ledger tracking test data inserted during a Verify run,
+ * plus a purge engine that removes those records from the underlying store
+ * after the suite completes.
+ *
+ * Contract: .gsd-t/contracts/test-data-ledger-contract.md
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const LEDGER_RELPATH = path.join('.gsd-t', 'test-data-ledger.jsonl');
+
+// ─── Adapter registry ─────────────────────────────────────────────────────
+
+const adapters = new Map();
+
+function registerAdapter(kind, adapter) {
+  if (typeof kind !== 'string' || kind.length === 0) {
+    throw new Error('registerAdapter: kind must be a non-empty string');
+  }
+  if (!adapter || typeof adapter.purge !== 'function') {
+    throw new Error('registerAdapter: adapter must export a purge(...) function');
+  }
+  adapters.set(kind, adapter);
+}
+
+// Built-in adapters auto-register on module load.
+registerAdapter('file-json-array', require('./gsd-t-test-data-adapters/file-json-array.cjs'));
+registerAdapter('localStorage-key-prefix', require('./gsd-t-test-data-adapters/localstorage-key-prefix.cjs'));
+registerAdapter('sqlite-table-where', require('./gsd-t-test-data-adapters/sqlite-table-where.cjs'));
+
+// ─── Public API ───────────────────────────────────────────────────────────
+
+function ledgerPathFor(projectDir) {
+  return path.join(projectDir, LEDGER_RELPATH);
+}
+
+function appendInsert({ projectDir, runId, kind, store, id, taggedPrefix, insertedAt }) {
+  if (typeof projectDir !== 'string' || projectDir.length === 0) {
+    throw new Error('appendInsert: projectDir is required');
+  }
+  if (typeof runId !== 'string' || runId.length === 0) {
+    throw new Error('appendInsert: runId is required');
+  }
+  if (typeof kind !== 'string' || kind.length === 0) {
+    throw new Error('appendInsert: kind is required');
+  }
+  if (typeof store !== 'string' || store.length === 0) {
+    throw new Error('appendInsert: store is required');
+  }
+  if (typeof id !== 'string' || id.length === 0) {
+    throw new Error('appendInsert: id is required');
+  }
+  const finalTaggedPrefix = typeof taggedPrefix === 'string' && taggedPrefix.length > 0
+    ? taggedPrefix
+    : 'E2E_';
+  if (!id.startsWith(finalTaggedPrefix)) {
+    throw new Error(`appendInsert: id "${id}" does not start with taggedPrefix "${finalTaggedPrefix}"`);
+  }
+  const finalInsertedAt = typeof insertedAt === 'string' && insertedAt.length > 0
+    ? insertedAt
+    : new Date().toISOString();
+
+  const row = {
+    runId,
+    kind,
+    store,
+    id,
+    taggedPrefix: finalTaggedPrefix,
+    insertedAt: finalInsertedAt,
+  };
+
+  const ledgerPath = ledgerPathFor(projectDir);
+  fs.mkdirSync(path.dirname(ledgerPath), { recursive: true });
+  fs.appendFileSync(ledgerPath, JSON.stringify(row) + '\n', 'utf8');
+  return { ok: true, ledgerPath };
+}
+
+function listInserts({ projectDir, runId }) {
+  if (typeof projectDir !== 'string' || projectDir.length === 0) {
+    throw new Error('listInserts: projectDir is required');
+  }
+  const ledgerPath = ledgerPathFor(projectDir);
+  if (!fs.existsSync(ledgerPath)) return [];
+  const raw = fs.readFileSync(ledgerPath, 'utf8');
+  const rows = [];
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (runId && parsed.runId !== runId) continue;
+      rows.push(parsed);
+    } catch {
+      // skip malformed lines (audit-trail is permissive)
+    }
+  }
+  return rows;
+}
+
+async function purgeRunInserts({ projectDir, runId, dryRun }) {
+  if (typeof projectDir !== 'string' || projectDir.length === 0) {
+    throw new Error('purgeRunInserts: projectDir is required');
+  }
+  if (typeof runId !== 'string' || runId.length === 0) {
+    throw new Error('purgeRunInserts: runId is required');
+  }
+  const rows = listInserts({ projectDir, runId });
+  const purged = [];
+  const skipped = [];
+  const errors = [];
+
+  for (const row of rows) {
+    if (dryRun === true) {
+      purged.push(row); // dry-run treats every targeted row as 'would be purged'
+      continue;
+    }
+    const adapter = adapters.get(row.kind);
+    if (!adapter) {
+      errors.push({ record: row, message: `no adapter registered for kind "${row.kind}"` });
+      continue;
+    }
+    try {
+      const result = await adapter.purge({
+        store: row.store,
+        id: row.id,
+        taggedPrefix: row.taggedPrefix,
+      });
+      if (result === 'purged') {
+        purged.push(row);
+      } else if (result === 'absent') {
+        skipped.push(row);
+      } else {
+        errors.push({ record: row, message: `adapter returned unexpected value "${String(result)}"` });
+      }
+    } catch (e) {
+      errors.push({ record: row, message: e && e.message ? e.message : String(e) });
+    }
+  }
+
+  return { purged, skipped, errors };
+}
+
+// ─── CLI ──────────────────────────────────────────────────────────────────
+
+const COLOR = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  dim: '\x1b[2m',
+};
+
+function parseArgs(argv) {
+  const opts = {
+    mode: null, // 'list' | 'purge'
+    runId: null,
+    dryRun: false,
+    json: false,
+    projectDir: process.cwd(),
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--list') opts.mode = 'list';
+    else if (a === '--purge') opts.mode = 'purge';
+    else if (a === '--dry-run') opts.dryRun = true;
+    else if (a === '--json') opts.json = true;
+    else if (a === '--run' || a === '--run-id') {
+      opts.runId = argv[++i] || null;
+    } else if (a === '--project') {
+      opts.projectDir = argv[++i] || process.cwd();
+    } else if (a === '-h' || a === '--help') {
+      opts.mode = 'help';
+    }
+  }
+  return opts;
+}
+
+function printHelp() {
+  process.stdout.write(`Usage: gsd-t test-data --list [--run <id>] [--json]
+       gsd-t test-data --purge --run <id> [--dry-run] [--json]
+
+Options:
+  --list           List ledger entries (optionally filtered by --run)
+  --purge          Purge ledger entries for a given --run
+  --run <id>       Verify run id (e.g., verify-m58-20260527T091800Z)
+  --dry-run        With --purge: report what would be purged without calling adapters
+  --json           Emit JSON envelope instead of pretty output
+  --project <dir>  Project directory (defaults to CWD)
+  -h, --help       Show this help
+
+Exit codes:
+  0   success
+  4   one or more adapter errors (purge mode)
+  64  CLI argument error
+`);
+}
+
+async function main(argv) {
+  const opts = parseArgs(argv);
+  if (opts.mode === 'help' || !opts.mode) {
+    printHelp();
+    return opts.mode === 'help' ? 0 : 64;
+  }
+
+  if (opts.mode === 'list') {
+    const rows = listInserts({ projectDir: opts.projectDir, runId: opts.runId });
+    if (opts.json) {
+      process.stdout.write(JSON.stringify({ ok: true, rows }) + '\n');
+    } else {
+      if (rows.length === 0) {
+        process.stdout.write(`${COLOR.dim}No ledger entries${opts.runId ? ` for run "${opts.runId}"` : ''}.${COLOR.reset}\n`);
+      } else {
+        process.stdout.write(`${COLOR.bold}Test data ledger${opts.runId ? ` — run ${opts.runId}` : ''}${COLOR.reset}\n`);
+        for (const r of rows) {
+          process.stdout.write(`  ${COLOR.blue}${r.kind}${COLOR.reset} ${r.id} ${COLOR.dim}(${r.store})${COLOR.reset}\n`);
+        }
+        process.stdout.write(`\n${COLOR.bold}Total:${COLOR.reset} ${rows.length}\n`);
+      }
+    }
+    return 0;
+  }
+
+  if (opts.mode === 'purge') {
+    if (!opts.runId) {
+      process.stderr.write('gsd-t test-data --purge requires --run <id>\n');
+      return 64;
+    }
+    const envelope = await purgeRunInserts({
+      projectDir: opts.projectDir,
+      runId: opts.runId,
+      dryRun: opts.dryRun,
+    });
+    if (opts.json) {
+      process.stdout.write(JSON.stringify({
+        ok: envelope.errors.length === 0,
+        runId: opts.runId,
+        dryRun: !!opts.dryRun,
+        purged: envelope.purged.length,
+        skipped: envelope.skipped.length,
+        errors: envelope.errors,
+      }) + '\n');
+    } else {
+      const tag = opts.dryRun ? '[DRY RUN] ' : '';
+      process.stdout.write(`${COLOR.bold}${tag}Purge run ${opts.runId}${COLOR.reset}\n`);
+      process.stdout.write(`  ${COLOR.green}purged:${COLOR.reset}  ${envelope.purged.length}\n`);
+      process.stdout.write(`  ${COLOR.yellow}skipped:${COLOR.reset} ${envelope.skipped.length}\n`);
+      process.stdout.write(`  ${COLOR.red}errors:${COLOR.reset}  ${envelope.errors.length}\n`);
+      if (envelope.errors.length > 0) {
+        process.stdout.write(`\n${COLOR.red}Errors:${COLOR.reset}\n`);
+        for (const e of envelope.errors.slice(0, 5)) {
+          process.stdout.write(`  - ${e.record.id} (${e.record.kind}): ${e.message}\n`);
+        }
+        if (envelope.errors.length > 5) {
+          process.stdout.write(`  … and ${envelope.errors.length - 5} more\n`);
+        }
+      }
+    }
+    return envelope.errors.length === 0 ? 0 : 4;
+  }
+
+  printHelp();
+  return 64;
+}
+
+module.exports = {
+  appendInsert,
+  listInserts,
+  purgeRunInserts,
+  registerAdapter,
+  main,
+  ledgerPathFor,
+  LEDGER_RELPATH,
+};
+
+if (require.main === module) {
+  main(process.argv.slice(2)).then(
+    (code) => process.exit(code),
+    (err) => {
+      process.stderr.write(`gsd-t test-data: ${err && err.message ? err.message : String(err)}\n`);
+      process.exit(1);
+    }
+  );
+}

package/bin/gsd-t-time-format.cjs

@@ -0,0 +1,94 @@
+/**
+ * gsd-t-time-format — M59
+ *
+ * Shared helpers for the v3.29.10 timestamp-precision format.
+ *
+ * Exports:
+ *   localIsoWithOffset([date])  → "YYYY-MM-DDTHH:MM:SS±HH:MM" (local offset)
+ *   localTimestampForProgress([date]) → "YYYY-MM-DD HH:MM TZ"  (human-readable, for progress.md fields)
+ *
+ * Both helpers source the current time from `new Date()` by default. The
+ * `[GSD-T NOW]` UserPromptSubmit signal feeds the system clock, so these
+ * are correct in any GSD-T spawn.
+ */
+
+const TZ_ABBR_FALLBACK = 'UTC';
+
+function pad2(n) {
+  const s = String(n);
+  return s.length < 2 ? `0${s}` : s;
+}
+
+/**
+ * ISO 8601 timestamp with local timezone offset (NOT UTC `Z`).
+ *
+ * Example: `2026-05-27T10:15:30-07:00` (PDT, summer)
+ *          `2026-12-15T10:15:30-08:00` (PST, winter)
+ */
+function localIsoWithOffset(date) {
+  const d = date instanceof Date ? date : new Date();
+  const yyyy = d.getFullYear();
+  const mm = pad2(d.getMonth() + 1);
+  const dd = pad2(d.getDate());
+  const hh = pad2(d.getHours());
+  const mi = pad2(d.getMinutes());
+  const ss = pad2(d.getSeconds());
+
+  const offsetMinTotal = -d.getTimezoneOffset(); // east of UTC is positive
+  const sign = offsetMinTotal >= 0 ? '+' : '-';
+  const offsetAbs = Math.abs(offsetMinTotal);
+  const offH = pad2(Math.floor(offsetAbs / 60));
+  const offM = pad2(offsetAbs % 60);
+
+  return `${yyyy}-${mm}-${dd}T${hh}:${mi}:${ss}${sign}${offH}:${offM}`;
+}
+
+/**
+ * Resolve a short human-readable TZ abbreviation (e.g., "PDT", "PST").
+ * Uses Intl.DateTimeFormat short timezone where available; falls back to
+ * the numeric offset string if the platform doesn't provide one.
+ */
+function shortTzAbbr(date) {
+  const d = date instanceof Date ? date : new Date();
+  try {
+    const parts = new Intl.DateTimeFormat('en-US', {
+      timeZoneName: 'short',
+    }).formatToParts(d);
+    const tzPart = parts.find((p) => p.type === 'timeZoneName');
+    if (tzPart && tzPart.value) return tzPart.value;
+  } catch {
+    /* fall through */
+  }
+  // Fallback — numeric offset like "GMT-07:00"
+  const offsetMin = -d.getTimezoneOffset();
+  const sign = offsetMin >= 0 ? '+' : '-';
+  const abs = Math.abs(offsetMin);
+  return `GMT${sign}${pad2(Math.floor(abs / 60))}:${pad2(abs % 60)}`;
+}
+
+/**
+ * Human-readable timestamp for progress.md visible fields:
+ *   "YYYY-MM-DD HH:MM TZ"
+ *
+ * Example: `2026-05-27 10:15 PDT`
+ *
+ * This is the M59 format for:
+ *   - `## Date:` line in progress.md frontmatter
+ *   - "Completed" cell in the Completed Milestones table
+ *   - "Date" cell in the Session Log table
+ */
+function localTimestampForProgress(date) {
+  const d = date instanceof Date ? date : new Date();
+  const yyyy = d.getFullYear();
+  const mm = pad2(d.getMonth() + 1);
+  const dd = pad2(d.getDate());
+  const hh = pad2(d.getHours());
+  const mi = pad2(d.getMinutes());
+  return `${yyyy}-${mm}-${dd} ${hh}:${mi} ${shortTzAbbr(d) || TZ_ABBR_FALLBACK}`;
+}
+
+module.exports = {
+  localIsoWithOffset,
+  localTimestampForProgress,
+  shortTzAbbr,
+};

package/bin/gsd-t.js

@@ -4580,6 +4580,15 @@ if (require.main === module) {
       });
       process.exit(res.status == null ? 1 : res.status);
     }
+    case "test-data": {
+      // M58 D1 — `gsd-t test-data --list|--purge` thin dispatcher.
+      const { spawnSync } = require("child_process");
+      const js = path.join(__dirname, "gsd-t-test-data-ledger.cjs");
+      const res = spawnSync(process.execPath, [js, ...args.slice(1)], {
+        stdio: "inherit",
+      });
+      process.exit(res.status == null ? 1 : res.status);
+    }
     case "stream-feed": {
       doStreamFeed(args.slice(1));
       break;

package/bin/orchestrator.js

@@ -26,6 +26,7 @@
 const fs = require("fs");
 const path = require("path");
 const { execFileSync, execFile, spawn: cpSpawn } = require("child_process");
+const { localIsoWithOffset } = require(path.join(__dirname, "gsd-t-time-format.cjs"));
 
 // ─── ANSI Colors ────────────────────────────────────────────────────────────
 
@@ -1275,11 +1276,13 @@ ${BOLD}Phases:${RESET} ${this.wf.phases.join(" → ")}
       }
 
       // 6f. Record phase completion
+      // M59 (v3.29.10): completedAt is local-offset ISO (`YYYY-MM-DDTHH:MM:SS±HH:MM`)
+      // rather than UTC `Z` — matches the human-readable progress.md fields.
       state.phaseResults[phase] = {
         completed: true,
         builtPaths,
         reviewCycles: reviewCycle + 1,
-        completedAt: new Date().toISOString(),
+        completedAt: localIsoWithOffset(),
       };
       state.completedPhases.push(phase);
       this.clearQueue(projectDir);

package/commands/gsd-t-complete-milestone.md

@@ -336,7 +336,7 @@ Create `summary.md`:
 ```markdown
 # Milestone Complete: {name}
 
-**Completed**: {date}
+**Completed**: {YYYY-MM-DD HH:MM TZ}
 **Duration**: {start date} → {end date}
 **Status**: {VERIFIED | FORCED}
 
@@ -419,14 +419,18 @@ Steps to apply the trim:
 # GSD-T Progress
 
 ## Version: {new version}
+## Status: ACTIVE
+## Date: {YYYY-MM-DD HH:MM TZ — source from live `[GSD-T NOW]`}
 ## Current Milestone
 None — ready for next milestone
 
 ## Completed Milestones
 | Milestone | Version | Completed | Tag |
 |-----------|---------|-----------|-----|
-| {name} | {version} | {date} | v{version} |
-| {previous} | {version} | {date} | v{version} |
+| {name} | {version} | {YYYY-MM-DD HH:MM TZ} | v{version} |
+| {previous} | {version} | {YYYY-MM-DD HH:MM TZ — keep existing rows as-is; forward-only format} | v{version} |
+<!-- M59 (v3.29.10): "Completed" cells are written `YYYY-MM-DD HH:MM TZ` from this version forward. Pre-3.29.10 rows that read `YYYY-MM-DD` stay as-is (forward-only — never rewrite). Readers MUST accept both. -->
+
 
 ## Decision Log
 

package/commands/gsd-t-help.md

@@ -469,6 +469,13 @@ Use these when user asks for help on a specific command:
 - **Use when**: Final pre-merge gate. Catches the TimeTracking v1.10.12 class (noImplicitAny regressions passed a warm-cache local tsc but failed CI's cold build).
 - **CLI**: `gsd-t ci-parity [--project-dir PATH] [--timeout-ms MS] [--json]`. Exit 0/4/2.
 
+### test-data (M58)
+- **Summary**: Append-only test-data ledger + purge engine. Tests register inserts via the `withTestData()` Playwright fixture; `gsd-t-verify` Step 4.5 purges them by adapter before VERDICT. Three built-in adapters: `localStorage-key-prefix`, `file-json-array`, `sqlite-table-where`. Each adapter refuses to delete records whose id does not start with the ledger row's `taggedPrefix` (defense in depth).
+- **Auto-invoked**: Yes — by `gsd-t-verify` Step 4.5 (FAIL-blocking, never warning-only)
+- **Files**: `bin/gsd-t-test-data-ledger.cjs`, `bin/gsd-t-test-data-adapters/*.cjs`, `templates/test-helpers/test-data-fixture.ts`
+- **Use when**: Test data hygiene. Catches the GSD-T-Board class (2442 orphaned `E2E_TEST_*` / `E2E_DRAG_*` ideas left in the production data store after a passing Verify run).
+- **CLI**: `gsd-t test-data --list [--run <id>] [--json]` / `gsd-t test-data --purge --run <id> [--dry-run] [--json] [--project <dir>]`. Exit 0 on success, 4 on adapter errors, 64 on usage error.
+
 ## Unknown Command
 
 If user asks for help on unrecognized command:

package/commands/gsd-t-init.md

@@ -180,7 +180,7 @@ Create `.gsd-t/progress.md`:
 ## Project: {name from CLAUDE.md or $ARGUMENTS}
 ## Version: {detected version, or 0.1.00}
 ## Status: INITIALIZED
-## Date: {today}
+## Date: {today YYYY-MM-DD HH:MM TZ — source from the live `[GSD-T NOW]` signal; never date-only}
 
 ## Milestones
 | # | Milestone | Status | Domains |

package/commands/gsd-t-verify.md

@@ -303,6 +303,49 @@ const { captureSpawn } = require('./bin/gsd-t-token-capture.cjs');
 `captureSpawn` parses `result.usage` and writes the row to `.gsd-t/token-log.md` under the canonical header. Tokens column renders as `in=N out=N cr=N cc=N $X.XX` or `—`, never `N/A`. Collect all reports, synthesize, create remediation plan.
 ```
 
+<!-- M58: Test Data Cleanup Gate -->
+## Step 4.5: Test Data Cleanup Gate (MANDATORY — FAIL-blocking, never warning-only)
+
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-verify --step 4 --step-label ".5: Test Data Cleanup Gate" 2>/dev/null || true
+```
+
+Origin: GSD-T-Board v0.1.10 Verify ran the Playwright suite, the suite
+passed, the milestone was tagged VERIFIED — and 2442 `E2E_TEST_*` /
+`E2E_DRAG_*` ideas stayed live in the production data store. The gate
+exists to catch that class: any test data registered during Verify via the
+`withTestData()` Playwright fixture (or by direct calls to
+`appendInsert(...)`) MUST be purged before VERDICT.
+
+```bash
+# Verify-run id — set at Step 1; if not, derive from milestone + UTC.
+: "${GSD_T_VERIFY_RUN_ID:=verify-${MILESTONE:-current}-$(date -u +%Y%m%dT%H%M%SZ)}"
+export GSD_T_VERIFY_RUN_ID
+
+# Purge anything the fixture (or appendInsert) registered during this run.
+gsd-t test-data --purge --run "$GSD_T_VERIFY_RUN_ID" --json > /tmp/gsd-t-test-data-purge.json
+TD_EXIT=$?
+```
+
+- `test-data --purge` exit **0** (`errors:[]`) → record
+  `Test data: purged=<N> skipped=<M>` in the verify report. Gate passes.
+- exit **4** (`errors.length > 0`) → verify FAIL. Append the first 5
+  `errors[].message` values to the verify report and surface the count of
+  remaining records. The fix is either (a) repair the adapter / store
+  configuration so purge succeeds, or (b) update the test to use the
+  fixture so the ledger has accurate entries.
+
+The gate runs AFTER the E2E suite (Step 4) so any tests that inserted
+test data via `withTestData(...)` have already populated the ledger.
+It runs BEFORE Step 5 (verify report) so the purge counts can land in the
+report. Tests that bypass the fixture and leave un-tagged data will not
+be caught here — they're caught at the project's next dataset audit.
+
+Pure-deterministic CLI check (no LLM). Contract:
+`.gsd-t/contracts/test-data-ledger-contract.md` v1.0.0 STABLE.
+Tagging: `.gsd-t/contracts/test-data-tagging-contract.md` v1.0.0 STABLE.
+<!-- /M58: Test Data Cleanup Gate -->
+
 ## Step 5: Compile Verification Report
 
 ```bash
@@ -322,6 +365,7 @@ Create or update `.gsd-t/verify-report.md`:
 - Code Quality: {PASS/WARN/FAIL} — {N} issues found
 - Unit Tests: {PASS/WARN/FAIL} — {N}/{total} passing
 - E2E Tests: {PASS/WARN/FAIL} — {N}/{total} specs passing
+- Test Data Cleanup: {PASS/FAIL} — purged={N} skipped={M} errors={E}
 - Security: {PASS/WARN/FAIL} — {N} findings
 - Integration: {PASS/WARN/FAIL}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "3.27.10",
+  "version": "3.29.10",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 54 slash commands with headless-by-default workflow spawning, unattended supervisor relay with event stream, graph-powered code analysis, real-time agent dashboard, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/scripts/gsd-t-date-guard.js

@@ -89,18 +89,25 @@ const FRESH_STAMP_PATTERNS = [
 ];
 
 // Generic ISO date — only validated when surrounded by strong "freshly stamping now"
-// context (e.g., right after labels like "Date:", "Today:", "Stamped:", etc.).
-// Two arms: (a) date+time (validated against full ±DRIFT_MINUTES window),
+// context (e.g., right after labels like the canonical frontmatter / metadata
+// keys captured below).
+// Two arms: (a) date+time (validated against full +/-DRIFT_MINUTES window),
 //          (b) date-only (validated as same-calendar-day-as-now, time-of-day ignored).
+//
+// M59 (v3.29.10): time portion may carry an optional trailing TZ token —
+// either a short abbreviation (PDT/PST/UTC/...), a numeric offset
+// (+/-HH:MM or +/-HHMM), or Z. The TZ is matched but not used for drift
+// math — drift is computed against the local clock, which already has the
+// live offset.
 const STAMPED_ISO_PATTERN = {
   name: "stamped-iso",
-  regex: /\b(?:Date|Today|Stamped|Updated|Created|Generated|Now|Timestamp|At)\s*[:=]\s*(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2}))?/gi,
+  regex: /\b(?:Date|Today|Stamped|Updated|Created|Generated|Now|Timestamp|At)\s*[:=]\s*(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::\d{2})?(?:\s+[A-Z]{2,5}|[+\-]\d{2}:?\d{2}|Z)?)?/gi,
   extract: (m) => {
     const hasTime = m[4] !== undefined;
     return {
       stamped: new Date(
         Number(m[1]), Number(m[2]) - 1, Number(m[3]),
-        hasTime ? Number(m[4]) : 12, // Date-only → noon, neutralizes timezone-edge false positives
+        hasTime ? Number(m[4]) : 12, // Date-only -> noon, neutralizes timezone-edge false positives
         hasTime ? Number(m[5]) : 0,
         0
       ),
@@ -109,6 +116,20 @@ const STAMPED_ISO_PATTERN = {
   },
 };
 
+// M59 (v3.29.10): table cells in progress.md's "Completed Milestones" and
+// "Session Log" tables now carry `YYYY-MM-DD HH:MM TZ`. We validate them
+// against +/-DRIFT_MINUTES (treat as a fresh stamp). Date-only cells in
+// pre-3.29.10 rows remain valid and are NOT flagged - those are historical
+// (forward-only rule), so this regex requires the HH:MM portion to fire.
+const PROGRESS_TABLE_CELL_PATTERN = {
+  name: "progress-table-cell",
+  regex: /\|\s*(\d{4})-(\d{2})-(\d{2})\s+(\d{2}):(\d{2})(?:\s+[A-Z]{2,5})?\s*\|/g,
+  extract: (m) => new Date(
+    Number(m[1]), Number(m[2]) - 1, Number(m[3]),
+    Number(m[4]), Number(m[5]), 0
+  ),
+};
+
 function isAllowlisted(filePath) {
   if (!filePath) return false;
   return ALLOWLIST_PATTERNS.some((re) => re.test(filePath));
@@ -119,7 +140,7 @@ function findStaleTimestamps(content, now, oldContent) {
   const findings = [];
   const oldText = typeof oldContent === "string" ? oldContent : "";
 
-  const allPatterns = [...FRESH_STAMP_PATTERNS, STAMPED_ISO_PATTERN];
+  const allPatterns = [...FRESH_STAMP_PATTERNS, STAMPED_ISO_PATTERN, PROGRESS_TABLE_CELL_PATTERN];
 
   for (const pattern of allPatterns) {
     const regex = new RegExp(pattern.regex.source, pattern.regex.flags);

package/scripts/gsd-t-design-review-server.js

@@ -13,6 +13,7 @@ const http = require("http");
 const { spawn } = require("child_process");
 const fs = require("fs");
 const path = require("path");
+const { localIsoWithOffset } = require(path.join(__dirname, "..", "bin", "gsd-t-time-format.cjs"));
 const url = require("url");
 
 // ── CLI args ──────────────────────────────────────────────────────────
@@ -422,7 +423,8 @@ function writeFeedback(items) {
   fs.writeFileSync(
     path.join(REVIEW_DIR, "review-complete.json"),
     JSON.stringify({
-      completedAt: new Date().toISOString(),
+      // M59 (v3.29.10): local-offset ISO (`YYYY-MM-DDTHH:MM:SS±HH:MM`) rather than UTC `Z`.
+      completedAt: localIsoWithOffset(),
       phase: readStatus().phase,
       items: items.map(i => ({ id: i.id, verdict: i.verdict })),
     }, null, 2)

package/templates/CLAUDE-global.md

@@ -167,11 +167,13 @@ Whenever you write a date or timestamp to any file — decision log entries in `
 2. If absent, run `node -e "console.log(new Date().toISOString())"` via Bash before writing.
 
 **Enforcement**: a PreToolUse hook (`scripts/gsd-t-date-guard.js`) blocks Write/Edit calls whose content contains timestamps drifting more than ±5 minutes from the live system clock. The guard:
-- Validates decision-log entries (`- YYYY-MM-DD HH:MM:`), filename timestamps (`continue-here-YYYY-MM-DDTHHMMSS`), banners (`Day: Mon DD, YYYY HH:MM`), and labeled stamps (`Date:`, `Updated:`, `Created:`, etc.).
+- Validates decision-log entries (`- YYYY-MM-DD HH:MM:`), filename timestamps (`continue-here-YYYY-MM-DDTHHMMSS`), banners (`Day: Mon DD, YYYY HH:MM`), labeled stamps (`Date:`, `Updated:`, `Created:`, etc., with optional TZ abbr / numeric offset / `Z`), and **progress.md table cells carrying `YYYY-MM-DD HH:MM TZ`** (M59, v3.29.10+ — Completed Milestones + Session Log).
 - For Edit, ignores timestamps that appear in BOTH `old_string` and `new_string` (pre-existing context, not new writes).
 - Allowlists machine-written paths (`.gsd-t/events/`, `.gsd-t/transcripts/`, `.gsd-t/metrics/`, `.git/`, `node_modules/`, archives, log files).
 - Fails open on internal error — broken tool calls would be worse than drift.
 
+**Timestamp precision in progress.md (M59, v3.29.10+)**: the `## Date:` frontmatter line, the "Completed" cell of the Completed Milestones table, and the "Date" cell of the Session Log table MUST be written as `YYYY-MM-DD HH:MM TZ` (e.g. `2026-05-27 10:15 PDT`). This is **forward-only** — pre-3.29.10 rows that read date-only (`YYYY-MM-DD`) stay as-is. Readers (status, dashboard, GSD-T-Board) MUST accept both. `archive-meta.json::completedAt` is local-offset ISO (`YYYY-MM-DDTHH:MM:SS±HH:MM`) — use `localIsoWithOffset()` from `bin/gsd-t-time-format.cjs`, not `new Date().toISOString()` (which produces UTC `Z`).
+
 If the guard blocks your write, do NOT bypass it. Re-read `[GSD-T NOW]`, regenerate the timestamp, retry.
 
 ## Conversation vs. Work
@@ -260,6 +262,34 @@ Every Playwright assertion must verify one of:
 
 **If a test would pass on an empty HTML page with the correct element IDs and no JavaScript, it is not a functional test.** Rewrite it.
 
+### Test Data Cleanup (MANDATORY — M58)
+
+**Tests that insert data into a project's stores MUST register those inserts with the GSD-T test-data ledger so Verify can purge them.** Tests that leave orphaned `E2E_*` records in production data violate this rule.
+
+The supported mechanism is the `withTestData()` Playwright fixture:
+
+```ts
+import { test as base } from '@playwright/test';
+import { withTestData } from '@tekyzinc/gsd-t/templates/test-helpers/test-data-fixture';
+
+export const test = base.extend(withTestData());
+
+test('drag idea creates new column', async ({ page, testData }) => {
+  const id = testData.tag('E2E_DRAG');  // → "E2E_DRAG_{runId}_{counter}"
+  await testData.register({
+    kind: 'localStorage-key-prefix',
+    store: 'gsd-t-board:idea:',
+    id,
+    taggedPrefix: 'E2E_',
+  });
+  // … UI interactions that insert a row keyed by `${store}${id}` …
+});
+```
+
+Three built-in adapters: `localStorage-key-prefix`, `file-json-array`, `sqlite-table-where`. Extend via `registerAdapter(kind, adapter)`. Each adapter refuses to delete a record whose id does not start with the ledger row's `taggedPrefix` (defense in depth — see `.gsd-t/contracts/test-data-tagging-contract.md`).
+
+After the E2E suite, `gsd-t-verify` Step 4.5 runs `gsd-t test-data --purge --run "$GSD_T_VERIFY_RUN_ID"`. If any adapter throws or refuses, verify FAILs the gate (block-promotion semantics — equivalent to a failing CI-Parity Gate). Contract: `.gsd-t/contracts/test-data-ledger-contract.md` v1.0.0 STABLE.
+
 ## QA Agent (Mandatory)
 
 Every code-producing/validating phase MUST run QA. QA writes ZERO feature code — it generates, runs, and gap-reports tests. Failure (or any shallow E2E test) blocks phase completion.

package/templates/progress.md

@@ -3,7 +3,7 @@
 ## Project: {Project Name}
 ## Version: 0.1.0
 ## Status: READY
-## Date: {Date}
+## Date: {YYYY-MM-DD HH:MM TZ}
 
 ## Current Milestone
 None — ready for next milestone
@@ -11,6 +11,8 @@ None — ready for next milestone
 ## Completed Milestones
 | Milestone | Version | Completed | Tag |
 |-----------|---------|-----------|-----|
+<!-- M59: "Completed" cell format is `YYYY-MM-DD HH:MM TZ` for entries written ≥ v3.29.10; older rows may be `YYYY-MM-DD`. Readers MUST accept both. -->
+
 
 ## Domains
 | Domain | Status | Tasks | Completed |
@@ -37,4 +39,6 @@ None — ready for next milestone
 ## Session Log
 | Date | Session | What was accomplished |
 |------|---------|----------------------|
-| {Date} | 1 | Project initialized |
+| {YYYY-MM-DD HH:MM TZ} | 1 | Project initialized |
+<!-- M59: "Date" cell format is `YYYY-MM-DD HH:MM TZ` for entries written ≥ v3.29.10; older rows may be `YYYY-MM-DD`. Readers MUST accept both. -->
+

package/templates/test-helpers/README.md

@@ -0,0 +1,98 @@
+# GSD-T Test Helpers
+
+Helpers that test suites can import to keep test data out of production stores.
+
+## `test-data-fixture.ts`
+
+Playwright fixture (`withTestData`) that auto-registers test inserts with the
+GSD-T test-data ledger. After Playwright finishes, the verify-final-step
+(`gsd-t-verify` Step 4.5) sweeps the ledger and purges every registered row.
+
+### Install
+
+```ts
+// playwright.config.ts (no changes — fixture is plugged in per-spec or via a base test)
+
+// test/_base.ts
+import { test as base } from '@playwright/test';
+import { withTestData } from '@tekyzinc/gsd-t/templates/test-helpers/test-data-fixture';
+
+export const test = base.extend(withTestData());
+export { expect } from '@playwright/test';
+```
+
+### Use
+
+```ts
+import { test } from './_base';
+
+test('drag idea creates new column', async ({ page, testData }) => {
+  const id = testData.tag('E2E_DRAG');
+  await testData.register({
+    kind: 'localStorage-key-prefix',
+    store: 'gsd-t-board:idea:',
+    id,
+    taggedPrefix: 'E2E_',
+  });
+
+  // ... interact with the UI; the app inserts a row keyed by `gsd-t-board:idea:${id}` ...
+});
+```
+
+### Tagging Convention
+
+All IDs that flow through `testData.register()` MUST start with a recognized
+prefix. Defaults to `E2E_`. Projects can declare additional prefixes in
+`.gsd-t/test-data-config.json`:
+
+```json
+{ "taggedPrefixes": ["E2E_", "FIXTURE_", "INTEGRATION_"] }
+```
+
+`testData.tag(prefix)` composes IDs of the form
+`{PREFIX}_{verifyRunId}_{counter}` — e.g.
+`E2E_DRAG_verify-m58-20260527T091800Z_3`.
+
+### How purge happens
+
+1. Each call to `testData.register(...)` appends a JSONL row to
+   `.gsd-t/test-data-ledger.jsonl`.
+2. After Playwright runs, `gsd-t-verify` Step 4.5 executes
+   `gsd-t test-data --purge --run "$GSD_T_VERIFY_RUN_ID"`.
+3. The ledger is read; each row is dispatched to its `kind`'s adapter; the
+   adapter removes the record from the store (or reports `absent` /
+   structured `error`).
+4. If any row produces an error, verify FAILs the Test Data Cleanup Gate
+   (block-promotion semantics — equivalent to a failing CI-Parity Gate).
+
+### Opt-in per-test purge
+
+For long suites where you want to clean up after every test, pass
+`purgePerTest: true`:
+
+```ts
+export const test = base.extend(withTestData({ purgePerTest: true }));
+```
+
+This invokes `purgeRunInserts` in the fixture's `afterEach` instead of
+deferring to the verify-final-step. Most suites should leave it off — the
+verify step is the canonical sweep and avoids per-test overhead.
+
+### Verify-run id
+
+The fixture reads `process.env.GSD_T_VERIFY_RUN_ID` and uses it as the
+ledger `runId`. `gsd-t-verify` sets this at the top of the verify run as
+`verify-${MILESTONE}-$(date -u +%Y%m%dT%H%M%SZ)`. For local development
+runs (where the env var is absent), the fixture falls back to
+`local-${randomUUID()}` so the ledger is still coherent.
+
+### What this does NOT do
+
+- It does NOT enforce that every test uses the fixture — the gate works by
+  finding orphans, not by lint. A test that bypasses the fixture and inserts
+  data the gate doesn't know about will leave that data behind.
+- It does NOT clean up data inserted before the suite started — that's a
+  pre-existing data hygiene concern.
+- It does NOT roll back database transactions. Use it for additive inserts
+  (rows, keys, files); for transactional cleanup, use your store's native
+  rollback.

package/templates/test-helpers/test-data-fixture.ts

@@ -0,0 +1,153 @@
+/**
+ * GSD-T M58 — Playwright Test Data fixture
+ *
+ * Auto-registers test data inserts with the GSD-T ledger so the Test Data
+ * Cleanup Gate (gsd-t-verify Step 4.5) can purge them after the suite.
+ *
+ * Usage:
+ *
+ *   import { test as base } from '@playwright/test';
+ *   import { withTestData } from '@tekyzinc/gsd-t/templates/test-helpers/test-data-fixture';
+ *
+ *   export const test = base.extend(withTestData());
+ *
+ *   test('drag idea creates new column', async ({ page, testData }) => {
+ *     const id = testData.tag('E2E_DRAG');
+ *     await testData.register({
+ *       kind: 'localStorage-key-prefix',
+ *       store: 'gsd-t-board:idea:',
+ *       id,
+ *       taggedPrefix: 'E2E_',
+ *     });
+ *     // ... UI interactions that insert {key: 'gsd-t-board:idea:' + id} ...
+ *   });
+ *
+ * Tagging convention: `{PREFIX}_{verifyRunId}_{counter}`.
+ *
+ * Run id comes from `process.env.GSD_T_VERIFY_RUN_ID` (set by gsd-t-verify).
+ * If absent, the fixture falls back to a per-process UUID so local runs still
+ * write a coherent ledger.
+ */
+
+import { randomUUID } from 'node:crypto';
+import * as path from 'node:path';
+
+// Resolve the ledger module path at runtime so this template file does not
+// require build-time linkage to the published package.
+function resolveLedger(): {
+  appendInsert: (row: LedgerRow) => { ok: boolean; ledgerPath: string };
+} {
+  // Caller can override via env (used by synthetic suites under test/fixtures/m58-d2/).
+  const override = process.env.GSD_T_LEDGER_MODULE_PATH;
+  const modulePath = override
+    ? path.resolve(override)
+    : require.resolve('@tekyzinc/gsd-t/bin/gsd-t-test-data-ledger.cjs');
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  return require(modulePath);
+}
+
+type AdapterKind = 'localStorage-key-prefix' | 'file-json-array' | 'sqlite-table-where' | string;
+
+interface LedgerRow {
+  projectDir: string;
+  runId: string;
+  kind: AdapterKind;
+  store: string;
+  id: string;
+  taggedPrefix?: string;
+  insertedAt?: string;
+}
+
+export interface TestDataHandle {
+  /**
+   * Compose a tagged identifier of the form `{PREFIX}_{runId}_{counter}`.
+   * Default prefix is `E2E_`.
+   */
+  tag(prefix?: string): string;
+
+  /**
+   * Record an insert in the ledger. Must be called before / immediately
+   * after the test inserts the row in its store so the verify-final-step
+   * can purge it.
+   */
+  register(opts: {
+    kind: AdapterKind;
+    store: string;
+    id: string;
+    taggedPrefix?: string;
+  }): Promise<void>;
+
+  /**
+   * The runId this fixture is writing under (read-only).
+   */
+  readonly runId: string;
+}
+
+export interface WithTestDataOptions {
+  /**
+   * Project directory (defaults to process.cwd()).
+   */
+  projectDir?: string;
+
+  /**
+   * Default tag prefix when `tag()` is called without one (defaults to `E2E_`).
+   */
+  defaultPrefix?: string;
+
+  /**
+   * Opt-in: per-test purge in `test.afterEach`. Default false — the canonical
+   * purge point is gsd-t-verify Step 4.5 (`gsd-t test-data --purge --run`).
+   */
+  purgePerTest?: boolean;
+}
+
+export function withTestData(opts: WithTestDataOptions = {}) {
+  const projectDir = opts.projectDir || process.cwd();
+  const defaultPrefix = opts.defaultPrefix || 'E2E_';
+  const runId = process.env.GSD_T_VERIFY_RUN_ID || `local-${randomUUID()}`;
+
+  // Playwright fixture factory shape: { testData: [async ({}, use) => {...}, { scope: 'test' }] }
+  return {
+    testData: [
+      async ({}, use: (handle: TestDataHandle) => Promise<void>) => {
+        let counter = 0;
+        const ledger = resolveLedger();
+        const handle: TestDataHandle = {
+          runId,
+          tag(prefix?: string) {
+            const p = prefix || defaultPrefix;
+            counter += 1;
+            // Normalise prefix to end with '_' so composed IDs match the
+            // taggedPrefix the adapter will guard against.
+            const base = p.endsWith('_') ? p : `${p}_`;
+            return `${base}${runId}_${counter}`;
+          },
+          async register({ kind, store, id, taggedPrefix }) {
+            const prefix = taggedPrefix || defaultPrefix;
+            ledger.appendInsert({
+              projectDir,
+              runId,
+              kind,
+              store,
+              id,
+              taggedPrefix: prefix,
+            });
+          },
+        };
+        await use(handle);
+        // Per-test purge is opt-in; canonical sweep is the verify-final-step.
+        if (opts.purgePerTest) {
+          // Lazy-load purgeRunInserts only when opted in.
+          // eslint-disable-next-line @typescript-eslint/no-var-requires
+          const ledgerMod = require(
+            process.env.GSD_T_LEDGER_MODULE_PATH
+              ? path.resolve(process.env.GSD_T_LEDGER_MODULE_PATH)
+              : '@tekyzinc/gsd-t/bin/gsd-t-test-data-ledger.cjs',
+          );
+          await ledgerMod.purgeRunInserts({ projectDir, runId });
+        }
+      },
+      { scope: 'test' },
+    ],
+  };
+}