npm - @tekyzinc/gsd-t - Versions diffs - 4.0.26 → 4.0.28 - Mend

@tekyzinc/gsd-t 4.0.26 → 4.0.28

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 (12) hide show

package/CHANGELOG.md +29 -0
package/README.md +91 -142
package/bin/scan-data-collector.js +88 -1
package/bin/scan-diagrams-generators.js +15 -7
package/bin/scan-diagrams.js +9 -0
package/bin/scan-renderer.js +32 -1
package/docs/architecture.md +231 -21
package/docs/infrastructure.md +461 -245
package/docs/requirements.md +226 -0
package/docs/workflows.md +353 -4
package/package.json +1 -1
package/templates/workflows/gsd-t-scan.workflow.js +49 -14

package/docs/infrastructure.md CHANGED Viewed

@@ -1,153 +1,396 @@
-# Infrastructure — GSD-T Framework (@tekyzinc/gsd-t)
+# Infrastructure - GSD-T Framework (@tekyzinc/gsd-t)
-## Last Updated: 2026-03-22 (M23 — Headless Mode)
+## Last Updated: 2026-06-04 (deep-scan M80)
-> **Scan #11 note (2026-04-16, v3.11.11)**: the `ANTHROPIC_API_KEY` setup section
-> below is now stale — the context meter switched to a local token estimator
-> in v3.11.11 and the key is no longer required by the meter. The key is still
-> consumed by `bin/runway-estimator.js` and some telemetry paths. Doctor was
-> updated; this doc was not. See `.gsd-t/techdebt.md` TD-103.
+---
 ## Quick Reference
 | Task | Command |
 |------|---------|
 | Install GSD-T | `npx @tekyzinc/gsd-t install` |
-| Check status | `npx @tekyzinc/gsd-t status` |
 | Update GSD-T | `npx @tekyzinc/gsd-t update` |
-| Update all projects | `npx @tekyzinc/gsd-t update-all` |
+| Update GSD-T + all projects | `npx @tekyzinc/gsd-t update-all` |
+| Check installation status | `npx @tekyzinc/gsd-t status` |
 | Diagnose issues | `npx @tekyzinc/gsd-t doctor` |
+| Scaffold a project | `npx @tekyzinc/gsd-t init [project-name]` |
+| Register current dir | `npx @tekyzinc/gsd-t register` |
 | View changelog | `npx @tekyzinc/gsd-t changelog` |
-| Register project | `npx @tekyzinc/gsd-t register` |
-| Publish to npm | `npm publish` (runs `npm test` automatically via prepublishOnly) |
+| Uninstall | `npx @tekyzinc/gsd-t uninstall` |
+| Run unit tests | `npm test` (Node built-in runner; prepublishOnly hook) |
+| Run E2E tests | `npm run e2e` (Playwright - chromium) |
+| Install Playwright | `npm run e2e:install` |
+| Publish to npm | `npm publish` (runs `npm test` first via prepublishOnly) |
 | Headless exec | `gsd-t headless <command> [--json] [--timeout=N] [--log]` |
-| Headless query | `gsd-t headless query <type>` (no LLM, <100ms) |
+| Headless query (no LLM) | `gsd-t headless query <type>` (<100ms, pure file parse) |
+| Code graph index | `gsd-t graph index` |
+| Code graph status | `gsd-t graph status` |
+| Code graph query | `gsd-t graph query <entity>` |
+| Preflight check | `gsd-t preflight [--json]` |
+| Context brief | `gsd-t brief --kind <kind> [--domain <d>]` |
+| Verify gate | `gsd-t verify-gate [--json]` |
+| CI-parity check | `gsd-t ci-parity [--json]` |
+| Build coverage check | `gsd-t build-coverage [--json]` |
+| Test data ledger | `gsd-t test-data --list | --purge --run <id>` |
+| Parallel tasks | `gsd-t parallel [--dry-run] [--domain <d>]` |
+| Workflow path resolver | `gsd-t workflow-path <name>` |
+| Journey coverage | `gsd-t check-coverage [--report] [--strict]` |
+| Doctor (full) | `gsd-t doctor [--prune] [--install-playwright] [--install-hooks] [--install-journey-hook]` |
+| Archive progress log | `node bin/archive-progress.cjs [--project DIR] [--dry-run] [--keep N]` |
+---
 ## Local Development
 ### Setup
 ```bash
-# Clone and install
+# Clone the repo
 git clone https://github.com/Tekyz-Inc/get-stuff-done-teams.git
 cd get-stuff-done-teams
-# No npm install needed — zero dependencies
-# Test the CLI directly:
+# No npm install needed for runtime - zero runtime dependencies
+# Install dev dependency (Playwright) if running E2E tests:
+npm install
+# Test the CLI directly (no build step needed):
 node bin/gsd-t.js status
+node bin/gsd-t.js install
+node bin/gsd-t.js doctor
 ```
 ### Testing
 ```bash
-# Run automated test suite (205 tests, zero dependencies)
+# Run all unit tests (Node built-in test runner, 78 test files)
 npm test
-# Test CLI subcommands manually
-node bin/gsd-t.js install
+# Run E2E tests (Playwright - requires chromium)
+npm run e2e:install   # one-time: install chromium
+npm run e2e           # run E2E suite
+# Test specific CLI subcommands manually
 node bin/gsd-t.js status
 node bin/gsd-t.js doctor
 node bin/gsd-t.js init test-project
-# Validate command files exist
-ls commands/*.md | wc -l  # Should be 48
-ls templates/*.md | wc -l  # Should be 9
+# Validate command file counts
+ls commands/*.md | wc -l   # 51 command files
+ls templates/stacks/*.md    # stack rule templates
-# Test new utility scripts
-node scripts/gsd-t-tools.js validate
-node scripts/gsd-t-tools.js git pre-commit-check
+# Test scan HTML export
+node bin/gsd-t.js scan --export=html
+# Output: scan-report.html (self-contained)
-# Test scan visual output
-node bin/gsd-t.js scan --export html
-# Output: scan-report.html (self-contained, no external deps)
+# Test stream feed server (loopback only, port 7842)
+node scripts/gsd-t-stream-feed-server.js --port 7842
-# Test dashboard server
-node scripts/gsd-t-dashboard-server.js --port 7433 --detach
-# Browser: http://localhost:7433
-node scripts/gsd-t-dashboard-server.js --stop
+# Test design review server (default port 3456)
+node scripts/gsd-t-design-review-server.js --port 3456 --target http://localhost:5173
+# Validate a workflow script path
+node bin/gsd-t.js workflow-path execute
+node bin/gsd-t.js workflow-path verify
 ```
