@tekyzinc/gsd-t 2.24.7 → 2.28.12

package/scripts/gsd-t-tools.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+'use strict';
+// gsd-t-tools.js — GSD-T state utility CLI. Zero external dependencies.
+// Returns compact JSON. Subcommands: state, validate, parse, list, git, template
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Find nearest .gsd-t/ directory walking up from cwd
+function findProjectRoot() {
+  let dir = process.cwd();
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, '.gsd-t'))) return dir;
+    dir = path.dirname(dir);
+  }
+  return process.cwd();
+}
+
+const root = findProjectRoot();
+const gsdDir = path.join(root, '.gsd-t');
+
+function readProgress() {
+  const p = path.join(gsdDir, 'progress.md');
+  if (!fs.existsSync(p)) return null;
+  return fs.readFileSync(p, 'utf8');
+}
+
+function stateGet(key) {
+  const content = readProgress();
+  if (!content) return { error: 'progress.md not found' };
+  const re = new RegExp(`^## ${escapeRe(key)}:\\s*(.+)`, 'm');
+  const m = content.match(re);
+  if (!m) return { error: `key not found: ${key}` };
+  return { key, value: m[1].trim() };
+}
+
+function stateSet(key, value) {
+  const p = path.join(gsdDir, 'progress.md');
+  if (!fs.existsSync(p)) return { error: 'progress.md not found' };
+  const content = fs.readFileSync(p, 'utf8');
+  const re = new RegExp(`(^## ${escapeRe(key)}:\\s*)(.+)`, 'm');
+  if (!re.test(content)) return { error: `key not found: ${key}` };
+  fs.writeFileSync(p, content.replace(re, `$1${value}`));
+  return { ok: true, key, value };
+}
+
+function validate() {
+  const required = [
+    '.gsd-t/progress.md',
+    '.gsd-t/contracts',
+    '.gsd-t/domains',
+    'CLAUDE.md',
+  ];
+  const results = {};
+  const missing = [];
+  for (const f of required) {
+    const exists = fs.existsSync(path.join(root, f));
+    results[f] = exists ? 'ok' : 'missing';
+    if (!exists) missing.push(f);
+  }
+  return { valid: missing.length === 0, results, missing };
+}
+
+function parseSection(sectionName) {
+  const content = readProgress();
+  if (!content) return { error: 'progress.md not found' };
+  const re = new RegExp(`## ${escapeRe(sectionName)}\\n([\\s\\S]*?)(?=\\n## |$)`);
+  const m = content.match(re);
+  if (!m) return { error: `section not found: ${sectionName}` };
+  return { section: sectionName, content: m[1].trim() };
+}
+
+function listDomains() {
+  const dir = path.join(gsdDir, 'domains');
+  if (!fs.existsSync(dir)) return { domains: [] };
+  const domains = fs.readdirSync(dir).filter(f => {
+    try { return fs.statSync(path.join(dir, f)).isDirectory(); } catch { return false; }
+  });
+  return { domains };
+}
+
+function listContracts() {
+  const dir = path.join(gsdDir, 'contracts');
+  if (!fs.existsSync(dir)) return { contracts: [] };
+  const contracts = fs.readdirSync(dir).filter(f => f.endsWith('.md'));
+  return { contracts };
+}
+
+function preCommitCheck() {
+  const result = {};
+  try {
+    result.branch = execSync('git branch --show-current', { cwd: root, encoding: 'utf8' }).trim();
+  } catch {
+    result.branch = 'error';
+  }
+  try {
+    const status = execSync('git status --porcelain', { cwd: root, encoding: 'utf8' }).trim();
+    result.clean = status.length === 0;
+    result.changes = status ? status.split('\n').filter(Boolean) : [];
+  } catch {
+    result.clean = 'error';
+  }
+  try {
+    result.lastCommit = execSync('git log -1 --format="%h %s"', { cwd: root, encoding: 'utf8' }).trim();
+  } catch {
+    result.lastCommit = 'error';
+  }
+  return result;
+}
+
+function templateScope(domain) {
+  const p = path.join(gsdDir, 'domains', domain, 'scope.md');
+  if (!fs.existsSync(p)) return { error: `scope.md not found for domain: ${domain}` };
+  return { domain, scope: fs.readFileSync(p, 'utf8') };
+}
+
+function templateTasks(domain) {
+  const p = path.join(gsdDir, 'domains', domain, 'tasks.md');
+  if (!fs.existsSync(p)) return { error: `tasks.md not found for domain: ${domain}` };
+  return { domain, tasks: fs.readFileSync(p, 'utf8') };
+}
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Parse args
+const args = process.argv.slice(2);
+const [cmd, subcmd, ...rest] = args;
+
+let result;
+if (cmd === 'state') {
+  if (subcmd === 'get' && rest[0]) {
+    result = stateGet(rest[0]);
+  } else if (subcmd === 'set' && rest[0] && rest[1]) {
+    result = stateSet(rest[0], rest[1]);
+  } else {
+    result = { error: 'Usage: state get <key> | state set <key> <value>' };
+  }
+} else if (cmd === 'validate') {
+  result = validate();
+} else if (cmd === 'parse' && subcmd === 'progress') {
+  const si = args.indexOf('--section');
+  const section = si !== -1 ? args[si + 1] : null;
+  result = section ? parseSection(section) : { error: 'Usage: parse progress --section <name>' };
+} else if (cmd === 'list') {
+  if (subcmd === 'domains') result = listDomains();
+  else if (subcmd === 'contracts') result = listContracts();
+  else result = { error: 'Usage: list domains | list contracts' };
+} else if (cmd === 'git' && subcmd === 'pre-commit-check') {
+  result = preCommitCheck();
+} else if (cmd === 'template') {
+  if (subcmd === 'scope' && rest[0]) result = templateScope(rest[0]);
+  else if (subcmd === 'tasks' && rest[0]) result = templateTasks(rest[0]);
+  else result = { error: 'Usage: template scope <domain> | template tasks <domain>' };
+} else {
+  result = {
+    error: cmd ? `Unknown command: ${cmd}` : 'No command specified',
+    usage: 'state get|set  validate  parse progress --section <name>  list domains|contracts  git pre-commit-check  template scope|tasks <domain>',
+  };
+}
+
+process.stdout.write(JSON.stringify(result, null, 2) + '\n');

