@tekyzinc/gsd-t 2.31.17 → 2.31.18

package/commands/gsd-t-complete-milestone.md

@@ -17,6 +17,30 @@ If status is not VERIFIED:
 
 If `--force` flag provided, proceed with warning in archive.
 
+## Step 1.5: Smoke Test Artifact Gate (MANDATORY — Categories 2 and 7)
+
+Before archiving, verify that high-risk features have testable artifacts. This gate catches what code review and unit tests cannot.
+
+**Scan this milestone's domains for any of the following:**
+- Audio capture/playback, speech recognition/synthesis
+- GPU/WebGPU/WebGL compute or rendering
+- ML inference, model loading, quantized model execution
+- Background workers, service workers, IPC channels
+- Native APIs (camera, bluetooth, filesystem, microphone)
+- WebAssembly modules
+- Any feature whose only prior "test" was manual user interaction
+
+**For each high-risk feature found:**
+
+1. Check that a smoke test script exists (in `scripts/`, `tests/`, or `.gsd-t/smoke-tests/`)
+2. Check that the script was run and passed (evidence in token-log.md, CI output, or a `.gsd-t/smoke-tests/{feature}.md` file with run results)
+3. If manual steps remain unavoidable: `.gsd-t/smoke-tests/{feature}.md` must exist documenting exact steps and confirming they passed
+
+**If any high-risk feature lacks a smoke test artifact → BLOCK completion.**
+Do not proceed to archiving. Create the smoke test now, run it, confirm it passes, then continue.
+
+> This gate exists because complete-milestone is the last opportunity to catch "shipped blind" features before they become user-facing bugs requiring 15 debug sessions to resolve.
+
 ## Step 2: Gap Analysis Gate
 
 After verification passes, run a gap analysis against `docs/requirements.md` scoped to this milestone's deliverables:

package/commands/gsd-t-debug.md

@@ -71,6 +71,27 @@ The contract didn't specify something it should have. Symptoms:
 
 → Update the contract, then fix implementations on both sides.
 
+## Step 2.5: Reproduce First (MANDATORY — Category 5)
+
+**A fix attempt without a reproduction script is a guess, not a fix.**
+
+Before touching any code:
+
+1. **Write a reproduction script** that demonstrates the bug. Automate as much as possible:
+   - Unit/integration bug → write a failing test that proves the bug exists
+   - UI/audio/GPU/worker bug (not fully automatable) → write the closest possible script: a headless probe, a log-based trigger, a mock that replicates the failure path. Document the manual remainder explicitly.
+   - If you cannot write any form of reproduction → you do not yet understand the bug. Keep investigating until you can.
+
+2. **Run the reproduction** and confirm it fails before attempting any fix.
+
+3. **Never close a debug session with "ready for testing."** A session closes only when the reproduction script passes. If manual steps remain, document them explicitly and confirm they passed.
+
+4. **Log the reproduction script path** in `.gsd-t/progress.md` Decision Log: what it tests, how to run it, what passing looks like.
+
+> This rule exists because code review cannot detect silent runtime failures (GPU compute shaders, audio context state, worker message drops). Only execution proves correctness.
+
+---
+
 ## Step 3: Debug (Solo or Team)
 
 ### Deviation Rules
@@ -84,13 +105,14 @@ When you encounter unexpected situations during the fix:
 **3-attempt limit**: If your fix doesn't work after 3 attempts, log to `.gsd-t/deferred-items.md` and stop trying.
 
 ### Solo Mode
-1. Reproduce the issue
+1. Reproduce the issue — **reproduction script must exist before step 2** (see Step 2.5)
 2. Trace through the relevant domain(s)
 3. Check contract compliance at each boundary
 4. Identify root cause
 5. **Destructive Action Guard**: If the fix requires destructive or structural changes (dropping tables, removing columns, changing schema, replacing architecture patterns, removing working modules) → STOP and present the change to the user with what exists, what will change, what will break, and a safe migration path. Wait for explicit approval.
 6. Fix and test — **adapt the fix to existing structures**, not the other way around
 7. Update contracts if needed
+8. **Category 6 — Bug Isolation Check**: After applying the fix, run the FULL test suite and all smoke tests — not just the reproduction script. Do not assume the bug was isolated. A fix that resolves one failure frequently uncovers adjacent failures. Every test must pass before the session closes.
 
 ### Team Mode (for complex cross-domain bugs)
 ```

package/commands/gsd-t-partition.md

@@ -17,6 +17,63 @@ If `.gsd-t/` doesn't exist, create the full directory structure:
 └── progress.md
 ```
 
