gsd-opencode 1.20.4 → 1.22.1

package/get-shit-done/workflows/validate-phase.md

@@ -0,0 +1,167 @@
+<purpose>
+Audit Nyquist validation gaps for a completed phase. Generate missing tests. Update VALIDATION.md.
+</purpose>
+
+<required_reading>
+@$HOME/.config/opencode/get-shit-done/references/ui-brand.md
+</required_reading>
+
+<process>
+
+## 0. Initialize
+
+```bash
+INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init phase-op "${PHASE_ARG}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`.
+
+```bash
+AUDITOR_MODEL=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" resolve-model gsd-nyquist-auditor --raw)
+NYQUIST_CFG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config get workflow.nyquist_validation --raw)
+```
+
+If `NYQUIST_CFG` is `false`: exit with "Nyquist validation is disabled. Enable via /gsd-settings."
+
+Display banner: `GSD > VALIDATE PHASE {N}: {name}`
+
+## 1. Detect Input State
+
+```bash
+VALIDATION_FILE=$(ls "${PHASE_DIR}"/*-VALIDATION.md 2>/dev/null | head -1)
+SUMMARY_FILES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null)
+```
+
+- **State A** (`VALIDATION_FILE` non-empty): Audit existing
+- **State B** (`VALIDATION_FILE` empty, `SUMMARY_FILES` non-empty): Reconstruct from artifacts
+- **State C** (`SUMMARY_FILES` empty): Exit — "Phase {N} not executed. Run /gsd-execute-phase {N} first."
+
+## 2. Discovery
+
+### 2a. read Phase Artifacts
+
+read all PLAN and SUMMARY files. Extract: task lists, requirement IDs, key-files changed, verify blocks.
+
+### 2b. Build Requirement-to-task Map
+
+Per task: `{ task_id, plan_id, wave, requirement_ids, has_automated_command }`
+
+### 2c. Detect Test Infrastructure
+
+State A: Parse from existing VALIDATION.md Test Infrastructure table.
+State B: Filesystem scan:
+
+```bash
+find . -name "pytest.ini" -o -name "jest.config.*" -o -name "vitest.config.*" -o -name "pyproject.toml" 2>/dev/null | head -10
+find . \( -name "*.test.*" -o -name "*.spec.*" -o -name "test_*" \) -not -path "*/node_modules/*" 2>/dev/null | head -40
+```
+
+### 2d. Cross-Reference
+
+Match each requirement to existing tests by filename, imports, test descriptions. Record: requirement → test_file → status.
+
+## 3. Gap Analysis
+
+Classify each requirement:
+
+| Status | Criteria |
+|--------|----------|
+| COVERED | Test exists, targets behavior, runs green |
+| PARTIAL | Test exists, failing or incomplete |
+| MISSING | No test found |
+
+Build: `{ task_id, requirement, gap_type, suggested_test_path, suggested_command }`
+
+No gaps → skip to Step 6, set `nyquist_compliant: true`.
+
+## 4. Present Gap Plan
+
+Call question with gap table and options:
+1. "Fix all gaps" → Step 5
+2. "Skip — mark manual-only" → add to Manual-Only, Step 6
+3. "Cancel" → exit
+
+## 5. Spawn gsd-nyquist-auditor
+
+```
+task(
+  prompt="read $HOME/.config/opencode/agents/gsd-nyquist-auditor.md for instructions.\n\n" +
+    "<files_to_read>{PLAN, SUMMARY, impl files, VALIDATION.md}</files_to_read>" +
+    "<gaps>{gap list}</gaps>" +
+    "<test_infrastructure>{framework, config, commands}</test_infrastructure>" +
+    "<constraints>Never modify impl files. Max 3 debug iterations. Escalate impl bugs.</constraints>",
+  subagent_type="gsd-nyquist-auditor",
+  model="{AUDITOR_MODEL}",
+  description="Fill validation gaps for Phase {N}"
+)
+```
+
+Handle return:
+- `## GAPS FILLED` → record tests + map updates, Step 6
+- `## PARTIAL` → record resolved, move escalated to manual-only, Step 6
+- `## ESCALATE` → move all to manual-only, Step 6
+
+## 6. Generate/Update VALIDATION.md
+
+**State B (create):**
+1. read template from `$HOME/.config/opencode/get-shit-done/templates/VALIDATION.md`
+2. Fill: frontmatter, Test Infrastructure, Per-task Map, Manual-Only, Sign-Off
+3. write to `${PHASE_DIR}/${PADDED_PHASE}-VALIDATION.md`
+
+**State A (update):**
+1. Update Per-task Map statuses, add escalated to Manual-Only, update frontmatter
+2. Append audit trail:
+
+```markdown
+## Validation Audit {date}
+| Metric | Count |
+|--------|-------|
+| Gaps found | {N} |
+| Resolved | {M} |
+| Escalated | {K} |
+```
+
+## 7. Commit
+
+```bash
+git add {test_files}
+git commit -m "test(phase-${PHASE}): add Nyquist validation tests"
+
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit-docs "docs(phase-${PHASE}): add/update validation strategy"
+```
+
+## 8. Results + Routing
+
+**Compliant:**
+```
+GSD > PHASE {N} IS NYQUIST-COMPLIANT
+All requirements have automated verification.
+▶ Next: /gsd-audit-milestone
+```
+
+**Partial:**
+```
+GSD > PHASE {N} VALIDATED (PARTIAL)
+{M} automated, {K} manual-only.
+▶ Retry: /gsd-validate-phase {N}
+```
+
+Display `/new` reminder.
+
+</process>
+
+<success_criteria>
+- [ ] Nyquist config checked (exit if disabled)
+- [ ] Input state detected (A/B/C)
+- [ ] State C exits cleanly
+- [ ] PLAN/SUMMARY files read, requirement map built
+- [ ] Test infrastructure detected
+- [ ] Gaps classified (COVERED/PARTIAL/MISSING)
+- [ ] User gate with gap table
+- [ ] Auditor spawned with complete context
+- [ ] All three return formats handled
+- [ ] VALIDATION.md created or updated
+- [ ] Test files committed separately
+- [ ] Results with routing presented
+</success_criteria>

