@tekyzinc/gsd-t 2.39.13 → 2.45.11

package/docs/GSD-T-README.md

@@ -12,6 +12,8 @@ A methodology for reliable, parallelizable development using Claude Code with op
 
 **Catches downstream effects** — analyzes impact before changes break things.
 
+**Self-learning rule engine** — declarative rules detect failure patterns from task metrics. Patches progress through 5 lifecycle stages with measurable improvement gates before graduating into permanent methodology.
+
 ---
 
 ## Quick Start
@@ -96,26 +98,27 @@ GSD-T reads all state files and tells you exactly where you left off.
 | `/user:gsd-t-milestone` | Define new milestone | Manual |
 | `/user:gsd-t-partition` | Decompose into domains + contracts | In wave |
 | `/user:gsd-t-discuss` | Multi-perspective design exploration | In wave |
-| `/user:gsd-t-plan` | Create atomic task lists per domain | In wave |
+| `/user:gsd-t-plan` | Create atomic task lists per domain (tasks auto-split to fit one context window) | In wave |
 | `/user:gsd-t-impact` | Analyze downstream effects | In wave |
-| `/user:gsd-t-execute` | Run tasks (solo or team) | In wave |
+| `/user:gsd-t-execute` | Run tasks — task-level fresh dispatch, worktree isolation, adaptive replanning | In wave |
 | `/user:gsd-t-test-sync` | Sync tests with code changes | In wave |
 | `/user:gsd-t-qa` | QA agent — test generation, execution, gap reporting | Auto-spawned |
 | `/user:gsd-t-integrate` | Wire domains together | In wave |
-| `/user:gsd-t-verify` | Run quality gates | In wave |
-| `/user:gsd-t-complete-milestone` | Archive + git tag | In wave |
+| `/user:gsd-t-verify` | Run quality gates + goal-backward verification → auto-invokes complete-milestone | In wave |
+| `/user:gsd-t-complete-milestone` | Archive + git tag (auto-invoked by verify, also standalone) | In wave |
 
 ### Automation & Utilities
 
 | Command | Purpose | Auto |
 |---------|---------|------|
 | `/user:gsd-t-wave` | Full cycle, auto-advances all phases | Manual |
-| `/user:gsd-t-status` | Cross-domain progress view | Manual |
+| `/user:gsd-t-status` | Cross-domain progress view with token breakdown, global ELO and cross-project rankings | Manual |
 | `/user:gsd-t-resume` | Restore context, continue | Manual |
 | `/user:gsd-t-quick` | Fast task with GSD-T guarantees | Manual |
 | `/user:gsd-t-reflect` | Generate retrospective from event stream, propose memory updates | Manual |
 | `/user:gsd-t-visualize` | Launch browser dashboard — SSE server + React Flow agent visualization | Manual |
 | `/user:gsd-t-debug` | Systematic debugging with state | Manual |
+| `/user:gsd-t-metrics` | View task telemetry, process ELO, signal distribution, domain health, and cross-project comparison (`--cross-project`) | Manual |
 | `/user:gsd-t-health` | Validate .gsd-t/ structure, optionally repair | Manual |
 | `/user:gsd-t-pause` | Save exact position for reliable resume | Manual |
 | `/user:gsd-t-log` | Sync progress Decision Log with recent git activity | Manual |
@@ -154,7 +157,7 @@ GSD-T reads all state files and tells you exactly where you left off.
 │                                              │    │  task + at verify)│     │
 │                                              │    └───────────────────┘     │
 │                                              ▼                              │
