@tekyzinc/gsd-t 3.12.15 → 3.13.11

package/commands/gsd-t-verify.md

@@ -23,6 +23,10 @@ Per `.gsd-t/contracts/model-selection-contract.md` v1.0.0.
 
 ## Step 1: Load State
 
+```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 1 --step-label "Load State" 2>/dev/null || true
+```
+
 Read:
 1. `CLAUDE.md`
 2. `.gsd-t/progress.md` — confirm status is INTEGRATED
@@ -33,6 +37,10 @@ Read:
 
 ## Step 1.5: Graph-Enhanced Traceability Check
 
+```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 1 --step-label ".5: Graph-Enhanced Traceability Check" 2>/dev/null || true
+```
+
 If `.gsd-t/graph/meta.json` exists (graph index is available):
 1. Query `getRequirementFor` on implemented entities to build a requirement-to-code traceability chain — flag entities with no requirement mapping
 2. Query `getDomainBoundaryViolations` to verify no cross-domain boundary violations exist in the final codebase
@@ -42,6 +50,10 @@ If graph is not available, skip this step.
 
 ## Step 2: Full Test Audit (Inline)
 
+```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 2 --step-label "Full Test Audit (Inline)" 2>/dev/null || true
+```
+
 Run the full test audit directly:
 
 1. Run the full test suite: `npm test` (or project equivalent) — record pass/fail counts
@@ -54,6 +66,10 @@ Verification cannot complete if any test fails or critical contract gaps remain.
 
 ## Step 2.5: High-Risk Domain Gate (MANDATORY — Categories 2 and 7)
 
+```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 2 --step-label ".5: High-Risk Domain Gate (MANDATORY — Categories 2 and 7)" 2>/dev/null || true
+```
+
 Before running standard verification dimensions, check whether this milestone involves any high-risk domain:
 
 **High-risk domains**: audio capture/playback, GPU/WebGPU/WebGL, ML/inference/model loading, background workers, native APIs (camera, bluetooth, filesystem), IPC, WebAssembly, real-time data streams.
@@ -85,6 +101,10 @@ For each such feature:
 
 ## Step 3: Define Verification Dimensions
 
+```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 3 --step-label "Define Verification Dimensions" 2>/dev/null || true
+```
+
 Standard dimensions (adjust based on project):
 
 1. **Functional Correctness**: Does it work per requirements?
@@ -115,6 +135,10 @@ Standard dimensions (adjust based on project):
 
 ## Step 4: Execute Verification
 
+```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 "Execute Verification" 2>/dev/null || true
+```
+
 ### Solo Mode (default)
 Work through each dimension sequentially. For each:
 1. Define what you're checking
@@ -188,6 +212,10 @@ Collect all reports, synthesize, create remediation plan.
 
 ## Step 5: Compile Verification Report
 
+```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 5 --step-label "Compile Verification Report" 2>/dev/null || true
+```
+
 Create or update `.gsd-t/verify-report.md`:
 
 ```markdown
@@ -226,6 +254,10 @@ Create or update `.gsd-t/verify-report.md`:
 
 ## Step 5.25: Metrics Quality Budget Check
 
+```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 5 --step-label ".25: Metrics Quality Budget Check" 2>/dev/null || true
+```
+
 Check task-metrics for the current milestone to detect quality budget violations:
 
 1. Run via Bash:
@@ -241,6 +273,10 @@ Check task-metrics for the current milestone to detect quality budget violations
 
 ## Step 5.5: Goal-Backward Verification (Post-Gate Behavior Check)
 
+```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 5 --step-label ".5: Goal-Backward Verification (Post-Gate Behavior Check)" 2>/dev/null || true
+```
+
 This step runs **after all 8 quality gates pass**. It verifies that milestone goals are actually achieved end-to-end — not just structurally present. It catches placeholder implementations that pass all structural gates.
 
 Refer to `.gsd-t/contracts/goal-backward-contract.md` for the full verification flow, placeholder patterns, and findings report format.
@@ -315,6 +351,10 @@ Add a `Goal-Backward:` line to the Step 5 verification report summary:
 
 ## Step 6: Handle Remediation
 
+```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 6 --step-label "Handle Remediation" 2>/dev/null || true
+```
+
 If there are CRITICAL findings:
 1. Create remediation tasks in the affected domain's `tasks.md`
 2. Execute fixes (solo — don't spawn teams for remediation)
@@ -323,6 +363,10 @@ If there are CRITICAL findings:
 
 ## Step 7: Update State
 
+```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 7 --step-label "Update State" 2>/dev/null || true
+```
+
 Update `.gsd-t/progress.md`:
 - If all PASS: Set status to `VERIFIED`
 - If CONDITIONAL PASS: Set status to `VERIFIED-WITH-WARNINGS`, list warnings
@@ -353,6 +397,10 @@ Update `.gsd-t/progress.md`:
 
 ## Step 8: Auto-Invoke Complete-Milestone
 
+```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 8 --step-label "Auto-Invoke Complete-Milestone" 2>/dev/null || true
+```
+
 **This step is MANDATORY and runs at ALL autonomy levels.** Completing a verified milestone is a mechanical operation (archive, tag, bump version, update docs). There is no decision that benefits from user review — the decision was made when verification passed.
 
 If status is VERIFY-FAILED:

package/commands/gsd-t-wave.md

@@ -25,6 +25,10 @@ Per `.gsd-t/contracts/model-selection-contract.md` v1.0.0. Each phase spawn pick
 
 ## Step 0.1: Verify Context Gate Readiness (MANDATORY — first thing in a fresh session)
 
+```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-wave --step 0 --step-label ".1: Verify Context Gate Readiness (MANDATORY — first thing in a fresh session)" 2>/dev/null || true
+```
+
 Run via Bash:
 
 ```bash
