@tekyzinc/gsd-t 2.39.13 → 2.46.11

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/framework-comparison-scorecard.md

@@ -0,0 +1,160 @@
+# Framework Comparison Scorecard
+
+**Purpose**: Unbiased comparison of development frameworks.
+**Instructions**: Score each framework 1-5 per dimension. Use the rubric at the bottom. Equal weights — no dimension gaming.
+
+---
+
+## Frameworks Being Compared
+
+| Slot | Framework | Version/Variant | Evaluator | Date |
+|------|-----------|-----------------|-----------|------|
+| F1   |           |                 |           |      |
+| F2   |           |                 |           |      |
+| F3   |           |                 |           |      |
+| F4   |           |                 |           |      |
+
+---
+
+## A. Onboarding & Adoption (Dimensions 1-3)
+
+| # | Dimension | What to Evaluate | F1 | F2 | F3 | F4 |
+|---|-----------|------------------|----|----|----|----|
+| 1 | Time to first productive output | How quickly can someone go from choosing the framework to shipping real work? |    |    |    |    |
+| 2 | Team adoption friction | How willing is a typical team to adopt it after initial exposure? |    |    |    |    |
+| 3 | Works without specific tooling | Can it be used with any IDE, editor, or AI assistant? |    |    |    |    |
+| | **Category Average** | | **—** | **—** | **—** | **—** |
+
+## B. Execution & Delivery (Dimensions 4-7)
+
+| # | Dimension | What to Evaluate | F1 | F2 | F3 | F4 |
+|---|-----------|------------------|----|----|----|----|
+| 4 | Defect prevention | How effectively does the framework prevent bugs from reaching production? |    |    |    |    |
+| 5 | Throughput | How many features can be shipped per unit time? |    |    |    |    |
+| 6 | Rework prevention | How well does the framework prevent completed work from needing redo? |    |    |    |    |
+| 7 | Idea-to-deploy cycle time | How quickly can a concept move from idea to production? |    |    |    |    |
+| | **Category Average** | | **—** | **—** | **—** | **—** |
+
+## C. Sustainability & Maintenance (Dimensions 8-11)
+
+| # | Dimension | What to Evaluate | F1 | F2 | F3 | F4 |
+|---|-----------|------------------|----|----|----|----|
+| 8  | New member ramp-up | How quickly can a new team member contribute independently? |    |    |    |    |
+| 9  | Context recovery | How easily can work resume after an interruption of days or weeks? |    |    |    |    |
+| 10 | Tech debt management | How well does the framework track and control technical debt? |    |    |    |    |
+| 11 | Documentation freshness | How well does the framework keep documentation accurate and current? |    |    |    |    |
+| | **Category Average** | | **—** | **—** | **—** | **—** |
+
+## D. Flexibility & Universality (Dimensions 12-15)
+
+| # | Dimension | What to Evaluate | F1 | F2 | F3 | F4 |
+|---|-----------|------------------|----|----|----|----|
+| 12 | Minimum viable process | Can you use a small portion of it and still get value? |    |    |    |    |
+| 13 | Project type coverage | Does it work across web, mobile, data, infra, and non-code projects? |    |    |    |    |
+| 14 | Team size range | Is it effective from 1-person teams to 50-person teams? |    |    |    |    |
+| 15 | Overhead proportionality | Does ceremony scale with project size rather than being fixed? |    |    |    |    |
+| | **Category Average** | | **—** | **—** | **—** | **—** |
+
+## E. Automation & AI-Agent Capabilities (Dimensions 16-19)
+
+| # | Dimension | What to Evaluate | F1 | F2 | F3 | F4 |
+|---|-----------|------------------|----|----|----|----|
+| 16 | Agentic workflow support | Does the framework enable AI agents to execute work autonomously (task dispatch, parallel execution, adaptive replanning)? |    |    |    |    |
+| 17 | QA automation | Does the framework automate test generation, execution, and gap detection — not just run existing tests? |    |    |    |    |
+| 18 | QA coverage enforcement | Does the framework enforce minimum coverage and block progress when tests are missing or failing? |    |    |    |    |
+| 19 | Contract enforcement | Does the framework define and validate interfaces between components automatically (API shapes, schemas, props)? |    |    |    |    |
+| | **Category Average** | | **—** | **—** | **—** | **—** |
+
+## F. Observability & Decision Quality (Dimensions 20-22)
+
+| # | Dimension | What to Evaluate | F1 | F2 | F3 | F4 |
+|---|-----------|------------------|----|----|----|----|
+| 20 | Decision traceability | Can you find why a choice was made 6 months later? |    |    |    |    |
+| 21 | Progress accuracy | Does reported progress match actual state? |    |    |    |    |
+| 22 | Risk visibility | Do problems surface early or only at integration? |    |    |    |    |
+| | **Category Average** | | **—** | **—** | **—** | **—** |
+
+---
+
+## Summary
+
+| Category                                    | F1 | F2 | F3 | F4 |
+|---------------------------------------------|----|----|----|----|
+| A. Onboarding & Adoption (1-3)              |    |    |    |    |
+| B. Execution & Delivery (4-7)               |    |    |    |    |
+| C. Sustainability & Maintenance (8-11)      |    |    |    |    |
+| D. Flexibility & Universality (12-15)       |    |    |    |    |
+| E. Automation & AI-Agent Capabilities (16-19) |    |    |    |    |
+| F. Observability & Decisions (20-22)        |    |    |    |    |
+| **Overall Average (1-5)**                   | **—** | **—** | **—** | **—** |
+| **Normalized Score (/100)**                 | **—** | **—** | **—** | **—** |
+
+### Calculation
+
+```
+Category Average = sum of dimension scores in category / number of dimensions in category
+Overall Average  = sum of all 22 dimension scores / 22
+Normalized /100  = Overall Average × 20
+```
+
+---
+
+## Radar Chart Data
+
+For visual comparison, plot each framework on a 6-axis radar chart using the category averages:
+
+```
+Axis 1: Onboarding & Adoption
+Axis 2: Execution & Delivery
+Axis 3: Sustainability & Maintenance
+Axis 4: Flexibility & Universality
+Axis 5: Automation & AI-Agent Capabilities
+Axis 6: Observability & Decisions
+```
+
+---
+
+## Scoring Rubric
+
+Use this rubric consistently across all frameworks and dimensions:
+
+| Score | Label         | Definition                                                                   |
+|-------|---------------|------------------------------------------------------------------------------|
+| 1     | Absent        | Not addressed by the framework. User must solve this entirely on their own.  |
+| 2     | Minimal       | Acknowledged but not enforced. Ad-hoc or optional guidance only.             |
+| 3     | Supported     | Present with some structure, but inconsistently applied or easy to skip.     |
+| 4     | Systematic    | Well-integrated, mostly enforced, clear process with known exceptions.       |
+| 5     | Core strength | Foundational to the framework. Systematically enforced, hard to bypass.      |
+
+### Scoring guidelines
+
+- **Score what the framework provides**, not what a disciplined team could achieve without it
+- **Score the default experience**, not the best-case customized setup
+- **Score independently** — don't let a high score in one dimension inflate adjacent ones
+- **Use 3 as the anchor** — most frameworks land at 3 for most dimensions. Reserve 1 and 5 for clear extremes
+- **When uncertain**, score conservatively (lower)
+
+---
+
+## Bias Checks
+
+Before finalizing scores, verify:
+
+- [ ] No single framework scores 5 on more than 9 of 22 dimensions
+- [ ] No single framework scores below 2 on more than 9 of 22 dimensions
+- [ ] Every framework has at least one category where it leads
+- [ ] The evaluator did not design or build any of the frameworks being compared (if they did, note the conflict and consider a second evaluator)
+- [ ] Dimensions were not added or removed after seeing preliminary scores
+
+---
+
+## Notes & Justifications
+
+Use this section to record reasoning for any score that might be controversial:
+
+| Dimension | Framework | Score | Justification |
+|-----------|-----------|-------|---------------|
+|           |           |       |               |
+|           |           |       |               |
+|           |           |       |               |
+|           |           |       |               |

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) |
 
 ---