npm - @tekyzinc/gsd-t - Versions diffs - 3.23.11 → 3.25.10 - Mend

@tekyzinc/gsd-t 3.23.11 → 3.25.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (74) hide show

package/CHANGELOG.md +48 -0
package/README.md +7 -0
package/bin/cli-preflight-checks/branch-guard.cjs +110 -0
package/bin/cli-preflight-checks/contracts-stable.cjs +128 -0
package/bin/cli-preflight-checks/deps-installed.cjs +89 -0
package/bin/cli-preflight-checks/manifest-fresh.cjs +98 -0
package/bin/cli-preflight-checks/ports-free.cjs +110 -0
package/bin/cli-preflight-checks/working-tree-state.cjs +149 -0
package/bin/cli-preflight.cjs +265 -0
package/bin/gsd-t-context-brief-kinds/design-verify.cjs +139 -0
package/bin/gsd-t-context-brief-kinds/execute.cjs +205 -0
package/bin/gsd-t-context-brief-kinds/qa.cjs +130 -0
package/bin/gsd-t-context-brief-kinds/red-team.cjs +131 -0
package/bin/gsd-t-context-brief-kinds/scan.cjs +118 -0
package/bin/gsd-t-context-brief-kinds/verify.cjs +157 -0
package/bin/gsd-t-context-brief.cjs +395 -0
package/bin/gsd-t-ratelimit-probe-worker.cjs +236 -0
package/bin/gsd-t-ratelimit-probe.cjs +648 -0
package/bin/gsd-t-verify-gate-judge.cjs +224 -0
package/bin/gsd-t-verify-gate.cjs +612 -0
package/bin/gsd-t.js +45 -1
package/bin/live-activity-report.cjs +615 -0
package/bin/m55-substrate-proof.cjs +134 -0
package/bin/parallel-cli-tee.cjs +206 -0
package/bin/parallel-cli.cjs +478 -0
package/commands/gsd-t-execute.md +31 -0
package/commands/gsd-t-help.md +21 -0
package/commands/gsd-t-verify.md +38 -0
package/docs/architecture.md +194 -0
package/docs/diagrams/.gsd-t/.context-meter-state.json +10 -0
package/docs/diagrams/.gsd-t/context-meter.log +9 -0
package/docs/diagrams/.gsd-t/events/2026-05-08.jsonl +45 -0
package/docs/diagrams/.gsd-t/events/2026-05-09.jsonl +1 -0
package/docs/diagrams/.gsd-t/heartbeat-cd9e7f59-ba5b-406a-9ed6-16762f039e81.jsonl +48 -0
package/docs/diagrams/01-top-level-map-d2.png +0 -0
package/docs/diagrams/01-top-level-map.d2 +77 -0
package/docs/diagrams/01-top-level-map.mmd +48 -0
package/docs/diagrams/01-top-level-map.png +0 -0
package/docs/diagrams/01-top-level-map.svg +126 -0
package/docs/diagrams/02-milestone-lifecycle-d2.png +0 -0
package/docs/diagrams/02-milestone-lifecycle.d2 +38 -0
package/docs/diagrams/02-milestone-lifecycle.mmd +36 -0
package/docs/diagrams/02-milestone-lifecycle.png +0 -0
package/docs/diagrams/02-milestone-lifecycle.svg +114 -0
package/docs/diagrams/03-wave-mode-d2.png +0 -0
package/docs/diagrams/03-wave-mode.d2 +33 -0
package/docs/diagrams/03-wave-mode.mmd +21 -0
package/docs/diagrams/03-wave-mode.png +0 -0
package/docs/diagrams/03-wave-mode.svg +113 -0
package/docs/diagrams/04-design-to-code-d2.png +0 -0
package/docs/diagrams/04-design-to-code.d2 +35 -0
package/docs/diagrams/04-design-to-code.mmd +29 -0
package/docs/diagrams/04-design-to-code.png +0 -0
package/docs/diagrams/04-design-to-code.svg +115 -0
package/docs/diagrams/05-backlog-d2.png +0 -0
package/docs/diagrams/05-backlog.d2 +40 -0
package/docs/diagrams/05-backlog.mmd +20 -0
package/docs/diagrams/05-backlog.png +0 -0
package/docs/diagrams/05-backlog.svg +113 -0
package/docs/diagrams/06-automation-utilities-d2.png +0 -0
package/docs/diagrams/06-automation-utilities.d2 +48 -0
package/docs/diagrams/06-automation-utilities.mmd +47 -0
package/docs/diagrams/06-automation-utilities.png +0 -0
package/docs/diagrams/06-automation-utilities.svg +110 -0
package/docs/diagrams/_theme.d2 +86 -0
package/docs/requirements.md +48 -0
package/docs/workflow-diagram.md +338 -0
package/package.json +1 -1
package/scripts/gsd-t-dashboard-server.js +190 -0
package/scripts/gsd-t-transcript.html +200 -0
package/templates/CLAUDE-global.md +46 -0
package/templates/prompts/design-verify-subagent.md +3 -0
package/templates/prompts/qa-subagent.md +3 -0
package/templates/prompts/red-team-subagent.md +3 -0