-### Scripts
+### Scripts Reference
 | Script | Purpose |
 |--------|---------|
-| `scripts/gsd-t-heartbeat.js` | Claude Code hook event logger (JSONL output, secret scrubbing) |
-| `scripts/npm-update-check.js` | Background npm registry version checker (path-validated) |
+| `scripts/gsd-t-heartbeat.js` | Claude Code hook event logger - JSONL output, secret scrubbing |
+| `scripts/gsd-t-auto-route.js` | UserPromptSubmit hook - auto-routes plain text via /gsd in GSD-T projects |
+| `scripts/gsd-t-update-check.js` | SessionStart hook - fetches latest npm version, emits update banners |
 | `scripts/gsd-t-fetch-version.js` | Synchronous npm registry fetch (5s timeout, 1MB limit) |
-| `scripts/gsd-t-tools.js` | State utility CLI — state get/set, validate, list, git check, template read (M13) |
-| `scripts/gsd-t-statusline.js` | Context usage bar + project state for Claude Code statusLine setting (M13) |
-| `scripts/gsd-t-event-writer.js` | Structured JSONL event appender CLI — writes to .gsd-t/events/ (M14) |
-| `scripts/gsd-t-dashboard-server.js` | Zero-dep SSE server for real-time dashboard — port 7433 (M15) |
-| `scripts/gsd-t-auto-route.js` | UserPromptSubmit hook — auto-routes plain text via /gsd in GSD-T projects (M16) |
-| `scripts/gsd-t-update-check.js` | SessionStart hook — fetches latest npm version, auto-updates GSD-T (M16) |
-| `bin/scan-schema.js` | ORM/DB schema detector + extractor — 7 ORM types (M17) |
-| `bin/scan-diagrams.js` | Diagram orchestrator — 6 diagram types, renders to SVG or placeholder (M17) |
-| `bin/scan-report.js` | Self-contained HTML scan report generator (M17) |
-| `bin/scan-export.js` | Export subcommand — DOCX (pandoc) + PDF (md-to-pdf) stubs (M17) |
+| `scripts/gsd-t-tools.js` | State utility CLI - get/set/validate/list/git-check/template-read |
+| `scripts/gsd-t-statusline.js` | Context usage bar + project state for Claude Code statusLine |
+| `scripts/gsd-t-event-writer.js` | Structured JSONL event appender CLI - writes to `.gsd-t/events/` |
+| `scripts/gsd-t-stream-feed-server.js` | WebSocket + SSE server for real-time agent stream (port 7842) |
+| `scripts/gsd-t-dashboard-autostart.cjs` | Dashboard process management - start/stop/check |
+| `scripts/gsd-t-date-guard.js` | PreToolUse hook - blocks Write/Edit with stale timestamps (+-5 min) |
+| `scripts/gsd-t-calibration-hook.js` | Detects compaction events from transcript - updates calibration data |
+| `scripts/gsd-t-compact-detector.js` | Appends compaction JSONL rows to `.gsd-t/metrics/compactions.jsonl` |
+| `scripts/gsd-t-compaction-scanner.js` | Backfills compaction log by scanning transcript history |
+| `scripts/gsd-t-token-aggregator.js` | Aggregates stream-feed JSONL into per-task token-usage.jsonl |
+| `scripts/gsd-t-watch-state.js` | Writes/reads agent watch-state JSON files (atomic write) |
+| `scripts/gsd-t-design-review-server.js` | Design review proxy server with inject overlay (port 3456) |
+| `scripts/npm-update-check.js` | Background npm registry version checker (path-validated) |
+### Bin Modules Reference
+| Module | Purpose |
+|--------|---------|
+| `bin/gsd-t.js` | Main CLI entry point - install, update, init, status, doctor, graph, headless, etc. |
+| `bin/orchestrator.js` | Design-phase orchestrator - element inventory + build pipeline |
+| `bin/design-orchestrator.js` | Design-to-code build pipeline - elements, widgets, pages |
+| `bin/cli-preflight.cjs` | Preflight gate - branch guard, dirty tree, ports, contract stability |
+| `bin/gsd-t-context-brief.cjs` | Per-spawn context brief generator (11 kinds: execute, verify, qa, etc.) |
+| `bin/gsd-t-verify-gate.cjs` | Track 1+2 verify gate - preflight + parallel CLI substrate |
+| `bin/gsd-t-verify-gate-judge.cjs` | Synthesis judge - merges triad results into VERIFIED / VERIFY-FAILED |
+| `bin/gsd-t-build-coverage.cjs` | CI-parity gate: checks all top-level dirs appear in Dockerfile COPY |
+| `bin/gsd-t-ci-parity.cjs` | CI-parity gate: compares local build config with CI config |
+| `bin/gsd-t-parallel.cjs` | Task parallelism orchestrator - mode-aware gating, fan-out decisions |
+| `bin/parallel-cli.cjs` | Worker pool executor - failFast, SIGTERM/SIGKILL escalation, tee |
+| `bin/parallel-cli-tee.cjs` | Tee streaming helper for parallel-cli output |
+| `bin/gsd-t-task-graph.cjs` | Task dependency graph builder |
+| `bin/gsd-t-file-disjointness.cjs` | File-disjointness safety gate for parallel worker safety |
+| `bin/gsd-t-depgraph-validate.cjs` | Dependency graph validation for task ordering |
+| `bin/gsd-t-test-data-ledger.cjs` | Test data registration/purge ledger for E2E cleanup |
+| `bin/archive-progress.cjs` | Rolls old Decision Log entries out of progress.md into archives |
+| `bin/global-sync-manager.js` | Global cross-project metrics sync to `~/.claude/metrics/` |
+| `bin/patch-lifecycle.js` | Candidate/applied/measured/promoted/graduated patch state machine |
+| `bin/metrics-collector.js` | Task-metrics JSONL writer for `.gsd-t/metrics/task-metrics.jsonl` |
+| `bin/rule-engine.js` | Loads rules from `.gsd-t/metrics/rules.jsonl`, evaluates, creates candidates |
+| `bin/model-selector.js` | Declarative phase-to-model mapping (haiku/sonnet/opus) |
+| `bin/playwright-bootstrap.cjs` | Playwright install + health check library |
+| `bin/ui-detection.cjs` | Detects whether project has a UI layer |
+| `bin/journey-coverage.cjs` | Journey coverage manifest builder |
+| `bin/journey-coverage-cli.cjs` | CLI wrapper for journey-coverage |
+| `bin/graph-cgc.js` | CodeGraphContext (CGC) Neo4j adapter |
+| `bin/graph-indexer.js` | Project file indexer for code graph |
+| `bin/graph-store.js` | Graph index read/write (8 JSON files per project) |
+| `bin/graph-query.js` | Query callers/imports/surfaces via grep fallback |
+| `bin/graph-overlay.js` | Overlays domain/contract metadata onto graph |
+| `bin/graph-parsers.js` | AST parsers for JS/TS/Python call extraction |
+| `bin/advisor-integration.js` | Advisor hook integration |
+| `bin/component-registry.js` | Component registry with atomic JSONL write |
+| `bin/debug-ledger.js` | Debug cycle ledger for headless debug-loop |
+| `bin/scan-*.js` | Scan engine modules (data-collector, schema, schema-parsers, report, report-sections, renderer, export, diagrams, diagrams-generators) |
+| `bin/gsd-t-time-format.cjs` | `localIsoWithOffset()` for POSIX-correct local timestamps |
+| `bin/gsd-t-completion-check.cjs` | Completion status check for milestone gate |
+---
 ## Distribution
 ### npm Package
 - **Registry**: https://www.npmjs.com/package/@tekyzinc/gsd-t
