docs: update documentation for v1.34.0 release (#1868)

2026-04-25 17:25:23 +02:00 · 2026-04-06 16:25:41 -04:00
parent 07b7d40f70
commit 641ea8ad42
5 changed files with 577 additions and 13 deletions
--- 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:** 60
+**Total commands:** 69

 ### 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:** 60
+**Total workflows:** 68

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

@@ -134,23 +134,26 @@ 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:** 21
+**Total agents:** 24

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

-Shared knowledge documents that workflows and agents `@-reference` (25 total):
+Shared knowledge documents that workflows and agents `@-reference` (35 total):

 **Core references:**
 - `checkpoints.md` — Checkpoint type definitions and interaction patterns
+- `gates.md` — 4 canonical gate types (Confirm, Quality, Safety, Transition) wired into plan-checker and verifier
 - `model-profiles.md` — Per-agent model tier assignments
 - `model-profile-resolution.md` — Model resolution algorithm documentation
 - `verification-patterns.md` — How to verify different artifact types
+- `verification-overrides.md` — Per-artifact verification override rules
 - `planning-config.md` — Full config schema and behavior
 - `git-integration.md` — Git commit, branching, and history patterns
 - `git-planning-commit.md` — Planning directory commit conventions
 - `questioning.md` — Dream extraction philosophy for project initialization
 - `tdd.md` — Test-driven development integration patterns
 - `ui-brand.md` — Visual output formatting patterns
+- `common-bug-patterns.md` — Common bug patterns for code review and verification

 **Workflow references:**
 - `agent-contracts.md` — Formal interface between orchestrators and agents
@@ -165,6 +168,17 @@ Shared knowledge documents that workflows and agents `@-reference` (25 total):
 - `decimal-phase-calculation.md` — Decimal sub-phase numbering rules
 - `workstream-flag.md` — Workstream active pointer conventions
 - `user-profiling.md` — User behavioral profiling methodology
+- `thinking-partner.md` — Conditional thinking partner activation at decision points
+
+**Thinking model references:**
+
+References for integrating thinking-class models (o3, o4-mini, Gemini 2.5 Pro) into GSD workflows:
+
+- `thinking-models-debug.md` — Thinking model patterns for debugging workflows
+- `thinking-models-execution.md` — Thinking model patterns for execution agents
+- `thinking-models-planning.md` — Thinking model patterns for planning agents
+- `thinking-models-research.md` — Thinking model patterns for research agents
+- `thinking-models-verification.md` — Thinking model patterns for verification agents

 **Modular planner decomposition:**

@@ -395,14 +409,14 @@ UI-SPEC.md (per phase) ───────────────────

 ```
 ~/.claude/                          # Claude Code (global install)
-├── commands/gsd/*.md               # 60 slash commands
+├── commands/gsd/*.md               # 69 slash commands
 ├── get-shit-done/
 │   ├── bin/gsd-tools.cjs           # CLI utility
 │   ├── bin/lib/*.cjs               # 19 domain modules
-│   ├── workflows/*.md              # 60 workflow definitions
-│   ├── references/*.md             # 25 shared reference docs
+│   ├── workflows/*.md              # 68 workflow definitions
+│   ├── references/*.md             # 35 shared reference docs
 │   └── templates/                  # Planning artifact templates
-├── agents/*.md                     # 21 agent definitions
+├── agents/*.md                     # 24 agent definitions
 ├── hooks/
 │   ├── gsd-statusline.js           # Statusline hook
 │   ├── gsd-context-monitor.js      # Context warning hook
--- a/docs/COMMANDS.md
+++ b/docs/COMMANDS.md
@@ -542,6 +542,57 @@ Show all commands and usage guide.

 ## Utility Commands

+### `/gsd-explore`
+
+Socratic ideation session — guide an idea through probing questions, optionally spawn research, then route output to the right GSD artifact (notes, todos, seeds, research questions, requirements, or a new phase).
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `topic` | No | Topic to explore (e.g., `/gsd-explore authentication strategy`) |
+
+```bash
+/gsd-explore                        # Open-ended ideation session
+/gsd-explore authentication strategy  # Explore a specific topic
+```
+
+---
+
+### `/gsd-undo`
+
+Safe git revert — roll back GSD phase or plan commits using the phase manifest with dependency checks and a confirmation gate.
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--last N` | (one of three required) | Show recent GSD commits for interactive selection |
+| `--phase NN` | (one of three required) | Revert all commits for a phase |
+| `--plan NN-MM` | (one of three required) | Revert all commits for a specific plan |
+
+**Safety:** Checks dependent phases/plans before reverting; always shows a confirmation gate.
+
+```bash
+/gsd-undo --last 5                  # Pick from the 5 most recent GSD commits
+/gsd-undo --phase 03                # Revert all commits for phase 3
+/gsd-undo --plan 03-02              # Revert commits for plan 02 of phase 3
+```
+
+---
+
+### `/gsd-import`
+
+Ingest an external plan file into the GSD planning system with conflict detection against `PROJECT.md` decisions before writing anything.
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--from <filepath>` | **Yes** | Path to the external plan file to import |
+
+**Process:** Detects conflicts → prompts for resolution → writes as GSD PLAN.md → validates via `gsd-plan-checker`
+
+```bash
+/gsd-import --from /tmp/team-plan.md  # Import and validate an external plan
+```
+
+---
+
 ### `/gsd-quick`

 Execute ad-hoc task with GSD guarantees.
@@ -809,6 +860,46 @@ Analyze existing codebase with parallel mapper agents.

 ---

+### `/gsd-scan`
+
+Rapid single-focus codebase assessment — lightweight alternative to `/gsd-map-codebase` that spawns one mapper agent instead of four parallel ones.
+
+| Flag | Description |
+|------|-------------|
+| `--focus tech\|arch\|quality\|concerns\|tech+arch` | Focus area (default: `tech+arch`) |
+
+**Produces:** Targeted document(s) in `.planning/codebase/`
+
+```bash
+/gsd-scan                           # Quick tech + arch overview
+/gsd-scan --focus quality           # Quality and code health only
+/gsd-scan --focus concerns          # Surface concerns and risk areas
+```
+
+---
+
+### `/gsd-intel`
+
+Query, inspect, or refresh queryable codebase intelligence files stored in `.planning/intel/`. Requires `intel.enabled: true` in `config.json`.
+
+| Argument | Description |
+|----------|-------------|
+| `query <term>` | Search intel files for a term |
+| `status` | Show intel file freshness (FRESH/STALE) |
+| `diff` | Show changes since last snapshot |
+| `refresh` | Rebuild all intel files from codebase analysis |
+
+**Produces:** `.planning/intel/` JSON files (stack, api-map, dependency-graph, file-roles, arch-decisions)
+
+```bash
+/gsd-intel status                   # Check freshness of intel files
+/gsd-intel query authentication     # Search intel for a term
+/gsd-intel diff                     # What changed since last snapshot
+/gsd-intel refresh                  # Rebuild intel index
+```
+
+---
+
 ## Update Commands

 ### `/gsd-update`
@@ -829,6 +920,75 @@ Restore local modifications after a GSD update.

 ---

+## Code Quality Commands
+
+### `/gsd-code-review`
+
+Review source files changed during a phase for bugs, security vulnerabilities, and code quality problems.
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `N` | **Yes** | Phase number whose changes to review (e.g., `2` or `02`) |
+| `--depth=quick\|standard\|deep` | No | Review depth level (overrides `workflow.code_review_depth` config). `quick`: pattern-matching only (~2 min). `standard`: per-file analysis with language-specific checks (~5–15 min, default). `deep`: cross-file analysis including import graphs and call chains (~15–30 min) |
+| `--files file1,file2,...` | No | Explicit comma-separated file list; skips SUMMARY/git scoping entirely |
+
+**Prerequisites:** Phase has been executed and has SUMMARY.md or git history
+**Produces:** `{phase}-REVIEW.md` in phase directory with severity-classified findings
+**Spawns:** `gsd-code-reviewer` agent
+
+```bash
+/gsd-code-review 3                          # Standard review for phase 3
+/gsd-code-review 2 --depth=deep             # Deep cross-file review
+/gsd-code-review 4 --files src/auth.ts,src/token.ts  # Explicit file list
+```
+
+---
+
+### `/gsd-code-review-fix`
+
+Auto-fix issues found by `/gsd-code-review`. Reads `REVIEW.md`, spawns a fixer agent, commits each fix atomically, and produces a `REVIEW-FIX.md` summary.
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `N` | **Yes** | Phase number whose REVIEW.md to fix |
+| `--all` | No | Include Info findings in fix scope (default: Critical + Warning only) |
+| `--auto` | No | Enable fix + re-review iteration loop, capped at 3 iterations |
+
+**Prerequisites:** Phase has a `{phase}-REVIEW.md` file (run `/gsd-code-review` first)
+**Produces:** `{phase}-REVIEW-FIX.md` with applied fixes summary
+**Spawns:** `gsd-code-fixer` agent
+
+```bash
+/gsd-code-review-fix 3                      # Fix Critical + Warning findings for phase 3
+/gsd-code-review-fix 3 --all               # Include Info findings
+/gsd-code-review-fix 3 --auto              # Fix and re-review until clean (max 3 iterations)
+```
+
+---
+
+### `/gsd-audit-fix`
+
+Autonomous audit-to-fix pipeline — runs an audit, classifies findings, fixes auto-fixable issues with test verification, and commits each fix atomically.
+
+| Flag | Description |
+|------|-------------|
+| `--source <audit>` | Which audit to run (default: `audit-uat`) |
+| `--severity high\|medium\|all` | Minimum severity to process (default: `medium`) |
+| `--max N` | Maximum findings to fix (default: 5) |
+| `--dry-run` | Classify findings without fixing (shows classification table) |
+
+**Prerequisites:** At least one phase has been executed with UAT or verification
+**Produces:** Fix commits with test verification; classification report
+
+```bash
+/gsd-audit-fix                              # Run audit-uat, fix medium+ issues (max 5)
+/gsd-audit-fix --severity high             # Only fix high-severity issues
+/gsd-audit-fix --dry-run                   # Preview classification without fixing
+/gsd-audit-fix --max 10 --severity all     # Fix up to 10 issues of any severity
+```
+
+---
+
 ## Fast & Inline Commands

 ### `/gsd-fast`
@@ -848,8 +1008,6 @@ Execute a trivial task inline — no subagents, no planning overhead. For typo f

 ---

-## Code Quality Commands
-
 ### `/gsd-review`

 Cross-AI peer review of phase plans from external AI CLIs.
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -20,6 +20,7 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new
    "commit_docs": true,
    "search_gitignored": false
  },
+  "context_profile": null,
  "workflow": {
    "research": true,
    "plan_check": true,
@@ -34,7 +35,9 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new
    "discuss_mode": "discuss",
    "skip_discuss": false,
    "text_mode": false,
-    "use_worktrees": true
+    "use_worktrees": true,
+    "code_review": true,
+    "code_review_depth": "standard"
  },
  "hooks": {
    "context_warnings": true,
@@ -73,7 +76,18 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new
  "security_asvs_level": 1,
  "security_block_on": "high",
  "agent_skills": {},
-  "response_language": null
+  "response_language": null,
+  "context_profile": null,
+  "features": {
+    "thinking_partner": false,
+    "global_learnings": false
+  },
+  "learnings": {
+    "max_inject": 10
+  },
+  "intel": {
+    "enabled": false
+  }
 }
 ```

@@ -88,6 +102,7 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new
 | `model_profile` | enum | `quality`, `balanced`, `budget`, `inherit` | `balanced` | Model tier for each agent (see [Model Profiles](#model-profiles)) |
 | `project_code` | string | any short string | (none) | Prefix for phase directory names (e.g., `"ABC"` produces `ABC-01-setup/`). Added in v1.31 |
 | `response_language` | string | language code | (none) | Language for agent responses (e.g., `"pt"`, `"ko"`, `"ja"`). Propagates to all spawned agents for cross-phase language consistency. Added in v1.32 |
+| `context_profile` | string | `dev`, `research`, `review` | (none) | Execution context preset that applies a pre-configured bundle of mode, model, and workflow settings for the current type of work. Added in v1.34 |

 > **Note:** `granularity` was renamed from `depth` in v1.22.3. Existing configs are auto-migrated.

@@ -113,6 +128,8 @@ All workflow toggles follow the **absent = enabled** pattern. If a key is missin
 | `workflow.skip_discuss` | boolean | `false` | When `true`, `/gsd-autonomous` bypasses the discuss-phase entirely, writing minimal CONTEXT.md from the ROADMAP phase goal. Useful for projects where developer preferences are fully captured in PROJECT.md/REQUIREMENTS.md. Added in v1.28 |
 | `workflow.text_mode` | boolean | `false` | Replaces AskUserQuestion TUI menus with plain-text numbered lists. Required for Claude Code remote sessions (`/rc` mode) where TUI menus don't render. Can also be set per-session with `--text` flag on discuss-phase. Added in v1.28 |
 | `workflow.use_worktrees` | boolean | `true` | When `false`, disables git worktree isolation for parallel execution. Users who prefer sequential execution or whose environment does not support worktrees can disable this. Added in v1.31 |
+| `workflow.code_review` | boolean | `true` | Enable `/gsd-code-review` and `/gsd-code-review-fix` commands. When `false`, the commands exit with a configuration gate message. Added in v1.34 |
+| `workflow.code_review_depth` | string | `standard` | Default review depth for `/gsd-code-review`: `quick` (pattern-matching only), `standard` (per-file analysis), or `deep` (cross-file with import graphs). Can be overridden per-run with `--depth=`. Added in v1.34 |

 ### Recommended Presets

@@ -230,6 +247,7 @@ Toggle optional capabilities via the `features.*` config namespace. Feature flag
 |---------|------|---------|-------------|
 | `features.thinking_partner` | boolean | `false` | Enable thinking partner analysis at workflow decision points |
 | `features.global_learnings` | boolean | `false` | Enable cross-project learnings pipeline (auto-copy at phase completion, planner injection) |
+| `intel.enabled` | boolean | `false` | Enable queryable codebase intelligence system. When `true`, `/gsd-intel` commands build and query a JSON index in `.planning/intel/`. Added in v1.34 |

 ### Usage

--- a/docs/FEATURES.md
+++ b/docs/FEATURES.md
@@ -86,6 +86,22 @@
  - [Worktree Toggle](#66-worktree-toggle)
  - [Project Code Prefixing](#67-project-code-prefixing)
  - [Claude Code Skills Migration](#68-claude-code-skills-migration)
+- [v1.34.0 Features](#v1340-features)
+  - [Global Learnings Store](#89-global-learnings-store)
+  - [Queryable Codebase Intelligence](#90-queryable-codebase-intelligence)
+  - [Execution Context Profiles](#91-execution-context-profiles)
+  - [Gates Taxonomy](#92-gates-taxonomy)
+  - [Code Review Pipeline](#93-code-review-pipeline)
+  - [Socratic Exploration](#94-socratic-exploration)
+  - [Safe Undo](#95-safe-undo)
+  - [Plan Import](#96-plan-import)
+  - [Rapid Codebase Scan](#97-rapid-codebase-scan)
+  - [Autonomous Audit-to-Fix](#98-autonomous-audit-to-fix)
+  - [Improved Prompt Injection Scanner](#99-improved-prompt-injection-scanner)
+  - [Stall Detection in Plan-Phase](#100-stall-detection-in-plan-phase)
+  - [Hard Stop Safety Gates in /gsd-next](#101-hard-stop-safety-gates-in-gsd-next)
+  - [Adaptive Model Preset](#102-adaptive-model-preset)
+  - [Post-Merge Hunk Verification](#103-post-merge-hunk-verification)
 - [v1.32 Features](#v132-features)
  - [STATE.md Consistency Gates](#69-statemd-consistency-gates)
  - [Autonomous `--to N` Flag](#70-autonomous---to-n-flag)
@@ -1894,3 +1910,272 @@ Test suite that scans all agent, workflow, and command files for embedded inject
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
 | `hooks.community` | boolean | `false` | Enable optional community hooks for commit validation, session state, and phase boundaries |
+
+---
+
+## v1.34.0 Features
+
+  - [Global Learnings Store](#89-global-learnings-store)
+  - [Queryable Codebase Intelligence](#90-queryable-codebase-intelligence)
+  - [Execution Context Profiles](#91-execution-context-profiles)
+  - [Gates Taxonomy](#92-gates-taxonomy)
+  - [Code Review Pipeline](#93-code-review-pipeline)
+  - [Socratic Exploration](#94-socratic-exploration)
+  - [Safe Undo](#95-safe-undo)
+  - [Plan Import](#96-plan-import)
+  - [Rapid Codebase Scan](#97-rapid-codebase-scan)
+  - [Autonomous Audit-to-Fix](#98-autonomous-audit-to-fix)
+  - [Improved Prompt Injection Scanner](#99-improved-prompt-injection-scanner)
+  - [Stall Detection in Plan-Phase](#100-stall-detection-in-plan-phase)
+  - [Hard Stop Safety Gates in /gsd-next](#101-hard-stop-safety-gates-in-gsd-next)
+  - [Adaptive Model Preset](#102-adaptive-model-preset)
+  - [Post-Merge Hunk Verification](#103-post-merge-hunk-verification)
+
+---
+
+### 89. Global Learnings Store
+
+**Commands:** Auto-triggered at phase completion; consumed by planner
+**Config:** `features.global_learnings`
+
+**Purpose:** Persist cross-session, cross-project learnings in a global store so the planner agent can learn from patterns across the entire project history — not just the current session.
+
+**Requirements:**
+- REQ-LEARN-01: Learnings MUST be auto-copied from `.planning/` to the global store at phase completion
+- REQ-LEARN-02: The planner agent MUST receive relevant learnings at spawn time via injection
+- REQ-LEARN-03: Injection MUST be capped by `learnings.max_inject` to avoid context bloat
+- REQ-LEARN-04: Feature MUST be opt-in via `features.global_learnings: true`
+
+**Config:**
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `features.global_learnings` | boolean | `false` | Enable cross-project learnings pipeline |
+| `learnings.max_inject` | number | (system default) | Maximum learnings entries injected into planner |
+
+---
+
+### 90. Queryable Codebase Intelligence
+
+**Command:** `/gsd-intel [query <term>|status|diff|refresh]`
+**Config:** `intel.enabled`
+
+**Purpose:** Maintain a queryable JSON index of codebase structure, API surface, dependency graph, file roles, and architecture decisions in `.planning/intel/`. Enables targeted lookups without reading the entire codebase.
+
+**Requirements:**
+- REQ-INTEL-01: Intel files MUST be stored as JSON in `.planning/intel/`
+- REQ-INTEL-02: `query` mode MUST search across all intel files for a term and group results by file
+- REQ-INTEL-03: `status` mode MUST report freshness (FRESH/STALE, stale threshold: 24 hours)
+- REQ-INTEL-04: `diff` mode MUST compare current intel state to the last snapshot
+- REQ-INTEL-05: `refresh` mode MUST spawn the intel-updater agent to rebuild all files
+- REQ-INTEL-06: Feature MUST be opt-in via `intel.enabled: true`
+
+**Intel files produced:**
+| File | Contents |
+|------|----------|
+| `stack.json` | Technology stack and dependencies |
+| `api-map.json` | Exported functions and API surface |
+| `dependency-graph.json` | Inter-module dependency relationships |
+| `file-roles.json` | Role classification for each source file |
+| `arch-decisions.json` | Detected architecture decisions |
+
+---
+
+### 91. Execution Context Profiles
+
+**Config:** `context_profile`
+
+**Purpose:** Select a pre-configured execution context (mode, model, workflow settings) tuned for a specific type of work without manually adjusting individual settings.
+
+**Requirements:**
+- REQ-CTX-01: `dev` profile MUST optimize for iterative development (balanced model, plan_check enabled)
+- REQ-CTX-02: `research` profile MUST optimize for research-heavy work (higher model tier, research enabled)
+- REQ-CTX-03: `review` profile MUST optimize for code review work (verifier and code_review enabled)
+
+**Available profiles:** `dev`, `research`, `review`
+
+**Config:**
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `context_profile` | string | (none) | Execution context preset: `dev`, `research`, or `review` |
+
+---
+
+### 92. Gates Taxonomy
+
+**References:** `get-shit-done/references/gates.md`
+**Agents:** plan-checker, verifier
+
+**Purpose:** Define 4 canonical gate types that structure all workflow decision points, enabling plan-checker and verifier agents to apply consistent gate logic.
+
+**Gate types:**
+| Type | Description |
+|------|-------------|
+| **Confirm** | User approves before proceeding (e.g., roadmap review) |
+| **Quality** | Automated quality check must pass (e.g., plan verification loop) |
+| **Safety** | Hard stop on detected risk or policy violation |
+| **Transition** | Phase or milestone boundary acknowledgment |
+
+**Requirements:**
+- REQ-GATES-01: plan-checker MUST classify each checkpoint as one of the 4 gate types
+- REQ-GATES-02: verifier MUST apply gate logic appropriate to the gate type
+- REQ-GATES-03: Hard stop safety gates MUST never be bypassed by `--auto` flags
+
+---
+
+### 93. Code Review Pipeline
+
+**Commands:** `/gsd-code-review`, `/gsd-code-review-fix`
+
+**Purpose:** Structured review of source files changed during a phase, with a separate auto-fix pass that commits each fix atomically.
+
+**Requirements:**
+- REQ-REVIEW-01: `gsd-code-review` MUST scope files to the phase using SUMMARY.md and git diff fallback
+- REQ-REVIEW-02: Review MUST support three depth levels: `quick`, `standard`, `deep`
+- REQ-REVIEW-03: Findings MUST be severity-classified: Critical, Warning, Info
+- REQ-REVIEW-04: `gsd-code-review-fix` MUST read REVIEW.md and fix Critical + Warning findings by default
+- REQ-REVIEW-05: Each fix MUST be committed atomically with a descriptive message
+- REQ-REVIEW-06: `--auto` flag MUST enable fix + re-review iteration loop, capped at 3 iterations
+- REQ-REVIEW-07: Feature MUST be gated by `workflow.code_review` config flag
+
+**Config:**
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `workflow.code_review` | boolean | `true` | Enable code review commands |
+| `workflow.code_review_depth` | string | `standard` | Default review depth: `quick`, `standard`, or `deep` |
+
+---
+
+### 94. Socratic Exploration
+
+**Command:** `/gsd-explore [topic]`
+
+**Purpose:** Guide a developer through exploring an idea via Socratic probing questions before committing to a plan. Routes outputs to the appropriate GSD artifact: notes, todos, seeds, research questions, requirements updates, or a new phase.
+
+**Requirements:**
+- REQ-EXPLORE-01: Exploration MUST use Socratic probing — ask questions before proposing solutions
+- REQ-EXPLORE-02: Session MUST offer to route outputs to the appropriate GSD artifact
+- REQ-EXPLORE-03: An optional topic argument MUST prime the first question
+- REQ-EXPLORE-04: Exploration MUST optionally spawn a research agent for technical feasibility
+
+---
+
+### 95. Safe Undo
+
+**Command:** `/gsd-undo --last N | --phase NN | --plan NN-MM`
+
+**Purpose:** Roll back GSD phase or plan commits safely using the phase manifest and git log, with dependency checks and a hard confirmation gate before any revert is applied.
+
+**Requirements:**
+- REQ-UNDO-01: `--phase` mode MUST identify all commits for the phase via manifest and git log fallback
+- REQ-UNDO-02: `--plan` mode MUST identify all commits for a specific plan
+- REQ-UNDO-03: `--last N` mode MUST display recent GSD commits for interactive selection
+- REQ-UNDO-04: System MUST check for dependent phases/plans before reverting
+- REQ-UNDO-05: A confirmation gate MUST be shown before any git revert is executed
+
+---
+
+### 96. Plan Import
+
+**Command:** `/gsd-import --from <filepath>`
+
+**Purpose:** Ingest an external plan file into the GSD planning system with conflict detection against `PROJECT.md` decisions, converting it to a valid GSD PLAN.md and validating it through the plan-checker.
+
+**Requirements:**
+- REQ-IMPORT-01: Importer MUST detect conflicts between the external plan and existing PROJECT.md decisions
+- REQ-IMPORT-02: All detected conflicts MUST be presented to the user for resolution before writing
+- REQ-IMPORT-03: Imported plan MUST be written as a valid GSD PLAN.md format
+- REQ-IMPORT-04: Written plan MUST pass `gsd-plan-checker` validation
+
+---
+
+### 97. Rapid Codebase Scan
+
+**Command:** `/gsd-scan [--focus tech|arch|quality|concerns|tech+arch]`
+
+**Purpose:** Lightweight alternative to `/gsd-map-codebase` that spawns a single mapper agent for a specific focus area, producing targeted output in `.planning/codebase/` without the overhead of 4 parallel agents.
+
+**Requirements:**
+- REQ-SCAN-01: Scan MUST spawn exactly one mapper agent (not four parallel agents)
+- REQ-SCAN-02: Focus area MUST be one of: `tech`, `arch`, `quality`, `concerns`, `tech+arch` (default)
+- REQ-SCAN-03: Output MUST be written to `.planning/codebase/` in the same format as `/gsd-map-codebase`
+
+---
+
+### 98. Autonomous Audit-to-Fix
+
+**Command:** `/gsd-audit-fix [--source <audit>] [--severity high|medium|all] [--max N] [--dry-run]`
+
+**Purpose:** End-to-end pipeline that runs an audit, classifies findings as auto-fixable vs. manual-only, then autonomously fixes auto-fixable issues with test verification and atomic commits.
+
+**Requirements:**
+- REQ-AUDITFIX-01: Findings MUST be classified as auto-fixable or manual-only before any changes
+- REQ-AUDITFIX-02: Each fix MUST be verified with tests before committing
+- REQ-AUDITFIX-03: Each fix MUST be committed atomically
+- REQ-AUDITFIX-04: `--dry-run` MUST show classification table without applying any fixes
+- REQ-AUDITFIX-05: `--max N` MUST limit the number of fixes applied in one run (default: 5)
+
+---
+
+### 99. Improved Prompt Injection Scanner
+
+**Hook:** `gsd-prompt-guard.js`
+**Script:** `scripts/prompt-injection-scan.sh`
+
+**Purpose:** Enhanced detection of prompt injection attempts in planning artifacts, adding invisible Unicode character detection, encoding obfuscation patterns, and entropy-based analysis.
+
+**Requirements:**
+- REQ-SCAN-INJ-01: Scanner MUST detect invisible Unicode characters (zero-width spaces, soft hyphens, etc.)
+- REQ-SCAN-INJ-02: Scanner MUST detect encoding obfuscation patterns (base64-encoded instructions, homoglyphs)
+- REQ-SCAN-INJ-03: Scanner MUST apply entropy analysis to flag high-entropy strings in unexpected positions
+- REQ-SCAN-INJ-04: Scanner MUST remain advisory-only — detection is logged, not blocking
+
+---
+
+### 100. Stall Detection in Plan-Phase
+
+**Command:** `/gsd-plan-phase`
+
+**Purpose:** Detect when the planner revision loop has stalled — producing the same output across multiple iterations — and break the cycle by escalating to a different strategy or exiting with a clear diagnostic.
+
+**Requirements:**
+- REQ-STALL-01: Revision loop MUST detect identical plan output across consecutive iterations
+- REQ-STALL-02: On stall detection, system MUST escalate strategy before retrying
+- REQ-STALL-03: Maximum stall retries MUST be bounded (capped at the existing max 3 iterations)
+
+---
+
+### 101. Hard Stop Safety Gates in /gsd-next
+
+**Command:** `/gsd-next`
+
+**Purpose:** Prevent `/gsd-next` from entering runaway loops by adding hard stop safety gates and a consecutive-call guard that interrupts autonomous chaining when repeated identical steps are detected.
+
+**Requirements:**
+- REQ-NEXT-GATE-01: `/gsd-next` MUST track consecutive same-step calls
+- REQ-NEXT-GATE-02: On repeated same-step, system MUST present a hard stop gate to the user
+- REQ-NEXT-GATE-03: User MUST explicitly confirm to continue past a hard stop gate
+
+---
+
+### 102. Adaptive Model Preset
+
+**Config:** `model_profile: "adaptive"`
+
+**Purpose:** Role-based model assignment that automatically selects the appropriate model tier based on the current agent's role, rather than applying a single tier to all agents.
+
+**Requirements:**
+- REQ-ADAPTIVE-01: `adaptive` preset MUST assign model tiers based on agent role (planner → quality tier, executor → balanced tier, etc.)
+- REQ-ADAPTIVE-02: `adaptive` MUST be selectable via `/gsd-set-profile adaptive`
+
+---
+
+### 103. Post-Merge Hunk Verification
+
+**Command:** `/gsd-reapply-patches`
+
+**Purpose:** After applying local patches post-update, verify that all hunks were actually applied by comparing the expected patch content against the live filesystem. Surface any dropped or partial hunks immediately rather than silently accepting incomplete merges.
+
+**Requirements:**
+- REQ-PATCH-VERIFY-01: Reapply-patches MUST verify each hunk was applied after the merge
+- REQ-PATCH-VERIFY-02: Dropped or partial hunks MUST be reported to the user with file and line context
+- REQ-PATCH-VERIFY-03: Verification MUST run after all patches are applied, not per-patch
--- a/docs/USER-GUIDE.md
+++ b/docs/USER-GUIDE.md
@@ -387,6 +387,87 @@ The `security.cjs` module scans for known injection patterns (role overrides, in

 ---

+## Code Review Workflow
+
+### Phase Code Review
+
+After executing a phase, run a structured code review before UAT:
+
+```bash
+/gsd-code-review 3               # Review all changed files in phase 3
+/gsd-code-review 3 --depth=deep  # Deep cross-file review (import graphs, call chains)
+```
+
+The reviewer scopes files automatically using SUMMARY.md (preferred) or git diff fallback. Findings are classified as Critical, Warning, or Info in `{phase}-REVIEW.md`.
+
+```bash
+/gsd-code-review-fix 3           # Fix Critical + Warning findings atomically
+/gsd-code-review-fix 3 --auto    # Fix and re-review until clean (max 3 iterations)
+```
+
+### Autonomous Audit-to-Fix
+
+To run an audit and fix all auto-fixable issues in one pass:
+
+```bash
+/gsd-audit-fix                   # Audit + classify + fix (medium+ severity, max 5)
+/gsd-audit-fix --dry-run         # Preview classification without fixing
+```
+
+### Code Review in the Full Phase Lifecycle
+
+The review step slots in after execution and before UAT:
+
+```
+/gsd-execute-phase N   ->  /gsd-code-review N  ->  /gsd-code-review-fix N  ->  /gsd-verify-work N
+```
+
+---
+
+## Exploration & Discovery
+
+### Socratic Exploration
+
+Before committing to a new phase or plan, use `/gsd-explore` to think through the idea:
+
+```bash
+/gsd-explore                           # Open-ended ideation
+/gsd-explore "caching strategy"        # Explore a specific topic
+```
+
+The exploration session guides you through probing questions, optionally spawns a research agent, and routes output to the appropriate GSD artifact: note, todo, seed, research question, requirements update, or new phase.
+
+### Codebase Intelligence
+
+For queryable codebase insights without reading the entire codebase, enable the intel system:
+
+```json
+{ "intel": { "enabled": true } }
+```
+
+Then build the index:
+
+```bash
+/gsd-intel refresh             # Analyze codebase and write .planning/intel/ files
+/gsd-intel query auth          # Search for a term across all intel files
+/gsd-intel status              # Check freshness of intel files
+/gsd-intel diff                # See what changed since last snapshot
+```
+
+Intel files cover stack, API surface, dependency graph, file roles, and architecture decisions.
+
+### Quick Scan
+
+For a focused assessment without full `/gsd-map-codebase` overhead:
+
+```bash
+/gsd-scan                      # Quick tech + arch overview
+/gsd-scan --focus quality      # Quality and code health only
+/gsd-scan --focus concerns     # Risk areas and concerns
+```
+
+---
+
 ## Command Reference

 ### Core Workflow
@@ -436,9 +517,14 @@ The `security.cjs` module scans for known injection patterns (role overrides, in

 | Command | Purpose | When to Use |
 |---------|---------|-------------|
-| `/gsd-map-codebase` | Analyze existing codebase | Before `/gsd-new-project` on existing code |
+| `/gsd-map-codebase` | Analyze existing codebase (4 parallel agents) | Before `/gsd-new-project` on existing code |
+| `/gsd-scan [--focus area]` | Rapid single-focus codebase scan (1 agent) | Quick assessment of a specific area |
+| `/gsd-intel [query\|status\|diff\|refresh]` | Query codebase intelligence index | Look up APIs, deps, or architecture decisions |
+| `/gsd-explore [topic]` | Socratic ideation — think through an idea before committing | Exploring unfamiliar solution space |
 | `/gsd-quick` | Ad-hoc task with GSD guarantees | Bug fixes, small features, config changes |
 | `/gsd-autonomous` | Run remaining phases autonomously (`--from N`, `--to N`) | Hands-free multi-phase execution |
+| `/gsd-undo --last N\|--phase NN\|--plan NN-MM` | Safe git revert using phase manifest | Roll back a bad execution |
+| `/gsd-import --from <file>` | Ingest external plan with conflict detection | Import plans from teammates or other tools |
 | `/gsd-debug [desc]` | Systematic debugging with persistent state (`--diagnose` for no-fix mode) | When something breaks |
 | `/gsd-forensics` | Diagnostic report for workflow failures | When state, artifacts, or git history seem corrupted |
 | `/gsd-add-todo [desc]` | Capture an idea for later | Think of something during a session |
@@ -452,6 +538,9 @@ The `security.cjs` module scans for known injection patterns (role overrides, in
 | Command | Purpose | When to Use |
 |---------|---------|-------------|
 | `/gsd-review --phase N` | Cross-AI peer review from external CLIs | Before executing, to validate plans |
+| `/gsd-code-review <N>` | Review source files changed in a phase for bugs and security issues | After execution, before verification |
+| `/gsd-code-review-fix <N>` | Auto-fix issues found by `/gsd-code-review` | After code review produces REVIEW.md |
+| `/gsd-audit-fix` | Autonomous audit-to-fix pipeline with classification and atomic commits | After UAT surfaces fixable issues |
 | `/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 |