@tekyzinc/gsd-t 2.39.13 → 2.45.11

package/commands/gsd-t-execute.md

@@ -60,11 +60,19 @@ Before choosing solo or team mode, read the `## Wave Execution Groups` section i
 
 **If no wave groups are defined** (older plans): fall back to the `Execution Order` list.
 
-### Solo Mode (default) — Domain Subagent Pattern
+### Solo Mode (default) — Domain Task-Dispatcher Pattern
 
-Each domain's work runs in an isolated Task subagent with a fresh context window. The orchestrator (this agent) stays lightweight — it only spawns subagents, collects summaries, verifies checkpoints, and updates progress.
+Each domain's work runs via a lightweight domain task-dispatcher. The dispatcher spawns one Task subagent PER TASK within that domain, giving each task a completely fresh context window with only the minimum required context. The orchestrator (this agent) stays lightweight — it only spawns dispatchers, collects summaries, verifies checkpoints, and updates progress.
 
-**OBSERVABILITY LOGGING (MANDATORY) — repeat for every domain subagent spawn:**
+**Context provided to each task subagent (fresh-dispatch-contract.md payload):**
+- `scope.md` for the domain
+- Relevant contracts (only those referenced by the task)
+- The single task from `tasks.md`
+- Graph context for the task's files (if available)
+- Up to 5 prior task summaries (10-20 lines each, most recent first)
+- Past failure/learning entries for this domain (max 5 lines)
+
+**OBSERVABILITY LOGGING (MANDATORY) — repeat for every task subagent spawn:**
 
 Before spawning — run via Bash:
 `T_START=$(date +%s) && DT_START=$(date +"%Y-%m-%d %H:%M") && TOK_START=${CLAUDE_CONTEXT_TOKENS_USED:-0} && TOK_MAX=${CLAUDE_CONTEXT_TOKENS_MAX:-200000}`
@@ -76,39 +84,80 @@ Compute tokens and compaction:
 - No compaction (TOK_END >= TOK_START): `TOKENS=$((TOK_END-TOK_START))`, COMPACTED=null
 - Compaction detected (TOK_END < TOK_START): `TOKENS=$(((TOK_MAX-TOK_START)+TOK_END))`, COMPACTED=$DT_END
 
-Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Tokens | Compacted |` if missing):
-`| {DT_START} | {DT_END} | gsd-t-execute | domain:{domain-name} | sonnet | {DURATION}s | {N} tasks, {pass/fail} | {TOKENS} | {COMPACTED} |`
+Compute context utilization — run via Bash:
+`if [ "${CLAUDE_CONTEXT_TOKENS_MAX:-0}" -gt 0 ]; then CTX_PCT=$(echo "scale=1; ${CLAUDE_CONTEXT_TOKENS_USED:-0} * 100 / ${CLAUDE_CONTEXT_TOKENS_MAX}" | bc); else CTX_PCT="N/A"; fi`
+
+Alert on context thresholds (display to user inline):
+- If CTX_PCT is a number and >= 85: `echo "🔴 CRITICAL: Context at ${CTX_PCT}% — compaction likely. Task MUST be split."`
+- If CTX_PCT is a number and >= 70: `echo "⚠️ WARNING: Context at ${CTX_PCT}% — approaching compaction threshold. Consider splitting in plan."`
+
+Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Tokens | Compacted | Domain | Task | Ctx% |` if missing):
+`| {DT_START} | {DT_END} | gsd-t-execute | task:{task-id} | sonnet | {DURATION}s | {pass/fail} | {TOKENS} | {COMPACTED} | {domain-name} | task-{task-id} | {CTX_PCT} |`
 
-**For each domain (in wave order), spawn:**
+**For each domain (in wave order), run the domain task-dispatcher:**
 
