@tekyzinc/gsd-t 3.29.11 → 4.0.12

package/templates/CLAUDE-global.md

@@ -201,14 +201,14 @@ If any are missing:
 Playwright readiness is enforced by executable code, not prose. Three layers:
 
 1. **Bootstrap library** — `bin/playwright-bootstrap.cjs` exports `hasPlaywright`, `detectPackageManager`, `installPlaywright`, `verifyPlaywrightHealth`. `bin/ui-detection.cjs` exports `hasUI`, `detectUIFlavor`. See `.gsd-t/contracts/playwright-bootstrap-contract.md`.
-2. **Spawn-time gate** — `bin/headless-auto-spawn.cjs::autoSpawnHeadless()` auto-installs Playwright before the spawn proceeds, when the command being run is in the testing/UI whitelist (`gsd-t-execute`, `gsd-t-test-sync`, `gsd-t-verify`, `gsd-t-quick`, `gsd-t-wave`, `gsd-t-milestone`, `gsd-t-complete-milestone`, `gsd-t-debug`, `gsd-t-integrate`) AND `hasUI(projectDir)` AND `!hasPlaywright(projectDir)`. On install failure, the gate writes `mode: 'blocked-needs-human'` to the headless session-state file and exits 4.
+2. **Workflow-stage gate** — the verify/execute Workflow scripts call `playwright-bootstrap.cjs::installPlaywright()` before any E2E stage when `hasUI(projectDir)` AND `!hasPlaywright(projectDir)`. On install failure the stage halts with a structured `blocked-needs-human` result. (M61: replaced the retired `headless-auto-spawn.cjs` spawn-time gate — the Workflow runtime owns spawning now.)
 3. **Commit-time gate** — `scripts/hooks/pre-commit-playwright-gate` (opt-in via `gsd-t doctor --install-hooks`) blocks commits that touch viewer/UI source files when Playwright tests have not passed since the most recent change. Reads `.gsd-t/.last-playwright-pass`; fails open on missing/corrupt timestamps.
 
 Operator overrides:
 - Manual install: `gsd-t setup-playwright [path]` (or `gsd-t doctor --install-playwright`).
 - Health check: `gsd-t doctor` reports `playwright missing` for any UI project without `playwright.config.*`.
 
-You no longer need to run a check yourself before testing commands — the gate runs every spawn.
+You no longer need to run a check yourself before testing commands — the Workflow stage runs the readiness gate before E2E.
 
 ### Playwright Cleanup
 