package/templates/CLAUDE-global.md

@@ -1,3 +1,4 @@
+<!-- GSD-T:START — Do not remove this marker. Content between START/END is managed by gsd-t update. -->
 # Prime Directives
 
 1. SIMPLICITY ABOVE ALL. Every change should be minimal and impact as little code as possible. No massive refactors.
@@ -54,6 +55,8 @@ PROJECT or FEATURE or SCAN
 | `/user:gsd-t-status` | Cross-domain progress view |
 | `/user:gsd-t-debug` | Systematic debugging |
 | `/user:gsd-t-quick` | Fast task, respects contracts |
+| `/user:gsd-t-health` | Validate .gsd-t/ structure, optionally repair |
+| `/user:gsd-t-pause` | Save exact position for reliable resume |
 | `/user:gsd-t-populate` | Auto-populate docs from existing codebase |
 | `/user:gsd-t-log` | Sync progress Decision Log with recent git activity |
 | `/user:gsd-t-resume` | Restore context, continue |
@@ -108,11 +111,13 @@ GSD-T tracks project version in `.gsd-t/progress.md` using semantic versioning:
 
 | Segment | Bumped When | Example |
 |---------|-------------|---------|
-| **Major** | Breaking changes, major rework, v1 launch | 1.0.0 → 2.0.0 |
-| **Minor** | New features, completed feature milestones | 1.1.0 → 1.2.0 |
-| **Patch** | Bug fixes, minor improvements, cleanup | 1.1.1 → 1.1.2 |
+| **Major** | Breaking changes, major rework, v1 launch | 1.0.10 → 2.0.10 |
+| **Minor** | New features, completed feature milestones | 1.10.10 → 1.11.10 |
+| **Patch** | Bug fixes, minor improvements, cleanup | 1.1.10 → 1.1.11 |
 
-- Version is set during `gsd-t-init` (starts at `0.1.0`)
+**Patch convention**: Patch numbers are always 2 digits (≥10). When resetting after a minor or major bump, start at **10** (not 0). This keeps patches always 2 characters without leading zeros, so semver stays valid.
+
+- Version is set during `gsd-t-init` (starts at `0.1.10`)
 - Version is bumped during `gsd-t-complete-milestone` based on milestone scope
 - Version is reflected in: `progress.md`, `README.md`, package manifest (if any), and git tags (`v{version}`)
 
@@ -221,20 +226,24 @@ This applies everywhere Playwright tests are executed: execute, test-sync, verif
 
 ## QA Agent (Mandatory)
 
-Any GSD-T phase that produces or validates code **MUST spawn a QA teammate**. The QA agent's sole job is test generation, execution, and gap reporting. It never writes feature code.
+Any GSD-T phase that produces or validates code **MUST run QA**. The QA agent's sole job is test generation, execution, and gap reporting. It never writes feature code.
 
-**Commands that must spawn QA agent:**
-`partition`, `plan`, `execute`, `verify`, `complete-milestone`, `quick`, `debug`, `integrate`, `test-sync`, `wave`
+**QA method by command:**
+- `execute`, `integrate` → spawn QA via **Task subagent** (lightweight, no TeamCreate)
+- `test-sync`, `verify`, `complete-milestone` → perform contract testing and gap analysis **inline**
+- `quick`, `debug` → run the full test suite **inline** as part of the command's Test & Verify step
+- `wave` → each phase agent handles QA per the rules above
+- `partition`, `plan` → no QA spawn needed (no code produced yet)
 
-**Spawn instruction:**
+**Task subagent spawn instruction (execute/integrate):**
 ```
-Teammate "qa": Read commands/gsd-t-qa.md for your full instructions.
-  Phase context: {current phase}. Read .gsd-t/contracts/ for contract definitions.
-  Your job: generate contract tests, run all tests, report gaps.
-  You do NOT write feature code.
+Task subagent (general-purpose):
+"Run the full test suite and contract compliance tests.
+Read .gsd-t/contracts/ for contract definitions.
+Report: pass/fail counts and any coverage gaps."
 ```
 
-**QA agent failure blocks phase completion.** Lead cannot proceed until QA reports PASS or user explicitly overrides.
+**QA failure blocks phase completion.** Lead cannot proceed until QA reports PASS or user explicitly overrides.
 
 ## API Documentation Guard (Swagger/OpenAPI)
 
@@ -407,7 +416,7 @@ Successor mapping:
 | `populate` | `status` | |
 | `setup` | `status` | |
 
-Commands with no successor (standalone): `quick`, `debug`, `brainstorm`, `status`, `help`, `resume`, `prompt`, `log`, backlog commands.
+Commands with no successor (standalone): `quick`, `debug`, `brainstorm`, `status`, `help`, `resume`, `prompt`, `log`, `health`, `pause`, backlog commands.
 
 Skip the hint if auto-advancing (Level 3 mid-wave) — only show when the user needs to manually invoke the next step.
 
@@ -456,3 +465,4 @@ When resuming work (new session or after /clear):
 6. Continue from current task — don't restart the phase
 
 **CRITICAL: Do NOT research how the system works. The docs tell you. Read them.**
+<!-- GSD-T:END — Do not remove this marker. -->