@@ -35,6 +39,10 @@ This calls `getSessionStatus()` which reads `.gsd-t/.context-meter-state.json` p
 
 ## Step 1: Load State (Lightweight)
 
+```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-wave --step 1 --step-label "Load State (Lightweight)" 2>/dev/null || true
+```
+
 Read ONLY:
 1. `.gsd-t/progress.md` — current status, milestone name, phase state
 2. `CLAUDE.md` — autonomy level only (scan for Level 1/2/3)
@@ -54,6 +62,10 @@ Do NOT attempt to fix progress.md yourself — that risks data loss.
 
 ## Step 2: Determine Resume Point
 
+```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-wave --step 2 --step-label "Determine Resume Point" 2>/dev/null || true
+```
+
 From progress.md status, determine which phase to start from:
 
 | Status | Next Phase |
@@ -72,6 +84,10 @@ From progress.md status, determine which phase to start from:
 
 ## Step 2.5: Token Budget Pre-Flight (if available)
 
+```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-wave --step 2 --step-label ".5: Token Budget Pre-Flight (if available)" 2>/dev/null || true
+```
+
 Before starting the phase loop, check the projected token cost for this milestone:
 
 Run via Bash:
@@ -85,6 +101,10 @@ If the file doesn't exist or returns nothing, skip silently and proceed.
 
 ## Step 3: Phase Orchestration Loop
 
+```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-wave --step 3 --step-label "Phase Orchestration Loop" 2>/dev/null || true
+```
+
 For each remaining phase, spawn an **independent agent** using the Task tool. Each agent gets a fresh context window, loads its own state from files, and reports back.
 
 ### Graph Availability
@@ -275,6 +295,10 @@ After each agent completes, run this spot-check before proceeding:
 
 ## Step 4: Autonomy Behavior
 
+```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-wave --step 4 --step-label "Autonomy Behavior" 2>/dev/null || true
+```
+
 **Level 3 (Full Auto)**: Auto-advance to next phase after each agent completes. Only STOP for:
 - Destructive Action Guard violations (reported by phase agent)
 - Impact analysis BLOCK verdict
@@ -285,6 +309,10 @@ After each agent completes, run this spot-check before proceeding:
 
 ## Step 5: Completion
 