@@ -290,213 +290,83 @@ Three built-in adapters: `localStorage-key-prefix`, `file-json-array`, `sqlite-t
 
 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)
+## Orthogonal Validation Triad (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.
-Protocol: `templates/prompts/qa-subagent.md`. Contract: `.gsd-t/contracts/qa-agent-contract.md`.
+Every code-producing phase ends with `gsd-t-verify.workflow.js`, which runs three orthogonal validators as `parallel()` `agent()` stages with schema-validated output. Per `.gsd-t/contracts/orthogonal-validation-contract.md` v1.0.0 STABLE, they are declared orthogonal objective functions — no collapse, no substitution, no transitive trust.
 
-## Design Verification Agent (Mandatory when design contract exists)
+- **`/code-review ultra`** — cooperative correctness + cleanup. Severity: `important` / `nit` / `pre-existing`. Skippable via `args.skipUltra=true` + `args.skipUltraReason`. `skipUltra=true` is INELIGIBLE for `VERIFIED`.
+- **Red Team** — adversarial / security / boundaries. Non-skippable. Protocol: `templates/prompts/red-team-subagent.md`. Verdict: `FAIL` (any CRITICAL or HIGH bug — blocks completion) or `GRUDGING-PASS` (exhaustive search, nothing found). CRITICAL/HIGH bugs get up to 2 fix cycles before deferral. Runs on `model: "opus"`.
+- **QA** — test execution + shallow-test detection + contract compliance. Non-skippable. Protocol: `templates/prompts/qa-subagent.md`. Writes ZERO feature code. Any shallow E2E test blocks phase completion. Runs on `model: "sonnet"`.
 
-When `.gsd-t/contracts/design-contract.md` or `.gsd-t/contracts/design/` exists, a dedicated agent opens a browser, compares the build against the design, and writes a structured element-by-element MATCH/DEVIATION table. Writes ZERO feature code. Deviations (or missing verification artifact) block phase completion.
-Protocol: `templates/prompts/design-verify-subagent.md`.
+When `.gsd-t/contracts/design-contract.md` or `.gsd-t/contracts/design/` exists, a fourth stage runs Design Verification (protocol: `templates/prompts/design-verify-subagent.md`) — opens a browser, compares the build against the design, returns a structured element-by-element MATCH/DEVIATION schema. Deviations block completion.
 
-## Red Team — Adversarial QA (Mandatory)
-
-After QA + Design Verification pass, every code-producing command spawns an adversarial subagent whose success is measured by bugs found, not tests passed. VERDICT is `FAIL` (bugs — blocks completion) or `GRUDGING PASS` (exhaustive search, nothing found). CRITICAL/HIGH bugs get up to 2 fix cycles before deferral.
-Protocol: `templates/prompts/red-team-subagent.md`.
+Synthesis stage merges results without category collapse. Verdict: `VERIFIED` / `VERIFIED-WITH-WARNINGS` / `VERIFY-FAILED`.
 
 ## Model Display (MANDATORY)
 
-**Before every subagent spawn, display the model being used to the user:**
-`⚙ [{model}] {command} → {brief description}` (e.g., `⚙ [sonnet] gsd-t-execute → domain: auth-service`, `⚙ [haiku] gsd-t-execute → QA validation`)
-
-This gives the user real-time visibility into which model is handling each operation.
+**Each Workflow `agent()` call declares its model explicitly** via the `model:` option (`"haiku"` / `"sonnet"` / `"opus"`). The Workflow runtime emits a `⚙ [{model}] {label}` line per stage in `/workflows`, giving the user real-time visibility into which model handles each operation.
 
 **Model assignments:**
-- `model: haiku` — strictly mechanical tasks: run test suites and report counts, check file existence, validate JSON structure, branch guard checks
-- `model: sonnet` — mid-tier reasoning: routine code changes, standard refactors, test writing, QA evaluation, straightforward synthesis
-- `model: opus` — high-stakes reasoning: architecture decisions, security analysis, complex debugging, cross-module refactors, Red Team adversarial QA, quality judgment on critical paths
-
-**Context Meter (M34/M38, v3.12.10+)** — The real context-window measurement feeding the headless-default spawn decision. A PostToolUse hook (`scripts/gsd-t-context-meter.js`) runs after every tool call, uses local token estimation to write the current input-token count into `.gsd-t/.context-meter-state.json`. `getSessionStatus()` reads that state file (fresh window = 5 minutes) with a historical heuristic fallback when the file is missing or stale. Command files consume the signal via a small bash shim (`CTX_PCT=$(node -e "…tb.getSessionStatus('.').pct")`). **Single-band model** (context-meter-contract v1.3.0): there's one threshold (default 85%) and one action — hand off to a detached headless spawn. No three-band routing, no silent downgrades, no MANDATORY STOP prose. The meter exists to inform spawn-time routing, not to pause work in-flight.
-
-## In-Session Conversation Capture (M45 D2)
-
-The orchestrator session's user↔assistant dialog is captured into
-`.gsd-t/transcripts/in-session-{sessionId}.ndjson` via a dedicated hook
-script (`scripts/hooks/gsd-t-conversation-capture.js`). The viewer's left
-rail labels these entries `💬 conversation` (front-end-only discriminator
-— the `in-session-` filename prefix is the contract).
-
-This hook captures **content** (user prompts + assistant replies). It is
-complementary to `scripts/hooks/gsd-t-in-session-usage-hook.js` (M43 D1),
-which captures per-turn **token usage** into
-`.gsd-t/metrics/token-usage.jsonl`. Both hooks coexist on the same events.
-
-**Install block** (append to `~/.claude/settings.json` alongside the existing
-context-meter, version-check, compact-detector, and in-session-usage hooks):
-
-```json
-{
-  "hooks": {
-    "SessionStart": [
-      { "matcher": "",
-        "hooks": [{ "type": "command",
-                    "command": "node \"$HOME/.claude/scripts/hooks/gsd-t-conversation-capture.js\"",
-                    "async": true }] }
-    ],
-    "UserPromptSubmit": [
-      { "matcher": "",
-        "hooks": [{ "type": "command",
-                    "command": "node \"$HOME/.claude/scripts/hooks/gsd-t-conversation-capture.js\"",
-                    "async": true }] }
-    ],
-    "Stop": [
-      { "matcher": "",
-        "hooks": [{ "type": "command",
-                    "command": "node \"$HOME/.claude/scripts/hooks/gsd-t-conversation-capture.js\"",
-                    "async": true }] }
-    ],
-    "PostToolUse": [
-      { "matcher": "",
-        "hooks": [{ "type": "command",
-                    "command": "GSD_T_CAPTURE_TOOL_USES=1 node \"$HOME/.claude/scripts/hooks/gsd-t-conversation-capture.js\"",
-                    "async": true }] }
-    ]
-  }
-}
-```
-
-The `PostToolUse` entry is **opt-in** via `GSD_T_CAPTURE_TOOL_USES=1`. Leave it
-unset unless you want per-tool frames in the NDJSON (full tool payloads are
-already recorded in `events/*.jsonl`).
-
-Contract: `.gsd-t/contracts/conversation-capture-contract.md` v1.0.0. Frame
-schema, file-naming, and session-id resolution rules are locked there.
+- `model: "haiku"` — strictly mechanical tasks: run test suites and report counts, check file existence, validate JSON structure, branch guard checks
+- `model: "sonnet"` — mid-tier reasoning: routine code changes, standard refactors, test writing, QA evaluation, straightforward synthesis
+- `model: "opus"` — high-stakes reasoning: architecture decisions, security analysis, complex debugging, cross-module refactors, Red Team adversarial QA, quality judgment on critical paths
 
-## Observability Logging (MANDATORY)
+**Context budget:** Workflow scripts receive a `budget` global (`budget.total`, `budget.spent()`, `budget.remaining()`) tied to the user's per-turn token target. Use it for dynamic loops (`while (budget.total && budget.remaining() > 50_000) { ... }`) or to scale fleet size. Opus 4.7/4.8 ship 1M context windows; the legacy meter at `bin/token-budget.cjs` was retired in M61 — use native `/context` for live in-session usage.
 
-Every command that spawns a Task subagent, invokes `claude -p`, or calls `spawn('claude', ...)` MUST route the spawn through `bin/gsd-t-token-capture.cjs` so the real token-usage envelope is parsed and recorded. This is the M41 canonical pattern — the pre-M41 bash block that wrote `| N/A |` is retired.
-
-### Pattern A — wrap a spawn callable with `captureSpawn`
-
-Preferred for new spawn sites. The wrapper owns the before/after timing, model banner, envelope parse, row write, and JSONL record.
-
-```
-node -e "
-const { captureSpawn } = require('./bin/gsd-t-token-capture.cjs');
-(async () => {
-  await captureSpawn({
-    command: 'gsd-t-execute',
-    step: 'Step 4',
-    model: 'sonnet',
-    description: 'domain: auth-service',
-    projectDir: '.',
-    domain: 'auth-service',
-    task: 'T-3',
-    spawnFn: async () => { /* actual Task(...) or spawn('claude', ...) call */ },
-  });
-})();
-"
-```
+## Desktop as Cockpit (M61 SC7 — v4.0.10+)
 
-### Pattern B — record after the result envelope is already in hand
+Routine GSD-T actions (milestone → partition → plan → execute → verify → deliver) run from the Claude Code desktop app via Workflows + Skills. CLI residue is intentional and limited to: (a) background hooks the harness fires automatically, (b) jobs that must outlive the desktop session. No routine build / rebuild / debug / deliver action should require terminal keystrokes.
 
-For command files where the Task subagent already ran and the caller has the result object. Identical row format, no timing wrap.
+## GSD-T Workflows (M61 — v4.0.10+)
 
-```
-node -e "
-const { recordSpawnRow } = require('./bin/gsd-t-token-capture.cjs');
-recordSpawnRow({
-  projectDir: '.',
-  command: 'gsd-t-verify',
-  step: 'Step 4',
-  model: 'haiku',
-  startedAt: '2026-04-21 10:00',
-  endedAt:   '2026-04-21 10:02',
-  usage: result.usage, // may be undefined — wrapper handles with '—'
-  domain: '-', task: '-',
-  ctxPct: 42,
-  notes: 'test audit + contract review',
-});
-"
-```
+GSD-T workflows live at `templates/workflows/`. Each workflow is a self-contained native Workflow script that handles one phase of the GSD-T lifecycle. Command files (`commands/gsd-t-*.md`) are thin invokers that call `Workflow({scriptPath, args})`.
 
-### Canonical `.gsd-t/token-log.md` header
+Canonical scripts:
+- `gsd-t-execute.workflow.js` — preflight → brief → file-disjointness → parallel(domain workers) → integrate → verify-gate
+- `gsd-t-verify.workflow.js` — preflight → verify-gate → M57 CI-parity → M58 test-data purge → parallel(/code-review ultra ∥ Red Team ∥ QA) → synthesis
+- `gsd-t-wave.workflow.js` — composes execute + verify as sub-workflows
+- `gsd-t-integrate.workflow.js` — cross-domain wire-up + light verify-gate
+- `gsd-t-debug.workflow.js` — 2-cycle diagnose/fix/verify (CLAUDE.md Prime Rule)
+- `gsd-t-quick.workflow.js` — preflight + brief + single-task + verify-gate (M56-D4)
+- `gsd-t-phase.workflow.js` — generic upper-stage runner (partition / plan / discuss / impact / milestone / prd / design-decompose / doc-ripple)
 
-```
-| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Tokens | Notes | Domain | Task | Ctx% |
-```
+Shared helpers: `templates/workflows/_lib.js` — `runPreflight`, `generateBrief`, `proveFileDisjointness`, `runVerifyGate`, `loadProtocol`, `readDomainTasks`, `readScope`. Each prefers project-local `bin/<tool>.cjs` and falls back to global `gsd-t` PATH binary (preserves M55-D5 project-local-bin invariant).
 
-The wrapper detects old headers (no `Tokens` column) and upgrades in place, preserving existing rows. The **Tokens** cell renders as `in=N out=N cr=N cc=N $X.XX` when usage is present, or `—` when absent. Never `0`. Never `N/A`. A zero is a measurement; a dash is an acknowledged gap.
+## Preflight Gate (KEPT from M55)
 
-For QA/validation subagents, append findings to `.gsd-t/qa-issues.md`:
-```
-| Date | Command | Step | Model | Duration(s) | Severity | Finding |
-```
-
-## Token Capture Rule (MANDATORY)
-
-Every `Task(...)` subagent spawn, every `claude -p` child process, and every `spawn('claude', ...)` call MUST flow through `bin/gsd-t-token-capture.cjs`. Either wrap with `captureSpawn({..., spawnFn})` or record explicitly with `recordSpawnRow({...})` after the call returns.
-
-No command file ships a bare `Task(...)` or `claude -p` line outside of a wrapper call. `gsd-t capture-lint` (D5) enforces this mechanically; violations fail the opt-in pre-commit hook.
-
-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.
+Every Workflow script begins with `lib.runPreflight({projectDir})`. Hard-fails on any `severity:"error"` check (wrong branch, occupied required port). Non-error checks record but do not block. Same envelope feeds `verify-gate` Track 1.
 
 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+)
+## Brief-First Worker Rule (KEPT from M55, REFRAMED for M61)
 
-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.
+Every Workflow `agent()` call threads `$BRIEF_PATH` — a ≤2,500-token JSON snapshot generated by `bin/gsd-t-context-brief.cjs`. Workers grep the brief instead of re-walking the repo. `execute.workflow.js` generates a per-domain brief inside the `parallel()` map (M55-D2 brief-per-spawn semantic).
 
-```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.
+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`."
 
 `.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+)
