docs: update documentation for v1.31.0 release

- CHANGELOG.md: 13 added, 1 changed, 21 fixed entries - README.md: quick mode flags, --chain, security/schema features, commands table - docs/FEATURES.md: v1.29-v1.31 feature sections (#56-#68) - docs/CONFIGURATION.md: 5 new config options, Security Settings section - Localized READMEs: ja-JP, ko-KR, zh-CN, pt-BR synced with English changes Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-01 18:17:26 -04:00
parent 8de750e855
commit 94a8005f97
8 changed files with 391 additions and 26 deletions
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -33,7 +33,8 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd:new
    "research_before_questions": false,
    "discuss_mode": "discuss",
    "skip_discuss": false,
-    "text_mode": false
+    "text_mode": false,
+    "use_worktrees": true
  },
  "hooks": {
    "context_warnings": true,
@@ -67,6 +68,10 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd:new
    "always_confirm_destructive": true,
    "always_confirm_external_services": true
  },
+  "project_code": null,
+  "security_enforcement": true,
+  "security_asvs_level": 1,
+  "security_block_on": "high",
  "agent_skills": {}
 }
 ```
@@ -80,6 +85,7 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd:new
 | `mode` | enum | `interactive`, `yolo` | `interactive` | `yolo` auto-approves decisions; `interactive` confirms at each step |
 | `granularity` | enum | `coarse`, `standard`, `fine` | `standard` | Controls phase count: `coarse` (3-5), `standard` (5-8), `fine` (8-12) |
 | `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 |

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