-- **Publish**: `npm publish` (requires npm login with Tekyz account)
-- **Version**: Managed in `package.json`, synced to `.gsd-t/progress.md`
+- **Current version**: see `package.json` ("version" field) - track at `~/.claude/.gsd-t-version`
+- **Publish**: `npm publish` (requires npm login with Tekyz account; `prepublishOnly` runs `npm test`)
+- **Zero runtime dependencies** - installer uses only Node.js built-ins
+- **Dev dependency**: `@playwright/test` ^1.55.0 (E2E tests only)
 - **Files shipped**: `bin/`, `commands/`, `scripts/`, `templates/`, `examples/`, `docs/`, `CHANGELOG.md`
 ### Installed Locations
 | What | Where |
 |------|-------|
-| Slash commands (48 files) | `~/.claude/commands/` |
-| Global config | `~/.claude/CLAUDE.md` |
+| Slash commands (51 files) | `~/.claude/commands/` |
+| Global CLAUDE.md | `~/.claude/CLAUDE.md` |
 | Heartbeat script | `~/.claude/scripts/gsd-t-heartbeat.js` |
+| Update-check script | `~/.claude/scripts/gsd-t-update-check.js` |
+| Auto-route script | `~/.claude/scripts/gsd-t-auto-route.js` |
 | State utility CLI | `~/.claude/scripts/gsd-t-tools.js` |
 | Statusline script | `~/.claude/scripts/gsd-t-statusline.js` |
+| Shared templates | `~/.claude/templates/` |
 | Hook configuration | `~/.claude/settings.json` (hooks section) |
 | Version file | `~/.claude/.gsd-t-version` |
 | Update cache | `~/.claude/.gsd-t-update-check` |
 | Project registry | `~/.claude/.gsd-t-projects` |
+| Global bin tools | `~/.claude/bin/` (see list below) |
+**Global bin tools** (copied to `~/.claude/bin/` on install):
+| Tool | Purpose |
+|------|---------|
+| `cli-preflight.cjs` | Preflight gate dispatch target |
+| `gsd-t-context-brief.cjs` | Brief generator dispatch target |
+| `gsd-t-verify-gate.cjs` | Verify gate dispatch target |
+| `gsd-t-verify-gate-judge.cjs` | Judge dispatch target |
+| `parallel-cli.cjs` | Parallel worker pool executor |
+| `gsd-t-build-coverage.cjs` | Build coverage check |
+| `gsd-t-ci-parity.cjs` | CI parity check |
+| `parallelism-report.cjs` | Parallelism report generator |
+| `live-activity-report.cjs` | Live activity report generator |
+### Installed Hooks (settings.json)
-## Repository Structure
+GSD-T registers these hooks in `~/.claude/settings.json`:
+| Hook type | Script | Purpose |
+|-----------|--------|---------|
+| `UserPromptSubmit` | `gsd-t-auto-route.js` | Emits `[GSD-T NOW]` clock signal; routes plain text via /gsd in GSD-T project dirs |
+| `SessionStart` | `gsd-t-update-check.js` | Fetches latest npm version; emits `[GSD-T AUTO-UPDATE]` / `[GSD-T UPDATE]` / `[GSD-T]` |
+| `UserPromptSubmit` | `gsd-t-heartbeat.js` | Logs conversation events to `.gsd-t/events/YYYY-MM-DD.jsonl` |
+| `PostToolUse` (dead) | context-meter hook | Installed but non-functional - context meter was retired in M61; hook silently exits 0 |
+| `PreToolUse` | `gsd-t-date-guard.js` | Blocks Write/Edit calls with timestamps drifting >5 min from live clock |
+Note: The context-meter PostToolUse hook is still written to settings.json on install (known defect - finding in scan) but silently no-ops since `scripts/gsd-t-context-meter.js` does not exist.
+### Figma MCP
+Auto-configured during install via `claude mcp add`:
+```bash
+# Configured automatically by gsd-t install. To add manually:
+claude mcp add --transport http -s user figma https://mcp.figma.com/mcp
 ```