+## Verify-Gate + Orthogonal Validation Triad (M61 v4.0.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.
+`gsd-t verify-gate --json` runs as a deterministic stage inside `gsd-t-verify.workflow.js`. Track 1 = preflight envelope. Track 2 = parallel-CLI substrate (`tsc`, `biome`/`ruff`, `npm test`, `knip`, `gitleaks`, `scc`/`lizard`). Both tracks always run; non-zero exit halts before the orthogonal triad.
 
-```bash
-gsd-t verify-gate --json > /tmp/gate.json || exit 4
-cat /tmp/gate.json | gsd-t verify-gate-judge > /tmp/judge-prompt.txt
-```
+After verify-gate, `verify.workflow.js` runs two FAIL-blocking gates inherited from M57 + M58:
+- M57 CI-Parity: `gsd-t build-coverage` + `gsd-t ci-parity` (origin TimeTracking v1.10.12 Dockerfile incident)
+- M58 Test-Data Purge: `gsd-t test-data --purge --run <id>` (origin GSD-T-Board v0.1.10 2442 E2E orphans incident)
 
-`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`.
+Then the orthogonal validation triad runs as `parallel()` `agent()` stages per `.gsd-t/contracts/orthogonal-validation-contract.md` v1.0.0 STABLE:
+- `/code-review ultra` — cooperative correctness + cleanup (skippable; requires `skipUltraReason`)
+- Red Team — adversarial / security / boundaries (non-skippable; verdict `FAIL` / `GRUDGING-PASS`)
+- QA — test mechanics + shallow-test detection + contract compliance (non-skippable)
 