@@ -104,6 +110,7 @@ All workflow toggles follow the **absent = enabled** pattern. If a key is missin
 | `workflow.discuss_mode` | string | `'discuss'` | Controls how `/gsd:discuss-phase` gathers context. `'discuss'` (default) asks questions one-by-one. `'assumptions'` reads the codebase first, generates structured assumptions with confidence levels, and only asks you to correct what's wrong. Added in v1.28 |
 | `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 |

 ### Recommended Presets

@@ -299,6 +306,18 @@ Control confirmation prompts during workflows.

 ---

+## Security Settings
+
+Settings for the security enforcement feature (v1.31). All follow the **absent = enabled** pattern.
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `security_enforcement` | boolean | `true` | Enable threat-model-anchored security verification via `/gsd:secure-phase`. When `false`, security checks are skipped entirely |
+| `security_asvs_level` | number (1-3) | `1` | OWASP ASVS verification level. Level 1 = opportunistic, Level 2 = standard, Level 3 = comprehensive |
+| `security_block_on` | string | `"high"` | Minimum severity that blocks phase advancement. Options: `"high"`, `"medium"`, `"low"` |
+
+---
+
 ## Hook Settings

 | Setting | Type | Default | Description |
@@ -397,6 +416,7 @@ The intent is the same as the Claude profile tiers -- use a stronger model for p
 | `CLAUDE_CONFIG_DIR` | Override default config directory (`~/.claude/`) |
 | `GEMINI_API_KEY` | Detected by context monitor to switch hook event name |
 | `WSL_DISTRO_NAME` | Detected by installer for WSL path handling |
+| `GSD_SKIP_SCHEMA_CHECK` | Skip schema drift detection during execute-phase (v1.31) |

 ---

--- a/docs/FEATURES.md
+++ b/docs/FEATURES.md
@@ -70,6 +70,22 @@
  - [Assumptions Discussion Mode](#53-assumptions-discussion-mode)
  - [UI Phase Auto-Detection](#54-ui-phase-auto-detection)
  - [Multi-Runtime Installer Selection](#55-multi-runtime-installer-selection)
+- [v1.29 Features](#v129-features)
+  - [Windsurf Runtime Support](#56-windsurf-runtime-support)
+  - [Internationalized Documentation](#57-internationalized-documentation)
+- [v1.30 Features](#v130-features)
+  - [GSD SDK](#58-gsd-sdk)
+- [v1.31 Features](#v131-features)
+  - [Schema Drift Detection](#59-schema-drift-detection)
+  - [Security Enforcement](#60-security-enforcement)
+  - [Documentation Generation](#61-documentation-generation)
+  - [Discuss Chain Mode](#62-discuss-chain-mode)
+  - [Single-Phase Autonomous](#63-single-phase-autonomous)
+  - [Scope Reduction Detection](#64-scope-reduction-detection)
+  - [Claim Provenance Tagging](#65-claim-provenance-tagging)
+  - [Worktree Toggle](#66-worktree-toggle)
+  - [Project Code Prefixing](#67-project-code-prefixing)
+  - [Claude Code Skills Migration](#68-claude-code-skills-migration)

 ---

@@ -1288,3 +1304,264 @@ Test suite that scans all agent, workflow, and command files for embedded inject
 1. **Detect** — Identify available AI CLI runtimes on the system
 2. **Prompt** — Present multi-select interface for runtime selection
 3. **Install** — Configure GSD for all selected runtimes in a single session
+
+---
+
+## v1.29 Features
+
+### 56. Windsurf Runtime Support
+
+**Part of:** `npx get-shit-done-cc`
+
+**Purpose:** Add Windsurf as a supported AI CLI runtime for GSD installation and execution.
+
+**Requirements:**
+- REQ-WINDSURF-01: Installer MUST detect Windsurf runtime and offer it as a target
+- REQ-WINDSURF-02: GSD commands MUST function correctly within Windsurf sessions
+
+**Process:**
+1. **Detect** — Identify Windsurf runtime availability on the system
+2. **Install** — Configure GSD skills and hooks for the Windsurf environment
+
+---
+
+### 57. Internationalized Documentation
+
+**Part of:** `docs/`
+
+**Purpose:** Provide GSD documentation in Portuguese, Korean, and Japanese.
+
+**Requirements:**
+- REQ-I18N-01: Documentation MUST be available in Portuguese (pt), Korean (ko), and Japanese (ja)
+- REQ-I18N-02: Translations MUST stay synchronized with English source documents
+
+**Process:**
+1. **Translate** — Convert core documentation into target languages
+2. **Publish** — Make translated documentation accessible alongside English originals
+
+---
+
+## v1.30 Features
+
+### 58. GSD SDK
+
+**Command:** Programmatic API (headless)
+
+**Purpose:** Headless TypeScript SDK for running GSD workflows programmatically without a CLI session.
+
+**Requirements:**
+- REQ-SDK-01: SDK MUST expose GSD workflow operations as TypeScript functions
+- REQ-SDK-02: SDK MUST support headless execution without interactive prompts
+- REQ-SDK-03: SDK MUST produce the same artifacts as CLI-driven workflows
+
+**Process:**
+1. **Import** — Import GSD SDK into a TypeScript/JavaScript project
+2. **Configure** — Set project path and workflow options programmatically
+3. **Execute** — Run GSD phases (discuss, plan, execute) via API calls
+
+---
+
+## v1.31 Features
+
+### 59. Schema Drift Detection
+
+**Command:** Automatic during `/gsd:execute-phase`
+
+**Purpose:** Detect when ORM schema files are modified without corresponding migration or push commands, preventing false-positive verification.
+
+**Requirements:**
+- REQ-SCHEMA-01: System MUST detect modifications to ORM schema files (Prisma, Drizzle, Payload, Sanity, Mongoose)
+- REQ-SCHEMA-02: System MUST verify corresponding migration/push commands exist when schema changes are detected
+- REQ-SCHEMA-03: System MUST implement two-layer defense: plan-time injection and execute-time gate
+- REQ-SCHEMA-04: System MUST support `GSD_SKIP_SCHEMA_CHECK` env var to override detection
+- REQ-SCHEMA-05: System MUST prevent false-positive verification when schema is modified without migration
+
+**Process:**
+1. **Detect** — Monitor ORM schema file modifications during plan execution
+2. **Verify** — Check that corresponding migration/push commands are present in the plan
+3. **Gate** — Block execution if schema drift is detected without migration (execute-time gate)
+4. **Inject** — Add migration reminders during plan generation (plan-time injection)
+
+**Config:** `GSD_SKIP_SCHEMA_CHECK` environment variable to bypass detection.
+
+---
+
+### 60. Security Enforcement
+
+**Command:** `/gsd:secure-phase <N>`
+
+**Purpose:** Threat-model-anchored security verification for phase implementations.
+
+**Requirements:**
+- REQ-SEC-01: System MUST perform threat-model-anchored verification (not blind scanning)
+- REQ-SEC-02: System MUST support configurable OWASP ASVS verification levels (1-3)
+- REQ-SEC-03: System MUST block phase advancement based on configurable severity threshold
+- REQ-SEC-04: System MUST spawn `gsd-security-auditor` agent for analysis
+
+**Produces:**
+| Artifact | Description |
+|----------|-------------|
+| Security audit report | Threat-model-anchored findings with severity classification |
+
+**Process:**
+1. **Model** — Build threat model from phase implementation context
+2. **Audit** — Spawn `gsd-security-auditor` to verify against threat model
+3. **Gate** — Block phase advancement if findings meet or exceed `security_block_on` severity
+
+**Config:**
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `security_enforcement` | boolean | `true` | Enable threat-model security verification |
+| `security_asvs_level` | number (1-3) | `1` | OWASP ASVS verification level |
+| `security_block_on` | string | `"high"` | Minimum severity to block phase advancement |
+
+---
+
+### 61. Documentation Generation
+
+**Command:** `/gsd:docs-update`
+
+**Purpose:** Generate and verify project documentation with accuracy checks.
+
+**Requirements:**
+- REQ-DOCS-01: System MUST spawn `gsd-doc-writer` agent to generate documentation
+- REQ-DOCS-02: System MUST spawn `gsd-doc-verifier` agent to check accuracy
+- REQ-DOCS-03: System MUST verify generated documentation against actual implementation
+
+**Produces:**
+| Artifact | Description |
+|----------|-------------|
+| Updated project documentation | Generated and verified documentation files |
+
+**Process:**
+1. **Generate** — Spawn `gsd-doc-writer` to create or update documentation from implementation
+2. **Verify** — Spawn `gsd-doc-verifier` to check documentation accuracy against codebase
+3. **Output** — Produce verified documentation with accuracy annotations
+
+---
+
+### 62. Discuss Chain Mode
+
+**Flag:** `/gsd:discuss-phase <N> --chain`
+
+**Purpose:** Auto-chain discuss, plan, and execute phases in one flow to reduce manual command sequencing.
+
+**Requirements:**
+- REQ-CHAIN-01: System MUST auto-chain discuss → plan → execute when `--chain` flag is provided
+- REQ-CHAIN-02: System MUST respect all gate settings between chained phases
+- REQ-CHAIN-03: System MUST halt the chain if any phase fails
+
+**Process:**
+1. **Discuss** — Run discuss-phase to gather context
+2. **Plan** — Automatically invoke plan-phase with gathered context
+3. **Execute** — Automatically invoke execute-phase with generated plan
+
+---
+
+### 63. Single-Phase Autonomous
+
+**Flag:** `/gsd:autonomous --only N`
+
+**Purpose:** Execute just one phase autonomously instead of all remaining phases.
+
+**Requirements:**
+- REQ-ONLY-01: System MUST execute only the specified phase number when `--only N` is provided
+- REQ-ONLY-02: System MUST follow the same discuss → plan → execute flow as full autonomous mode
+- REQ-ONLY-03: System MUST stop after the specified phase completes
+
+**Process:**
+1. **Select** — Identify the target phase from `--only N` argument
+2. **Execute** — Run full autonomous flow (discuss → plan → execute) for that single phase
+3. **Stop** — Halt after the phase completes instead of advancing to the next
+
+---
+
+### 64. Scope Reduction Detection
+
+**Part of:** `/gsd:plan-phase`
+
+**Purpose:** Prevent silent requirement dropping during plan generation with three-layer defense.
+
+**Requirements:**
+- REQ-SCOPE-01: System MUST prohibit planners from reducing scope without explicit justification
+- REQ-SCOPE-02: System MUST have plan-checker verify requirement dimension coverage
+- REQ-SCOPE-03: System MUST have orchestrator recover dropped requirements and re-inject them
+- REQ-SCOPE-04: System MUST implement three-layer defense: planner prohibition, checker dimension, orchestrator recovery
+
+**Process:**
+1. **Prohibit** — Planner instructions explicitly forbid scope reduction
+2. **Check** — Plan-checker verifies all phase requirements are covered in the plan
+3. **Recover** — Orchestrator detects dropped requirements and re-injects them into the planning loop
+
+---
+
+### 65. Claim Provenance Tagging
+
+**Part of:** `/gsd:research-phase`
+
+**Purpose:** Ensure research claims are tagged with source evidence and assumptions are logged separately.
+
+**Requirements:**
+- REQ-PROVENANCE-01: Researcher MUST mark claims with source evidence references
+- REQ-PROVENANCE-02: Assumptions MUST be logged separately from sourced claims
+- REQ-PROVENANCE-03: System MUST distinguish between evidenced facts and inferred assumptions
+
+**Process:**
+1. **Research** — Researcher gathers information from codebase and domain sources
+2. **Tag** — Each claim is annotated with its source (file path, documentation, API response)
+3. **Separate** — Assumptions without direct evidence are logged in a distinct section
+
+---
+
+### 66. Worktree Toggle
+
+**Config:** `workflow.use_worktrees: false`
+
+**Purpose:** Disable git worktree isolation for users who prefer sequential execution.
+
+**Requirements:**
+- REQ-WORKTREE-01: System MUST respect `workflow.use_worktrees` setting when deciding isolation strategy
+- REQ-WORKTREE-02: System MUST default to `true` (worktrees enabled) for backward compatibility
+- REQ-WORKTREE-03: System MUST fall back to sequential execution when worktrees are disabled
+
+**Config:**
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `workflow.use_worktrees` | boolean | `true` | When `false`, disables git worktree isolation |
+
+---
+
+### 67. Project Code Prefixing
+
+**Config:** `project_code: "ABC"`
+
+**Purpose:** Prefix phase directory names with a project code for multi-project disambiguation.
+
+**Requirements:**
+- REQ-PREFIX-01: System MUST prefix phase directories with project code when configured (e.g., `ABC-01-setup/`)
+- REQ-PREFIX-02: System MUST use standard naming when `project_code` is not set
+- REQ-PREFIX-03: System MUST apply prefix consistently across all phase operations
+
+**Config:**
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `project_code` | string | (none) | Prefix for phase directory names |
+
+---
+
+### 68. Claude Code Skills Migration
+
+**Part of:** `npx get-shit-done-cc`
+
+**Purpose:** Migrate GSD commands to Claude Code 2.1.88+ skills format with backward compatibility.
+
+**Requirements:**
+- REQ-SKILLS-01: Installer MUST write `skills/gsd-*/SKILL.md` for Claude Code 2.1.88+
+- REQ-SKILLS-02: Installer MUST auto-clean legacy `commands/gsd/` directory
+- REQ-SKILLS-03: Installer MUST maintain backward compatibility with older Claude Code versions via Gemini path
+
+**Process:**
+1. **Detect** — Check Claude Code version to determine skills support
+2. **Migrate** — Write `skills/gsd-*/SKILL.md` files for each GSD command
+3. **Clean** — Remove legacy `commands/gsd/` directory if skills are installed
+4. **Fallback** — Maintain Gemini path compatibility for older Claude Code versions
--- a/docs/zh-CN/README.md
+++ b/docs/zh-CN/README.md
@@ -71,6 +71,8 @@ GSD 解决了这个问题。它是让 Claude Code 变得可靠的上下文工程

 想要描述需求然后正确构建出来的人 —— 不用假装自己在运营一个 50 人的工程组织。

+内置的质量门禁能捕获真正的问题：模式漂移检测会标记缺少迁移的 ORM 变更，安全强制将验证锚定到威胁模型，范围缩减检测防止规划器默默丢弃你的需求。
+
 ---

 ## 快速开始
@@ -344,7 +346,7 @@ claude --dangerously-skip-permissions

 循环 **讨论 → 规划 → 执行 → 验证** 直到里程碑完成。

-如果你想在讨论期间更快速地输入，使用 `/gsd:discuss-phase <n> --batch` 一次回答一组小问题，而不是一个一个来。
+如果你想在讨论期间更快速地输入，使用 `/gsd:discuss-phase <n> --batch` 一次回答一组小问题，而不是一个一个来。使用 `--chain` 可以自动链式执行从讨论到规划+执行，中间不停顿。

 每个阶段都会获得你的输入（讨论）、适当的研究（规划）、干净的执行（执行）和人工验证（验证）。上下文保持新鲜。质量保持高水平。

@@ -365,10 +367,18 @@ claude --dangerously-skip-permissions
 快速模式给你 GSD 保证（原子提交、状态跟踪）和更快的路径：

 - **相同代理** —— 规划者 + 执行者，相同质量
- **跳过可选步骤** —— 无研究、无计划检查器、无验证器
+- **跳过可选步骤** —— 默认无研究、无计划检查器、无验证器
 - **独立跟踪** —— 存放在 `.planning/quick/`，不是阶段

-用于：bug 修复、小功能、配置更改、一次性任务。
+**`--discuss` 标志：** 规划前的轻量讨论，发现灰色地带。
+
+**`--research` 标志：** 规划前启动聚焦研究员。调查实现方法、库选项和陷阱。当你不确定如何处理任务时使用。
+
+**`--full` 标志：** 启用所有阶段 —— 讨论 + 研究 + 计划检查 + 验证。快速任务形式的完整 GSD 管道。
+
+**`--validate` 标志：** 仅启用计划检查 + 执行后验证（之前 `--full` 的行为）。
+
+标志可组合：`--discuss --research --validate` 提供讨论 + 研究 + 计划检查 + 验证。

 ```
 /gsd:quick
