docs: update README and docs/ for v1.27 release

Add documentation for all new v1.27 features: - 7 new commands (/gsd:fast, /gsd:review, /gsd:plant-seed, /gsd:thread, /gsd:add-backlog, /gsd:review-backlog, /gsd:pr-branch) - Security hardening (security.cjs, prompt guard hook, workflow guard hook) - Multi-repo workspace support, discussion audit trail, advisor mode - New config options (research_before_questions, hooks.workflow_guard) - Updated component counts in ARCHITECTURE.md Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-25 17:25:23 +02:00 · 2026-03-20 12:21:53 -04:00
parent 47cb2b5c16
commit d5f2a7ea19
6 changed files with 485 additions and 31 deletions
--- a/README.md
+++ b/README.md
@@ -428,6 +428,8 @@ GSD handles it for you:
 | `PLAN.md` | Atomic task with XML structure, verification steps |
 | `SUMMARY.md` | What happened, what changed, committed to history |
 | `todos/` | Captured ideas and tasks for later work |
+| `threads/` | Persistent context threads for cross-session work |
+| `seeds/` | Forward-looking ideas that surface at the right milestone |

 Size limits based on where Claude's quality degrades. Stay under, get consistent excellence.

@@ -560,11 +562,14 @@ You're never locked in. The system adapts.
 | `/gsd:pr-branch` | Create clean PR branch filtering `.planning/` commits |
 | `/gsd:audit-uat` | Audit verification debt — find phases missing UAT |

-### Backlog
+### Backlog & Threads

 | Command | What it does |
 |---------|--------------|
-| `/gsd:plant-seed <idea>` | Park ideas in backlog parking lot for future milestones |
+| `/gsd:plant-seed <idea>` | Capture forward-looking ideas with trigger conditions — surfaces at the right milestone |
+| `/gsd:add-backlog <desc>` | Add idea to backlog parking lot (999.x numbering, outside active sequence) |
+| `/gsd:review-backlog` | Review and promote backlog items to active milestone or remove stale entries |
+| `/gsd:thread [name]` | Persistent context threads — lightweight cross-session knowledge for work spanning multiple sessions |

 ### Utilities

@@ -662,6 +667,20 @@ At milestone completion, GSD offers squash merge (recommended) or merge with his

 ## Security