-│  complete-milestone ◄── verify ◄── integrate ◄──────────────────────┘      │
+│  verify+complete ◄──────────── integrate ◄──────────────────────┘          │
 │                                                                             │
 └─────────────────────────────────────────────────────────────────────────────┘
 ```

package/docs/architecture.md

@@ -1,6 +1,6 @@
 # Architecture — GSD-T Framework (@tekyzinc/gsd-t)
 
-## Last Updated: 2026-03-19 (Scan #10, Post-M20/M21)
+## Last Updated: 2026-03-22 (M23 — Headless Mode)
 
 ## System Overview
 
@@ -16,7 +16,7 @@ The framework has no runtime — it is consumed entirely by Claude Code's slash
 - **Purpose**: Install, update, diagnose, and manage GSD-T across projects
 - **Location**: `bin/gsd-t.js` (1,798 lines, 90+ functions, all ≤ 30 lines)
 - **Dependencies**: Node.js built-ins only (fs, path, os, child_process, https, crypto)
-- **Subcommands**: install, update, status, doctor, init, uninstall, update-all, register, changelog, graph (index/status/query)
+- **Subcommands**: install, update, status, doctor, init, uninstall, update-all, register, changelog, graph (index/status/query), headless (exec/query)
 - **Organization**: Configuration → Guard section → Helpers → Heartbeat → Commands → Install/Update → Init → Status → Uninstall → Update-All → Doctor → Register → Update Check → Help → Main dispatch
 - **All functions ≤ 30 lines** (M6 refactoring). Largest: `doRegister()` at 30 lines, `summarize()` at 30 lines.
 
@@ -66,6 +66,18 @@ The framework has no runtime — it is consumed entirely by Claude Code's slash
 - **`scripts/gsd-t-dashboard.html`** (194 lines): React 17 + React Flow v11.11.4 + Dagre via CDN (no build step, no npm deps). Dark theme (`#0d1117`). Renders agent hierarchy as directed graph from `parent_agent_id` relationships. Live event feed (max 200, outcome color-coded). Auto-reconnects on SSE disconnect. Port configurable via `?port=` URL param.
 - **`commands/gsd-t-visualize.md`** (104 lines, 48th command): Starts server via `--detach`, polls `/ping` up to 5s, opens browser cross-platform (win32/darwin/linux). Accepts `stop` argument to shut down server. Step 0 self-spawn with OBSERVABILITY LOGGING.
 
+### Headless Mode (M23 — complete)
+- **doHeadless(args)**: Dispatch function for the `headless` CLI subcommand.
+- **doHeadlessExec(command, cmdArgs, flags)**: Wraps `claude -p "/user:gsd-t-{command}"` via `execFileSync`. Verifies claude CLI availability, enforces timeout, writes log file if `--log` requested. Returns structured JSON if `--json` flag set.
+- **parseHeadlessFlags(args)**: Extracts `--json`, `--timeout=N`, `--log` from raw args. Returns `{ flags, positional }`.
+- **buildHeadlessCmd(command, cmdArgs)**: Builds the `/user:gsd-t-{command}` prompt string.
+- **mapHeadlessExitCode(processExitCode, output)**: Maps process exit code + output text patterns to GSD-T exit codes (0–4).
+- **headlessLogPath(projectDir, timestamp)**: Generates `.gsd-t/headless-{timestamp}.log` path.
+- **doHeadlessQuery(type)**: Dispatches to one of 7 query functions. All pure Node.js file reads, no LLM calls, <100ms.
+- **Query functions** (7): `queryStatus`, `queryDomains`, `queryContracts`, `queryDebt`, `queryContext`, `queryBacklog`, `queryGraph` — each reads corresponding `.gsd-t/` file and returns typed JSON result.
+- **Exit codes**: 0=success, 1=verify-fail, 2=context-budget-exceeded, 3=error, 4=blocked-needs-human
+- **CI/CD examples**: `docs/ci-examples/github-actions.yml` (GitHub Actions), `docs/ci-examples/gitlab-ci.yml` (GitLab CI)
+
 ### Graph Engine (M20 — complete)
 - **`bin/graph-store.js`** (147 lines): File-based graph storage in `.gsd-t/graph/`. 8 JSON files (index, calls, imports, contracts, requirements, tests, surfaces, meta). Read/write operations, MD5 file hashing for incremental indexing, staleness detection. Zero external deps. Note: no symlink protection (TD-099).
 - **`bin/graph-parsers.js`** (327 lines): Language-specific entity parsers. JS/TS: function declarations, arrow functions, classes, methods, imports (ES/CJS), exports. Python: def/class/import. Regex-based (no Tree-sitter). Returns `{ entities, imports, calls }`.
@@ -271,6 +283,76 @@ QA runs inline or as Task subagent depending on phase (M10 refactor). Removed fr
 | 2026-02-18 | gsd-t-tools.js as state utility CLI | Reduces token-heavy markdown parsing; compact JSON responses save ~50K tokens/wave | Parsing progress.md inline (original) |
 | 2026-02-18 | continue-here files for pause/resume | More precise than progress.md; captures exact task+next-action, not just phase | progress.md alone (less precise) |
 