-Defensive on missing `.gsd-t/ratelimit-map.json` → fallback `maxConcurrency=2` with a structured note.
+Synthesis stage merges results WITHOUT collapsing categories. Verdict: `VERIFIED` / `VERIFIED-WITH-WARNINGS` / `VERIFY-FAILED`. `skipUltra=true` is INELIGIBLE for `VERIFIED`.
 
 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.
-
-The only in-session surface is the `/gsd` router (`commands/gsd.md`), and only for dialog-only exploratory turns. The moment Step 2.5 classifies a turn as `workflow`, the router hands off to a detached spawn.
-
-Legacy `watch` / `inSession` params are accepted-and-ignored with a one-shot stderr deprecation warning (scheduled removal in v3.0.0 of the contract). `shouldSpawnHeadless` is a constant `() => true`.
-
-Contract: `.gsd-t/contracts/headless-default-contract.md` v2.0.0 (see also `unattended-event-stream-contract.md`, `unattended-supervisor-contract.md`).
+Contracts: `verify-gate-contract.md` v1.0.0 STABLE + `orthogonal-validation-contract.md` v1.0.0 STABLE.
 
 ## API Documentation Guard (Swagger/OpenAPI)
 

package/templates/CLAUDE-project.md

@@ -1,113 +1,127 @@
-# {Project Name}
+# GSD-T Framework (@tekyzinc/gsd-t)
+
+Prime Directives, core guards, and workflow rules live in `~/.claude/CLAUDE.md`. This file covers what's specific to this repo.
 
 ## Overview