+### Built-in Security Hardening
+
+GSD includes defense-in-depth security since v1.27:
+
+- **Path traversal prevention** — All user-supplied file paths (`--text-file`, `--prd`) are validated to resolve within the project directory
+- **Prompt injection detection** — Centralized `security.cjs` module scans for injection patterns in user-supplied text before it enters planning artifacts
+- **PreToolUse prompt guard hook** — `gsd-prompt-guard` scans writes to `.planning/` for embedded injection vectors (advisory, not blocking)
+- **Safe JSON parsing** — Malformed `--fields` arguments are caught before they corrupt state
+- **Shell argument validation** — User text is sanitized before shell interpolation
+- **CI-ready injection scanner** — `prompt-injection-scan.test.cjs` scans all agent/workflow/command files for embedded injection vectors
+
+> [!NOTE]
+> Because GSD generates markdown files that become LLM system prompts, any user-controlled text flowing into planning artifacts is a potential indirect prompt injection vector. These protections are designed to catch such vectors at multiple layers.
+
 ### Protecting Sensitive Files

 GSD's codebase mapping and analysis commands read files to understand your project. **Protect files containing secrets** by adding them to Claude Code's deny list:
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -113,7 +113,7 @@ User-facing entry points. Each file contains YAML frontmatter (name, description
 - **Copilot:** Slash commands (`/gsd:command-name`)
 - **Antigravity:** Skills

-**Total commands:** 37
+**Total commands:** 44

 ### Workflows (`get-shit-done/workflows/*.md`)

@@ -124,7 +124,7 @@ Orchestration logic that commands reference. Contains the step-by-step process i
 - State update patterns
 - Error handling and recovery

-**Total workflows:** 41
+**Total workflows:** 46

 ### Agents (`agents/*.md`)

@@ -134,7 +134,7 @@ Specialized agent definitions with frontmatter specifying:
 - `tools` — Allowed tool access (Read, Write, Edit, Bash, Grep, Glob, WebSearch, etc.)
 - `color` — Terminal output color for visual distinction

-**Total agents:** 15
+**Total agents:** 16

 ### References (`get-shit-done/references/*.md`)

@@ -156,6 +156,7 @@ Markdown templates for all planning artifacts. Used by `gsd-tools.cjs template f
 - `summary.md` (+ `summary-minimal.md`, `summary-standard.md`, `summary-complex.md`) — Granularity-aware summary templates
 - `DEBUG.md` — Debug session tracking template
 - `UI-SPEC.md`, `UAT.md`, `VALIDATION.md` — Specialized verification templates
+- `discussion-log.md` — Discussion audit trail template
 - `codebase/` — Brownfield mapping templates (stack, architecture, conventions, concerns, structure, testing, integrations)
 - `research-project/` — Research output templates (SUMMARY, STACK, FEATURES, ARCHITECTURE, PITFALLS)

@@ -168,10 +169,12 @@ Runtime hooks that integrate with the host AI agent:
 | `gsd-statusline.js` | `statusLine` | Displays model, task, directory, and context usage bar |
 | `gsd-context-monitor.js` | `PostToolUse` / `AfterTool` | Injects agent-facing context warnings at 35%/25% remaining |
 | `gsd-check-update.js` | `SessionStart` | Background check for new GSD versions |
+| `gsd-prompt-guard.js` | `PreToolUse` | Scans `.planning/` writes for prompt injection patterns (advisory) |
+| `gsd-workflow-guard.js` | `PreToolUse` | Detects file edits outside GSD workflow context (advisory, opt-in via `hooks.workflow_guard`) |

 ### CLI Tools (`get-shit-done/bin/`)

-Node.js CLI utility (`gsd-tools.cjs`) with 15 domain modules:
+Node.js CLI utility (`gsd-tools.cjs`) with 17 domain modules:

 | Module | Responsibility |
 |--------|---------------|
@@ -187,6 +190,8 @@ Node.js CLI utility (`gsd-tools.cjs`) with 15 domain modules:
 | `milestone.cjs` | Milestone archival, requirements marking |
 | `commands.cjs` | Misc commands (slug, timestamp, todos, scaffolding, stats) |
 | `model-profiles.cjs` | Model profile resolution table |
+| `security.cjs` | Path traversal prevention, prompt injection detection, safe JSON parsing, shell argument validation |
+| `uat.cjs` | UAT file parsing, verification debt tracking, audit-uat support |

 ---

@@ -218,7 +223,7 @@ Orchestrator (workflow .md)

 | Category | Agents | Parallelism |
 |----------|--------|-------------|
-| **Researchers** | gsd-project-researcher, gsd-phase-researcher, gsd-ui-researcher | 4 parallel (stack, features, architecture, pitfalls) |
+| **Researchers** | gsd-project-researcher, gsd-phase-researcher, gsd-ui-researcher, gsd-advisor-researcher | 4 parallel (stack, features, architecture, pitfalls); advisor spawns during discuss-phase |
 | **Synthesizers** | gsd-research-synthesizer | Sequential (after researchers complete) |
 | **Planners** | gsd-planner, gsd-roadmapper | Sequential |
 | **Checkers** | gsd-plan-checker, gsd-integration-checker, gsd-ui-checker, gsd-nyquist-auditor | Sequential (verification loop, max 3 iterations) |
@@ -404,6 +409,8 @@ Equivalent paths for other runtimes:
 ├── todos/
 │   ├── pending/            # Captured ideas
 │   └── done/               # Completed todos
+├── threads/               # Persistent context threads (from /gsd:thread)
+├── seeds/                 # Forward-looking ideas (from /gsd:plant-seed)
 ├── debug/                  # Active debug sessions
 │   ├── *.md                # Active sessions
 │   ├── resolved/           # Archived sessions
@@ -480,6 +487,20 @@ Debounce: 5 tool uses between repeated warnings. Severity escalation (WARNING→
 - Missing bridge files handled gracefully (subagents, fresh sessions)
 - Context monitor is advisory — never issues imperative commands that override user preferences

+### Security Hooks (v1.27)
+
+**Prompt Guard** (`gsd-prompt-guard.js`):
+- Triggers on Write/Edit to `.planning/` files
+- Scans content for prompt injection patterns (role override, instruction bypass, system tag injection)
+- Advisory-only — logs detection, does not block
+- Patterns are inlined (subset of `security.cjs`) for hook independence
+
+**Workflow Guard** (`gsd-workflow-guard.js`):
+- Triggers on Write/Edit to non-`.planning/` files
+- Detects edits outside GSD workflow context (no active `/gsd:` command or Task subagent)
+- Advises using `/gsd:quick` or `/gsd:fast` for state-tracked changes
+- Opt-in via `hooks.workflow_guard: true` (default: false)
+
 ---

 ## Runtime Abstraction
--- a/docs/COMMANDS.md
+++ b/docs/COMMANDS.md
@@ -44,14 +44,16 @@ Capture implementation decisions before planning.
 |------|-------------|
 | `--auto` | Auto-select recommended defaults for all questions |
 | `--batch` | Group questions for batch intake instead of one-by-one |
+| `--analyze` | Add trade-off analysis during discussion |

 **Prerequisites:** `.planning/ROADMAP.md` exists
-**Produces:** `{phase}-CONTEXT.md`
+**Produces:** `{phase}-CONTEXT.md`, `{phase}-DISCUSSION-LOG.md` (audit trail)

 ```bash
 /gsd:discuss-phase 1                # Interactive discussion for phase 1
 /gsd:discuss-phase 3 --auto         # Auto-select defaults for phase 3
 /gsd:discuss-phase --batch          # Batch mode for current phase
+/gsd:discuss-phase 2 --analyze      # Discussion with trade-off analysis
 ```

 ---
@@ -609,6 +611,151 @@ Restore local modifications after a GSD update.

 ---

+## Fast & Inline Commands
+
+### `/gsd:fast`
+
+Execute a trivial task inline — no subagents, no planning overhead. For typo fixes, config changes, small refactors, forgotten commits.
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `task description` | No | What to do (prompted if omitted) |
+
+**Not a replacement for `/gsd:quick`** — use `/gsd:quick` for anything needing research, multi-step planning, or verification.
+
+```bash
+/gsd:fast "fix typo in README"
+/gsd:fast "add .env to gitignore"
+```
+
+---
+
+## Code Quality Commands
+
+### `/gsd:review`
+
+Cross-AI peer review of phase plans from external AI CLIs.
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `--phase N` | **Yes** | Phase number to review |
+
+| Flag | Description |
+|------|-------------|
+| `--gemini` | Include Gemini CLI review |
+| `--claude` | Include Claude CLI review (separate session) |
+| `--codex` | Include Codex CLI review |
+| `--all` | Include all available CLIs |
+
+**Produces:** `{phase}-REVIEWS.md` — consumable by `/gsd:plan-phase --reviews`
+
+```bash
+/gsd:review --phase 3 --all
+/gsd:review --phase 2 --gemini
+```
+
+---
+
+### `/gsd:pr-branch`
+
+Create a clean PR branch by filtering out `.planning/` commits.
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `target branch` | No | Base branch (default: `main`) |
+
+**Purpose:** Reviewers see only code changes, not GSD planning artifacts.
+
+```bash
+/gsd:pr-branch                     # Filter against main
+/gsd:pr-branch develop             # Filter against develop
+```
+
+---
+
+### `/gsd:audit-uat`
+
+Cross-phase audit of all outstanding UAT and verification items.
+
+**Prerequisites:** At least one phase has been executed with UAT or verification
+**Produces:** Categorized audit report with human test plan
+
+```bash
+/gsd:audit-uat
+```
+
+---
+
+## Backlog & Thread Commands
+
+### `/gsd:add-backlog`
+
+Add an idea to the backlog parking lot using 999.x numbering.
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `description` | **Yes** | Backlog item description |
+
+**999.x numbering** keeps backlog items outside the active phase sequence. Phase directories are created immediately so `/gsd:discuss-phase` and `/gsd:plan-phase` work on them.
+
+```bash
+/gsd:add-backlog "GraphQL API layer"
+/gsd:add-backlog "Mobile responsive redesign"
+```
+
+---
+
+### `/gsd:review-backlog`
+
+Review and promote backlog items to active milestone.
+
+**Actions per item:** Promote (move to active sequence), Keep (leave in backlog), Remove (delete).
+
+```bash
+/gsd:review-backlog
+```
+
+---
+
+### `/gsd:plant-seed`
+
+Capture a forward-looking idea with trigger conditions — surfaces automatically at the right milestone.
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `idea summary` | No | Seed description (prompted if omitted) |
+
+Seeds solve context rot: instead of a one-liner in Deferred that nobody reads, a seed preserves the full WHY, WHEN to surface, and breadcrumbs to details.
+
+**Produces:** `.planning/seeds/SEED-NNN-slug.md`
+**Consumed by:** `/gsd:new-milestone` (scans seeds and presents matches)
+
+```bash
+/gsd:plant-seed "Add real-time collaboration when WebSocket infra is in place"
+```
+
+---
+
+### `/gsd:thread`
+
+Manage persistent context threads for cross-session work.
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| (none) | — | List all threads |
+| `name` | — | Resume existing thread by name |
+| `description` | — | Create new thread |
+
+Threads are lightweight cross-session knowledge stores for work that spans multiple sessions but doesn't belong to any specific phase. Lighter weight than `/gsd:pause-work`.
+
+```bash
+/gsd:thread                         # List all threads
+/gsd:thread fix-deploy-key-auth     # Resume thread
+/gsd:thread "Investigate TCP timeout in pasta service"  # Create new
+```
+
+---
+
 ## Community Commands

 ### `/gsd:join-discord`
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -29,7 +29,12 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd:new
    "ui_phase": true,
    "ui_safety_gate": true,
    "node_repair": true,
-    "node_repair_budget": 2
+    "node_repair_budget": 2,
+    "research_before_questions": false
+  },
+  "hooks": {
+    "context_warnings": true,
+    "workflow_guard": false
  },
  "parallelization": {
    "enabled": true,
@@ -91,6 +96,7 @@ All workflow toggles follow the **absent = enabled** pattern. If a key is missin
 | `workflow.ui_safety_gate` | boolean | `true` | Prompt to run /gsd:ui-phase for frontend phases during plan-phase |
 | `workflow.node_repair` | boolean | `true` | Autonomous task repair on verification failure |
 | `workflow.node_repair_budget` | number | `2` | Max repair attempts per failed task |
+| `workflow.research_before_questions` | boolean | `false` | Run research before discussion questions instead of after |

 ### Recommended Presets

@@ -113,6 +119,17 @@ All workflow toggles follow the **absent = enabled** pattern. If a key is missin

 If `.planning/` is in `.gitignore`, `commit_docs` is automatically `false` regardless of config.json. This prevents git errors.

+---
+
+## Hook Settings
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `hooks.context_warnings` | boolean | `true` | Show context window usage warnings via context monitor hook |
+| `hooks.workflow_guard` | boolean | `false` | Warn when file edits happen outside GSD workflow context (advises using `/gsd:quick` or `/gsd:fast`) |
+
+The prompt injection guard hook (`gsd-prompt-guard.js`) is always active and cannot be disabled — it's a security feature, not a workflow toggle.
+
 ### Private Planning Setup

 To keep planning artifacts out of git:
--- a/docs/FEATURES.md
+++ b/docs/FEATURES.md
@@ -53,6 +53,15 @@
  - [Developer Profiling](#38-developer-profiling)
  - [Execution Hardening](#39-execution-hardening)
  - [Verification Debt Tracking](#40-verification-debt-tracking)
+- [v1.27 Features](#v127-features)
+  - [Fast Mode](#41-fast-mode)
+  - [Cross-AI Peer Review](#42-cross-ai-peer-review)
+  - [Backlog Parking Lot](#43-backlog-parking-lot)
+  - [Persistent Context Threads](#44-persistent-context-threads)
+  - [PR Branch Filtering](#45-pr-branch-filtering)
+  - [Security Hardening](#46-security-hardening)
+  - [Multi-Repo Workspace Support](#47-multi-repo-workspace-support)
+  - [Discussion Audit Trail](#48-discussion-audit-trail)

 ---

@@ -973,3 +982,145 @@ When verification returns `human_needed`, items are persisted as a trackable HUM
 - REQ-DEBT-04: System MUST persist human_needed verification items as trackable UAT files
 - REQ-DEBT-05: System MUST warn (non-blocking) during phase completion and transition when verification debt exists
 - REQ-DEBT-06: `/gsd:audit-uat` MUST scan all phases, categorize items by testability, and produce a human test plan
+
+---
+
+## v1.27 Features
+
+### 41. Fast Mode
+
+**Command:** `/gsd:fast [task description]`
+
+**Purpose:** Execute trivial tasks inline without spawning subagents or generating PLAN.md files. For tasks too small to justify planning overhead: typo fixes, config changes, small refactors, forgotten commits, simple additions.
+
+**Requirements:**
+- REQ-FAST-01: System MUST execute the task directly in the current context without subagents
+- REQ-FAST-02: System MUST produce an atomic git commit for the change
+- REQ-FAST-03: System MUST track the task in `.planning/quick/` for state consistency
+- REQ-FAST-04: System MUST NOT be used for tasks requiring research, multi-step planning, or verification
+
+**When to use vs `/gsd:quick`:**
+- `/gsd:fast` — One-sentence tasks executable in under 2 minutes (typo, config change, small addition)
+- `/gsd:quick` — Anything needing research, multi-step planning, or verification
+
+---
+
+### 42. Cross-AI Peer Review
+
+**Command:** `/gsd:review --phase N [--gemini] [--claude] [--codex] [--all]`
+
+**Purpose:** Invoke external AI CLIs (Gemini, Claude, Codex) to independently review phase plans. Produces structured REVIEWS.md with per-reviewer feedback.
+
+**Requirements:**
+- REQ-REVIEW-01: System MUST detect available AI CLIs on the system
+- REQ-REVIEW-02: System MUST build a structured review prompt from phase plans
+- REQ-REVIEW-03: System MUST invoke each selected CLI independently
+- REQ-REVIEW-04: System MUST collect responses and produce `REVIEWS.md`
+- REQ-REVIEW-05: Reviews MUST be consumable by `/gsd:plan-phase --reviews`
+
+**Produces:** `{phase}-REVIEWS.md` — Per-reviewer structured feedback
+
+---
+
+### 43. Backlog Parking Lot
+
+**Commands:** `/gsd:add-backlog <description>`, `/gsd:review-backlog`, `/gsd:plant-seed <idea>`
+
+**Purpose:** Capture ideas that aren't ready for active planning. Backlog items use 999.x numbering to stay outside the active phase sequence. Seeds are forward-looking ideas with trigger conditions that surface automatically at the right milestone.
+
+**Requirements:**
+- REQ-BACKLOG-01: Backlog items MUST use 999.x numbering to stay outside active phase sequence
+- REQ-BACKLOG-02: Phase directories MUST be created immediately so `/gsd:discuss-phase` and `/gsd:plan-phase` work on them
+- REQ-BACKLOG-03: `/gsd:review-backlog` MUST support promote, keep, and remove actions per item
+- REQ-BACKLOG-04: Promoted items MUST be renumbered into the active milestone sequence
+- REQ-SEED-01: Seeds MUST capture the full WHY and WHEN to surface conditions
+- REQ-SEED-02: `/gsd:new-milestone` MUST scan seeds and present matches
+
+**Produces:**
+| Artifact | Description |
+|----------|-------------|
+| `.planning/phases/999.x-slug/` | Backlog item directory |
+| `.planning/seeds/SEED-NNN-slug.md` | Seed with trigger conditions |
+
+---
+
+### 44. Persistent Context Threads
+
+**Command:** `/gsd:thread [name | description]`
+
+**Purpose:** Lightweight cross-session knowledge stores for work that spans multiple sessions but doesn't belong to any specific phase. Lighter weight than `/gsd:pause-work` — no phase state, no plan context.
+
+**Requirements:**
+- REQ-THREAD-01: System MUST support create, list, and resume modes
+- REQ-THREAD-02: Threads MUST be stored in `.planning/threads/` as markdown files
+- REQ-THREAD-03: Thread files MUST include Goal, Context, References, and Next Steps sections
+- REQ-THREAD-04: Resuming a thread MUST load its full context into the current session
+- REQ-THREAD-05: Threads MUST be promotable to phases or backlog items
+
+**Produces:** `.planning/threads/{slug}.md` — Persistent context thread
+
+---
+
+### 45. PR Branch Filtering
+
+**Command:** `/gsd:pr-branch [target branch]`
+
+**Purpose:** Create a clean branch suitable for pull requests by filtering out `.planning/` commits. Reviewers see only code changes, not GSD planning artifacts.
+
+**Requirements:**
+- REQ-PRBRANCH-01: System MUST identify commits that only modify `.planning/` files
+- REQ-PRBRANCH-02: System MUST create a new branch with planning commits filtered out
+- REQ-PRBRANCH-03: Code changes MUST be preserved exactly as committed
+
+---
+
+### 46. Security Hardening
+
+**Purpose:** Defense-in-depth security for GSD's planning artifacts. Because GSD generates markdown files that become LLM system prompts, user-controlled text flowing into these files is a potential indirect prompt injection vector.
+
+**Components:**
+
+**1. Centralized Security Module** (`security.cjs`)
+- Path traversal prevention — validates file paths resolve within the project directory
+- Prompt injection detection — scans for known injection patterns in user-supplied text
+- Safe JSON parsing — catches malformed input before state corruption
+- Field name validation — prevents injection through config field names
+- Shell argument validation — sanitizes user text before shell interpolation
+
+**2. Prompt Injection Guard Hook** (`gsd-prompt-guard.js`)
+PreToolUse hook that scans Write/Edit calls targeting `.planning/` for injection patterns. Advisory-only — logs detection for awareness without blocking legitimate operations.
+
+**3. Workflow Guard Hook** (`gsd-workflow-guard.js`)
+PreToolUse hook that detects when Claude attempts file edits outside a GSD workflow context. Advises using `/gsd:quick` or `/gsd:fast` instead of direct edits. Configurable via `hooks.workflow_guard` (default: false).
+
+**4. CI-Ready Injection Scanner** (`prompt-injection-scan.test.cjs`)
+Test suite that scans all agent, workflow, and command files for embedded injection vectors.
+
+**Requirements:**
+- REQ-SEC-01: All user-supplied file paths MUST be validated against the project directory
+- REQ-SEC-02: Prompt injection patterns MUST be detected before text enters planning artifacts
+- REQ-SEC-03: Security hooks MUST be advisory-only (never block legitimate operations)
+- REQ-SEC-04: JSON parsing of user input MUST catch malformed data gracefully
+- REQ-SEC-05: macOS `/var` → `/private/var` symlink resolution MUST be handled in path validation
+
+---
+
+### 47. Multi-Repo Workspace Support
+
+**Purpose:** Auto-detection and project root resolution for monorepos and multi-repo setups. Supports workspaces where `.planning/` may need to resolve across repository boundaries.
+
+**Requirements:**
+- REQ-MULTIREPO-01: System MUST auto-detect multi-repo workspace configuration
+- REQ-MULTIREPO-02: System MUST resolve project root across repository boundaries
+- REQ-MULTIREPO-03: Executor MUST record per-repo commit hashes in multi-repo mode
+
+---
+
+### 48. Discussion Audit Trail
+
+**Purpose:** Auto-generate `DISCUSSION-LOG.md` during `/gsd:discuss-phase` for full audit trail of decisions made during discussion.
+
+**Requirements:**
+- REQ-DISCLOG-01: System MUST auto-generate DISCUSSION-LOG.md during discuss-phase
+- REQ-DISCLOG-02: Log MUST capture questions asked, options presented, and decisions made
+- REQ-DISCLOG-03: Decision IDs MUST enable traceability from discuss-phase to plan-phase
--- a/docs/USER-GUIDE.md
+++ b/docs/USER-GUIDE.md
@@ -8,6 +8,8 @@ A detailed reference for workflows, troubleshooting, and configuration. For quic

 - [Workflow Diagrams](#workflow-diagrams)
 - [UI Design Contract](#ui-design-contract)
+- [Backlog & Threads](#backlog--threads)
+- [Security](#security)
 - [Command Reference](#command-reference)
 - [Configuration Reference](#configuration-reference)
 - [Usage Examples](#usage-examples)
@@ -237,6 +239,72 @@ Controlled by `workflow.ui_safety_gate` config toggle.

 ---

+## Backlog & Threads
+
+### Backlog Parking Lot
+
+Ideas that aren't ready for active planning go into the backlog using 999.x numbering, keeping them outside the active phase sequence.
+
+```
+/gsd:add-backlog "GraphQL API layer"     # Creates 999.1-graphql-api-layer/
+/gsd:add-backlog "Mobile responsive"     # Creates 999.2-mobile-responsive/
+```
+
+Backlog items get full phase directories, so you can use `/gsd:discuss-phase 999.1` to explore an idea further or `/gsd:plan-phase 999.1` when it's ready.
+
+**Review and promote** with `/gsd:review-backlog` — it shows all backlog items and lets you promote (move to active sequence), keep (leave in backlog), or remove (delete).
+
+### Seeds
+
+Seeds are forward-looking ideas with trigger conditions. Unlike backlog items, seeds surface automatically when the right milestone arrives.
+
+```
+/gsd:plant-seed "Add real-time collab when WebSocket infra is in place"
+```
+
+Seeds preserve the full WHY and WHEN to surface. `/gsd:new-milestone` scans all seeds and presents matches.
+
+**Storage:** `.planning/seeds/SEED-NNN-slug.md`
+
+### Persistent Context Threads
+
+Threads are lightweight cross-session knowledge stores for work that spans multiple sessions but doesn't belong to any specific phase.
+
+```
+/gsd:thread                              # List all threads
+/gsd:thread fix-deploy-key-auth          # Resume existing thread
+/gsd:thread "Investigate TCP timeout"    # Create new thread
+```
+
+Threads are lighter weight than `/gsd:pause-work` — no phase state, no plan context. Each thread file includes Goal, Context, References, and Next Steps sections.
+
+Threads can be promoted to phases (`/gsd:add-phase`) or backlog items (`/gsd:add-backlog`) when they mature.
+
+**Storage:** `.planning/threads/{slug}.md`
+
+---
+
+## Security
+
+### Defense-in-Depth (v1.27)
+
+GSD generates markdown files that become LLM system prompts. This means any user-controlled text flowing into planning artifacts is a potential indirect prompt injection vector. v1.27 introduced centralized security hardening:
+
+**Path Traversal Prevention:**
+All user-supplied file paths (`--text-file`, `--prd`) are validated to resolve within the project directory. macOS `/var` → `/private/var` symlink resolution is handled.
+
+**Prompt Injection Detection:**
+The `security.cjs` module scans for known injection patterns (role overrides, instruction bypasses, system tag injections) in user-supplied text before it enters planning artifacts.
+
+**Runtime Hooks:**
+- `gsd-prompt-guard.js` — Scans Write/Edit calls to `.planning/` for injection patterns (always active, advisory-only)
+- `gsd-workflow-guard.js` — Warns on file edits outside GSD workflow context (opt-in via `hooks.workflow_guard`)
+
+**CI Scanner:**
+`prompt-injection-scan.test.cjs` scans all agent, workflow, and command files for embedded injection vectors. Run as part of the test suite.
+
+---
+
 ### Execution Wave Coordination

 ```
@@ -289,6 +357,7 @@ Controlled by `workflow.ui_safety_gate` config toggle.
 | `/gsd:execute-phase <N>` | Execute all plans in parallel waves | After planning is complete |
 | `/gsd:verify-work [N]` | Manual UAT with auto-diagnosis | After execution completes |
 | `/gsd:ship [N]` | Create PR from verified work | After verification passes |
+| `/gsd:fast <text>` | Inline trivial tasks — skips planning entirely | Typo fixes, config changes, small refactors |
 | `/gsd:next` | Auto-detect state and run next step | Anytime — "what should I do next?" |
 | `/gsd:ui-review [N]` | Retroactive 6-pillar visual audit | After execution or verify-work (frontend projects) |
 | `/gsd:audit-milestone` | Verify milestone met its definition of done | Before completing milestone |
@@ -331,6 +400,23 @@ Controlled by `workflow.ui_safety_gate` config toggle.
 | `/gsd:set-profile <profile>` | Quick profile switch | Change cost/quality tradeoff |
 | `/gsd:reapply-patches` | Restore local modifications after update | After `/gsd:update` if you had local edits |

+### Code Quality & Review
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/gsd:review --phase N` | Cross-AI peer review from external CLIs | Before executing, to validate plans |
+| `/gsd:pr-branch` | Clean PR branch filtering `.planning/` commits | Before creating PR with planning-free diff |
+| `/gsd:audit-uat` | Audit verification debt across all phases | Before milestone completion |
+
+### Backlog & Threads
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/gsd:add-backlog <desc>` | Add idea to backlog parking lot (999.x) | Ideas not ready for active planning |
+| `/gsd:review-backlog` | Promote/keep/remove backlog items | Before new milestone, to prioritize |
+| `/gsd:plant-seed <idea>` | Forward-looking idea with trigger conditions | Ideas that should surface at a future milestone |
+| `/gsd:thread [name]` | Persistent context threads | Cross-session work outside the phase structure |
+
 ---

 ## Configuration Reference
@@ -354,15 +440,20 @@ GSD stores project settings in `.planning/config.json`. Configure during `/gsd:n
    "verifier": true,
    "nyquist_validation": true,
    "ui_phase": true,
-    "ui_safety_gate": true
+    "ui_safety_gate": true,
+    "research_before_questions": false
  },
-  "git": {
-    "branching_strategy": "none",
-    "phase_branch_template": "gsd/phase-{phase}-{slug}",
-    "milestone_branch_template": "gsd/{milestone}-{slug}",
-    "quick_branch_template": null
-  }
-}
+  "hooks": {
+    "context_warnings": true,
+    "workflow_guard": false
+  },
+  "git": {
+    "branching_strategy": "none",
+    "phase_branch_template": "gsd/phase-{phase}-{slug}",
+    "milestone_branch_template": "gsd/{milestone}-{slug}",
+    "quick_branch_template": null
+  }
+}
 ```

 ### Core Settings
@@ -392,17 +483,25 @@ GSD stores project settings in `.planning/config.json`. Configure during `/gsd:n
 | `workflow.nyquist_validation` | `true`, `false` | `true` | Validation architecture research during plan-phase; 8th plan-check dimension |
 | `workflow.ui_phase` | `true`, `false` | `true` | Generate UI design contracts for frontend phases |
 | `workflow.ui_safety_gate` | `true`, `false` | `true` | plan-phase prompts to run /gsd:ui-phase for frontend phases |
+| `workflow.research_before_questions` | `true`, `false` | `false` | Run research before discussion questions instead of after |

-Disable these to speed up phases in familiar domains or when conserving tokens.
+### Hook Settings
+
+| Setting | Options | Default | What it Controls |
+|---------|---------|---------|------------------|
+| `hooks.context_warnings` | `true`, `false` | `true` | Context window usage warnings |
+| `hooks.workflow_guard` | `true`, `false` | `false` | Warn on file edits outside GSD workflow context |
+
+Disable workflow toggles to speed up phases in familiar domains or when conserving tokens.

 ### Git Branching

 | Setting | Options | Default | What it Controls |
 |---------|---------|---------|------------------|
-| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | When and how branches are created |
-| `git.phase_branch_template` | Template string | `gsd/phase-{phase}-{slug}` | Branch name for phase strategy |
-| `git.milestone_branch_template` | Template string | `gsd/{milestone}-{slug}` | Branch name for milestone strategy |
-| `git.quick_branch_template` | Template string or `null` | `null` | Optional branch name for `/gsd:quick` tasks |
+| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | When and how branches are created |
+| `git.phase_branch_template` | Template string | `gsd/phase-{phase}-{slug}` | Branch name for phase strategy |
+| `git.milestone_branch_template` | Template string | `gsd/{milestone}-{slug}` | Branch name for milestone strategy |
+| `git.quick_branch_template` | Template string or `null` | `null` | Optional branch name for `/gsd:quick` tasks |

 **Branching strategies explained:**

@@ -412,15 +511,15 @@ Disable these to speed up phases in familiar domains or when conserving tokens.
 | `phase` | At each `execute-phase` | One phase per branch | Code review per phase, granular rollback |
 | `milestone` | At first `execute-phase` | All phases share one branch | Release branches, PR per version |

-**Template variables:** `{phase}` = zero-padded number (e.g., "03"), `{slug}` = lowercase hyphenated name, `{milestone}` = version (e.g., "v1.0"), `{num}` / `{quick}` = quick task ID (e.g., "260317-abc").
-
-Example quick-task branching:
-
-```json
-"git": {
-  "quick_branch_template": "gsd/quick-{num}-{slug}"
-}
-```
+**Template variables:** `{phase}` = zero-padded number (e.g., "03"), `{slug}` = lowercase hyphenated name, `{milestone}` = version (e.g., "v1.0"), `{num}` / `{quick}` = quick task ID (e.g., "260317-abc").
+
+Example quick-task branching:
+
+```json
+"git": {
+  "quick_branch_template": "gsd/quick-{num}-{slug}"
+}
+```

 ### Model Profiles (Per-Agent Breakdown)