+### GSD 2 Tier 1 — Execution Quality (M22 — complete v2.40.10)
+
+Five interlocking capabilities eliminate context rot, enable safe parallel execution, and verify behavior rather than structure alone.
+
+**Task-Level Fresh Dispatch**
+
+Execute dispatches one subagent per TASK (not per domain). Each task agent gets a fresh context window containing only: domain scope.md, relevant contracts, the single current task, graph context for touched files, and prior task summaries (10-20 lines each). Context utilization per task: ~10-20% (down from 60-75% cumulative per domain). Compaction never triggers. The domain dispatcher (lightweight orchestrator) sequences tasks and passes summaries — it never accumulates full task context.
+
+```
+Execute orchestrator (summaries only — ~4-8% ctx)
+  └── Domain-A task-dispatcher
+       ├── Task 1 subagent (fresh, 10-20% ctx) → summary → dies
+       ├── Task 2 subagent (fresh + task 1 summary) → summary → dies
+       └── Task N subagent (fresh + prior summaries) → summary → dies
+```
+
+**Plan command constraint** (added M22): Every task must fit in one context window. If estimated scope exceeds 70% context, plan splits the task automatically.
+
+**Worktree Isolation**
+
+Parallel domain agents work in isolated git worktrees via Agent tool's `isolation: "worktree"` parameter. No shared filesystem — domains cannot step on each other's files. Merges are sequential and atomic:
+
+```
+Dispatch N domains (isolation: "worktree") → parallel execution
+  └── Domain A completes → merge A → run integration tests
+  └── Domain B completes → merge B → run integration tests
+  └── Conflict or test failure → rollback that domain, others unaffected
+```
+
+Rollback granularity is per-domain (not per-commit). Worktrees are cleaned up after all merges complete.
+
+**Goal-Backward Verification**
+
+After all structural quality gates pass (tests, contracts, file existence), a goal-backward pass verifies behavior. Reads milestone goals, traces each requirement to code, and checks for placeholders:
+- `console.log("TODO")` / `console.log("implement X")`
+- Hardcoded return values (`return "Synced"`, `return 200` on a path that should compute)
+- `// TODO`, `// FIXME`, `// PLACEHOLDER` comments in critical paths
+- UI components rendering static strings where dynamic data is required
+
+Applied in: `verify`, `complete-milestone`, `wave` (verification phase).
+
+**Adaptive Replanning**
+
+After each domain completes in execute, the orchestrator reads the domain's result summary and evaluates whether remaining domain plans remain valid. If execution revealed new constraints (deprecated API, schema mismatch, missing dependency, incompatible library), affected domain `tasks.md` files are rewritten on disk before the next domain is dispatched.
+
+Guard: max 2 replanning cycles per execute run. After that, pause for user input (prevents new-constraint → replan → new-constraint loops).
+
+**Context Observability**
+
+Extended token-log.md format (M22) includes `Domain`, `Task`, and `Ctx%` columns:
+
+```
+| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Tokens | Compacted | Domain | Task | Ctx% |
+```
+
+Alert thresholds (inline display):
+- `Ctx% >= 70%` → warning: task approaching compaction, consider splitting
+- `Ctx% >= 85%` → critical: compaction likely, task MUST be split
+
+`gsd-t-status` displays token breakdown by domain/task/phase. `gsd-t-visualize` consumes the same data for dashboard rendering.
+
+## Planned Architecture Changes (M23-M24)
+
+**M23: Headless Mode**
+- New `gsd-t headless` CLI subcommand wrapping `claude -p` for unattended execution.
+- New `gsd-t headless query` for instant JSON state access (no LLM).
+
+**M24: Docker**
+- Dockerfile + docker-compose for containerized enterprise execution.
+
 ## Known Architecture Concerns
 
 1. **CLI single-file size**: bin/gsd-t.js at 1,438 lines exceeds the 200-line convention, but splitting adds complexity for questionable benefit given zero-dependency constraint. Accepted deviation.

package/docs/ci-examples/desktop.ini

@@ -0,0 +1,2 @@
+[.ShellClassInfo]
+IconResource=C:\Program Files\Google\Drive File Stream\122.0.1.0\GoogleDriveFS.exe,27

package/docs/ci-examples/github-actions.yml