-{Brief project description — what problem does this solve and for whom?}
+
+Contract-driven development methodology for Claude Code. npm package providing slash commands, a CLI installer, templates, and stack rules for reliable parallelizable AI-assisted development.
 
 ## Autonomy Level
-**Level 3 — Full Auto** (only pause for blockers or completion)
-<!-- Options: Level 1 (Supervised), Level 2 (Standard), Level 3 (Full Auto) -->
+
+> Overrides global: pins the default from `~/.claude/CLAUDE.md` § Autonomy Levels.
+
+**Level 3 — Full Auto**. Only pause for blockers, destructive actions, or project completion.
 
 ## Tech Stack
-- **Language**: {e.g., Python 3.12}
-- **Framework**: {e.g., FastAPI}
-- **Database**: {e.g., PostgreSQL with SQLAlchemy async}
-- **Frontend**: {e.g., Jinja2 templates, React, etc.}
-- **Testing**: {e.g., Playwright}
-- **Deployment**: {e.g., Google Cloud Run}
-
-## Documentation
-- Requirements: docs/requirements.md
-- Architecture: docs/architecture.md
-- Workflows: docs/workflows.md
-- Infrastructure: docs/infrastructure.md
-
-## Branch Guard
-<!-- Declare which branch this terminal session should work on. -->
-<!-- Claude will verify the branch before every commit. -->
-**Expected branch**: {main | master | feature-branch-name}
-
-## Context Meter (M34/M38/M43 D4, v3.16.x+) — Observational Only
-<!-- The Context Meter is a PostToolUse hook that uses local token estimation -->
-<!-- and writes the current context % to .gsd-t/.context-meter-state.json. -->
-<!-- Under M43 D4 (channel-separation inversion) the meter is OBSERVATIONAL ONLY: -->
-<!-- the pct is recorded into the token-log Ctx% column on the next spawn, -->
-<!-- but no threshold gates any routing decision. Every command spawns detached -->
-<!-- unconditionally (see Always-Headless section below). -->
-<!-- Config: .gsd-t/context-meter-config.json — modelWindowSize, checkFrequency. -->
-<!-- Verify: `npx @tekyzinc/gsd-t doctor`. -->
-
-## Always-Headless Spawn (M43 D4, v3.16.x+) — Channel Separation
-<!-- Every GSD-T command spawns detached, unconditionally. No --watch flag. -->
-<!-- No --in-session flag. No --headless opt-in. No context-meter threshold -->
-<!-- that reroutes. The dialog channel is reserved for human↔Claude conversation; -->
-<!-- every workflow turn 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. -->
-<!-- The only in-session surface is the /gsd router, and only for dialog-only -->
-<!-- exploratory turns (Step 2.5 classifier → `conversational`). -->
-<!-- Legacy watch/inSession params on autoSpawnHeadless() are accepted-and-ignored. -->
-<!-- Contracts: headless-default-contract.md v2.0.0, unattended-event-stream-contract.md v1.0.0, -->
-<!-- unattended-supervisor-contract.md v1.1.0. -->
-
-## Model Selection
-<!-- Model choice is made surgically per-phase via bin/model-selector.js (model-selection-contract.md v1.0.0): -->
-<!--   - haiku  — mechanical: test runners, file-existence checks, JSON validation, branch guards -->
-<!--   - sonnet — routine: execute, test-sync, doc-ripple wiring, quick, integrate, debug fix-apply -->
-<!--   - opus   — high-stakes: partition, Red Team, verify judgment, debug root-cause, contracts -->
-
-<!-- For multi-branch parallel work (e.g., web + mobile in separate terminals), -->
-<!-- each terminal's CLAUDE.md should declare its own expected branch. -->
-<!-- Example: Web terminal → master, Mobile terminal → Mobile -->
-
-## Quality North Star
-
-<!-- Define the quality identity of this project. Subagents read this section and apply it as a quality lens. -->
-<!-- Choose one of the presets below or write your own 1–3 sentence persona, then remove the others. -->
-
-<!-- PRESET: library (npm package, SDK, shared utility) -->
-<!-- This is a published npm library. Every public API must be intuitive, well-documented, and backward-compatible. Type safety and zero-dependency design are non-negotiable. -->
-
-<!-- PRESET: web-app (user-facing web application) -->
-<!-- This is a user-facing web application. Every feature must be accessible, performant, and visually consistent. The user experience is the product. -->
-
-<!-- PRESET: cli (developer CLI or command-line utility) -->
-<!-- This is a developer CLI tool. Every command must be fast, predictable, and produce clear output. Error messages must explain what went wrong and how to fix it. -->
-
-<!-- CUSTOM: replace this line with your own 1–3 sentence quality persona -->
-{Quality persona — describe what "excellent" means for this project}
-
-## GSD-T Workflow
-This project uses contract-driven development.
-- State: .gsd-t/progress.md
-- Contracts: .gsd-t/contracts/
-- Domains: .gsd-t/domains/
-
-## Workflow Preferences
-<!-- Override global defaults from ~/.claude/CLAUDE.md -->
-<!-- Delete lines you don't need to override — globals apply automatically -->
-
-### Research Policy
-<!-- Example overrides: -->
-<!-- "Always research — this project uses cutting-edge APIs" -->
-<!-- "Skip research — well-understood CRUD app" -->
-
-### Phase Flow
-<!-- Example overrides: -->
-<!-- "ALWAYS run Discussion — architecture decisions are critical" -->
-<!-- "Skip discuss unless truly required" -->
-
-## Project-Specific Conventions
-<!-- Add conventions that override or extend the global CLAUDE.md -->
-
-## Don't Do These Things
-<!-- Add project-specific "never do" rules -->
-- NEVER skip type hints to save time.
-- NEVER mark a feature complete without tests.
+
+- **Language**: JavaScript (Node.js >= 16), zero external runtime deps for the installer
+- **Distribution**: npm package `@tekyzinc/gsd-t`
+- **CLI**: `bin/gsd-t.js` (install, update, init, status, uninstall, doctor, graph, headless, …)
+- **Testing**: `npm test` (Node built-in test runner) + manual CLI testing
+
+## Project Structure
+
+```
+bin/                     — CLI entry (gsd-t.js) + orchestrators (orchestrator.js, design-orchestrator.js)
+                           + support modules (gsd-t-context-brief.cjs, cli-preflight.cjs, gsd-t-verify-gate.cjs, model-selector.js, …)
+commands/                — slash commands for Claude Code (GSD-T workflow + utility)
+templates/               — document + prompt + stack templates
+  CLAUDE-{global,project}.md, requirements.md, architecture.md, workflows.md,
+  infrastructure.md, progress.md, backlog.md, backlog-settings.md, design-contract.md
+  prompts/               — validation subagent protocols (qa, red-team, design-verify)
+  stacks/                — Stack Rules Engine templates (injected at spawn time)
+scripts/                 — runtime scripts (design review, context meter hook, event writer)
+examples/                — example project structure + settings
+docs/methodology.md      — GSD → GSD-T evolution and concepts
+package.json, README.md, GSD-T-README.md, CHANGELOG.md
+```
+
+Exact command list: `ls commands/`. Exact stack rule set: `ls templates/stacks/`. Don't hand-maintain counts in docs.
+
+## Meta-Project Notes
+
+- The "source" is the `.md` files in `commands/` + `templates/` and the JS in `bin/` + `scripts/`. There is no `src/`.
+- Changes to command files change the methodology itself — treat them as code; verify by running the workflow.
+- The `.gsd-t/` state dir coexists with the commands that *define* `.gsd-t/` — intentional.
+- `bin/gsd-t.js` is the primary testable surface; command files are validated by use.
+
+## Conventions
+
+**CLI** — ANSI colors via escape codes, zero external deps, sync file APIs, version tracked in `package.json` and `~/.claude/.gsd-t-version`.
+
+**Command files** — pure markdown, no frontmatter, accept `$ARGUMENTS`, step-numbered, thin Workflow invokers (`Workflow({scriptPath, args})`). Include a Document Ripple section listing files the underlying Workflow expects domain workers to update. Validation protocol bodies stay in `templates/prompts/*-subagent.md`; Workflow scripts load them via `_lib.loadProtocol(name)`. Don't inline the protocol.
+
+**Templates** — `{Project Name}`, `{Date}`, `{description}` replacement tokens; tables for structured data.
+
+**Directory structure** — `.gsd-t/contracts/` (domain interfaces), `.gsd-t/domains/{name}/` (scope/tasks/constraints), `.gsd-t/milestones/` (archives), `.gsd-t/scan/` (analysis outputs).
+
+**Publishing** — after `npm publish`, ALWAYS run `/gsd-t-version-update-all` to propagate to registered projects.
+
+## GSD-T Workflows (M61 — v4.0.10+)
+
+Phase orchestration lives in `templates/workflows/`. Each command file (`commands/gsd-t-*.md`) is a thin invoker that calls `Workflow({scriptPath, args})`. Canonical scripts:
+
+- `gsd-t-execute.workflow.js` — preflight → brief → file-disjointness → parallel(domain workers) → integrate → verify-gate
+- `gsd-t-verify.workflow.js` — orthogonal triad with M57 CI-parity + M58 test-data purge as FAIL-blocking gates
+- `gsd-t-wave.workflow.js`, `-integrate`, `-debug`, `-quick`, `-phase` (generic upper-stage runner)
+
+Shared helpers: `templates/workflows/_lib.js`. Each helper prefers project-local `bin/<tool>.cjs` and falls back to global `gsd-t` PATH binary.
+
+The brains stay in `bin/`: `gsd-t-file-disjointness.cjs`, `gsd-t-task-graph.cjs`, `gsd-t-context-brief.cjs`, `cli-preflight.cjs`, `gsd-t-verify-gate.cjs`, `gsd-t-verify-gate-judge.cjs`, `gsd-t-build-coverage.cjs`, `gsd-t-ci-parity.cjs`, `gsd-t-test-data-ledger.cjs`, `journey-coverage.cjs`. Workflows invoke them via `lib.*` helpers.
+
+## Validation Protocols (KEPT — methodology layer)
+
+Three validation protocol bodies stay at `templates/prompts/`:
+- `qa-subagent.md` — test mechanics + shallow-test detection + contract compliance
+- `red-team-subagent.md` — adversarial / security / boundaries; verdict `FAIL` / `GRUDGING-PASS`
+- `design-verify-subagent.md` — visual MATCH/DEVIATION against the design contract
+
+These are invoked as Workflow `agent()` stages with schema-validated output. The methodology body is unchanged; only the invocation context (Workflow stage vs. Task subagent) updated. Per `.gsd-t/contracts/orthogonal-validation-contract.md` v1.0.0 STABLE.
+
+
+# Destructive Action Guard (MANDATORY)
+
+**NEVER perform destructive or structural changes without explicit user approval.** This applies at ALL autonomy levels.
+
+Before any of these actions, STOP and ask the user:
+- DROP TABLE, DROP COLUMN, DROP INDEX, TRUNCATE, DELETE without WHERE
+- Renaming or removing database tables or columns
+- Schema migrations that lose data or break existing queries
+- Replacing an existing architecture pattern (e.g., normalized → denormalized)
+- Removing or replacing existing files/modules that contain working functionality
+- Changing ORM models in ways that conflict with the existing database schema
+- Removing API endpoints or changing response shapes that existing clients depend on
+- Any change that would require other parts of the system to be rewritten
+
+**Rule: "Adapt new code to existing structures, not the other way around."**
+
+## Pre-Commit Gate (project-specific additions)
+
+The global gate applies first (see `~/.claude/CLAUDE.md`). Additionally for this repo:
+
+- **Command file interface/behavior changed** → update `GSD-T-README.md` + `README.md` commands table + `templates/CLAUDE-global.md` + `commands/gsd-t-help.md`.
+- **Command added/removed** → update all 4 files above, bump `package.json`, update any command-counting logic in `bin/gsd-t.js`.
+- **New command invokes a Workflow** → verify `scriptPath` resolves to `templates/workflows/<name>.workflow.js` and `args` shape matches the script's `meta.phases`.
+- **CLI installer changed** → smoke test `install`, `update`, `status`, `doctor`, `init`, `uninstall`.
+- **Template changed** → verify `gsd-t-init` still produces correct output.
+- **Wave flow changed (phases added/removed/reordered)** → update `gsd-t-wave.md`, `GSD-T-README.md` wave diagram, `README.md` workflow section.
+- **Contract or domain boundary changed** → update `.gsd-t/contracts/` and owning `scope.md`.
+
+## Don't
+
+- NEVER add external npm runtime dependencies to the installer — zero-dep invariant.
+- NEVER rename a command without updating all 4 reference files above.
+- NEVER modify wave phase sequence without updating wave, README, GSD-T-README in the same commit.
+- NEVER let installer's command count diverge from `commands/` directory reality.
+- NEVER inline validation-subagent protocol bodies into Workflow scripts — `_lib.loadProtocol("qa"|"red-team"|"design-verify")` reads the methodology body from `templates/prompts/`.
+
+## Recovery After Interruption
+
+1. Read `.gsd-t/progress.md`
+2. Read `README.md` for what the package delivers
+3. Check `commands/` and `package.json` for current state
+4. Continue from current task; don't restart the phase
 
 ## Current Status