@@ -469,7 +479,7 @@ lmn012o feat(08-02): 创建注册端点
 | 命令 | 作用 |
 |---------|--------------|
 | `/gsd:new-project [--auto]` | 完整初始化：提问 → 研究 → 需求 → 路线图 |
-| `/gsd:discuss-phase [N] [--auto]` | 在规划前捕获实现决策 |
+| `/gsd:discuss-phase [N] [--auto] [--chain]` | 在规划前捕获实现决策（`--chain` 自动链式执行规划+执行） |
 | `/gsd:plan-phase [N] [--auto]` | 阶段的研究 + 规划 + 验证 |
 | `/gsd:execute-phase <N>` | 在并行波次中执行所有计划，完成后验证 |
 | `/gsd:verify-work [N]` | 手动用户验收测试 ¹ |
@@ -518,7 +528,7 @@ lmn012o feat(08-02): 创建注册端点
 | `/gsd:add-todo [desc]` | 捕获想法留待后用 |
 | `/gsd:check-todos` | 列出待处理事项 |
 | `/gsd:debug [desc]` | 带持久状态的系统化调试 |
-| `/gsd:quick [--full] [--discuss]` | 用 GSD 保证执行临时任务（`--full` 添加计划检查和验证，`--discuss` 先收集上下文） |
+| `/gsd:quick [--full] [--discuss] [--research]` | 用 GSD 保证执行临时任务（`--full` 启用全部阶段，`--discuss` 先收集上下文，`--research` 规划前调查方法） |
 | `/gsd:health [--repair]` | 验证 `.planning/` 目录完整性，用 `--repair` 自动修复 |

 <sup>¹ 由 Reddit 用户 OracleGreyBeard 贡献</sup>