@@ -0,0 +1,104 @@
+# GSD-T Headless Mode — GitHub Actions Example
+#
+# This workflow demonstrates using `gsd-t headless` for automated milestone
+# verification in CI/CD pipelines.
+#
+# Prerequisites:
+#   - ANTHROPIC_API_KEY secret configured in your GitHub repository
+#   - GSD-T installed globally (npm install -g @tekyzinc/gsd-t)
+#   - Claude Code CLI installed (npm install -g @anthropic-ai/claude-code)
+#
+# Usage: Copy this file to .github/workflows/gsd-t-verify.yml in your project
+
+name: GSD-T Headless Verify
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      command:
+        description: 'GSD-T command to run (default: verify)'
+        required: false
+        default: 'verify'
+
+jobs:
+  gsd-t-verify:
+    name: GSD-T Quality Gates
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install GSD-T
+        run: npm install -g @tekyzinc/gsd-t @anthropic-ai/claude-code
+
+      - name: Query project status (no LLM needed)
+        id: status
+        run: |
+          STATUS=$(gsd-t headless query status)
+          echo "status=$STATUS" >> $GITHUB_OUTPUT
+          echo "GSD-T Project Status: $STATUS"
+
+      - name: Run GSD-T headless verify
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          gsd-t headless ${{ github.event.inputs.command || 'verify' }} \
+            --json \
+            --timeout=1200 \
+            --log
+        # Exit codes:
+        #   0 = success
+        #   1 = verify-fail (tests/gates failed)
+        #   2 = context-budget-exceeded (try splitting milestone)
+        #   3 = error (claude CLI error)
+        #   4 = blocked-needs-human (requires manual review)
+
+      - name: Upload headless log on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: gsd-t-headless-log
+          path: .gsd-t/headless-*.log
+          retention-days: 7
+
+  gsd-t-status-gate:
+    name: GSD-T State Query Gate
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install GSD-T
+        run: npm install -g @tekyzinc/gsd-t
+
+      - name: Check project status
+        run: gsd-t headless query status
+
+      - name: Check for open tech debt
+        run: |
+          DEBT=$(gsd-t headless query debt)
+          COUNT=$(echo "$DEBT" | node -e "const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); process.exit(d.data.count > 0 ? 1 : 0)" || echo "")
+          echo "Tech debt items: $DEBT"
+
+      - name: List active domains
+        run: gsd-t headless query domains
+
+      - name: Check graph index
+        run: gsd-t headless query graph

package/docs/ci-examples/gitlab-ci.yml

@@ -0,0 +1,116 @@
+# GSD-T Headless Mode — GitLab CI Example
+#
+# This pipeline demonstrates using `gsd-t headless` for automated milestone
+# verification and state queries in GitLab CI/CD.
+#
+# Prerequisites:
+#   - ANTHROPIC_API_KEY variable configured in GitLab CI/CD settings
+#   - Node.js 20+ runner
+#
+# Usage: Copy the relevant stages/jobs into your .gitlab-ci.yml
+
+stages:
+  - status
+  - verify
+  - report
+
+variables:
+  NODE_VERSION: "20"
+  GSD_T_TIMEOUT: "1200"
+
+# ─── Status Stage (no LLM, runs fast) ────────────────────────────────────────
+
+gsd-t-status:
+  stage: status
+  image: node:${NODE_VERSION}
+  before_script:
+    - npm install -g @tekyzinc/gsd-t
+  script:
+    - echo "=== Project Status ==="
+    - gsd-t headless query status
+    - echo "=== Active Domains ==="
+    - gsd-t headless query domains
+    - echo "=== Contracts ==="
+    - gsd-t headless query contracts
+    - echo "=== Tech Debt ==="
+    - gsd-t headless query debt
+    - echo "=== Backlog ==="
+    - gsd-t headless query backlog
+  artifacts:
+    reports:
+      # Capture JSON output for downstream jobs
+      dotenv: .gsd-t-status.env
+  allow_failure: false
+
+# ─── Verify Stage (LLM-powered, requires ANTHROPIC_API_KEY) ─────────────────
+
+gsd-t-verify:
+  stage: verify
+  image: node:${NODE_VERSION}
+  before_script:
+    - npm install -g @tekyzinc/gsd-t @anthropic-ai/claude-code
+  script:
+    - >
+      gsd-t headless verify
+      --json
+      --timeout=${GSD_T_TIMEOUT}
+      --log
+  after_script:
+    - cat .gsd-t/headless-*.log 2>/dev/null || true
+  artifacts:
+    when: always
+    paths:
+      - .gsd-t/headless-*.log
+    expire_in: 1 week
+  # Exit code mapping:
+  #   0 = success — pipeline continues
+  #   1 = verify-fail — pipeline fails (tests/quality gates failed)
+  #   2 = context-budget-exceeded — pipeline fails (split milestone required)
+  #   3 = error — pipeline fails (check claude CLI config)
+  #   4 = blocked-needs-human — pipeline fails with manual review needed
+  variables:
+    ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
+  only:
+    - main
+    - develop
+    - merge_requests
+
+# ─── Report Stage ────────────────────────────────────────────────────────────
+
+gsd-t-context-report:
+  stage: report
+  image: node:${NODE_VERSION}
+  before_script:
+    - npm install -g @tekyzinc/gsd-t
+  script:
+    - echo "=== Token/Context Usage ==="
+    - gsd-t headless query context
+    - echo "=== Graph Index ==="
+    - gsd-t headless query graph
+  when: always
+  allow_failure: true
+
+# ─── Nightly Headless Execute ─────────────────────────────────────────────────
+# Run overnight to execute a milestone phase unattended
+
+gsd-t-nightly-execute:
+  stage: verify
+  image: node:${NODE_VERSION}
+  before_script:
+    - npm install -g @tekyzinc/gsd-t @anthropic-ai/claude-code
+  script:
+    - >
+      gsd-t headless execute
+      --json
+      --timeout=3600
+      --log
+  artifacts:
+    when: always
+    paths:
+      - .gsd-t/headless-*.log
+    expire_in: 2 weeks
+  variables:
+    ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
+  only:
+    - schedules  # Only runs on scheduled pipelines
+  allow_failure: false