-get-stuff-done-teams/
-├── bin/gsd-t.js        — CLI installer (~1,438 lines, zero dependencies)
-├── commands/           — 45 slash command files (41 GSD-T + 4 utility)
-├── scripts/            — 5 hook/utility scripts (added gsd-t-tools.js, gsd-t-statusline.js in M13)
-├── templates/          — 9 document templates
-├── examples/           — Reference project structure
-├── docs/               — Methodology + living docs
-├── .gsd-t/             — GSD-T state (self-managed)
-└── package.json        — npm package config
+Check current status:
+```bash
+gsd-t doctor
 ```
-## Headless Mode (M23)
+---
-Headless mode enables non-interactive GSD-T execution for CI/CD pipelines and overnight builds.
+## Project Directory Structure (.gsd-t/)
+Each GSD-T project has a `.gsd-t/` state directory created by `gsd-t init`. Key subdirectories:
+| Path | Purpose | Committed? |
+|------|---------|-----------|
+| `.gsd-t/progress.md` | Milestone/phase state + decision log | Yes |
+| `.gsd-t/backlog.md` | Backlog items | Yes |
+| `.gsd-t/backlog-settings.md` | Backlog defaults (apps, types) | Yes |
+| `.gsd-t/contracts/` | Domain interface contracts (STABLE/DRAFT) | Yes |
+| `.gsd-t/domains/` | Per-domain scope/tasks/constraints | Yes |
+| `.gsd-t/milestones/` | Completed milestone archives + archive-meta.json | Yes |
+| `.gsd-t/progress-archive/` | Rolled-out decision log entries (NNN-YYYY-MM-DD.md) | Yes |
+| `.gsd-t/techdebt.md` | Tech debt register | Yes |
+| `.gsd-t/scan/` | Deep-scan output (architecture.md, security.md, quality.md, etc.) | Yes |
+| `.gsd-t/events/` | JSONL event stream (YYYY-MM-DD.jsonl, heartbeat writes) | No (gitignored) |
+| `.gsd-t/metrics/` | Task metrics, compaction log, token-usage, rollup | No (gitignored) |
+| `.gsd-t/stream-feed/` | WebSocket frame JSONL (YYYY-MM-DD.jsonl) | No (gitignored) |
+| `.gsd-t/briefs/` | Per-spawn context briefs (ephemera) | No (gitignored) |
+| `.gsd-t/.unattended/` | Supervisor state, PID, run log, stop sentinel | No (gitignored) |
+| `.gsd-t/token-log.md` | Headless exec token log rows | No (gitignored) |
+| `.gsd-t/token-metrics.jsonl` | Legacy M35-era per-spawn token records | No (gitignored) |
+| `.gsd-t/.context-meter-state.json` | Context meter state (retired, kept for compat) | No (gitignored) |
+| `.gsd-t/.last-playwright-pass` | Timestamp of last Playwright pass (pre-commit gate) | No |
-### headless exec
+---
+## Ports and Services
+| Service | Default Port | Env Override | Notes |
+|---------|-------------|--------------|-------|
+| Stream Feed Server | 7842 | `GSD_T_STREAM_FEED_PORT` | Loopback only (127.0.0.1) - WebSocket + SSE |
+| Design Review Server | 3456 | `--port` arg | Proxies dev server with inject overlay |
+| Neo4j (graph engine) | 7687 (Bolt) / 7474 (HTTP) | Docker container | Container name: `gsd-t-neo4j` |
+---
+## Graph Engine (CGC + Neo4j)
+The code graph engine is an optional feature for deep code analysis. It requires Docker.
+### Setup
+```bash
+# Install CGC (CodeGraphContext) - requires Python
+pip install codegraphcontext
+# Install/start Neo4j container (done automatically by gsd-t install / gsd-t doctor)
+docker run -d --name gsd-t-neo4j \
+  -p 7474:7474 -p 7687:7687 \
+  -e NEO4J_AUTH=neo4j/gsdt-graph-2026 \
+  --restart unless-stopped \
+  neo4j:5-community
+# Configure CGC to point at the container
+cgc config set DEFAULT_DATABASE neo4j
+cgc config set NEO4J_URI bolt://localhost:7687
+cgc config set NEO4J_PASSWORD gsdt-graph-2026
+```
+**Security note**: The password `gsdt-graph-2026` is hardcoded in the installer (known defect - see techdebt.md). This is a local-only Neo4j instance but the password is publicly known. For sensitive codebases, change the password after setup:
+```bash
+# Change Neo4j password post-install (Neo4j browser at http://localhost:7474)
+# Then update CGC config:
+cgc config set NEO4J_PASSWORD <new-password>
+```
+### Container Management
+```bash
+# Check container status
+gsd-t doctor
+# Start stopped container
+docker start gsd-t-neo4j
+# Stop container
+docker stop gsd-t-neo4j
+# Check if running
+docker inspect gsd-t-neo4j --format '{{.State.Running}}'
+```
+### Graph CLI Usage
+```bash
+# Index the current project
+gsd-t graph index
+# Check index status
+gsd-t graph status
+# Query an entity
+gsd-t graph query MyClass
+# Show task domain assignments
+gsd-t graph tasks [table|json]
+```
+---
+## Secrets and Credentials
+**Names only - never store values in docs.**
+| Name | Purpose | Where set |
+|------|---------|-----------|
+| `ANTHROPIC_API_KEY` | Token counting / diagnostics only (NOT inference - inference uses Claude Max subscription) | Shell profile or CI secret |
+| `GSD_T_STREAM_FEED_PORT` | Override stream feed server port | Environment |
+| `GSD_T_AGENT_ID` | Agent identity for watch-state files (CLI arg `--agent-id` preferred) | Environment or CLI |
+| Neo4j password | CGC graph engine auth - see security note above | `~/.codegraphcontext/.env` |
+**ANTHROPIC_API_KEY** is used only for `count_tokens` diagnostics. All LLM inference uses the Claude Max subscription (local install) - never billed to the API key for build work.
+```bash
+# Set in shell profile (optional - only needed for token diagnostics)
+export ANTHROPIC_API_KEY="sk-ant-..."
+# Verify
+gsd-t doctor
+```
+---
-Wraps `claude -p "/gsd-t-{command} {args}"` for unattended execution.
+## Headless Execution
+Headless mode runs GSD-T commands non-interactively via `claude -p` with `--dangerously-skip-permissions`.
+### headless exec
 ```bash
 gsd-t headless verify --json --timeout=1200 --log
 gsd-t headless execute --timeout=3600
 gsd-t headless wave --json
+gsd-t headless quick "add error handling to auth module"
 ```
 **Flags:**
 | Flag | Default | Description |
 |------|---------|-------------|