-See `.gsd-t/progress.md` for current milestone/phase state.
 
-## Deployed URLs
-- **Production**: {url}
-- **Staging**: {url}
-- **Local**: http://localhost:{port}
+See `.gsd-t/progress.md`.

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

@@ -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).
 
+<!-- M61 D7-T3: Workflow-stage invocation -->
+**Invocation context.** When this protocol runs as a native Workflow `agent()` stage, your **final emission MUST be a single StructuredOutput object** matching the design-verification schema. Bash/git/Read/screenshot tool use is permitted DURING the audit; the final emission is the JSON envelope with one entry per design element + overall verdict. When this protocol runs from a Task subagent (legacy path), the deliverable is the markdown comparison table. Same methodology; different envelope.
+
 <!-- 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.
 

package/templates/prompts/qa-subagent.md

@@ -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.
 
+<!-- M61 D7-T3: Workflow-stage invocation -->
+**Invocation context.** When this protocol runs as a native Workflow `agent()` stage (via `templates/workflows/gsd-t-verify.workflow.js` or sibling), your **final emission MUST be a single StructuredOutput object** matching the QA schema declared by the Workflow (see `orthogonal-validation-contract.md` v1.0.0). Bash/git tool use is permitted DURING the work (running tests, reading files); the final emission is the JSON envelope, not a markdown report. When this protocol runs from a Task subagent (legacy path), the deliverable is the markdown report below. Same methodology; different envelope.
+
 <!-- 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.
 

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