package/docs/desktop.ini

@@ -0,0 +1,2 @@
+[.ShellClassInfo]
+IconResource=C:\Program Files\Google\Drive File Stream\122.0.1.0\GoogleDriveFS.exe,27

package/docs/infrastructure.md

@@ -1,6 +1,6 @@
 # Infrastructure — GSD-T Framework (@tekyzinc/gsd-t)
 
-## Last Updated: 2026-03-09 (Scan #9, Post-M17)
+## Last Updated: 2026-03-22 (M23 — Headless Mode)
 
 ## Quick Reference
 
@@ -14,6 +14,8 @@
 | 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) |
+| Headless exec | `gsd-t headless <command> [--json] [--timeout=N] [--log]` |
+| Headless query | `gsd-t headless query <type>` (no LLM, <100ms) |
 
 ## Local Development
 
@@ -109,6 +111,90 @@ get-stuff-done-teams/
 └── package.json        — npm package config
 ```
 
+## Headless Mode (M23)
+
+Headless mode enables non-interactive GSD-T execution for CI/CD pipelines and overnight builds.
+
+### headless exec
+
+Wraps `claude -p "/user:gsd-t-{command} {args}"` for unattended execution.
+
+```bash
+gsd-t headless verify --json --timeout=1200 --log
+gsd-t headless execute --timeout=3600
+gsd-t headless wave --json
+```
+
+**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` |
+
+**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) |
+
+**JSON envelope shape (--json flag):**
+```json
+{
+  "success": true,
+  "exitCode": 0,
+  "gsdtExitCode": 0,
+  "command": "verify",
+  "args": [],
+  "output": "...",
+  "timestamp": "2026-03-22T10:00:00.000Z",
+  "duration": 42150,
+  "logFile": ".gsd-t/headless-1742641200000.log"
+}
+```
+
+### headless query
+
+Pure Node.js file parsing — no LLM calls, <100ms response.
+
+```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
+```
+
+All queries return JSON to stdout.
+
+### CI/CD Integration
+
+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
+
+**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:**
+```yaml
+gsd-t-verify:
+  script:
+    - gsd-t headless verify --json --timeout=1200
+  variables:
+    ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
+```
+
 ## Security Notes
 
 - Zero npm dependencies — no supply chain risk

package/docs/prd-graph-engine.md

@@ -6,12 +6,12 @@
 | **PRD ID** | PRD-GRAPH-001 |
 | **Date** | 2026-03-18 |
 | **Author** | GSD-T Team |
-| **Status** | DRAFT |
+| **Status** | DELIVERED (M20 + M21 complete — 2026-03-20) |
 | **Milestones** | M20 (Graph Abstraction + Indexer + CGC), M21 (Graph-Powered Commands) |
 | **Version Target** | 2.37.10 (M20), 2.38.10 (M21) |
 | **Priority** | P0 — foundational for all future enhancements |
 | **Predecessor** | M19 (Shared Service Detection v2.35.10) |
-| **Successor** | Scan self-validation, then GSD 2 milestones (M22+) |
+| **Successor** | GSD 2 milestones (M22 COMPLETE, M23-M24 queued) |
 
 ---