package/scripts/gsd-t-transcript.html CHANGED Viewed

@@ -209,6 +209,32 @@
     .frame.tool-use > .ts, .frame.thinking > .ts { padding: 8px 0 0 12px; }
     .frame.tool-result > .ts { padding-top: 8px; }
     .frame.compact-marker > .ts { padding: 0; min-width: 64px; }
+    /* M54 D2 T1 — LIVE ACTIVITY rail section.
+       Additive only. No existing CSS renamed or removed. */
+    #rail-live-activity { padding: 0 0 8px 0; border-bottom: 1px solid var(--border); margin-bottom: 4px; }
+    #rail-live-activity .la-heading { display: flex; align-items: center; justify-content: space-between; padding: 8px 12px 4px 12px; font-size: 11px; text-transform: uppercase; color: var(--fg-xdim); letter-spacing: 0.08em; }
+    .la-list { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 2px; }
+    .la-entry { display: grid; grid-template-columns: 10px 18px 1fr auto; align-items: center; gap: 4px; padding: 5px 12px; cursor: pointer; border-radius: 4px; font-size: 12px; }
+    .la-entry:hover { background: var(--bg-soft); }
+    .la-dot { width: 8px; height: 8px; border-radius: 50%; flex-shrink: 0; }
+    .la-dot-running { background: #2dd4bf; }
+    .la-dot-stale { background: var(--fg-xdim, #6b7280); }
+    .la-icon { font-family: var(--mono); font-size: 13px; text-align: center; color: var(--fg-dim); }
+    .la-label { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; max-width: 40ch; color: var(--fg); font-family: var(--mono); font-size: 11px; }
+    .la-duration { font-family: var(--mono); font-size: 11px; color: var(--fg-xdim); text-align: right; white-space: nowrap; }
+    .la-empty { padding: 4px 12px 0 12px; color: var(--fg-xdim); font-size: 11px; font-style: italic; }
+    /* Kind icon slots — glyphs set in JS via KIND_ICONS map */
+    .la-icon-bash   { color: var(--accent-warm, #f0a500); }
+    .la-icon-monitor { color: var(--accent, #58a6ff); }
+    .la-icon-tool   { color: var(--fg-dim, #8b949e); }
+    .la-icon-spawn  { color: var(--green, #3fb950); }
+    @keyframes accent-pulse {
+      0%   { box-shadow: inset 2px 0 0 0 #2dd4bf; opacity: 1; }
+      50%  { box-shadow: inset 2px 0 0 0 #2dd4bf; opacity: 0.6; }
+      100% { box-shadow: inset 2px 0 0 0 #2dd4bf; opacity: 1; }
+    }
+    .la-pulsing { animation: accent-pulse 1.5s ease-in-out infinite; }
   </style>
 </head>
 <body data-spawn-id="__SPAWN_ID__">
@@ -226,6 +252,15 @@
       <div class="rail-header"><span>★ Main Session</span></div>
       <div class="rail-body" id="rail-main-body"><div class="empty">No in-session conversation captured yet.</div></div>
     </section>
+    <!-- M54 D2 T1 — LIVE ACTIVITY section (additive, between Main Session and Live Spawns).
+         Populated by 5s polling JS (D2 T2). CSS @keyframes accent-pulse in <style> block above. -->
+    <section id="rail-live-activity">
+      <div class="la-heading"><span>⚡ Live Activity</span></div>
+      <ul id="la-list" class="la-list">
+        <!-- Entries injected by polling JS (T2). Empty section header visible when list is empty. -->
+      </ul>
+      <div class="la-empty" id="la-empty-msg">No active operations detected.</div>
+    </section>
     <section class="rail-live" data-rail-section="live">
       <div class="rail-header"><span>Live Spawns</span></div>
       <div class="rail-body">
@@ -1615,6 +1650,171 @@
         poll();
         setInterval(poll, 5000);
       })();
+      // ── M54 D2 T2 — Live Activity Rail ────────────────────────────────────
+      // Polls /api/live-activity every 5s (same cadence as /api/parallelism).
+      // Appends entries to #la-list, applies .la-pulsing on new entries,
+      // removes entries when they disappear from the API response.
+      // Click handler: stopPulse + loadTailUrl (NO auto-switch on arrival).
+      // Additive only — no existing function renamed or removed.
+      (function wireLiveActivity() {
+        const laList = document.getElementById('la-list');
+        const laEmpty = document.getElementById('la-empty-msg');
+        if (!laList) return; // section not present in this page variant
+        // Map of id → { element, startedAt, stopPulseTimer }
+        const _current = new Map();
+        // Format duration in seconds as human-readable string
+        function fmtDuration(ms) {
+          const s = Math.floor(ms / 1000);
+          if (s < 60) return s + 's';
+          const m = Math.floor(s / 60), rs = s % 60;
+          if (m < 60) return m + 'm ' + rs + 's';
+          const h = Math.floor(m / 60), rm = m % 60;
+          return h + 'h ' + rm + 'm';
+        }
+        // Kind icon mapping
+        const KIND_ICONS = { bash: '$', monitor: '👁', tool: '🔧', spawn: '↳' };
+        // Load the tailUrl content into the bottom pane (mirrors existing bottom-pane loaders)
+        function loadTailUrl(tailUrl) {
+          const streamEl = document.getElementById('stream');
+          if (!streamEl) return;
+          fetch(tailUrl)
+            .then(function(r) { return r.text(); })
+            .then(function(text) {
+              streamEl.innerHTML = '<pre style="margin:0;padding:12px;font-family:var(--mono);font-size:12px;white-space:pre-wrap;word-break:break-word;">' + _esc(text) + '</pre>';
+            })
+            .catch(function(err) {
+              console.log('[la] tail load error:', err && err.message);
+            });
+        }
+        function _esc(s) {
+          return String(s).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');
+        }
+        // Remove .la-pulsing from entry element
+        function stopPulse(id) {
+          const item = _current.get(id);
+          if (!item || !item.element) return;
+          item.element.classList.remove('la-pulsing');
+          if (item.stopPulseTimer) { clearTimeout(item.stopPulseTimer); item.stopPulseTimer = null; }
+        }
+        // Append a new .la-entry to #la-list
+        function appendActivity(entry) {
+          const li = document.createElement('li');
+          li.className = 'la-entry la-pulsing';
+          li.setAttribute('data-id', entry.id);
+          li.setAttribute('data-kind', entry.kind);
+          li.setAttribute('data-tail-url', entry.tailUrl || '');
+          const dot = document.createElement('span');
+          dot.className = 'la-dot la-dot-running';
+          li.appendChild(dot);
+          const icon = document.createElement('span');
+          icon.className = 'la-icon la-icon-' + entry.kind;
+          icon.textContent = KIND_ICONS[entry.kind] || '?';
+          li.appendChild(icon);
+          const label = document.createElement('span');
+          label.className = 'la-label';
+          const labelText = String(entry.label || '').slice(0, 40);
+          label.textContent = labelText;
+          label.title = entry.label || '';
+          li.appendChild(label);
+          const dur = document.createElement('span');
+          dur.className = 'la-duration';
+          dur.textContent = fmtDuration(entry.durationMs || 0);
+          li.appendChild(dur);
+          li.addEventListener('click', function() {
+            stopPulse(entry.id);
+            if (entry.tailUrl) loadTailUrl(entry.tailUrl);
+          });
+          laList.appendChild(li);
+          // Schedule pulse stop after 30s (condition c)
+          const timer = setTimeout(function() { stopPulse(entry.id); }, 30000);
+          _current.set(entry.id, { element: li, startedAt: entry.startedAt, stopPulseTimer: timer });
+          if (laEmpty) laEmpty.style.display = 'none';
+        }
+        // Remove a .la-entry from #la-list
+        function removeActivity(id) {
+          const item = _current.get(id);
+          if (!item) return;
+          if (item.stopPulseTimer) clearTimeout(item.stopPulseTimer);
+          if (item.element && item.element.parentNode) item.element.parentNode.removeChild(item.element);
+          _current.delete(id);
+          if (laEmpty && _current.size === 0) laEmpty.style.display = '';
+        }
+        // Update the duration counter for an existing entry
+        function updateDuration(id, startedAt) {
+          const item = _current.get(id);
+          if (!item || !item.element) return;
+          const dur = item.element.querySelector('.la-duration');
+          if (!dur) return;
+          const start = startedAt ? new Date(startedAt).getTime() : 0;
+          const elapsed = start ? Math.max(0, Date.now() - start) : 0;
+          dur.textContent = fmtDuration(elapsed);
+        }
+        // Fetch /api/live-activity, return envelope (or {activities:[]} on error)
+        async function fetchLiveActivity() {
+          try {
+            const r = await fetch('/api/live-activity');
+            if (!r.ok) {
+              console.log('[la] /api/live-activity returned', r.status);
+              return { activities: [] };
+            }
+            return await r.json();
+          } catch (err) {
+            console.log('[la] fetch error:', err && err.message);
+            return { activities: [] };
+          }
+        }
+        // Reconcile current DOM state with new API response
+        function reconcile(activities) {
+          // Build a Map of new activities by id
+          const newById = new Map();
+          for (const entry of (activities || [])) {
+            newById.set(entry.id, entry);
+          }
+          // Remove entries no longer present
+          for (const id of Array.from(_current.keys())) {
+            if (!newById.has(id)) removeActivity(id);
+          }
+          // Add new entries; update durations for existing ones
+          for (const [id, entry] of newById) {
+            if (_current.has(id)) {
+              updateDuration(id, entry.startedAt);
+            } else {
+              appendActivity(entry);
+            }
+          }
+        }
+        // Initial poll + 5s interval (same cadence as /api/parallelism)
+        async function poll() {
+          const data = await fetchLiveActivity();
+          reconcile(data.activities);
+        }
+        poll();
+        setInterval(poll, 5000);
+      })();
     })();
   </script>
 </body>

package/templates/CLAUDE-global.md CHANGED Viewed

@@ -412,6 +412,52 @@ No command file ships a bare `Task(...)` or `claude -p` line outside of a wrappe
 Rationale: the pre-M41 convention silently wrote `N/A` tokens because no caller parsed the `usage` envelope. The wrapper is the single place that parses it. Bypassing the wrapper re-introduces blind spots.
+## Mandatory Preflight Before Spawn (M55 — v3.25.10+)
+Every command that spawns a Task subagent or invokes `claude -p` MUST run `gsd-t preflight` first. Hard-fails on any `severity:"error"` check (wrong branch, occupied required port). Non-error checks (warn/info) record but do not block.
+```bash
+gsd-t preflight --json > /tmp/gsd-t-preflight.json || exit 4
+```
+Catches drift early — wrong branch, port collision, DRAFT contracts past PARTITIONED — before any LLM work fires. Same envelope is consumed by `gsd-t verify-gate` Track 1, so failing fast at execute time saves the verify round-trip.
+Library: `bin/cli-preflight.cjs::runPreflight({projectDir, checks?})`.
+Contract: `.gsd-t/contracts/cli-preflight-contract.md` v1.0.0 STABLE.
+## Brief-First Worker Rule (M55 — v3.25.10+)
+Every parallel worker prompt scaffold MUST thread `$BRIEF_PATH` — a ≤2,500-token JSON snapshot generated once per spawn by `bin/gsd-t-context-brief.cjs`. The brief replaces the 30–60k context re-read every parallel worker would otherwise perform (CLAUDE.md + contracts + scope + relevant code) — the dominant ITPM-relief lever in M55.
+```bash
+SPAWN_ID="execute-${DOMAIN}-$(date -u +%Y%m%dT%H%M%SZ)"
+gsd-t brief --kind execute --domain "${DOMAIN}" --spawn-id "${SPAWN_ID}" --out ".gsd-t/briefs/${SPAWN_ID}.json"
+export BRIEF_PATH=".gsd-t/briefs/${SPAWN_ID}.json"
+```
+The 3 validation-subagent protocols (`templates/prompts/{qa,red-team,design-verify}-subagent.md`) carry the canonical instruction "If you're about to grep, read, or run a test, check the brief first at `$BRIEF_PATH`." Workers grep the brief instead of re-walking the repo.
+`.gsd-t/briefs/` is gitignored — briefs are per-spawn ephemera, not committed artifacts.
+Library: `bin/gsd-t-context-brief.cjs::generateBrief(...)`.
+Contract: `.gsd-t/contracts/context-brief-contract.md` v1.0.0 STABLE.
+## Two-Track Verify-Gate (M55 — v3.25.10+)
+`gsd-t verify-gate --json` is the canonical pre-merge gate. Track 1 = D1 preflight envelope (hard-fail on any `severity:"error"` check). Track 2 = D2 parallel-CLI substrate fans out off-the-shelf CLIs (`tsc`, `biome`/`ruff`, `npm test`, `knip`, `gitleaks`, `scc`/`lizard`). Both tracks always run; both report.
+```bash
+gsd-t verify-gate --json > /tmp/gate.json || exit 4
+cat /tmp/gate.json | gsd-t verify-gate-judge > /tmp/judge-prompt.txt
+```
+`top-level ok = (skipTrack1 || track1.ok) && (skipTrack2 || track2.ok)` — purely deterministic. The LLM judge sees only the ≤500-token deterministic `summary`; never raw stdout/stderr. The judge confirms or contradicts the deterministic verdict; it never overrides `ok`.
+Defensive on missing `.gsd-t/ratelimit-map.json` → fallback `maxConcurrency=2` with a structured note.
+Library: `bin/gsd-t-verify-gate.cjs::runVerifyGate(...)` + `bin/gsd-t-verify-gate-judge.cjs::buildJudgePrompt(...)`.
+Contract: `.gsd-t/contracts/verify-gate-contract.md` v1.0.0 STABLE.
 ## Always-Headless Spawn (M43 D4, v3.16.x+) — Channel Separation
 Every GSD-T command spawns detached, unconditionally. There is no `--watch`, no `--in-session`, no `--headless` opt-in, no context-meter threshold that reroutes, no low-water-mark bypass. The dialog channel is reserved for human↔Claude conversation; everything else is a detached headless child. Interactive session shows a launch banner + live-transcript URL + event-stream path, then exits. Results surface via the read-back banner on the user's next message.

package/templates/prompts/design-verify-subagent.md CHANGED Viewed

@@ -4,6 +4,9 @@ You are the Design Verification Agent. Your ONLY job is to visually compare the
 **FAIL-BY-DEFAULT.** Every visual element starts UNVERIFIED. You must prove each one matches — never assume. "Looks close" is not a verdict. "Appears to match" is not a verdict. The only valid verdicts are `✅ MATCH` (with proof) or `❌ DEVIATION` (with specific values).
+<!-- M55-D5: brief-first rule -->
+**Brief first.** If you're about to grep, read, or run a test, check the brief first at `$BRIEF_PATH` (a ≤2,500-token JSON snapshot of design contracts + scope + design tokens + relevant component paths, generated by `bin/gsd-t-context-brief.cjs --kind design-verify`). The brief lists the design contracts, design-token files, and component paths in scope for this verification — your starting checklist. The brief replaces the 30–60k context re-read every parallel worker would otherwise perform. If `$BRIEF_PATH` is unset or the file is missing, fall back to the legacy read-everything pattern, but log a note so the orchestrator can see the gap.
 ## Step 0: Element Count Reconciliation (run BEFORE anything else)
 A missing widget is the easiest deviation to miss in a 30-row comparison table — and the most catastrophic.

package/templates/prompts/qa-subagent.md CHANGED Viewed

@@ -2,6 +2,9 @@
 You are the QA agent. Your sole job is test generation, execution, and gap reporting. You write ZERO feature code. You never modify implementation files — only test files and reports.
+<!-- M55-D5: brief-first rule -->
+**Brief first.** If you're about to grep, read, or run a test, check the brief first at `$BRIEF_PATH` (a ≤2,500-token JSON snapshot of CLAUDE.md + contracts + scope + constraints, generated by `bin/gsd-t-context-brief.cjs`). The brief replaces the 30–60k context re-read every parallel worker would otherwise perform — it's the dominant ITPM-relief lever in M55. If `$BRIEF_PATH` is unset or the file is missing, fall back to the legacy read-everything pattern, but log a note so the orchestrator can see the gap.
 ## What to Do
 1. **Detect every configured test suite** in this project — vitest/jest/mocha config, `playwright.config.*`, `cypress.config.*`. Run EVERY suite that exists.

package/templates/prompts/red-team-subagent.md CHANGED Viewed

@@ -2,6 +2,9 @@
 You are a Red Team QA adversary. Your job is to BREAK the code that was just written for this domain. You operate with inverted incentives — your value is measured by REAL bugs found, not tests passed.
+<!-- M55-D5: brief-first rule -->
+**Brief first.** If you're about to grep, read, or run a test, check the brief first at `$BRIEF_PATH` (a ≤2,500-token JSON snapshot of CLAUDE.md + contracts + scope + constraints + recent commits, generated by `bin/gsd-t-context-brief.cjs --kind red-team`). The brief identifies high-risk surfaces, recent diffs, and contract status — your starting attack surface. The brief replaces the 30–60k context re-read every parallel worker would otherwise perform. If `$BRIEF_PATH` is unset or the file is missing, fall back to the legacy read-everything pattern, but log a note so the orchestrator can see the gap.
 ## Hard Rules
 - **Bugs found = value.** A short attack list is failure.