* docs: add context optimization design spec, implementation plan, and pi-layer research
- Spec: 6-change design for GSD extension context optimization
- Plan: 9-task TDD implementation plan with exact file paths and code
- Pi-layer doc: 10 infrastructure opportunities (research only, not planned)
Part of #3171, #3406, #3452, #3433.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(context): add observation masking for auto-mode sessions
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(context): add phase handoff anchors for auto-mode
Introduces PhaseAnchor read/write utilities so downstream agents can
inherit decisions, blockers, and intent written at phase boundaries
without re-inferring from conversation history.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(context): add capability-aware model routing and context management preferences
Implement ADR-004 Phase 2 capability scoring with 7-dimension model
profiles, task requirement vectors, and weighted scoring. Add
ContextManagementConfig preferences for observation masking thresholds.
Wire capability scoring into auto-model-selection dispatch path.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(context): wire observation masking, phase anchors, and tool truncation
Register observation masker in before_provider_request hook to replace
old tool results with placeholders during auto-mode. Add tool result
truncation (configurable via context_management.tool_result_max_chars).
Inject phase handoff anchors into prompt builders so downstream phases
inherit decisions from research/planning. Write anchors after successful
phase completion. Update ADR-004 status to Implemented.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* chore: remove internal planning artifacts from PR
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: add capability routing, observation masking, and context management
Update dynamic-model-routing.md with capability-aware scoring section.
Update token-optimization.md with observation masking, tool truncation,
and phase handoff anchor documentation. Update configuration.md with
context_management preference block and capability_routing flag.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Merge branch 'main' into feat/gsd-context-optimization
* fix: add context_management to known keys and prevent tool truncation state corruption
- Add missing 'context_management' to KNOWN_PREFERENCE_KEYS set so users
don't get spurious unknown-key warnings when configuring it.
- Replace in-place mutation of tool result content with immutable spread
to prevent corrupting shared conversation message objects.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: add stop and backtrack to triage-ui classification labels
The Classification type gained stop and backtrack variants from main
but triage-ui.ts was not updated, causing a TypeScript build failure.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: context masker and tool truncation operate on correct pi-ai message format
The observation masker and tool result truncation in before_provider_request
were checking m.type === "toolResult" but the actual pi-ai payload uses
m.role === "toolResult" with content as TextContent[] arrays (not strings).
bashExecution messages are converted to {role:"user"} by convertToLlm before
the hook fires, so checking m.type === "bashExecution" was a no-op.
- Fix context-masker to match on role, handle array content, detect bash
results by their "Ran `" prefix
- Fix register-hooks truncation to operate on role:"toolResult" with
array content blocks
- Update tests to use correct pi-ai LLM payload format
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
- custom-models.md: add Command Allowlist section under Value Resolution
explaining the restriction, default list, and how to override via
allowedCommandPrefixes setting or GSD_ALLOWED_COMMAND_PREFIXES env var
- configuration.md: add URL Blocking (fetch_page) section documenting
what's blocked by default, why, and how to allowlist specific hosts
via fetchAllowedUrls setting or GSD_FETCH_ALLOWED_URLS env var
- configuration.md: add both env vars to the Environment Variables table
Flip two safety mechanisms from opt-in to opt-out so all users benefit
from rollback protection and merge regression checks without manual
configuration.
- git.snapshots: false → true (creates recovery refs before destructive ops)
- git.pre_merge_check: false → "auto" in solo mode (auto-detects test runner)
Both remain configurable; users can explicitly disable with snapshots: false
or pre_merge_check: false.
Closes#2677
All other .gsd/ state files use uppercase naming (DECISIONS.md,
REQUIREMENTS.md, PROJECT.md, etc). This renames the canonical
preferences file to PREFERENCES.md while keeping a migration
fallback — the loader checks PREFERENCES.md first, then falls
back to lowercase preferences.md for existing installations.
Closes#2700
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
osascript display notification is silently swallowed by macOS when the
calling terminal app (Ghostty, iTerm2, etc.) lacks notification
permissions in System Settings. The command exits 0 with no error,
making the failure invisible.
terminal-notifier registers as its own Notification Center app, so
macOS prompts the user for permission on first use — the expected UX.
Changes:
- Add findExecutable() helper to locate terminal-notifier on PATH
- buildDesktopNotificationCommand() prefers terminal-notifier when
available, falls back to osascript (preserving existing behavior)
- Update tests to handle both terminal-notifier and osascript paths
- Add macOS delivery note to docs/configuration.md notifications section
- Add troubleshooting entry for notifications not appearing on macOS
Fixes#2632
Co-authored-by: Yang Yang(NYC) <Yang.Yang2@bcg.com>
Files added by PR #2008 that were not in main were dropped during
the merge. Restore all src/, docs/, and scripts/ files from the
pre-merge PR head.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add a proper public-facing documentation site using Mintlify with 19 MDX
pages covering getting started, auto mode, commands, configuration, and
all user-facing features. Move internal/SDK documentation (Pi SDK, TUI,
context & hooks, research notes, ADRs) to docs-internal/ since they
should not be part of the public documentation.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Cover all new features across README, commands, configuration,
auto-mode, and getting-started docs: GitHub sync extension, Skill
tool resolution, health check phase 2, forensics debugger upgrade,
auto PR on milestone completion, RUNTIME.md template, welcome screen,
GSD_HOME/GSD_PROJECT_ID env vars, browser/runtime UAT types, pipeline
decomposition, sliding-window stuck detection, and data-loss recovery.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Centralise all ~/.gsd path construction through app-paths.ts (compiled
code) or a module-level `gsdHome` const (runtime extensions that cannot
import app-paths). When GSD_HOME is set, every path that previously
resolved under ~/.gsd now resolves under the override.
Existing overrides (GSD_STATE_DIR, GSD_CODING_AGENT_DIR) continue to
take precedence when set.
- Wire resolveProfileDefaults into loadEffectiveGSDPreferences so
token_profile: budget actually sets cheaper models and skips phases
- Add /gsd rate <over|ok|under> command to submit user feedback on
model tier assignments, completing the adaptive routing feedback loop
- Document that models config is required for dynamic routing activation
- Document ceiling behavior when dynamic routing is active
- Document reassess_after_slice as required for reassessment
Closes#1505 (partial — escalateTier wiring deferred to follow-up)
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: add Node LTS pinning guide for macOS Homebrew users
New doc (docs/node-lts-macos.md) explains how to pin Node 24 LTS
via Homebrew to avoid running on odd-numbered development releases.
Covers brew install/link/pin, version managers as alternatives,
and verification steps.
Added notice banner in README linking to the guide.
* docs: document /gsd config for global API keys
Added Global API Keys section to configuration.md explaining:
- /gsd config saves keys to ~/.gsd/agent/auth.json
- Keys apply to all projects automatically
- Three supported keys: Tavily, Brave, Context7
- How precedence works (env vars > saved keys)
- Anthropic models don't need search keys
Updated commands.md gsd config entry to link to the new section.
Added Set up API keys section to getting-started.md for first-run.
* docs: add Node LTS pinning guide for macOS Homebrew users
New doc (docs/node-lts-macos.md) explains how to pin Node 24 LTS
via Homebrew to avoid running on odd-numbered development releases.
Covers brew install/link/pin, version managers as alternatives,
and verification steps.
Added notice banner in README linking to the guide.
* docs: recommend pi-dashscope extension for DashScope models
The built-in alibaba-coding-plan provider uses the Anthropic-compat
endpoint and lacks per-model thinking format and compatibility flags,
causing issues like #1003 (MiniMax-M2.5 thinking loop).
The community pi-dashscope extension uses the correct OpenAI-compat
endpoint, sets thinkingFormat per model (qwen/zai), includes compat
flags (supportsDeveloperRole, supportsReasoningEffort), and provides
an interactive /dashscope-configure command.
Added Community Provider Extensions section to configuration docs
recommending pi-dashscope over the built-in provider.
* docs: add Node LTS pinning guide for macOS Homebrew users
New doc (docs/node-lts-macos.md) explains how to pin Node 24 LTS
via Homebrew to avoid running on odd-numbered development releases.
Covers brew install/link/pin, version managers as alternatives,
and verification steps.
Added notice banner in README linking to the guide.
* feat: auto-create PR on milestone completion (#687)
New git preferences:
- git.auto_pr (boolean, default false): create a PR when a
milestone completes via gh CLI
- git.pr_target_branch (string, default main branch): target
branch for auto-created PRs (e.g. develop, qa, staging)
Implementation:
- GitPreferences: added auto_pr and pr_target_branch fields
- preferences.ts: added validation for both fields
- auto-worktree.ts: after push, pushes milestone branch and
creates PR via 'gh pr create' (non-fatal on failure)
Documentation:
- configuration.md: added fields to git config block, table,
and new git.auto_pr section with requirements and flow
- git-strategy.md: added Automatic Pull Requests section with
Gitflow example config
Adds git.isolation: "none" so developers can use GSD's full planning/execution
methodology with all work happening directly on their current branch — no worktree,
no milestone branch, no merge step.
- Preference plumbing: "none" accepted/validated, getIsolationMode() helper
- Core bypass: all worktree/branch gates in auto.ts skip in none mode
- Peripheral: doctor skips worktree checks, system prompt omits worktree context
- Docs: git-strategy, configuration, auto-mode, troubleshooting, system prompt updated
- Tests: 11 new tests, 621/621 pass
* feat: add worktree post-create hook for environment setup (#597)
Add git.worktree_post_create preference — a script path that GSD
runs after creating any worktree (both auto-mode and manual /worktree).
The script receives SOURCE_DIR and WORKTREE_DIR as environment
variables, enabling users to copy .env files, symlink asset
directories, or run other setup commands that git worktrees don't
inherit from the main tree.
Implementation:
- Add worktree_post_create field to GitPreferences interface
- Add validation in validatePreferences (must be non-empty string)
- Add runWorktreePostCreateHook() in auto-worktree.ts — resolves
relative paths against project root, runs with 30s timeout,
failure is non-fatal (warning only)
- Integrate hook call in createAutoWorktree() (auto-mode path)
- Integrate hook call in worktree-command.ts (manual /worktree path)
- Update docs/configuration.md with full usage guide and example
hook script
- Update preferences-reference.md with field documentation
Example configuration:
git:
worktree_post_create: .gsd/hooks/post-worktree-create
Example hook script:
#!/bin/bash
cp "$SOURCE_DIR/.env" "$WORKTREE_DIR/.env"
ln -sf "$SOURCE_DIR/assets" "$WORKTREE_DIR/assets"
Closes#597
* fix: use Node.js scripts in hook tests for Windows compatibility
Replace bash hook scripts with cross-platform Node.js scripts in
worktree-post-create-hook.test.ts. On macOS/Linux, scripts use
#!/usr/bin/env node shebang. On Windows, generates batch files
that invoke node -e. Fixes windows-portability CI failures.
* fix: Windows CI failures in worktree post-create hook tests
- Use path.isAbsolute() instead of startsWith("/") to detect absolute
paths on Windows (fixes double-path bug like C:\...\C:\...)
- Add .bat extension to hook scripts on Windows so they are recognized
as executable by cmd.exe
- Extract isWin constant and hookPath() helper for consistent
platform-aware test setup
Fixes 3 failing tests in windows-portability CI job:
- executes hook script with correct env vars
- supports absolute hook paths
- hook can copy files from source to worktree
* fix: adopt main's help command and error message in commands.ts
The auto-merge missed main's addition of the help handler, showHelp
function, and updated description/subcommands array. Added them
manually and updated the visualizer help text to reflect 7-tab TUI.
* fix: write Windows hook scripts as .bat + companion .js file
The previous approach embedded multi-line JavaScript in a node -e "..."
argument inside the .bat file. cmd.exe splits on newlines, so each JS
line was interpreted as a separate batch command ('const' is not
recognized...).
Now writes the JS code to a companion .js file and the .bat invokes
it with `node "%~dp0<file>.js"`, which works reliably on Windows.
---------
Co-authored-by: TÂCHES <afromanguy@me.com>
Update both docs/configuration.md (user-facing) and
src/resources/extensions/gsd/docs/preferences-reference.md (internal)
with complete coverage of all GSD preferences:
- Add /gsd prefs subcommands table (global, project, status, wizard, setup)
- Document token_profile (budget/balanced/quality) and phases settings
- Document context_pause_threshold field
- Document remote_questions configuration (Slack/Discord)
- Document git.merge_strategy (squash/merge) and git.isolation (worktree/branch)
- Expand post_unit_hooks with missing agent field
- Expand pre_dispatch_hooks with skip_if, unit_type, model fields
and action validation rules
- Add known unit types list for hook before/after arrays
- Add examples for pre-dispatch hooks (modify/skip/replace)
- Add examples for token profile, phases, and remote questions
- Update models to show all 6 phases (research, planning, execution,
execution_simple, completion, subagent)
- Add full example combining all major settings