+## Step 1.5: Assumption Audit (MANDATORY — complete before domain work begins)
+
+Before partitioning, surface and lock down all assumptions baked into the requirements. Unexamined assumptions become architectural decisions no one approved.
+
+Work through each category below. For every match found, write the explicit disposition into the affected domain's `constraints.md` and into the Decision Log in `.gsd-t/progress.md`.
+
+---
+
+### Category 1: External Reference Assumptions
+
+Scan requirements for any external project, file, component, library, or URL mentioned by name or path. For each one found, explicitly confirm which disposition applies — and lock it in the contract before any domain touches it:
+
+| Disposition | Meaning |
+|-------------|---------|
+| `USE`       |  Import and depend on it — treat as a dependency |
+| `INSPECT`   |  Read source for patterns only — do not import or copy code |
+| `BUILD`     |  Build equivalent functionality from scratch — do not read or use it |
+
+**No external reference survives partition without a locked disposition.**
+
+Trigger phrases to watch for: "reference X", "like X", "similar to Y", "see W for how it handles Z", any file path or project name, any URL.
+
+> If Level 3 (Full Auto): state the inferred disposition and reason; lock it unless it's ambiguous.
+> If ambiguous (e.g., "reference X" could mean USE or INSPECT): pause and ask the user before proceeding.
+
+---
+
+### Category 3: Black Box Assumptions
+
+Any component, module, or library **not written in this milestone** that a domain will call, import, or depend on → the agent that executes that domain must read its source before treating it as correct. This includes internal project modules written in a previous milestone.
+
+For each such component identified:
+1. Name it explicitly in the domain's `constraints.md` under a `## Must Read Before Using` section
+2. List the specific functions or behaviors the domain depends on
+3. The execute agent is prohibited from treating it as a black box — it must read the listed items before implementing
+
+---
+
+### Category 4: User Intent Assumptions
+
+Scan requirements for ambiguous language. Flag every instance where intent could be interpreted more than one way. Common patterns:
+
+- "like X" / "similar to Y" — does this mean the same UX, the same architecture, or just the same concept?
+- "the way X handles it" — inspiration, direct port, or behavioral equivalent?
+- "reference Z" — does this mean read it, use it, or replicate it?
+- "build something that does W" — from scratch, or using an existing library?
+- Any requirement where a reasonable developer could make two different implementation choices
+
+For each ambiguous item:
+1. State the two (or more) possible interpretations explicitly
+2. State which interpretation you are locking in and why
+3. If genuinely unclear: pause and ask the user — do not infer and proceed
+
+> **Rule**: Ambiguous intent that reaches execute unresolved becomes a wrong assumption. Resolve it here or pay for it in debug sessions.
+
+---
+
 ## Step 2: Identify Domains
 
 Decompose the milestone into 2-5 independent domains. Each domain should:

package/commands/gsd-t-verify.md

@@ -24,6 +24,37 @@ Run the full test audit directly:
 
 Verification cannot complete if any test fails or critical contract gaps remain.
 
+## Step 2.5: High-Risk Domain Gate (MANDATORY — Categories 2 and 7)
+
+Before running standard verification dimensions, check whether this milestone involves any high-risk domain:
+
+**High-risk domains**: audio capture/playback, GPU/WebGPU/WebGL, ML/inference/model loading, background workers, native APIs (camera, bluetooth, filesystem), IPC, WebAssembly, real-time data streams.
+
+**If any high-risk domain is present:**
+
+### Category 2 — Technology Reliability Gate
+Initialization success does not prove runtime correctness. These technologies can initialize cleanly and fail silently at runtime (compute shader errors, audio context state loss, worker message drops, inference failures).
+
+For each high-risk domain:
+1. A **smoke test script** must exist that exercises actual runtime behavior — not just initialization
+2. The smoke test must have been run and passed
+3. "It initialized without throwing" is NOT a passing smoke test
+4. If no smoke test exists → create one now before proceeding with any other verification dimension
+5. Smoke test failure → verification FAIL (not WARN)
+
+### Category 7 — Manual QA as Test Gate
+"The user will manually test it" is not a test artifact. Scan the milestone's domains for any feature whose acceptance criteria relies solely on manual user testing.
+
+For each such feature:
+1. A smoke test script must exist that automates as much of the verification as possible
+2. Any remaining manual steps must be explicitly documented in `.gsd-t/smoke-tests/{feature}.md` with exact steps and expected outcomes
+3. The documented manual steps must have been executed and passed (noted in the file)
+4. If neither automated smoke test nor documented manual procedure exists → verification FAIL
+
+> These gates exist because the pre-commit checklist "did you run the affected tests?" is meaningless when the only test is "user presses Ctrl+Space." That is not a test. It is hope.
+
+---
+
 ## Step 3: Define Verification Dimensions
 
 Standard dimensions (adjust based on project):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.31.17",
+  "version": "2.31.18",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 46 slash commands with backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",