-| `--json`        | off    | Output structured JSON envelope |
-| `--timeout=N`   | 300s   | Kill process after N seconds |
-| `--log`         | off    | Write output to `.gsd-t/headless-{timestamp}.log` |
+| `--json` | off | Output structured JSON envelope |
+| `--timeout=N` | 300s | Kill process after N seconds |
+| `--log` | off | Write output to `.gsd-t/headless-{timestamp}.log` |
 **Exit codes:**
 | Code | Meaning |
 |------|---------|
-| 0    | success |
-| 1    | verify-fail (tests or quality gates failed) |
-| 2    | context-budget-exceeded (split the milestone) |
-| 3    | error (claude CLI error or process failure) |
-| 4    | blocked-needs-human (requires manual intervention) |
+| 0 | Success |
+| 1 | Verify-fail (tests or quality gates failed) |
+| 2 | Context-budget-exceeded (split the milestone) |
+| 3 | Error (claude CLI error or process failure) |
+| 4 | Blocked-needs-human (requires manual intervention) |
+**JSON envelope shape:**
-**JSON envelope shape (--json flag):**
 ```json
 {
   "success": true,
@@ -156,265 +399,238 @@ gsd-t headless wave --json
   "command": "verify",
   "args": [],
   "output": "...",
-  "timestamp": "2026-03-22T10:00:00.000Z",
+  "timestamp": "2026-06-04T10:00:00.000Z",
   "duration": 42150,
-  "logFile": ".gsd-t/headless-1742641200000.log"
+  "logFile": ".gsd-t/headless-1749034800000.log"
 }
 ```
 ### headless query
-Pure Node.js file parsing — no LLM calls, <100ms response.
+Pure Node.js file parsing - no LLM calls, <100ms.
 ```bash
-gsd-t headless query status     # Version, milestone, phase
-gsd-t headless query domains    # Domain list with flags
-gsd-t headless query contracts  # Contract file list
-gsd-t headless query debt       # Tech debt items
-gsd-t headless query context    # Token log summary
-gsd-t headless query backlog    # Backlog items
-gsd-t headless query graph      # Graph index metadata
+gsd-t headless query status      # Version, milestone, phase
+gsd-t headless query domains     # Domain list with flags
+gsd-t headless query contracts   # Contract file list
+gsd-t headless query debt        # Tech debt items
+gsd-t headless query context     # Token log summary
+gsd-t headless query backlog     # Backlog items (note: parse bug - always empty, see techdebt)
+gsd-t headless query graph       # Graph index metadata
 ```
 All queries return JSON to stdout.
-### CI/CD Integration
+### debug-loop
+```bash
+gsd-t headless --debug-loop <command>
+```
+Runs up to 20 fix/verify cycles on a failing command. Exits code 0 (fixed), 1 (max iterations), or 4 (escalation needed).
-Example workflow files are in `docs/ci-examples/`:
-- `github-actions.yml` — GitHub Actions workflow with verify + status gate jobs
-- `gitlab-ci.yml` — GitLab CI pipeline with status/verify/report stages
+**Known defect**: `spawnClaudeSession` (used by debug-loop) is missing `--dangerously-skip-permissions`, causing all tool use to fail. See techdebt.md.
+---
+## CI/CD Integration
+### GitHub Actions
-**Quick setup for GitHub Actions:**
 ```yaml
 - name: GSD-T Verify
-  env:
-    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
   run: gsd-t headless verify --json --timeout=1200
 ```
-**Quick setup for GitLab CI:**
+Note: `ANTHROPIC_API_KEY` is optional (token diagnostics only). Inference runs via Claude Max and does not require the API key in CI.
+### GitLab CI
 ```yaml
 gsd-t-verify:
   script:
     - gsd-t headless verify --json --timeout=1200
-  variables:
-    ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
 ```