+```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-wave --step 5 --step-label "Completion" 2>/dev/null || true
+```
+
 When all phases are done:
 ```
 ═══════════════════════════════════════════════════════════════════════════════

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "3.12.15",
+  "version": "3.13.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-watch-state.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+/**
+ * scripts/gsd-t-watch-state.js — GSD-T Watch-State Writer CLI
+ *
+ * Records per-agent progress into `.gsd-t/.watch-state/{agent_id}.json` so
+ * the watch-progress renderer can reconstruct the workflow tree live.
+ *
+ * Contract: `.gsd-t/contracts/watch-progress-contract.md` v1.0.0
+ * Owner:    D2 (M39 `d2-progress-watch`)
+ *
+ * Subcommands (contract §4):
+ *   start    — create/overwrite a new in-progress record
+ *   advance  — record current step (acts as start if no file exists)
+ *   done     — terminal: status=done, sets completed_at
+ *   skip     — terminal: status=skipped, sets completed_at
+ *   fail     — terminal: status=failed, sets completed_at
+ *
+ * Exit codes:
+ *   0 — success
+ *   1 — validation (bad args, unknown subcommand)
+ *   2 — filesystem (EACCES / ENOSPC / permission)
+ *
+ * Zero external deps (Node.js built-ins only).
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const STATE_DIR_REL = path.join(".gsd-t", ".watch-state");
+const VALID_SUB = new Set(["start", "advance", "done", "skip", "fail"]);
+
+function _parseArgs(argv) {
+  const out = { _sub: argv[0] || null };
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith("--")) continue;
+    const key = a.slice(2);
+    const next = argv[i + 1];
+    if (next === undefined || next.startsWith("--")) {
+      out[key] = true;
+    } else {
+      out[key] = next;
+      i++;
+    }
+  }
+  return out;
+}
+
+function _validate(sub, args) {
+  if (!VALID_SUB.has(sub)) return `unknown subcommand: ${sub}`;
+  if (sub === "start" || sub === "advance") {
+    if (!args["command"]) return "--command is required";
+    if (!args["step"] || !/^-?\d+$/.test(String(args["step"]))) {
+      return "--step must be an integer";
+    }
+    if (!args["step-label"]) return "--step-label is required";
+  }
+  return null;
+}
+
+function _resolveAgentId(args) {
+  const v = args["agent-id"];
+  if (v && typeof v === "string" && v !== "true") return v;
+  if (process.env.GSD_T_AGENT_ID) return process.env.GSD_T_AGENT_ID;
+  return `shell-${process.pid}-${Date.now()}`;
+}
+
+function _stateDir(cwd) {
+  return path.join(cwd || process.cwd(), STATE_DIR_REL);
+}
+
+function _readExisting(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch (_) {
+    return null;
+  }
+}
+
+function _atomicWrite(filePath, data) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  const rand = crypto.randomBytes(4).toString("hex");
+  const tmp = `${filePath}.tmp-${process.pid}-${rand}`;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n");
+  fs.renameSync(tmp, filePath);
+}
+
+function _parseParentId(raw) {
+  if (raw === undefined || raw === null || raw === "null" || raw === "") return null;
+  return String(raw);
+}
+
+function _parseMetadata(raw) {
+  if (!raw || raw === true) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch (_) {
+    return {};
+  }
+}
+
+function _buildRecord(sub, args, existing, resolvedAgentId) {
+  const now = new Date().toISOString();
+  const base = existing || {
+    agent_id: resolvedAgentId || args["agent-id"],
+    parent_agent_id: _parseParentId(args["parent-id"]),
+    command: "",
+    step: 0,
+    step_label: "",
+    status: "pending",
+    started_at: null,
+    completed_at: null,
+    metadata: {},
+  };
+  // Always sync parent_agent_id if explicitly provided (supports late lineage).
+  if (args["parent-id"] !== undefined) base.parent_agent_id = _parseParentId(args["parent-id"]);
+  const mergedMeta = Object.assign({}, base.metadata || {}, _parseMetadata(args["metadata"]));
+  base.metadata = mergedMeta;
+  if (sub === "start" || sub === "advance") {
+    base.command = String(args["command"]);
+    base.step = parseInt(args["step"], 10);
+    base.step_label = String(args["step-label"]);
+    base.status = "in_progress";
+    base.completed_at = null;
+    if (!base.started_at) base.started_at = now;
+  } else if (sub === "done") {
+    base.status = "done";
+    base.completed_at = now;
+  } else if (sub === "skip") {
+    base.status = "skipped";
+    base.completed_at = now;
+  } else if (sub === "fail") {
+    base.status = "failed";
+    base.completed_at = now;
+  }
+  return base;
+}
+
+function main(argv, cwd) {
+  const args = _parseArgs(argv);
+  const sub = args._sub;
+  const err = _validate(sub, args);
+  if (err) {
+    process.stderr.write(`[gsd-t-watch-state] ${err}\n`);
+    return 1;
+  }
+  const agentId = _resolveAgentId(args);
+  const filePath = path.join(_stateDir(cwd), `${agentId}.json`);
+  const existing = _readExisting(filePath);
+  const record = _buildRecord(sub, args, existing, agentId);
+  try {
+    _atomicWrite(filePath, record);
+  } catch (e) {
+    process.stderr.write(`[gsd-t-watch-state] fs error: ${e.message}\n`);
+    return 2;
+  }
+  return 0;
+}
+
+if (require.main === module) {
+  const code = main(process.argv.slice(2));
+  process.exit(code);
+}
+
+module.exports = { main, _parseArgs, _validate, _buildRecord, _stateDir };