-**Pre-task experience retrieval (before spawning each domain subagent):**
+**Pre-dispatch experience retrieval (before dispatching each domain's tasks):**
 Run via Bash:
 `grep -i "\[failure\]\|\[learning\]" .gsd-t/progress.md | grep -i "{domain-name}" | tail -5`
 
 If results found:
-- Prepend a `## ⚠️ Past Failures (retrieve before acting)` block to the subagent prompt (max 5 lines from results)
+- Store as `PAST_FAILURES` — prepend to each task subagent prompt (max 5 lines)
 - Write event via Bash: `node ~/.claude/scripts/gsd-t-event-writer.js --type experience_retrieval --command gsd-t-execute --reasoning "{N past failures found for {domain-name}}" --outcome null || true`
 
 If no results found: proceed normally (no warning block, no event write).
 
+**Pre-flight intelligence check (before dispatching each domain's tasks):**
+Run via Bash:
+`node -e "const m = require('./bin/metrics-collector.js'); const w = m.getPreFlightWarnings('{domain-name}'); if(w.length) w.forEach(x => console.log('⚠️ ' + x));" 2>/dev/null || true`
+
+Display any warnings inline (non-blocking — execution proceeds regardless).
+
+**Active Rule Injection (before dispatching each domain's tasks):**
+Run via Bash:
+`node -e "const re = require('./bin/rule-engine.js'); const m = re.evaluateRules('{domain-name}', { projectDir: '.' }); if(m.length) m.forEach(x => console.log('RULE: ' + x.rule.name + ' — ' + x.rule.description + ' [' + x.severity + ']')); else console.log('No active rules for {domain-name}');" 2>/dev/null || true`
+
+If rules fire: inject up to 10 lines of rule warnings into each task subagent prompt (concise format: `RULE: {name} — {description}`). These inform the subagent of known patterns — non-blocking.
+If no rules fire: log "No active rules for {domain-name}" and continue.
+
+**Domain task-dispatcher (lightweight — sequences tasks, passes summaries):**
+
+For each task in `.gsd-t/domains/{domain-name}/tasks.md` (in order, skip completed):
+
+1. Load prior summaries: Read up to 5 most recent `.gsd-t/domains/{domain-name}/task-*-summary.md` files (10-20 lines each)
+2. Load graph context (if `.gsd-t/graph/meta.json` exists): query task's files for relevant graph context
+3. Display: `⚙ [sonnet] gsd-t-execute → domain: {domain-name}, task-{task-id}`
+4. Run observability Bash (T_START / DT_START / TOK_START / TOK_MAX)
+5. Spawn task subagent:
+
 ```
 Task subagent (general-purpose, model: sonnet, mode: bypassPermissions):
-"You are executing all tasks for the {domain-name} domain.
+"You are executing a single task for the {domain-name} domain.
 
-Read before starting (load your own context — do not assume anything):
-1. CLAUDE.md — project conventions (CRITICAL)
-2. .gsd-t/domains/{domain-name}/scope.md — what you own
-3. .gsd-t/domains/{domain-name}/constraints.md — patterns to follow
-4. ALL files in .gsd-t/contracts/ — your interfaces
-5. .gsd-t/domains/{domain-name}/tasks.md — your task list
-6. .gsd-t/contracts/integration-points.md — wave order and checkpoints
+{PAST_FAILURES block if any — ## ⚠️ Past Failures (read before acting)\n{lines}}
+
+## Your Task
+{full task block from tasks.md — id, description, files, contract refs, dependencies, acceptance criteria}
+
+## Domain Scope
+{contents of .gsd-t/domains/{domain-name}/scope.md}
+
+## Relevant Contracts
+{contents of each contract file referenced by this task}
+
+## Graph Context (if available)
+{graph query results for this task's files — omit section if unavailable}
 
-Execute each incomplete task in order:
-1. Read task description, files list, and contract refs
+## Prior Task Summaries (most recent first, max 5)
+{contents of task-{N}-summary.md files — 10-20 lines each}
+
+## Instructions
+
+Execute the task above:
+1. Read the task description, files list, and contract refs carefully
 2. Read relevant contracts — implement EXACTLY what they specify
-3. Destructive Action Guard: if task involves DROP TABLE, schema changes that lose
+3. Destructive Action Guard: if the task involves DROP TABLE, schema changes that lose
    data, removing working modules, or replacing architecture patterns → write a
-   NEEDS-APPROVAL entry to .gsd-t/deferred-items.md, skip the task, continue
+   NEEDS-APPROVAL entry to .gsd-t/deferred-items.md, skip the task, stop here
 4. Implement the task
 5. Verify acceptance criteria are met
 6. Write comprehensive tests (MANDATORY — no feature code without test code):
@@ -116,42 +165,101 @@ Execute each incomplete task in order:
    - Playwright E2E (if UI/routes/flows changed): new specs for new features, cover
      all modes, form validation, empty/loading/error states, common edge cases
    - If no test framework exists: set one up as part of this task
-7. Run ALL tests — unit, integration, Playwright. Fix failures (up to 2 attempts)
+   - If the project has a UI but no Playwright E2E specs exist for the features being
+     touched: WRITE THEM. A placeholder spec is not sufficient — write real E2E tests
+     that exercise the actual UI functionality being built or changed.
+7. Run ALL test suites — this is NOT optional, not conditional, not "if applicable":
+   a. Detect configured test runners: check for vitest/jest config, playwright.config.*, cypress.config.*
+   b. Run EVERY detected suite. Unit tests alone are NEVER sufficient when E2E exists.
+   c. If `playwright.config.*` exists → run `npx playwright test` (full suite, not just affected specs)
+   d. If E2E tests fail → fix (up to 2 attempts) before proceeding
+   e. Report ALL suite results: "Unit: X/Y pass | E2E: X/Y pass" — never report just one
 8. Run Pre-Commit Gate checklist from CLAUDE.md — update all affected docs BEFORE committing
-9. Commit immediately: feat({domain-name}/task-{N}): {description}
-10. Update .gsd-t/progress.md — mark task complete; prefix the Decision Log entry with an outcome tag based on how the task completed:
-    - Task completed successfully on first attempt → prefix `[success]`
-    - Task completed after a fix (required debugging or correction) → prefix `[learning]`
-    - Task deferred to .gsd-t/deferred-items.md → prefix `[deferred]`
-    - Task failed after 3 attempts → prefix `[failure]`
-11. Spawn QA subagent (model: haiku) after each task:
-    'Run the full test suite. Read .gsd-t/contracts/ for definitions.
-     Report: pass/fail counts and coverage gaps.'
+9. Commit immediately: feat({domain-name}/task-{task-id}): {description}
+10. Update .gsd-t/progress.md — mark this task complete; prefix the Decision Log entry:
+    - Completed successfully on first attempt → prefix `[success]`
+    - Completed after a fix → prefix `[learning]`
+    - Deferred to .gsd-t/deferred-items.md → prefix `[deferred]`
+    - Failed after 3 attempts → prefix `[failure]`
+11. Spawn QA subagent (model: haiku) after completing the task:
+    'Run ALL configured test suites — detect and run every one:
+     a. Unit tests (vitest/jest/mocha): run the full suite, report pass/fail counts
+     b. E2E tests: check for playwright.config.* or cypress.config.* — if found, run the FULL E2E suite
+     c. NEVER skip E2E when a config file exists. Running only unit tests is a QA FAILURE.
+     d. Read .gsd-t/contracts/ for contract definitions. Check contract compliance.
+     Report format: "Unit: X/Y pass | E2E: X/Y pass (or N/A if no config) | Contract: compliant/violations"'
     If QA fails, fix before proceeding. Append issues to .gsd-t/qa-issues.md.
+12. Write task summary to .gsd-t/domains/{domain-name}/task-{task-id}-summary.md:
+    ## Task {task-id} Summary — {domain-name}
+    - **Status**: PASS | FAIL
+    - **Files modified**: {list}
+    - **Constraints discovered**: {any new constraints or surprises}
+    - **Tests**: {pass/fail count}
+    - **Notes**: {10-20 lines max — key decisions, patterns, warnings}
 
 Deviation rules:
 - Bug blocking progress → fix, max 3 attempts; if still blocked, log to
-  .gsd-t/deferred-items.md and continue to next task
-- Missing dependency task requires → add minimum needed, document in commit message
-- Non-trivial blocker → fix and log to .gsd-t/deferred-items.md
+  .gsd-t/deferred-items.md and stop (report FAIL in summary)
+- Missing dependency → add minimum needed, document in commit message
+- Non-trivial blocker → log to .gsd-t/deferred-items.md
 - Architectural change required → write NEEDS-APPROVAL to .gsd-t/deferred-items.md,
-  skip the task, continue — never self-approve structural changes
-
-When all tasks are complete, report:
-- Tasks completed: N/N
-- Test results: pass/fail counts
-- Commits made: list of commit hashes
-- Deferred items (if any): list from .gsd-t/deferred-items.md"
+  skip the task, stop here — never self-approve structural changes
+
+Report back:
+- Task: {task-id}
+- Status: PASS | FAIL
+- Files modified: {list}
+- Tests: {pass/fail count}
+- Commit: {hash}
+- Deferred items (if any)"
 ```
 
-**After each domain subagent returns (orchestrator responsibilities):**
-1. Log to `.gsd-t/token-log.md` (see observability block above)
-2. Check `.gsd-t/deferred-items.md` for any `NEEDS-APPROVAL` entries — if found, STOP and present to user before spawning the next domain
-3. If a CHECKPOINT is reached per `integration-points.md`, verify contract compliance (see Step 4) before proceeding to the next wave/domain
-4. Update `.gsd-t/progress.md` with domain completion status
+6. After task subagent returns:
+   - Run observability Bash (T_END / TOK_END / DURATION / CTX_PCT)
+   - Append to token-log.md (per-task row)
+   - Alert on CTX_PCT thresholds (display to user inline)
+   - **Emit task-metrics record** — run via Bash:
+     `node bin/metrics-collector.js --milestone {milestone} --domain {domain-name} --task task-{task-id} --command execute --duration_s $DURATION --tokens_used $TOKENS --context_pct ${CTX_PCT:-0} --pass {true|false} --fix_cycles {0|N} --signal_type {pass-through|fix-cycle} --notes "{brief outcome}" 2>/dev/null || true`
+     Signal type: `pass-through` if task passed on first attempt; `fix-cycle` if rework was needed.
+   - **Emit task_complete event** — run via Bash:
+     `node ~/.claude/scripts/gsd-t-event-writer.js --type task_complete --command gsd-t-execute --reasoning "signal_type={signal_type}, domain={domain-name}" --outcome {success|failure} || true`
+   - Check `.gsd-t/deferred-items.md` for `NEEDS-APPROVAL` — if found, STOP and present to user before proceeding to the next task
+   - Read the task summary from `.gsd-t/domains/{domain-name}/task-{task-id}-summary.md` to use as prior summary for the next task
+
+**After all tasks in a domain complete (orchestrator responsibilities):**
+1. Check `.gsd-t/deferred-items.md` for any `NEEDS-APPROVAL` entries — if found, STOP and present to user before spawning the next domain
+2. If a CHECKPOINT is reached per `integration-points.md`, verify contract compliance (see Step 4) before proceeding to the next wave/domain
+3. Update `.gsd-t/progress.md` with domain completion status
+4. **Adaptive Replan Check** (per `adaptive-replan-contract.md`) — run after EVERY domain completes, before dispatching the next domain:
+
+   a. **Read domain summaries**: Read all `.gsd-t/domains/{completed-domain}/task-*-summary.md` files. Extract every `**Constraints discovered**:` field. If ALL are empty or "none", skip to the next domain (fast path — no replan needed).
+
+   b. **Assess affected domains** — two modes:
+      - **Graph available** (`.gsd-t/graph/meta.json` exists): For each changed module mentioned in the constraints, run `query('getImporters', { file })` to find which remaining domains import it. Also run `query('getDomainBoundaryViolations', {})` to check if constraint changes affect domain boundaries. Scope replan to ONLY those domains.
+      - **Graph unavailable** (fallback): Check ALL remaining unexecuted domains' `tasks.md` files — less precise but functional.
+
+   c. **Check for invalidated assumptions**: Read each affected remaining domain's `.gsd-t/domains/{domain}/tasks.md`. For each task, check whether any assumption is invalidated by the discovered constraints (e.g., wrong column name, deprecated API, wrong library, missing prerequisite, throughput limits).
+
+   d. **If invalidated assumptions found**: Revise the affected domain's `tasks.md` on disk. Append a Revision block at the end of the file (do NOT overwrite existing tasks — append only):
+      ```markdown
+      ## Revision (Replan Cycle {N})
+      - **Trigger**: {completed-domain} — constraint discovered during execution
+      - **Constraint**: {exact constraint text from summary}
+      - **Changes**: {what was revised in this domain's tasks — list specific task IDs and what changed}
+      - **Rationale**: {why this revision is needed — what would break without it}
+      ```
+
+   e. **Increment replan cycle counter** (track as `REPLAN_CYCLES` in orchestrator state, starting at 0).
+
+   f. **Cycle guard**: If `REPLAN_CYCLES > 2`, STOP and pause for user input:
+      "Replan cycle limit (2) exceeded. {N} constraints are still propagating. Please review `.gsd-t/domains/*/tasks.md` and resolve manually, then re-run execute."
+
+   g. **Log to Decision Log** in `.gsd-t/progress.md`: `- {date}: [replan] Cycle {N} — {completed-domain} constraint propagated to {list of affected domains}: {brief constraint summary}`
+
+   h. The revised `tasks.md` files are now on disk — the next domain's dispatcher will read the updated version automatically (disk-based handoff, no in-memory state sharing needed).
 
 ### Team Mode (when agent teams are enabled)
-Spawn teammates for domains within the same wave. Only domains in the same wave can run in parallel — do not spawn teammates for domains in different waves simultaneously:
+Spawn teammates for domains within the same wave. Only domains in the same wave can run in parallel — do not spawn teammates for domains in different waves simultaneously. Each teammate uses the **domain task-dispatcher pattern** — one subagent per task within their domain (same as solo mode).
 
 ```
 Create an agent team for execution:
@@ -173,16 +281,37 @@ RULES FOR ALL TEAMMATES:
   - Tests are part of the deliverable, not a follow-up
 - If a task is marked BLOCKED, message the lead and wait
 - Run the Pre-Commit Gate checklist from CLAUDE.md BEFORE every commit — update all affected docs
-- After completing each task, message the lead with:
-  "DONE: {domain} Task {N} - {summary of what was created/modified}"
-- If you need to deviate from a contract, STOP and message the lead
 - **Commit immediately after each task**: `feat({domain}/task-{N}): {description}` — do NOT batch commits
 - **Deviation Rules**: (1) Bug blocking progress → fix, 3 attempts max; (2) Missing dependency → add minimum needed; (3) Blocker → fix and log to deferred-items.md; (4) Architectural change → STOP, message lead, never self-approve
 
+**Task-dispatcher pattern per teammate:**
+For each task in your domain's tasks.md (in order, skip completed):
+1. Load prior summaries: read up to 5 most recent `.gsd-t/domains/{your-domain}/task-*-summary.md` files
+2. Load graph context for task's files (if .gsd-t/graph/meta.json exists)
+3. Spawn one Task subagent (model: sonnet) with ONLY:
+   - scope.md, relevant contracts, the single task, graph context, prior summaries
+   - Instruction to write task summary to `.gsd-t/domains/{domain}/task-{id}-summary.md`
+     (format per fresh-dispatch-contract.md Task Summary Format)
+4. After task subagent returns, read the summary and pass it as prior context to the next task
+5. After completing each task, message the lead with:
+   "DONE: {domain} Task {N} - {summary of what was created/modified}"
+6. If you need to deviate from a contract, STOP and message the lead
+
 Teammate assignments:
-- Teammate "{domain-1}": Execute .gsd-t/domains/{domain-1}/tasks.md
-- Teammate "{domain-2}": Execute .gsd-t/domains/{domain-2}/tasks.md
-- Teammate "{domain-3}": Execute .gsd-t/domains/{domain-3}/tasks.md
+- Teammate "{domain-1}": Execute .gsd-t/domains/{domain-1}/tasks.md (task-dispatcher pattern, isolated worktree)
+- Teammate "{domain-2}": Execute .gsd-t/domains/{domain-2}/tasks.md (task-dispatcher pattern, isolated worktree)
+- Teammate "{domain-3}": Execute .gsd-t/domains/{domain-3}/tasks.md (task-dispatcher pattern, isolated worktree)
+
+**Worktree isolation (per domain teammate):**
+Each domain teammate MUST be spawned with `isolation: "worktree"` on the Agent tool:
+```
+Agent({
+  prompt: "{domain execution prompt — include: 'You are working in an isolated git worktree. All your changes are isolated to this worktree branch. Do not push; the lead will merge your branch after all domains complete.'}",
+  isolation: "worktree"
+})
+```
+Each teammate works in its own isolated copy of the repository. Changes from one domain do not affect another domain's working tree. This is required for parallel safety — see `.gsd-t/contracts/worktree-isolation-contract.md`.
+
 Lead responsibilities (QA is handled via Task subagent — spawn one after each domain checkpoint):
 - Use delegate mode (Shift+Tab)
 - Track completions from teammate messages
@@ -192,6 +321,82 @@ Lead responsibilities (QA is handled via Task subagent — spawn one after each
   3. Unblock waiting teammates
 - Update .gsd-t/progress.md after each completion
 - Resolve any contract conflicts immediately
+
+**Sequential Merge Protocol (lead runs after ALL domain agents complete):**
+
+Once all domain teammates report completion, the lead performs sequential atomic merges. This is the critical integration step — see `.gsd-t/contracts/worktree-isolation-contract.md` for the full merge protocol.
+
+1. **Determine merge order**: Read `.gsd-t/contracts/integration-points.md` — use the dependency graph to sort domains. Domains with no upstream dependencies merge first. Example: if domain-A has no deps and domain-B depends on domain-A's output, merge order is [domain-A, domain-B].
+
+2. **For each domain (in dependency order)**:
+
+   a. **File ownership validation (pre-merge)**: Check files the domain agent modified against the domain's `.gsd-t/domains/{domain}/scope.md`:
+      - If `.gsd-t/graph/meta.json` exists: run `query('getDomainBoundaryViolations', { domain })` — flag any files modified outside the domain's declared ownership
+      - If graph unavailable: list files changed in the worktree branch via `git diff --name-only` and compare against scope.md manually
+      - If violations found: log them in `.gsd-t/progress.md` as `[violation] {domain}: modified {file} outside scope`, but do NOT block merge — flag for immediate review after merge
+
+   b. **Merge the domain's worktree branch**:
+      ```bash
+      # The worktree branch name is returned by the Agent tool when isolation: "worktree" is used
+      git merge --no-ff {domain-worktree-branch} -m "integrate({domain}): merge worktree branch"
+      ```
+
+   c. **Contract validation (post-merge)**: Read each contract in `.gsd-t/contracts/` — verify the merged code still satisfies all contract shapes (API shapes, schemas, interfaces). If a contract is violated, log it immediately.
+
+   d. **Run integration tests**:
+      ```bash
+      node --test test/
+      # or project's test command from package.json
+      ```
+
+   e. **If tests PASS**: Continue to the next domain in merge order.
+
+   f. **If tests FAIL**: Roll back this domain's merge:
+      ```bash
+      git reset --hard HEAD~1
+      # or: git revert HEAD --no-edit
+      ```
+      Log failure: `[rollback] {domain}: merge rolled back — integration tests failed after merge`
+      Record in `.gsd-t/progress.md` Decision Log.
+      Continue with remaining domains (other domains' merges are not affected).
+
+3. **Post-merge ownership report**: After all merges complete (successful or rolled back), log a summary in `.gsd-t/progress.md`:
+   ```
+   ## Worktree Merge Summary — {date}
+   - {domain-1}: MERGED | tests: PASS | violations: {N}
+   - {domain-2}: ROLLED BACK | reason: integration tests failed
+   - {domain-3}: MERGED | tests: PASS | violations: 0
+   ```
+
+**Worktree Cleanup (MANDATORY — run after merge protocol, success or failure):**
+
+After all merges complete (whether all passed, some rolled back, or errors occurred):
+
+1. List all worktree branches created during this execution run:
+   ```bash
+   git worktree list
+   git branch --list "gsd-t-worktree-*"
+   ```
+
+2. Remove each domain worktree:
+   ```bash
+   git worktree remove --force {worktree-path}
+   git branch -D {worktree-branch}
+   ```
+
+3. **Orphaned worktree detection**: If any worktrees remain after cleanup (can happen if an agent crashed):
+   ```bash
+   git worktree prune
+   ```
+   Log: `[cleanup] Pruned {N} orphaned worktrees via git worktree prune`
+
+4. Verify no worktrees remain except the main working tree:
+   ```bash
+   git worktree list
+   # should show only: {main-path} {commit} [branch]
+   ```
+
+Cleanup is not optional — orphaned worktrees waste disk space and can confuse subsequent executions. Always run cleanup, even if earlier steps failed.
 ```
 
 ## Step 4: Checkpoint Handling

package/commands/gsd-t-help.md

@@ -39,8 +39,8 @@ MILESTONE WORKFLOW                                          [auto] = in wave
   test-sync    [auto] Sync tests with code changes
   qa           [auto] QA agent — test generation, execution, gap reporting
   integrate    [auto] Wire domains together at boundaries
-  verify       [auto] Run quality gates
-  complete-milestone [auto] Archive milestone + git tag
+  verify       [auto] Run quality gates → auto-invokes complete-milestone
+  complete-milestone [auto] Archive milestone + git tag (auto-invoked by verify)
 
 AUTOMATION                                                                Auto
 ───────────────────────────────────────────────────────────────────────────────
@@ -231,10 +231,12 @@ Use these when user asks for help on a specific command:
 - **Use when**: Architectural decisions need exploration
 
 ### plan
-- **Summary**: Create atomic task lists for each domain
+- **Summary**: Create atomic task lists for each domain (each task must fit in one context window)
 - **Auto-invoked**: Yes (in wave, after discuss)
 - **Creates**: `.gsd-t/domains/*/tasks.md`
 - **Use when**: Ready to define specific implementation tasks
+- **Note (M22)**: Tasks auto-split if estimated scope exceeds 70% context window — guarantees fresh dispatch works
+- **Note (M26)**: Pre-mortem step now also reads rules.jsonl for historical failure patterns via getPreMortemRules
 
 ### impact
 - **Summary**: Analyze downstream effects of planned changes
@@ -247,6 +249,8 @@ Use these when user asks for help on a specific command:
 - **Auto-invoked**: Yes (in wave, after impact)
 - **Updates**: Domain tasks, progress.md, source code
 - **Use when**: Ready to implement
+- **Note (M22)**: Task-level fresh dispatch (one subagent per task, ~10-20% context each). Team mode uses worktree isolation (`isolation: "worktree"`) — zero file conflicts. Adaptive replanning between domain completions.
+- **Note (M26)**: Active rule injection — evaluates declarative rules from rules.jsonl before dispatching each domain's tasks. Fires matching rules as warnings in subagent prompts.
 
 ### test-sync
 - **Summary**: Keep tests aligned with code changes
@@ -267,27 +271,32 @@ Use these when user asks for help on a specific command:
 - **Use when**: Domains are complete and need to work together
 
 ### verify
-- **Summary**: Run quality gates across all dimensions
+- **Summary**: Run quality gates across all dimensions, including goal-backward behavior verification
 - **Auto-invoked**: Yes (in wave, after integrate)
 - **Creates**: `.gsd-t/verify-report.md`
 - **Use when**: Checking that milestone meets requirements
+- **Note (M22)**: Goal-backward verification step added — checks for placeholder implementations (console.log/TODO/hardcoded returns) after structural gates pass
 
 ### complete-milestone
 - **Summary**: Archive milestone documentation and create git tag
-- **Auto-invoked**: Yes (in wave, after verify passes)
+- **Auto-invoked**: Yes — by verify (Step 8, all autonomy levels) and in wave
 - **Creates**: `.gsd-t/milestones/{name}/`, git tag
-- **Use when**: Milestone is done and verified
+- **Use when**: Auto-runs after verify passes. Can also be invoked standalone to manually close a milestone.
+- **Note (M22)**: Goal-backward gate runs as final check before archiving — blocks completion if placeholders remain
+- **Note (M26)**: Distillation extended with rule engine evaluation, patch candidate generation, promotion gate checks, graduation, consolidation, and quality budget governance
 
 ### wave
-- **Summary**: Run complete cycle automatically: partition through complete
+- **Summary**: Run complete cycle automatically: partition through verify+complete
 - **Auto-invoked**: No (user triggers)
-- **Runs**: partition → discuss → plan → impact → execute → test-sync → integrate → verify → complete-milestone
+- **Runs**: partition → discuss → plan → impact → execute → test-sync → integrate → verify+complete
 - **Use when**: Ready to execute a full milestone hands-off
 
 ### status
-- **Summary**: Show current progress across all domains
+- **Summary**: Show current progress across all domains, including token breakdown by domain/task/phase, global ELO and cross-project rankings
 - **Auto-invoked**: No
-- **Reads**: All `.gsd-t/` files
+- **Note (M22)**: Displays context observability data — token usage by domain, avg tokens/task, peak Ctx% per domain
+- **Note (M27)**: Displays global ELO and cross-project rankings when global metrics exist
+- **Reads**: All `.gsd-t/` files, `~/.claude/metrics/` (global metrics)
 - **Use when**: Need to see where things stand
 
 ### resume
@@ -316,6 +325,12 @@ Use these when user asks for help on a specific command:
 - **Creates**: `.gsd-t/dashboard.pid` (when starting server)
 - **Use when**: Monitoring live agent activity during execute/wave phases; run `gsd-t-visualize stop` to stop the server
 
+### metrics
+- **Summary**: View task telemetry, process ELO, signal distribution, domain health, and cross-project comparison (with `--cross-project` flag)
+- **Auto-invoked**: No
+- **Reads**: `.gsd-t/metrics/task-metrics.jsonl`, `.gsd-t/metrics/rollup.jsonl`, `~/.claude/metrics/` (when `--cross-project`)
+- **Use when**: Reviewing process health, first-pass rates, ELO trends, anomaly flags, or comparing signal distributions across projects
+
 ### debug
 - **Summary**: Systematic debugging with persistent state
 - **Auto-invoked**: No

package/commands/gsd-t-integrate.md

@@ -50,9 +50,26 @@ For each contract file:
 
 Fix any mismatches BEFORE proceeding to integration.
 
+## Step 2.5: Worktree Merge Status Check
+
+Before wiring integration points, check whether team mode execution left any domains with rolled-back worktree merges:
+
+1. Read `.gsd-t/progress.md` — look for `[rollback]` entries in the Decision Log from the execute phase
+2. If any domains were rolled back: list them and their failure reasons before proceeding
+3. Integration point wiring should only proceed for domains whose worktree merges PASSED — rolled-back domains are not yet in the main working tree
+
+If rolled-back domains exist, report them to the user (or if Level 3: log to `.gsd-t/deferred-items.md` as `[integration-gap] {domain}: not yet merged — worktree rollback during execute`). Do NOT attempt to re-merge rolled-back domains here; that requires re-running execute for the affected domain.
+
 ## Step 3: Wire Integration Points
 
-Work through each integration point in `integration-points.md`:
+Work through each integration point in `integration-points.md`. If integration work spans multiple domains with independent tasks, use the **task-level dispatch pattern** (per fresh-dispatch-contract.md): spawn one Task subagent per integration task, passing only the relevant contracts, the specific integration point to wire, and summaries from prior integration tasks (max 5, 10-20 lines each). This prevents context accumulation across integration tasks.
+
+**Multi-domain integration merging**: If integration work itself requires merging domain outputs that weren't merged during execute (e.g., domains executed in separate waves and integration needs to combine them), use the Sequential Merge Protocol from `.gsd-t/contracts/worktree-isolation-contract.md`:
+1. Sort domains by dependency order (from integration-points.md)
+2. Merge domain A's branch → run tests → merge domain B's branch → run tests
+3. If tests fail after a merge, roll back that domain's merge and log the failure
+4. Contract validation runs between merges
+5. All temporary branches cleaned up after integration completes
 
 For each connection:
 1. Identify the producing domain (provides the interface)
@@ -105,8 +122,11 @@ Spawn a QA subagent via the Task tool to verify contract compliance at all domai
 Task subagent (general-purpose, model: haiku):
 "Run contract compliance tests for this integration. Read .gsd-t/contracts/ for all contract definitions.
 Test every domain boundary: verify that producers and consumers match their contract shapes.
-Run the full test suite.
-Report: boundary-by-boundary test results with pass/fail counts."
+Run ALL configured test suites — detect and run every one:
+a. Unit tests (vitest/jest/mocha): run the full suite
+b. E2E tests: check for playwright.config.* or cypress.config.* — if found, run the FULL E2E suite
+c. NEVER skip E2E when a config file exists. Running only unit tests is a QA FAILURE.
+Report: 'Unit: X/Y pass | E2E: X/Y pass (or N/A if no config) | Boundary: pass/fail by contract'"
 ```
 
 **OBSERVABILITY LOGGING (MANDATORY):**
@@ -117,8 +137,13 @@ After subagent returns — run via Bash:
 Compute tokens and compaction:
 - No compaction (TOK_END >= TOK_START): `TOKENS=$((TOK_END-TOK_START))`, COMPACTED=null
 - Compaction detected (TOK_END < TOK_START): `TOKENS=$(((TOK_MAX-TOK_START)+TOK_END))`, COMPACTED=$DT_END
-Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Tokens | Compacted |` if missing):
-`| {DT_START} | {DT_END} | gsd-t-integrate | Step 5 | haiku | {DURATION}s | {pass/fail}, {N} boundaries tested | {TOKENS} | {COMPACTED} |`
+Compute context utilization — run via Bash:
+`if [ "${CLAUDE_CONTEXT_TOKENS_MAX:-0}" -gt 0 ]; then CTX_PCT=$(echo "scale=1; ${CLAUDE_CONTEXT_TOKENS_USED:-0} * 100 / ${CLAUDE_CONTEXT_TOKENS_MAX}" | bc); else CTX_PCT="N/A"; fi`
+Alert on context thresholds (display to user inline):
+- If CTX_PCT >= 85: `echo "🔴 CRITICAL: Context at ${CTX_PCT}% — compaction likely. Task MUST be split."`
+- If CTX_PCT >= 70: `echo "⚠️ WARNING: Context at ${CTX_PCT}% — approaching compaction threshold. Consider splitting in plan."`
+Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Tokens | Compacted | Domain | Task | Ctx% |` if missing):
+`| {DT_START} | {DT_END} | gsd-t-integrate | Step 5 | haiku | {DURATION}s | {pass/fail}, {N} boundaries tested | {TOKENS} | {COMPACTED} | | | {CTX_PCT} |`
 If QA found issues, append each to `.gsd-t/qa-issues.md` (create with header `| Date | Command | Step | Model | Duration(s) | Severity | Finding |` if missing):
 `| {DT_START} | gsd-t-integrate | Step 5 | haiku | {DURATION}s | {severity} | {finding} |`
 
@@ -145,9 +170,12 @@ Integration is where the real system takes shape. Verify documentation matches r
 After integration and doc ripple, verify everything works together:
 
 1. **Update tests**: Add or update integration tests for newly wired domain boundaries
-2. **Run all tests**: Execute the full test suite — integration often introduces cross-domain failures
+2. **Run ALL configured test suites** — detect and run every one:
+   a. Unit/integration tests (vitest/jest/mocha)
+   b. If `playwright.config.*` exists → run `npx playwright test` (full suite, not just affected specs)
+   c. Unit tests alone are NEVER sufficient when E2E exists
+   d. Report: "Unit: X/Y pass | E2E: X/Y pass"
 3. **Verify passing**: All tests must pass. If any fail, fix before proceeding (up to 2 attempts)
-4. **Run E2E tests**: If an E2E framework exists, run the full E2E suite — integration is where end-to-end flows break
 5. **Smoke test results**: Ensure the Step 4 smoke test results are still valid after any fixes
 
 ## Step 8: Handle Integration Issues