package/get-shit-done/workflows/verify-phase.md

@@ -18,8 +18,8 @@ Then verify each level against the actual codebase.
 </core_principle>
 
 <required_reading>
-@~/.config/opencode/get-shit-done/references/verification-patterns.md
-@~/.config/opencode/get-shit-done/templates/verification-report.md
+@$HOME/.config/opencode/get-shit-done/references/verification-patterns.md
+@$HOME/.config/opencode/get-shit-done/templates/verification-report.md
 </required_reading>
 
 <process>
@@ -28,14 +28,15 @@ Then verify each level against the actual codebase.
 Load phase operation context:
 
 ```bash
-INIT=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs init phase-op "${PHASE_ARG}")
+INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init phase-op "${PHASE_ARG}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
 Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`, `has_plans`, `plan_count`.
 
 Then load phase details and list plans/summaries:
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs roadmap get-phase "${phase_number}"
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "${phase_number}"
 grep -E "^| ${phase_number}" .planning/REQUIREMENTS.md 2>/dev/null
 ls "$phase_dir"/*-SUMMARY.md "$phase_dir"/*-PLAN.md 2>/dev/null
 ```
@@ -50,7 +51,7 @@ Use gsd-tools to extract must_haves from each PLAN:
 
 ```bash
 for plan in "$PHASE_DIR"/*-PLAN.md; do
-  MUST_HAVES=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs frontmatter get "$plan" --field must_haves)
+  MUST_HAVES=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" frontmatter get "$plan" --field must_haves)
   echo "=== $plan ===" && echo "$MUST_HAVES"
 done
 ```
@@ -64,7 +65,7 @@ Aggregate all must_haves across plans for phase-level verification.
 If no must_haves in frontmatter (MUST_HAVES returns error or empty), check for Success Criteria:
 
 ```bash
-PHASE_DATA=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs roadmap get-phase "${phase_number}" --raw)
+PHASE_DATA=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "${phase_number}" --raw)
 ```
 
 Parse the `success_criteria` array from the JSON output. If non-empty:
@@ -100,7 +101,7 @@ Use gsd-tools for artifact verification against must_haves in each PLAN:
 
 ```bash
 for plan in "$PHASE_DIR"/*-PLAN.md; do
-  ARTIFACT_RESULT=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs verify artifacts "$plan")
+  ARTIFACT_RESULT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" verify artifacts "$plan")
   echo "=== $plan ===" && echo "$ARTIFACT_RESULT"
 done
 ```
@@ -132,7 +133,7 @@ Use gsd-tools for key link verification against must_haves in each PLAN:
 
 ```bash
 for plan in "$PHASE_DIR"/*-PLAN.md; do
-  LINKS_RESULT=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs verify key-links "$plan")
+  LINKS_RESULT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" verify key-links "$plan")
   echo "=== $plan ===" && echo "$LINKS_RESULT"
 done
 ```
@@ -213,7 +214,7 @@ REPORT_PATH="$PHASE_DIR/${PHASE_NUM}-VERIFICATION.md"
 
 Fill template sections: frontmatter (phase/timestamp/status/score), goal achievement, artifact table, wiring table, requirements coverage, anti-patterns, human verification, gaps summary, fix plans (if gaps_found), metadata.
 
-See ~/.config/opencode/get-shit-done/templates/verification-report.md for complete template.
+See $HOME/.config/opencode/get-shit-done/templates/verification-report.md for complete template.
 </step>
 
 <step name="return_to_orchestrator">

package/get-shit-done/workflows/verify-work.md

@@ -15,7 +15,7 @@ No Pass/Fail buttons. No severity questions. Just: "Here's what should happen. D
 </philosophy>
 
 <template>
-@~/.config/opencode/get-shit-done/templates/UAT.md
+@$HOME/.config/opencode/get-shit-done/templates/UAT.md
 </template>
 
 <process>
@@ -24,7 +24,8 @@ No Pass/Fail buttons. No severity questions. Just: "Here's what should happen. D
 If $ARGUMENTS contains a phase number, load context:
 
 ```bash
-INIT=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs init verify-work "${PHASE_ARG}")
+INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init verify-work "${PHASE_ARG}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
 Parse JSON for: `planner_model`, `checker_model`, `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `has_verification`.
@@ -108,6 +109,19 @@ Examples:
   → Expected: "Clicking Reply opens inline composer below comment. Submitting shows reply nested under parent with visual indentation."
 
 Skip internal/non-observable items (refactors, type changes, etc.).
+
+**Cold-start smoke test injection:**
+
+After extracting tests from SUMMARYs, scan the SUMMARY files for modified/created file paths. If ANY path matches these patterns:
+
+`server.ts`, `server.js`, `app.ts`, `app.js`, `index.ts`, `index.js`, `main.ts`, `main.js`, `database/*`, `db/*`, `seed/*`, `seeds/*`, `migrations/*`, `startup*`, `docker-compose*`, `Dockerfile*`
+
+Then **prepend** this test to the test list:
+
+- name: "Cold Start Smoke Test"
+- expected: "Kill any running server/service. Clear ephemeral state (temp DBs, caches, lock files). Start the application from scratch. Server boots without errors, any seed/migration completes, and a primary query (health check, homepage load, or basic API call) returns live data."
+
+This catches bugs that only manifest on fresh start — race conditions in startup sequences, silent seed failures, missing environment setup — which pass against warm state but break in production.
 </step>
 
 <step name="create_uat_file">
@@ -292,7 +306,7 @@ Clear Current Test section:
 
 Commit the UAT file:
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit "test({phase_num}): complete UAT - {passed} passed, {issues} issues" --files ".planning/phases/XX-name/{phase_num}-UAT.md"
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "test({phase_num}): complete UAT - {passed} passed, {issues} issues" --files ".planning/phases/XX-name/{phase_num}-UAT.md"
 ```
 
 Present summary:
@@ -334,7 +348,7 @@ Spawning parallel debug agents to investigate each issue.
 ```
 
 - Load diagnose-issues workflow
-- Follow @~/.config/opencode/get-shit-done/workflows/diagnose-issues.md
+- Follow @$HOME/.config/opencode/get-shit-done/workflows/diagnose-issues.md
 - Spawn parallel debug agents for each issue
 - Collect root causes
 - Update UAT.md with root causes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd-opencode",
-  "version": "1.20.4",
+  "version": "1.22.1",
   "description": "GSD-OpenCode distribution manager - install, verify, and maintain your GSD-OpenCode installation",
   "type": "module",
   "main": "bin/gsd.js",