@@ -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.
 
+<!-- M61 D7-T3: Workflow-stage invocation -->
+**Invocation context.** When this protocol runs as a native Workflow `agent()` stage (via `templates/workflows/gsd-t-verify.workflow.js` or sibling), your **final emission MUST be a single StructuredOutput object** matching the RED_TEAM schema declared by the Workflow. Bash/git/Read tool use is permitted DURING attack development; the final emission is the JSON envelope with `verdict ∈ {FAIL, GRUDGING-PASS}` and `bugs[]` array. When this protocol runs from a Task subagent (legacy path), the deliverable is the markdown report at `.gsd-t/red-team-report.md`. Same methodology; different envelope.
+
 <!-- 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.
 
@@ -42,7 +45,7 @@ Summary:
 - SHALLOW TESTS REWRITTEN: {count}
 - CONTRACTS VERIFIED: {N}/{total}
 - ATTACK VECTORS TRIED: every category attempted, each with one-line result
-- VERDICT: `FAIL` ({N} bugs found) | `GRUDGING PASS` (exhaustive search, nothing found)
+- VERDICT: `FAIL` ({N} bugs found) | `GRUDGING-PASS` (exhaustive search, nothing found)
 
 Write findings to `.gsd-t/red-team-report.md`. If bugs found, also append to `.gsd-t/qa-issues.md`.
 
@@ -96,5 +99,5 @@ category attacks.
 - Unblock exercise: {manifest update, exit code, stderr summary}
 
 ### VERDICT
-{GRUDGING PASS — N patches written, all caught | FAIL — {M} pass-through(s)}
+{GRUDGING-PASS — N patches written, all caught | FAIL — {M} pass-through(s)}
 ```