docs: fill documentation gaps from v1.32.0 audit

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-04 08:54:14 -04:00
parent 2c36244f08
commit c8d7ab3501
6 changed files with 143 additions and 5 deletions
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -287,6 +287,7 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 - PASS/FAIL with specific evidence
 - Logs issues for `/gsd-verify-work` to address
 - Milestone scope filtering: gaps addressed in later phases are marked as "deferred", not reported as failures (v1.32)
+- **Test quality audit** (v1.32): verifies that tests prove what they claim by checking for disabled/skipped tests on requirements, circular test patterns (system generating its own expected values), assertion strength (existence vs. value vs. behavioral), and expected value provenance. Blockers from test quality audit override an otherwise passing verification

 ---

--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -148,6 +148,16 @@ Shared knowledge documents that workflows and agents `@-reference`:
 - `tdd.md` — Test-driven development integration patterns
 - `ui-brand.md` — Visual output formatting patterns

+### Modular Planner Decomposition
+
+The planner agent (`agents/gsd-planner.md`) was decomposed from a single monolithic file into a core agent plus reference modules to stay under the 50K character limit imposed by some runtimes. The planner now `@-references` specialized modules:
+
+- `planner-gap-closure.md` — Gap closure mode behavior (reads VERIFICATION.md, targeted replanning)
+- `planner-reviews.md` — Cross-AI review integration (reads REVIEWS.md from `/gsd-review`)
+- `planner-revision.md` — Plan revision patterns for iterative refinement
+
+This keeps the base planner prompt under the character budget while preserving full functionality through on-demand reference loading.
+
 ### Templates (`get-shit-done/templates/`)

 Markdown templates for all planning artifacts. Used by `gsd-tools.cjs template fill` and `scaffold` commands to create pre-structured files:
@@ -249,11 +259,20 @@ Wave Analysis:
 ```

 Each executor gets:
- Fresh 200K context window
+- Fresh 200K context window (or up to 1M for models that support it)
 - The specific PLAN.md to execute
 - Project context (PROJECT.md, STATE.md)
 - Phase context (CONTEXT.md, RESEARCH.md if available)

+### Adaptive Context Enrichment (1M Models)
+
+When the context window is 500K+ tokens (1M-class models like Opus 4.6, Sonnet 4.6), subagent prompts are automatically enriched with additional context that would not fit in standard 200K windows:
+
+- **Executor agents** receive prior wave SUMMARY.md files and the phase CONTEXT.md/RESEARCH.md, enabling cross-plan awareness within a phase
+- **Verifier agents** receive all PLAN.md, SUMMARY.md, CONTEXT.md files plus REQUIREMENTS.md, enabling history-aware verification
+
+The orchestrator reads `context_window` from config (`gsd-tools.cjs config-get context_window`) and conditionally includes richer context when the value is >= 500,000. For standard 200K windows, prompts use truncated versions with cache-friendly ordering to maximize context efficiency.
+
 #### Parallel Commit Safety

 When multiple executors run within the same wave, two mechanisms prevent conflicts:
--- a/docs/COMMANDS.md
+++ b/docs/COMMANDS.md
@@ -506,11 +506,28 @@ Interactive command center for managing multiple phases from one terminal.
 - Recommends optimal next actions based on dependencies and progress
 - Dispatches work: discuss runs inline, plan/execute run as background agents
 - Designed for power users parallelizing work across phases from one terminal
+- Supports per-step passthrough flags via `manager.flags` config (see [Configuration](CONFIGURATION.md#manager-passthrough-flags))

 ```bash
 /gsd-manager                        # Open command center dashboard
 ```

+**Manager Passthrough Flags:**
+
+Configure per-step flags in `.planning/config.json` under `manager.flags`. These flags are appended to each dispatched command:
+
+```json
+{
+  "manager": {
+    "flags": {
+      "discuss": "--auto",
+      "plan": "--skip-research",
+      "execute": "--validate"
+    }
+  }
+}
+```
+
 ---

 ### `/gsd-help`
@@ -847,6 +864,7 @@ Cross-AI peer review of phase plans from external AI CLIs.
 | `--claude` | Include Claude CLI review (separate session) |
 | `--codex` | Include Codex CLI review |
 | `--coderabbit` | Include CodeRabbit review |
+| `--opencode` | Include OpenCode review (via GitHub Copilot) |
 | `--all` | Include all available CLIs |

 **Produces:** `{phase}-REVIEWS.md` — consumable by `/gsd-plan-phase --reviews`
@@ -1011,6 +1029,23 @@ node gsd-tools.cjs state planned-phase --phase 3 --plans 2

 ## Community Commands

+### Community Hooks
+
+Optional git and session hooks gated behind `hooks.community: true` in `.planning/config.json`. All are no-ops unless explicitly enabled.
+
+| Hook | Purpose |
+|------|---------|
+| `gsd-validate-commit.sh` | Enforce Conventional Commits format on git commit messages |
+| `gsd-session-state.sh` | Track session state transitions |
+| `gsd-phase-boundary.sh` | Enforce phase boundary checks |
+
+Enable with:
+```json
+{ "hooks": { "community": true } }
+```
+
+---
+
 ### `/gsd-join-discord`

 Open Discord community invite.
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -328,6 +328,34 @@ Settings for the security enforcement feature (v1.31). All follow the **absent =

 ---

+## Manager Passthrough Flags
+
+Configure per-step flags that `/gsd-manager` appends to each dispatched command. This allows customizing how the manager runs discuss, plan, and execute steps without manual flag entry.
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `manager.flags.discuss` | string | (none) | Flags appended to discuss-phase commands (e.g., `"--auto"`) |
+| `manager.flags.plan` | string | (none) | Flags appended to plan-phase commands (e.g., `"--skip-research"`) |
+| `manager.flags.execute` | string | (none) | Flags appended to execute-phase commands (e.g., `"--validate"`) |
+
+**Example:**
+
+```json
+{
+  "manager": {
+    "flags": {
+      "discuss": "--auto",
+      "plan": "--skip-research",
+      "execute": "--validate"
+    }
+  }
+}
+```
+
+Invalid flag tokens are sanitized and logged as warnings. Only recognized GSD flags are passed through.
+
+---
+
 ## Model Profiles

 ### Profile Definitions
--- a/docs/FEATURES.md
+++ b/docs/FEATURES.md
@@ -104,6 +104,9 @@
  - [Response Language Config](#83-response-language-config)
  - [Manual Update Procedure](#84-manual-update-procedure)
  - [New Runtime Support (Trae, Cline, Augment Code)](#85-new-runtime-support-trae-cline-augment-code)
+  - [Autonomous `--interactive` Flag](#86-autonomous---interactive-flag)
+  - [Commit-Docs Guard Hook](#87-commit-docs-guard-hook)
+  - [Community Hooks Opt-In](#88-community-hooks-opt-in)

 ---

@@ -1840,3 +1843,54 @@ Test suite that scans all agent, workflow, and command files for embedded inject
 - REQ-TRAE-01: Installer MUST support `--trae` flag for Trae IDE installation
 - REQ-CLINE-01: Installer MUST support Cline via `.clinerules` configuration
 - REQ-AUGMENT-01: Installer MUST support Augment Code with skill conversion and config management
+
+---
+
+### 86. Autonomous `--interactive` Flag
+
+**Flag:** `/gsd-autonomous --interactive`
+
+**Purpose:** Lean-context autonomous mode that keeps discuss-phase interactive (user answers questions) while dispatching plan and execute as background agents.
+
+**Requirements:**
+- REQ-INTERACT-01: `--interactive` MUST run discuss-phase inline with interactive questions (not auto-answered)
+- REQ-INTERACT-02: `--interactive` MUST dispatch plan-phase and execute-phase as background agents for context isolation
+- REQ-INTERACT-03: `--interactive` MUST enable pipeline parallelism — discuss Phase N+1 while Phase N builds
+- REQ-INTERACT-04: Main context MUST only accumulate discuss conversations (lean context)
+
+**Process:**
+1. **Discuss inline** — Run discuss-phase in the main context with user interaction
+2. **Dispatch** — Send plan and execute to background agents with fresh context windows
+3. **Pipeline** — While background agents build Phase N, begin discussing Phase N+1
+
+---
+
+### 87. Commit-Docs Guard Hook
+
+**Hook:** `gsd-commit-docs.js`
+
+**Purpose:** PreToolUse hook that enforces the `commit_docs` configuration, preventing `.planning/` files from being committed when `planning.commit_docs` is `false`.
+
+**Requirements:**
+- REQ-COMMITDOCS-01: Hook MUST intercept git commit commands that stage `.planning/` files
+- REQ-COMMITDOCS-02: Hook MUST block commits containing `.planning/` files when `commit_docs` is `false`
+- REQ-COMMITDOCS-03: Hook MUST be advisory — does not block when `commit_docs` is `true` or absent
+
+---
+
+### 88. Community Hooks Opt-In
+
+**Hooks:** `gsd-validate-commit.sh`, `gsd-session-state.sh`, `gsd-phase-boundary.sh`
+
+**Purpose:** Optional git and session hooks for GSD projects, gated behind `hooks.community: true` in config.
+
+**Requirements:**
+- REQ-COMMUNITY-01: All community hooks MUST be no-ops unless `hooks.community` is `true` in `.planning/config.json`
+- REQ-COMMUNITY-02: `gsd-validate-commit.sh` MUST enforce Conventional Commits format on git commit messages
+- REQ-COMMUNITY-03: `gsd-session-state.sh` MUST track session state transitions
+- REQ-COMMUNITY-04: `gsd-phase-boundary.sh` MUST enforce phase boundary checks
+
+**Config:**
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `hooks.community` | boolean | `false` | Enable optional community hooks for commit validation, session state, and phase boundaries |
--- a/docs/USER-GUIDE.md
+++ b/docs/USER-GUIDE.md
@@ -363,10 +363,11 @@ The `security.cjs` module scans for known injection patterns (role overrides, in
         │     └── Executor C (fresh 200K context) -> commit
         │
         └── Verifier
-               └── Check codebase against phase goals
-                     │
-                     ├── PASS -> VERIFICATION.md (success)
-                     └── FAIL -> Issues logged for /gsd-verify-work
+               ├── Check codebase against phase goals
+               ├── Test quality audit (disabled tests, circular patterns, assertion strength)
+               │
+               ├── PASS -> VERIFICATION.md (success)
+               └── FAIL -> Issues logged for /gsd-verify-work
 ```

 ### Brownfield Workflow (Existing Codebase)