-## Context Meter Setup (M34, v2.75.10+)
+### Pre-commit Hooks (opt-in)
-The Context Meter is a PostToolUse hook that measures real context consumption via the Anthropic `count_tokens` API. It is **required** for the `gsd-t-execute`, `gsd-t-wave`, `gsd-t-quick`, `gsd-t-integrate`, and `gsd-t-debug` session-stop gates to work.
+Install via `gsd-t init --install-hooks` or `gsd-t doctor --install-hooks`:
-**API key — required**
+| Hook | Script | Status |
+|------|--------|--------|
+| Playwright gate | `scripts/hooks/pre-commit-playwright-gate` | Active |
+| Journey coverage | `scripts/hooks/pre-commit-journey-coverage` | Active |
+| Capture lint | `scripts/hooks/pre-commit-capture-lint` | BROKEN - references retired `gsd-t capture-lint` subcommand (see techdebt) |
-```bash
-# Shell profile (~/.zshrc, ~/.bashrc, ~/.config/fish/config.fish)
-export ANTHROPIC_API_KEY="sk-ant-..."
+**Do not install `pre-commit-capture-lint`** - it will block all commits unconditionally. The `gsd-t capture-lint` subcommand was removed in M61.
-# Verify
-echo $ANTHROPIC_API_KEY | head -c 10
-```
-Get a key at [https://console.anthropic.com](https://console.anthropic.com). Free tier is sufficient — `count_tokens` is billed per call at negligible cost.
-**CI/CD**: set `ANTHROPIC_API_KEY` as a secret (`secrets.ANTHROPIC_API_KEY` in GitHub Actions, masked variables in GitLab CI). The existing verify workflow example above already threads the secret through.
+---
-**Per-project `.env.local` (optional)**: drop `ANTHROPIC_API_KEY=sk-ant-...` into the project's ignored env file and source it in your shell profile if you need per-project keys.
+## Workflow Scripts
-**Verify with doctor**:
+Native Workflow scripts live in `templates/workflows/`. Use `gsd-t workflow-path <name>` to resolve the absolute path (required for `Workflow({scriptPath})` calls from consumer projects).
 ```bash
-npx @tekyzinc/gsd-t doctor
+# Get absolute path to a workflow script
+gsd-t workflow-path execute
+gsd-t workflow-path verify
+gsd-t workflow-path wave
 ```
-Expected GREEN output:
+Available workflow scripts:
-```
-Context Meter
-  ✅ API key set (ANTHROPIC_API_KEY)
-  ✅ PostToolUse hook registered in ~/.claude/settings.json
-  ✅ scripts/gsd-t-context-meter.js exists
-  ✅ .gsd-t/context-meter-config.json loads cleanly
-  ✅ count_tokens dry-run: 7 tokens
-```
+| Script | Purpose |
+|--------|---------|
+| `gsd-t-execute.workflow.js` | Preflight + brief + disjointness + parallel domain workers + integrate + verify-gate |
+| `gsd-t-verify.workflow.js` | Orthogonal triad (code-review + Red Team + QA) + CI-parity + test-data purge |
+| `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 debug loop |
+| `gsd-t-quick.workflow.js` | Preflight + brief + single-task + verify-gate |
+| `gsd-t-phase.workflow.js` | Generic upper-stage runner (partition/plan/discuss/impact/milestone/prd) |
+| `gsd-t-scan.workflow.js` | Volume-scaled deep codebase analysis + dimension files + HTML report |
+**Known defect (M71 - CRITICAL)**: All workflow scripts except `gsd-t-scan.workflow.js` use `require('./_lib.js')` at the top level. The native Workflow sandbox does not provide `require` - these crash immediately with `ReferenceError: require is not defined`. Migration to sandbox-native patterns is pending. See techdebt.md.
+---
-If any check is RED, doctor exits with code 1.
+## Context Meter / Calibration
-**Config file** — `.gsd-t/context-meter-config.json`:
+The context meter was retired in M61. The calibration hook (`scripts/gsd-t-calibration-hook.js`) and compaction detector (`scripts/gsd-t-compact-detector.js`) remain active and write to `.gsd-t/metrics/compactions.jsonl`.
+**Context window**: Opus 4.7/4.8 and Sonnet 4.5+ have 1M token context windows. The `templates/context-meter-config.json` template ships with a stale 200K `modelWindowSize` - update per-project configs to 1000000. The calibration hook uses `SAFE_DEFAULT_WINDOW = 1_000_000` correctly.
 ```json
 {
   "enabled": true,
-  "apiKeyEnvVar": "ANTHROPIC_API_KEY",
-  "modelWindowSize": 200000,
-  "thresholdPct": 85,
+  "modelWindowSize": 1000000,
+  "thresholdPct": 75,
   "checkFrequency": 1
 }
 ```
-**Threshold bands** (M35 v3.0.0 — three bands, lower-bound inclusive):
+---
-| Band   | Range    | Orchestrator action                                                              |
-|--------|----------|----------------------------------------------------------------------------------|
-| normal | 0–69%    | Proceed                                                                          |
-| warn   | 70–84%   | Log warning; cue for explicit pause/resume at the next clean boundary            |
-| stop   | ≥85%     | Halt cleanly with resume instruction; command refuses to start if runway crosses |
+## Model Selection
-**Zero silent quality degradation.** There is no `downgrade` band and no `conserve` band. Models are **never** swapped at runtime under context pressure — model choice is a plan-time decision made by `bin/model-selector.js`, and quality-critical phases (Red Team, doc-ripple, Design Verify) always run at their designated tier. See `.gsd-t/contracts/token-budget-contract.md` v3.0.0.
+`bin/model-selector.js` maps phases to inference tiers:
-**Structural guarantee**: because the runway estimator refuses runs that project past 85% and the stop band fires at 85%, the runtime's 95% native compact is structurally unreachable under healthy operation. `halt_type: native-compact` in `.gsd-t/token-metrics.jsonl` is a defect signal.
+| Phase | Model | Notes |
+|-------|-------|-------|
+| `execute` | sonnet | Domain workers |
+| `verify` / `qa` | sonnet | QA subagent |
+| `red-team` | opus | Adversarial analysis |
+| `design-verify` | opus | Visual comparison |
+| `plan` | sonnet | Note: contract says opus - known divergence (see techdebt) |
+| `integrate` | sonnet | Cross-domain wire-up |
+| `scan` | sonnet | Volume-scaled slices |
+| `debug` | sonnet | Fix cycles |
-**Upgrading from pre-M34**: `gsd-t update-all` runs a one-time task-counter retirement migration in every registered project (deletes `bin/task-counter.cjs`, `.gsd-t/task-counter-config.json`, `.gsd-t/.task-counter-state.json`, and the `.gsd-t/.task-counter` file; writes `.gsd-t/.task-counter-retired-v1` marker). After upgrade you **must** set `ANTHROPIC_API_KEY` — doctor will fail otherwise.
+Use `gsd-t doctor` to verify model-selector is loaded correctly.
-## Runway-Protected Execution (M35)
+---
-M35 adds four components on top of the Context Meter. Together they replace graduated degradation with a pre-flight gate + pause/resume model.
+## Unattended Supervisor
-### Per-phase model selection — `bin/model-selector.js`
+The unattended supervisor runs a GSD-T milestone to completion in a detached process. Underlying commands were rearchitected in M61 - `/gsd-t-unattended` and `/gsd-t-unattended-watch` commands reference deleted bin modules and are currently non-functional (see techdebt.md CRITICAL finding). Use the `/loop` skill with native Workflows instead.
-Declarative rules table mapping each phase (`plan`, `execute`, `red-team`, `doc-ripple`, `design-verify`, `qa`, `integrate`, ...) to a default tier (`haiku`|`sonnet`|`opus`). Complexity signals promoted from the task plan (`cross_module_refactor`, `security_boundary`, `data_loss_risk`, `contract_design`) escalate sonnet→opus. Each command file documents its assignments in a `## Model Assignment` block.
+### State Files
-Contract: `.gsd-t/contracts/model-selection-contract.md` v1.0.0
+| File | Purpose |
+|------|---------|
+| `.gsd-t/.unattended/supervisor.pid` | Integer PID - exists only while supervisor is alive |
+| `.gsd-t/.unattended/state.json` | Live state snapshot - status, iter, milestone, lastTick |
+| `.gsd-t/.unattended/run.log` | Append-only worker stdout+stderr |
+| `.gsd-t/.unattended/stop` | Sentinel - touching this requests graceful stop |
+| `.gsd-t/.unattended/config.json` | Optional per-project config overrides |
-### Pre-flight runway estimator — `bin/runway-estimator.js`
+Contract: `.gsd-t/contracts/unattended-supervisor-contract.md` v1.0.0
-Reads historical per-spawn consumption from `.gsd-t/token-metrics.jsonl` via a three-tier query fallback (exact match on `{command, phase, domain}` → command+phase → command) and produces a confidence-weighted projection of end-of-run `pct`. If the projection would cross `STOP_THRESHOLD_PCT = 85`, the command refuses to start — the interactive session exits cleanly and an autonomous headless continuation is auto-spawned. The user never types `/clear`.
+---
-### Headless auto-spawn — `bin/headless-auto-spawn.js`
+## Progress Log Archival
-Detached child-process spawn (`child_process.spawn` with `detached:true`, `stdio:['ignore', fd, fd]`, `child.unref()`). Writes `.gsd-t/headless-sessions/{session-id}.json` with session metadata, polls with `process.kill(pid, 0)` liveness probe (timer `.unref()`-ed), marks `status: completed`, and posts a macOS `osascript` notification when done (graceful no-op on non-darwin). `bin/check-headless-sessions.js` renders the read-back banner on the next `gsd-t-resume` / `gsd-t-status`.
+Old Decision Log entries are rolled out of `progress.md` into numbered archives to keep it lean.
-Directory: `.gsd-t/headless-sessions/` — one JSON per session, plus optional `{id}-context.json` and log files.
+```bash
+# Run archival (idempotent)
+node bin/archive-progress.cjs
-### Per-spawn token telemetry — retired in M38
+# Preview without changes
+node bin/archive-progress.cjs --dry-run
-Between M35 and M38 GSD-T wrote an 18-field JSONL record per subagent spawn to `.gsd-t/token-metrics.jsonl`. M38 deletes that instrumentation along with the runway estimator and the three-band meter that consumed it; the headless-by-default spawn model doesn't need pre-flight projection, and the single-band meter measures itself directly via the Anthropic count_tokens API. Historical records are preserved in milestone archives but the file is no longer written.
+# Override defaults (keep 5 live, 20 per archive)
+node bin/archive-progress.cjs --keep 10 --per-archive 30
-## Metrics CLI — `gsd-t metrics`
+# Target a specific project
+node bin/archive-progress.cjs --project /path/to/project
+```
-Read-only surface onto the token telemetry stream. Backward-compatible with pre-M35 `metrics` output; new flags surface M35 data.
+Archives land in `.gsd-t/progress-archive/NNN-YYYY-MM-DD.md`. An `index.md` is rebuilt on each run.
-| Flag                  | Output                                                                                 |
-|-----------------------|----------------------------------------------------------------------------------------|
-| (no flag)             | Task telemetry, process ELO, domain health (pre-M35 behavior)                          |
-| `--tokens`            | Per-command / per-phase token usage summary from `.gsd-t/token-metrics.jsonl`          |
-| `--halts`             | Count + breakdown of `halt_type` values — flags any `native-compact` as a defect       |
-| `--context-window`    | Trailing 20-run window of `end_pct` with runway headroom                               |
-| `--cross-project`     | Cross-project ranking (pre-M35, unchanged)                                             |
+---
-## `/advisor` escalation convention
+## Security Notes
-When a sonnet-default phase hits a complexity signal that warrants opus (e.g., cross-module refactor detected mid-execution), the command may emit an `/advisor` hook line in its output — a structured suggestion for the orchestrator to escalate the **next** spawn of that phase to opus. This is a plan-time signal, not a runtime swap: the current spawn completes at its assigned tier, and the escalation applies to subsequent work. See `.gsd-t/contracts/model-selection-contract.md` for the hook schema.
+- Zero npm runtime dependencies - no supply chain risk
+- All file writes check for symlinks first
+- Input validation on project names, versions, session IDs, paths
+- Heartbeat stdin capped at 1MB
+- HTTP requests use HTTPS with timeouts (5s for version check)
+- Init operations use exclusive file creation (`{ flag: "wx" }`)
+- Watch-state files: `gsd-t-watch-state.js` uses `--agent-id` to construct file paths - ensure agent IDs contain only alphanumeric/hyphen/underscore characters (path traversal vulnerability in current version, see techdebt)
+- Stream feed POST `/ingest` has no body size limit (denial-of-service risk, see techdebt)
+- Neo4j password is hardcoded in installer (see techdebt) - change after install for sensitive codebases
+- Design review server: `item.id` values from queue files are used unsanitized in file paths (path traversal, see techdebt)
-## Unattended Supervisor Setup (M36)
+---
-The unattended supervisor runs an active GSD-T milestone to completion in a detached OS process — no terminal needed, no human intervention required.
+## Troubleshooting
-### Quick Start
+**`gsd-t: command not found`**
 ```bash
-# From within an interactive Claude session:
-/gsd-t-unattended
-# From the terminal (detached — returns immediately):
-gsd-t unattended --hours=24 --milestone=M36
-# Watch current run status (in-session, 270s tick):
-/gsd-t-unattended-watch
-# Request a graceful stop:
-/gsd-t-unattended-stop
+# Install globally
+npm install -g @tekyzinc/gsd-t
+# or use npx
+npx @tekyzinc/gsd-t status
 ```
-### CLI Flags
+**Hooks not firing**
+```bash
+gsd-t doctor
+# Check "Hooks" section output
+# Re-run install if missing:
+npx @tekyzinc/gsd-t install
 ```
-gsd-t unattended [OPTIONS]
-  --hours=24              Wall-clock cap in hours (default: 24)
-  --max-iterations=200    Worker iteration cap (default: 200)
-  --project=.             Project directory (default: cwd)
-  --branch=AUTO           Branch to run on; AUTO = current non-protected branch
-  --on-done=print         Terminal action: print | merge-commit (merge-commit is v2)
-  --dry-run               Preflight only; no spawn
-  --verbose               Extra log detail
-  --test-mode             Uses stub worker; for CI and smoke tests
-```
-### Config File (optional)
-`.gsd-t/unattended-config.json` — per-project overrides. Absence = hardcoded defaults.
+**Workflow fails with `ReferenceError: require is not defined`**
-```json
-{
-  "hours": 24,
-  "maxIterations": 200,
-  "gutterNoProgressIters": 5,
-  "workerTimeoutMs": 3600000,
-  "protectedBranches": ["main", "master", "develop", "trunk"],
-  "dirtyTreeWhitelist": [".gsd-t/.unattended/*", ".gsd-t/events/*.jsonl"]
-}
-```
+This is a known CRITICAL defect (M71 migration incomplete). All workflow scripts except `gsd-t-scan.workflow.js` crash in the native Workflow sandbox. See techdebt.md. Workaround: use `/gsd-t-execute` etc. in hand-driven mode via Claude Code slash commands, not via the native `Workflow()` tool directly.
-### State Files
+**Neo4j container stopped**
-| File | Purpose |
-|------|---------|
-| `.gsd-t/.unattended/supervisor.pid` | Integer PID. Exists only while supervisor is alive. |
-| `.gsd-t/.unattended/state.json` | Live state snapshot — status, iter, milestone, lastTick, etc. Full schema in `unattended-supervisor-contract.md`. |
-| `.gsd-t/.unattended/run.log` | Append-only worker stdout+stderr. Never truncated during a run. |
-| `.gsd-t/.unattended/stop` | Sentinel — touching this file requests a graceful stop. |
-| `.gsd-t/.unattended/config.json` | Optional per-project config overrides (same keys as CLI flags). |
-### Required Platform Helpers
-| Platform | Sleep Prevention | Notifications |
-|----------|-----------------|---------------|
-| macOS | `caffeinate` (built-in) | `osascript` (built-in) |
-| Linux | `systemd-inhibit` or no-op | `notify-send` (install via `apt`/`dnf`) |
-| Windows | NOT supported — see `docs/unattended-windows-caveats.md` | no-op |
-macOS and Linux work out of the box on standard installs. Windows can run the supervisor but the machine may sleep mid-run.
-### Contract
-`.gsd-t/contracts/unattended-supervisor-contract.md` v1.0.0 — authoritative state schema, exit-code table, status enum, launch/resume handshakes.
-### Troubleshooting
-**Supervisor won't start**
-- Check `.gsd-t/.unattended/run.log` for error output
-- Run `gsd-t unattended --dry-run` to run pre-flight checks without spawning
-- Verify no protected branch: `git branch --show-current`
-**"Already running" error**
 ```bash
-# Verify supervisor is actually alive:
-kill -0 $(cat .gsd-t/.unattended/supervisor.pid) && echo "alive" || echo "stale PID"
+docker start gsd-t-neo4j
+# Or check status:
+gsd-t doctor
+```
-# If stale, remove PID file:
-rm .gsd-t/.unattended/supervisor.pid
+**Dashboard orphan processes**
-# Or request a graceful stop:
-/gsd-t-unattended-stop
-# (or) touch .gsd-t/.unattended/stop
+```bash
+gsd-t doctor --prune
 ```
-**Watch loop stopped firing**
-- Re-invoke `/gsd-t-resume` from a fresh session
-- Step 0 auto-reattach reads `supervisor.pid` — if the supervisor is still alive, it re-enters the watch loop automatically (no manual steps needed)
+**Journey coverage pre-commit hook blocks commits**
-**Supervisor crashed mid-run**
-- The watch loop detects crash via `kill -0` failure
-- Check `.gsd-t/.unattended/run.log` and final `state.json` for diagnostics
-- Resume normally with `/gsd-t-resume` — the milestone continues from its last checkpoint
----
+```bash
+# Check which files are missing coverage
+gsd-t check-coverage --report
+# Or remove the hook from .git/hooks/pre-commit if not needed
+```
-## Security Notes
+**All commits blocked by pre-commit-capture-lint hook**
-- Zero npm dependencies — no supply chain risk
-- All file writes check for symlinks first
-- Input validation on project names, versions, session IDs, paths
-- Heartbeat stdin capped at 1MB
-- HTTP requests use HTTPS with timeouts
-- Init operations use exclusive file creation (`{ flag: "wx" }`)
+Remove the hook section from `.git/hooks/pre-commit` - the `gsd-t capture-lint` subcommand was retired in M61 and no longer exists. The hook unconditionally exits 1.