@tekyzinc/gsd-t 5.10.10 → 5.10.11

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v5.10.10** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v5.10.11** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
 
 **Eliminates context rot** — task-level fresh dispatch (one subagent per task, ~10-20% context each) means compaction never triggers.
 **Compaction-proof debug loops** — `gsd-t headless --debug-loop` runs test-fix-retest cycles as separate `claude -p` sessions. A JSONL debug ledger persists all hypothesis/fix/learning history across fresh sessions. Anti-repetition preamble injection prevents retrying failed hypotheses. Escalation tiers (sonnet → opus → human) and a hard iteration ceiling enforced externally.

package/bin/gsd-t-claude-md-changelog.cjs

@@ -0,0 +1,360 @@
+#!/usr/bin/env node
+/**
+ * gsd-t-claude-md-changelog.cjs
+ *
+ * M110: CLAUDE.md changelog tracking.
+ * Maintains an append-only changelog for CLAUDE.md mutations.
+ *
+ * Commands:
+ *   scaffold <projectDir>              Create changelog file if missing
+ *   append <projectDir> <type> [desc]  Append an entry (rewritten|updated|external)
+ *   check-external <projectDir>        Detect external updates (mtime > last entry)
+ *   get-last-entry-time <projectDir>   Return ISO timestamp of last entry (for hooks)
+ *
+ * Entry format:
+ *   **[Rewritten|Updated|External update detected] {date} {time} | {model} | GSD-T v{gsdtVersion} | project v{projectVersion}**
+ *   - bullet 1 (for Updated only)
+ *   - bullet 2
+ *
+ * Exit codes:
+ *   0 — success / up-to-date
+ *   1 — external update detected (check-external only)
+ *   2 — corrupt changelog (HALT)
+ *   64 — bad input
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const CHANGELOG_FILENAME = 'CLAUDE.md updates.md';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+function getChangelogPath(projectDir) {
+  return path.join(projectDir, CHANGELOG_FILENAME);
+}
+
+function getClaudeMdPath(projectDir) {
+  const rootPath = path.join(projectDir, 'CLAUDE.md');
+  const dotClaudePath = path.join(projectDir, '.claude', 'CLAUDE.md');
+  if (fs.existsSync(rootPath)) return rootPath;
+  if (fs.existsSync(dotClaudePath)) return dotClaudePath;
+  return rootPath;
+}
+
+function halt(message, exitCode) {
+  console.error(JSON.stringify({ error: message }));
+  process.exit(exitCode);
+}
+
+function getGsdtVersion() {
+  const pkgPath = path.join(__dirname, '..', 'package.json');
+  if (!fs.existsSync(pkgPath)) {
+    halt('GSD-T package.json not found: ' + pkgPath, 64);
+  }
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  if (!pkg.version) {
+    halt('GSD-T package.json missing version field', 64);
+  }
+  return pkg.version;
+}
+
+function getProjectVersion(projectDir) {
+  const pkgPath = path.join(projectDir, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    if (pkg.version) return pkg.version;
+  }
+  const pyprojectPath = path.join(projectDir, 'pyproject.toml');
+  if (fs.existsSync(pyprojectPath)) {
+    const content = fs.readFileSync(pyprojectPath, 'utf8');
+    const match = content.match(/version\s*=\s*["']([^"']+)["']/);
+    if (match) return match[1];
+  }
+  return 'unversioned';
+}
+
+function getClaudeModel() {
+  const model = process.env.CLAUDE_MODEL || process.env.MODEL;
+  if (!model) return 'Claude';
+  if (model.includes('opus-5') || model.includes('opus5')) return 'Claude-Opus-5';
+  if (model.includes('opus-4.5') || model.includes('opus4.5')) return 'Claude-Opus-4.5';
+  if (model.includes('opus')) return 'Claude-Opus';
+  if (model.includes('sonnet-5') || model.includes('sonnet5')) return 'Claude-Sonnet-5';
+  if (model.includes('sonnet')) return 'Claude-Sonnet';
+  if (model.includes('haiku')) return 'Claude-Haiku';
+  return model;
+}
+
+function formatDate(date) {
+  const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+                  'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+  const month = months[date.getMonth()];
+  const day = date.getDate();
+  const year = date.getFullYear();
+  let hours = date.getHours();
+  const ampm = hours >= 12 ? 'pm' : 'am';
+  hours = hours % 12 || 12;
+  const minutes = date.getMinutes().toString().padStart(2, '0');
+  return `${month} ${day}, ${year} ${hours}:${minutes}${ampm}`;
+}
+
+/**
+ * Parse the timestamp of the last entry in the changelog.
+ *
+ * @returns {Date | null} Date of last entry, or null if no file/entries
+ * @throws Calls halt() and exits if changelog is corrupt
+ */
+function parseLastEntryTime(changelogPath) {
+  if (!fs.existsSync(changelogPath)) {
+    return null;
+  }
+
+  const content = fs.readFileSync(changelogPath, 'utf8');
+
+  const hasHeader = content.includes('# CLAUDE.md Change Log');
+  const hasEntries = content.includes('**Rewritten') ||
+                     content.includes('**Updated') ||
+                     content.includes('**External update detected');
+
+  if (hasHeader && !hasEntries) {
+    return null;
+  }
+
+  // Match entries with optional ~ before time (e.g., "~3:00pm" or "3:00pm")
+  const entryPattern = /\*\*(?:Rewritten|Updated|External update detected)\s+(\w+\s+\d+,\s+\d{4}\s+~?\d{1,2}:\d{2}(?:am|pm))/gi;
+
+  let lastMatch = null;
+  let match;
+  while ((match = entryPattern.exec(content)) !== null) {
+    lastMatch = match[1];
+  }
+
+  if (!lastMatch) {
+    halt('Changelog file is corrupt — has content but no parseable entries: ' + changelogPath, 2);
+  }
+
+  // Remove optional ~ and parse the date
+  const parsed = new Date(lastMatch.replace(/~/, '').replace(/(\d{1,2}:\d{2})(am|pm)/i, (_, time, ampm) => {
+    const [h, m] = time.split(':');
+    let hour = parseInt(h, 10);
+    if (ampm.toLowerCase() === 'pm' && hour !== 12) hour += 12;
+    if (ampm.toLowerCase() === 'am' && hour === 12) hour = 0;
+    return `${hour.toString().padStart(2, '0')}:${m}`;
+  }));
+
+  if (isNaN(parsed.getTime())) {
+    halt('Changelog file has unparseable date: ' + changelogPath, 2);
+  }
+
+  return parsed;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Commands
+// ─────────────────────────────────────────────────────────────────────────────
+
+function scaffold(projectDir) {
+  const changelogPath = getChangelogPath(projectDir);
+
+  if (fs.existsSync(changelogPath)) {
+    console.log(JSON.stringify({ status: 'exists', path: changelogPath }));
+    process.exit(0);
+  }
+
+  const content = `# CLAUDE.md Change Log
+
+Append-only record of CLAUDE.md rewrites and updates.
+
+---
+
+`;
+
+  fs.writeFileSync(changelogPath, content, 'utf8');
+  console.log(JSON.stringify({ status: 'created', path: changelogPath }));
+  process.exit(0);
+}
+
+function append(projectDir, type, description, bullets) {
+  const changelogPath = getChangelogPath(projectDir);
+
+  if (!fs.existsSync(changelogPath)) {
+    const content = `# CLAUDE.md Change Log
+
+Append-only record of CLAUDE.md rewrites and updates.
+
+---
+
+`;
+    fs.writeFileSync(changelogPath, content, 'utf8');
+  }
+
+  const now = new Date();
+  const dateStr = formatDate(now);
+  const model = getClaudeModel();
+  const gsdtVersion = getGsdtVersion();
+  const projectVersion = getProjectVersion(projectDir);
+
+  let typeLabel;
+  switch (type.toLowerCase()) {
+    case 'rewritten':
+    case 'rewrite':
+      typeLabel = 'Rewritten';
+      break;
+    case 'updated':
+    case 'update':
+      typeLabel = 'Updated';
+      break;
+    case 'external':
+      typeLabel = 'External update detected';
+      break;
+    default:
+      halt('Unknown type: ' + type + '. Use: rewritten, updated, external', 64);
+  }
+
+  let entry = `\n**${typeLabel} ${dateStr} | ${model} | GSD-T v${gsdtVersion} | project v${projectVersion}**\n`;
+
+  if (description && typeLabel === 'Rewritten') {
+    entry += `\n${description}\n`;
+  }
+
+  if (bullets && bullets.length > 0 && typeLabel === 'Updated') {
+    entry += '\n';
+    for (const bullet of bullets) {
+      entry += `- ${bullet}\n`;
+    }
+  }
+
+  fs.appendFileSync(changelogPath, entry, 'utf8');
+  console.log(JSON.stringify({
+    status: 'appended',
+    type: typeLabel,
+    path: changelogPath,
+    timestamp: now.toISOString()
+  }));
+  process.exit(0);
+}
+
+/**
+ * check-external: Detects if CLAUDE.md was modified outside GSD-T.
+ *
+ * Exit codes:
+ *   0 — up to date, no action needed
+ *   1 — external update detected, caller should append entry
+ *   2 — changelog is corrupt (HALT)
+ */
+function checkExternal(projectDir) {
+  const changelogPath = getChangelogPath(projectDir);
+  const claudeMdPath = getClaudeMdPath(projectDir);
+
+  if (!fs.existsSync(claudeMdPath)) {
+    console.log(JSON.stringify({ status: 'no-claude-md', path: claudeMdPath }));
+    process.exit(0);
+  }
+
+  const claudeMdStat = fs.statSync(claudeMdPath);
+  const claudeMdMtime = claudeMdStat.mtime;
+
+  const lastEntryTime = parseLastEntryTime(changelogPath);
+
+  if (lastEntryTime === null) {
+    console.log(JSON.stringify({
+      status: 'external-detected',
+      reason: 'no-prior-entries',
+      claudeMdMtime: claudeMdMtime.toISOString()
+    }));
+    process.exit(1);
+  }
+
+  const bufferMs = 60 * 1000;
+
+  if (claudeMdMtime.getTime() > lastEntryTime.getTime() + bufferMs) {
+    console.log(JSON.stringify({
+      status: 'external-detected',
+      reason: 'mtime-newer',
+      claudeMdMtime: claudeMdMtime.toISOString(),
+      lastEntryTime: lastEntryTime.toISOString()
+    }));
+    process.exit(1);
+  }
+
+  console.log(JSON.stringify({
+    status: 'up-to-date',
+    claudeMdMtime: claudeMdMtime.toISOString(),
+    lastEntryTime: lastEntryTime.toISOString()
+  }));
+  process.exit(0);
+}
+
+function getLastEntryTime(projectDir) {
+  const changelogPath = getChangelogPath(projectDir);
+  const result = parseLastEntryTime(changelogPath);
+
+  if (result === null) {
+    console.log(JSON.stringify({ status: 'none' }));
+    process.exit(0);
+  }
+
+  console.log(JSON.stringify({
+    status: 'found',
+    timestamp: result.toISOString()
+  }));
+  process.exit(0);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CLI
+// ─────────────────────────────────────────────────────────────────────────────
+
+function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (!command) {
+    console.error('Usage: gsd-t-claude-md-changelog <command> [args]');
+    console.error('Commands: scaffold, append, check-external, get-last-entry-time');
+    process.exit(64);
+  }
+
+  switch (command) {
+    case 'scaffold': {
+      const projectDir = args[1] || process.cwd();
+      scaffold(projectDir);
+      break;
+    }
+    case 'append': {
+      const projectDir = args[1] || process.cwd();
+      const type = args[2];
+      const description = args[3];
+      let bullets = [];
+      if (args[4]) {
+        const parsed = JSON.parse(args[4]);
+        if (!Array.isArray(parsed)) {
+          halt('Bullets must be a JSON array', 64);
+        }
+        bullets = parsed;
+      }
+      if (!type) {
+        halt('Usage: gsd-t-claude-md-changelog append <projectDir> <type> [description] [bulletsJson]', 64);
+      }
+      append(projectDir, type, description, bullets);
+      break;
+    }
+    case 'check-external': {
+      const projectDir = args[1] || process.cwd();
+      checkExternal(projectDir);
+      break;
+    }
+    case 'get-last-entry-time': {
+      const projectDir = args[1] || process.cwd();
+      getLastEntryTime(projectDir);
+      break;
+    }
+    default:
+      halt('Unknown command: ' + command, 64);
+  }
+}
+
+main();

package/bin/gsd-t.js

@@ -3166,6 +3166,8 @@ const PROJECT_BIN_TOOLS = [
   // M90 D2 — Loop ledger (non-convergence detection + halt directive; §3).
   // Propagated so project-local runCli helpers (gsd-t-debug.workflow.js) can invoke it.
   "gsd-t-loop-ledger.cjs",
+  // M110 — CLAUDE.md changelog tracking. Scaffolds and appends to the changelog file.
+  "gsd-t-claude-md-changelog.cjs",
   // Backlog #40 — deterministic archive+sweep of a completed milestone's domain dirs
   // (complete-milestone Step 7). Propagated so complete-milestone can invoke it project-local.
   "gsd-t-archive-domains.cjs",

package/commands/gsd-t-init.md

@@ -367,6 +367,19 @@ The `bin/gsd-t.js init` flow calls `runLoggingScaffoldStep(projectDir)` (from `b
 
 See `.gsd-t/contracts/logging-scaffold-seam-contract.md` for the full seam envelope shape consumed by d2 (trace), d4 (audit), and d5 (migrate-logging).
 
+## Step 11.6: CLAUDE.md Changelog Scaffold (M110)
+
+Scaffold the CLAUDE.md changelog file if it doesn't exist:
+
+```bash
+node bin/gsd-t-claude-md-changelog.cjs scaffold .
+```
+
+This creates `CLAUDE.md updates.md` — an append-only log of CLAUDE.md changes. The file tracks:
+- Rewrites (via `/gsd-t-setup`)
+- Updates (user-directed edits)
+- External changes (modifications outside GSD-T sessions)
+
 ## Step 12: Test Verification
 
 After initialization:

package/commands/gsd-t-setup.md

@@ -299,6 +299,16 @@ Wait for user confirmation before writing.
 2. Verify it's valid markdown (no broken tables, unclosed code blocks)
 3. If `.gsd-t/progress.md` exists, log the setup in the Decision Log
 
+## Step 7.5: Update CLAUDE.md Changelog (M110)
+
+After writing the project CLAUDE.md, update the changelog:
+
+```bash
+node bin/gsd-t-claude-md-changelog.cjs append . rewritten "Generated via /gsd-t-setup"
+```
+
+If the changelog file doesn't exist, the command scaffolds it first.
+
 ## Document Ripple
 
 ### Always update:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "5.10.10",
+  "version": "5.10.11",
   "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-changelog-check.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * gsd-t-changelog-check.js
+ *
+ * SessionStart hook: checks if CLAUDE.md was modified outside GSD-T since the
+ * last tracked changelog entry. If so, appends an "External update detected" entry.
+ *
+ * Runs once at session start, not on every prompt.
+ * Exit codes:
+ *   0 — success (up to date, or external update logged)
+ *   1 — not a GSD-T project (no .gsd-t/), or no CLI found — silent skip, not an error
+ *   2 — changelog CLI failed unexpectedly
+ */
+
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+function findCli() {
+  const globalRoot = execSync('npm root -g', { encoding: 'utf8' }).trim();
+  const globalCli = path.join(globalRoot, '@tekyzinc', 'gsd-t', 'bin', 'gsd-t-claude-md-changelog.cjs');
+  if (fs.existsSync(globalCli)) return globalCli;
+
+  const localCli = path.join(process.cwd(), 'bin', 'gsd-t-claude-md-changelog.cjs');
+  if (fs.existsSync(localCli)) return localCli;
+
+  return null;
+}
+
+function main() {
+  const cwd = process.cwd();
+
+  // Only run in GSD-T projects — silent exit if not
+  if (!fs.existsSync(path.join(cwd, '.gsd-t'))) {
+    process.exit(0);
+  }
+
+  const cli = findCli();
+  if (!cli) {
+    // CLI not installed — silent exit (GSD-T may not be fully set up yet)
+    process.exit(0);
+  }
+
+  let checkResult;
+  try {
+    checkResult = execSync(`node "${cli}" check-external "${cwd}"`, { encoding: 'utf8' });
+    // Exit code 0 = up to date
+    process.exit(0);
+  } catch (e) {
+    if (e.status === 1) {
+      // External update detected — append entry
+      execSync(`node "${cli}" append "${cwd}" external`, { encoding: 'utf8' });
+      process.stdout.write('CLAUDE.md changelog: external update detected and logged.\n');
+      process.exit(0);
+    }
+    if (e.status === 2) {
+      // Corrupt changelog — report but don't block session
+      process.stderr.write('CLAUDE.md changelog is corrupt. Run: node bin/gsd-t-claude-md-changelog.cjs get-last-entry-time .\n');
+      process.exit(0);
+    }
+    // Unexpected error — report it
+    process.stderr.write('CLAUDE.md changelog check failed: ' + (e.message || 'unknown error') + '\n');
+    process.exit(2);
+  }
+}
+
+main();

package/scripts/gsd-t-changelog-post-edit.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/**
+ * gsd-t-changelog-post-edit.js
+ *
+ * PostToolUse hook for Write|Edit: after a successful write to CLAUDE.md,
+ * reminds Claude to update the changelog.
+ *
+ * Receives JSON on stdin with tool_input containing file_path.
+ * Outputs reminder text to stdout if the target was CLAUDE.md.
+ *
+ * Does NOT auto-append — Claude should consciously decide what changed and
+ * call the append command with appropriate bullets.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', () => {
+  let data;
+  try {
+    data = JSON.parse(input);
+  } catch {
+    process.exit(0);
+  }
+
+  // Get the file path from tool_input
+  const toolInput = data.tool_input;
+  if (!toolInput) {
+    process.exit(0);
+  }
+
+  let filePath;
+  if (typeof toolInput === 'string') {
+    try {
+      const parsed = JSON.parse(toolInput);
+      filePath = parsed.file_path;
+    } catch {
+      process.exit(0);
+    }
+  } else if (typeof toolInput === 'object') {
+    filePath = toolInput.file_path;
+  }
+
+  if (!filePath) {
+    process.exit(0);
+  }
+
+  // Check if it's CLAUDE.md (root or .claude/)
+  const basename = path.basename(filePath);
+  if (basename !== 'CLAUDE.md') {
+    process.exit(0);
+  }
+
+  // Check if it's NOT the global ~/.claude/CLAUDE.md (only track project CLAUDE.md)
+  const homeClaudeMd = path.join(process.env.HOME || '', '.claude', 'CLAUDE.md');
+  if (path.resolve(filePath) === path.resolve(homeClaudeMd)) {
+    process.exit(0);
+  }
+
+  // It's a project CLAUDE.md — remind to update changelog
+  const projectDir = data.cwd || process.cwd();
+  const changelogPath = path.join(projectDir, 'CLAUDE.md updates.md');
+
+  process.stdout.write(
+    `[M110] You just modified CLAUDE.md. Update the changelog:\n` +
+    `  node bin/gsd-t-claude-md-changelog.cjs append "${projectDir}" updated "" '["<describe what changed>"]'\n`
+  );
+
+  process.exit(0);
+});