73c1af5168
Commands are now installed as commands/gsd/<name>.md and invoked as /gsd:<name> in Claude Code. The old hyphen form /gsd-<name> was still hardcoded in hundreds of places across workflows, references, templates, lib modules, and command files — causing "Unknown command" errors whenever GSD suggested a command to the user. Replace all /gsd-<cmd> occurrences where <cmd> is a known command name (derived at runtime from commands/gsd/*.md) using a targeted Node.js script. Agent names, tool names (gsd-sdk, gsd-tools), directory names, and path fragments are not touched. Adds regression test tests/bug-2543-gsd-slash-namespace.test.cjs that enforces zero legacy occurrences going forward. Removes inverted tests/stale-colon-refs.test.cjs (bug #1748) which enforced the now-obsolete hyphen form; the new bug-2543 test supersedes it. Updates 5 assertion tests that hardcoded the old hyphen form to accept the new colon form. Closes #2543 Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
71 lines
3.8 KiB
Markdown
71 lines
3.8 KiB
Markdown
# Gates Taxonomy
|
|
|
|
Canonical gate types used across GSD workflows. Every validation checkpoint maps to one of these four types.
|
|
|
|
---
|
|
|
|
## Gate Types
|
|
|
|
### Pre-flight Gate
|
|
**Purpose:** Validates preconditions before starting an operation.
|
|
**Behavior:** Blocks entry if conditions unmet. No partial work created.
|
|
**Recovery:** Fix the missing precondition, then retry.
|
|
**Examples:**
|
|
- Plan-phase checks for REQUIREMENTS.md before planning
|
|
- Execute-phase validates PLAN.md exists before execution
|
|
- Discuss-phase confirms phase exists in ROADMAP.md
|
|
|
|
### Revision Gate
|
|
**Purpose:** Evaluates output quality and routes to revision if insufficient.
|
|
**Behavior:** Loops back to producer with specific feedback. Bounded by iteration cap.
|
|
**Recovery:** Producer addresses feedback; checker re-evaluates. The loop also escalates early if issue count does not decrease between consecutive iterations (stall detection). After max iterations, escalates unconditionally.
|
|
**Examples:**
|
|
- Plan-checker reviewing PLAN.md (max 3 iterations)
|
|
- Verifier checking phase deliverables against success criteria
|
|
|
|
### Escalation Gate
|
|
**Purpose:** Surfaces unresolvable issues to the developer for a decision.
|
|
**Behavior:** Pauses workflow, presents options, waits for human input.
|
|
**Recovery:** Developer chooses action; workflow resumes on selected path.
|
|
**Examples:**
|
|
- Revision loop exhausted after 3 iterations
|
|
- Merge conflict during worktree cleanup
|
|
- Ambiguous requirement needing clarification
|
|
|
|
### Abort Gate
|
|
**Purpose:** Terminates the operation to prevent damage or waste.
|
|
**Behavior:** Stops immediately, preserves state, reports reason.
|
|
**Recovery:** Developer investigates root cause, fixes, restarts from checkpoint.
|
|
**Examples:**
|
|
- Context window critically low during execution
|
|
- STATE.md in error state blocking /gsd:next
|
|
- Verification finds critical missing deliverables
|
|
|
|
---
|
|
|
|
## Gate Matrix
|
|
|
|
| Workflow | Phase | Gate Type | Artifacts Checked | Failure Behavior |
|
|
|----------|-------|-----------|-------------------|------------------|
|
|
| plan-phase | Entry | Pre-flight | REQUIREMENTS.md, ROADMAP.md | Block with missing-file message |
|
|
| plan-phase | Step 12 | Revision | PLAN.md quality | Loop to planner (max 3) |
|
|
| plan-phase | Post-revision | Escalation | Unresolved issues | Surface to developer |
|
|
| execute-phase | Entry | Pre-flight | PLAN.md | Block with missing-plan message |
|
|
| execute-phase | Completion | Revision | SUMMARY.md completeness | Re-run incomplete tasks |
|
|
| verify-work | Entry | Pre-flight | SUMMARY.md | Block with missing-summary |
|
|
| verify-work | Evaluation | Escalation | Failed criteria | Surface gaps to developer |
|
|
| next | Entry | Abort | Error state, checkpoints | Stop with diagnostic |
|
|
|
|
---
|
|
|
|
## Implementing Gates
|
|
|
|
Use this taxonomy when designing or auditing workflow validation points:
|
|
|
|
- **Pre-flight** gates belong at workflow entry points. They are cheap, deterministic checks that prevent wasted work. If you can verify a precondition with a file-existence check or a config read, use a pre-flight gate.
|
|
- **Revision** gates belong after a producer step where quality varies. Always pair them with an iteration cap to prevent infinite loops. The cap should reflect the cost of each iteration -- expensive operations get fewer retries.
|
|
- **Escalation** gates belong wherever automated resolution is impossible or ambiguous. They are the safety valve between revision loops and abort. Present the developer with clear options and enough context to decide.
|
|
- **Abort** gates belong at points where continuing would cause damage, waste significant resources, or produce meaningless output. They should preserve state so work can resume after the root cause is fixed.
|
|
|
|
**Selection heuristic:** Start with pre-flight. If the check happens after work is produced, it is a revision gate. If the revision loop cannot resolve the issue, escalate. If continuing is dangerous, abort.
|