docs: map existing codebase

2026-03-27 00:21:00 +00:00
parent f50d2f8446
commit d963902a28
7 changed files with 1215 additions and 0 deletions
--- a/.planning/codebase/ARCHITECTURE.md
+++ b/.planning/codebase/ARCHITECTURE.md
@@ -0,0 +1,170 @@
 # Architecture
 **Analysis Date:** 2026-03-27
 ## Pattern Overview
 **Overall:** Agent-orchestrated agentic code framework (GSD - Get Shit Done)
 **Key Characteristics:**
 - Multi-agent cooperative system: 18 specialized agents working in coordinated workflows
 - Document-driven state management: All decisions and progress stored as Markdown files
 - Workflow-based orchestration: 56 workflows guide agent interactions and user engagement
 - Agentic code execution: Plans are executable prompts for Claude model execution
 - Extensible per-runtime: Same architecture replicated across 7 IDE/agent providers (.claude, .agent, .gemini, .codex, .cursor, .windsurf, .opencode)
 ## Layers
 **Orchestration Layer:**
 - Purpose: Coordinate user commands, route to agents, manage phase/milestone progression
 - Location: `.claude/get-shit-done/workflows/`
 - Contains: 56 workflow definitions (markdown files), each defining a multi-step process
 - Depends on: gsd-tools.cjs CLI for state management, git operations, config parsing
 - Used by: All commands (user entry points)
 **Agent Layer:**
 - Purpose: Specialized reasoning for different task types (planning, execution, research, verification, mapping)
 - Location: `.claude/agents/` (18 agents)
 - Contains: Agent role definitions, instructions, tool access lists
 - Agents: gsd-planner, gsd-executor, gsd-phase-researcher, gsd-verifier, gsd-debugger, gsd-codebase-mapper, gsd-integration-checker, gsd-ui-auditor, gsd-plan-checker, and 9 others
 - Depends on: Workflow coordination, tools (Read, Write, Bash, Grep, Glob, WebFetch)
 - Used by: Orchestration workflows, invoked via `@agent-name` or Task() calls
 **State Management Layer:**
 - Purpose: Persistent tracking of project progress, decisions, and configuration
 - Location: `.planning/` (global state), phase directories (phase-local state)
 - Contains: STATE.md (global), CONTEXT.md (decisions), ROADMAP.md (scope), PLAN.md (task breakdown), SUMMARY.md (execution results), VERIFICATION.md (quality gates)
 - Depends on: gsd-tools.cjs for parsing, git for history
 - Used by: All agents and orchestration layer
 **Tool Layer:**
 - Purpose: Provide execution capabilities for agents
 - Location: Various (bash, file I/O, git, web)
 - Tools: Read, Write, Edit, Bash, Grep, Glob, WebFetch, mcp__context7__*
 - Depends on: Agent invocations
 - Used by: Agents during execution
 **CLI Tool Layer:**
 - Purpose: Centralized state/config operations shared across 50+ workflow/agent files
 - Location: `.claude/get-shit-done/bin/gsd-tools.cjs` (~1000 lines)
 - Contains: 100+ commands for state management, phase operations, validation, progress tracking
 - Depends on: Node.js built-ins, git, file system
 - Used by: Every workflow and agent (called via bash subprocess)
 ## Data Flow
 **Phase Planning Flow:**
 1. User invokes `/gsd:plan-phase PHASE_NUMBER`
 2. Orchestrator (plan-phase workflow) loads PHASE state via gsd-tools.cjs
 3. Planner agent (gsd-planner) reads CONTEXT.md (user decisions), codebase structure, creates PLAN.md
 4. Plan Checker agent validates PLAN.md structure and quality
 5. PLAN.md written to phase directory
 6. User reviews, optionally discusses via `/gsd:discuss-phase` → updates CONTEXT.md
 7. Flow loops if plan changes needed
 **Phase Execution Flow:**
 1. User invokes `/gsd:execute-phase PHASE_NUMBER`
 2. Executor orchestrator loads phase plans (multiple per phase)
 3. Plans grouped by wave (dependency-aware parallelization)
 4. For each wave:
   - Executor agent loads PLAN.md
   - Executes tasks sequentially (each task → code change → test verification)
   - Commits per-task (atomic commits for rollback safety)
   - Writes SUMMARY.md with results
 5. Orchestrator collects all SUMMARY.md files
 6. Verifier agent checks phase completion against VERIFICATION.md
 7. STATE.md updated with completion status
 8. Planning docs committed to git (if commit_docs: true)
 **Verification Flow:**
 1. Phase execution completes, SUMMARY.md produced
 2. Verifier agent compares output against VERIFICATION.md (user-defined success criteria)
 3. If gaps detected: Trigger `/gsd:plan-phase --gaps` for remedial planning
 4. Remedial PLAN.md created with gap-closure tasks
 5. Execute → Verify loop continues until no gaps
 **State Management Flow:**
 1. STATE.md maintains global position: current_phase, current_milestone, workstream, blockers
 2. Phase directories contain CONTEXT.md (decisions), PLAN.md (tasks), SUMMARY.md (results), VERIFICATION.md (success gates)
 3. ROADMAP.md holds master scope: all phases with descriptions
 4. .planning/config.json: branching strategy, model profiles, search behavior
 5. Each operation updates relevant state file, committed atomically
 ## Key Abstractions
 **Phase:**
 - Purpose: Logical unit of work scoped by user, contains multiple Plans
 - Examples: `1`, `1.1`, `1.2` (decimal numbering for sub-phases)
 - Pattern: Each phase has directory `.planning/phases/N/` with CONTEXT.md, PLAN.md, SUMMARY.md, VERIFICATION.md
 **Plan:**
 - Purpose: Executable task breakdown derived from phase scope (typically 2-3 tasks per plan)
 - Examples: `PLAN-01.md`, `PLAN-02.md` within a phase directory
 - Pattern: PLAN.md contains frontmatter (metadata), objective, context references, tasks array, success criteria
 **Task:**
 - Purpose: Atomic unit of work within a plan (code change, test, commit)
 - Types: `type="auto"` (fully autonomous), `type="checkpoint"` (pause before), `type="review"` (requires human sign-off)
 - Pattern: Task has action (what to do), verification criteria, expected artifacts
 **Workflow:**
 - Purpose: Multi-step process coordinating user input and agent actions
 - Examples: `plan-phase.md`, `execute-phase.md`, `discuss-phase.md`
 - Pattern: Workflows define steps with conditional branching, agent spawning, state updates
 **Agent Profiles:**
 - Purpose: Model selection strategy for agent execution (quality vs cost)
 - Profiles: `quality` (Opus for all), `balanced` (Opus planning, Sonnet execution), `budget` (minimal Opus)
 - Pattern: Resolved via gsd-tools.cjs based on `.planning/config.json` model_profile setting
 ## Entry Points
 **Command Entry Point:**
 - Location: `.claude/get-shit-done/workflows/` (any `.md` file)
 - Triggers: User invokes `/gsd:WORKFLOW_NAME [args]`
 - Responsibilities: Parse arguments, call gsd-tools.cjs init command, route to agents or inline execution
 **Agent Entry Point:**
 - Location: `.claude/agents/AGENT_NAME.md`
 - Triggers: Spawned by orchestrator via `@AGENT_NAME` mention or Task() call
 - Responsibilities: Load context, read mandatory files, execute role-specific logic, return results
 **Tool Entry Point:**
 - Location: `.claude/get-shit-done/bin/gsd-tools.cjs`
 - Triggers: `node gsd-tools.cjs <command> [args]`
 - Responsibilities: Parse subcommands, perform atomic state/git operations, output JSON
 ## Error Handling
 **Strategy:** Graceful degradation with checkpoint pauses
 **Patterns:**
 - **Auth Errors:** Executor pauses at checkpoint, waits for user to provide credentials
 - **Verification Failures:** Verifier identifies gaps, planner creates remedial PLAN.md, executor runs gap-closure phase
 - **Invalid State:** gsd-tools.cjs validate commands detect inconsistencies, suggest repairs
 - **Parse Failures:** Frontmatter validation catches schema violations early
 - **Git Conflicts:** Executor respects branching strategy, creates feature branches per config
 ## Cross-Cutting Concerns
 **Logging:** Shell output captured from gsd-tools.cjs, bash task execution. Errors logged to console, summary tracked in SUMMARY.md.
 **Validation:** gsd-tools.cjs provides `validate` commands for:
 - Phase numbering consistency
 - Plan structure (required fields, task arrays)
 - References (@ paths resolve to existing files)
 - Artifacts (must_haves tracked in PLAN.md)
 **Authentication:** Config stored in `~/.gsd/` (outside repo), environment variable overrides for CI. Secrets never committed to git.
 **Atomicity:** gsd-tools.cjs commit command handles commit_docs check and .gitignore detection. Each task commits separately for rollback safety.
 **Determinism:** Model profiles ensure same agent type always gets same model (unless inherit mode). Frontmatter schema validation prevents parsing ambiguity.
 ---
 *Architecture analysis: 2026-03-27*
--- a/.planning/codebase/CONCERNS.md
+++ b/.planning/codebase/CONCERNS.md
@@ -0,0 +1,250 @@
 # Codebase Concerns
 **Analysis Date:** 2026-03-27
 ## Silent Error Handling (Critical)
 **Widespread use of empty catch blocks:**
 - Files: `/.claude/hooks/gsd-prompt-guard.js`, `/.claude/hooks/gsd-context-monitor.js`, `/.claude/hooks/gsd-workflow-guard.js`, `/.claude/hooks/gsd-statusline.js`, `/.claude/hooks/gsd-check-update.js`
 - Issue: 14+ catch blocks across hooks swallow errors silently with `catch (e) {}` or `catch (e) { // comment }` without logging
 - Impact: Failures in hook execution go undetected, making debugging difficult. When files are corrupted, config fails to parse, or file system errors occur, no indication is provided to users or developers
 - Current mitigation: Comments explain intent (e.g., "Silent fail -- bridge is best-effort", "don't break statusline on parse errors"), but no logging mechanism exists
 - Recommendation: Implement optional debug logging to stderr (only when hooks are invoked in debug mode) without breaking normal operation. Use environment variable like `GSD_HOOK_DEBUG=1` to enable error logging
 ---
 ## Fragile Hook Timeout Architecture
 **Context-Monitor Hook (`.claude/hooks/gsd-context-monitor.js`)**:
 - Issue: 10-second stdin timeout (line 35) is tight for slow systems. On Windows/Git Bash, pipe delays can exceed this
 - Files: `/.claude/hooks/gsd-context-monitor.js` (line 35: `setTimeout(() => process.exit(0), 10000)`)
 - Current mitigation: Comments reference issues #775, #1162 indicating this was a known problem
 - Risk: On systems with slow I/O, the hook exits prematurely without reading input, potentially leaving metrics unprocessed
 - Safe modification: Consider detecting platform and adjusting timeout accordingly, or make timeout configurable via environment variable
 ---
 ## Hardcoded Buffer Percentage
 **Status Line Hook Context Normalization**:
 - Issue: 16.5% buffer hardcoded for Claude Code autocompact (line 29)
 - Files: `/.claude/hooks/gsd-statusline.js` (line 29: `const AUTO_COMPACT_BUFFER_PCT = 16.5`)
 - Impact: If Claude Code changes autocompact behavior or other models have different buffers, context calculations become inaccurate
 - Recommendation: Make this configurable via `.planning/config.json` with sensible defaults per model (Claude, Gemini, OpenCode)
 ---
 ## Stale Hook Version Tracking
 **Hook Version Header Validation**:
 - Issue: Version detection depends on comment headers in JavaScript files (line 78 in `gsd-check-update.js`)
 - Files: `/.claude/hooks/gsd-check-update.js` (lines 73-92)
 - Risk: If hook files are minified, reformatted, or copied incorrectly, version headers can be lost, making stale hook detection fail silently
 - Current state: Detects "unknown" version if header is missing, but this doesn't prevent the hook from running with wrong version
 - Recommendation: Add a checksum or content hash validation in addition to version headers to detect unintended hook modifications
 ---
 ## Process Detachment on Windows
 **Check-Update Hook Background Process**:
 - Issue: Uses `spawn()` with `detached: true` (line 111 in `gsd-check-update.js`)
 - Files: `/.claude/hooks/gsd-check-update.js` (lines 108-114)
 - Impact: Background npm process can hang on Windows if not properly detached. Blocks are prevented by `unref()` (line 114), but edge cases remain if process fails
 - Current state: `windowsHide: true` flag added, `stdio: 'ignore'` set
 - Recommendation: Add timeout to background spawn, return immediately after unref, and consider writing to log file instead of silently ignoring errors
 ---
 ## Config File Parsing Without Validation
 **Multiple Hooks Read `.planning/config.json`**:
 - Issue: Config files are parsed with `JSON.parse()` but no schema validation exists
 - Files: `/.claude/hooks/gsd-context-monitor.js` (line 53), `/.claude/hooks/gsd-workflow-guard.js` (line 65)
 - Risk: Malformed JSON or missing expected fields cause silent failures. If config structure changes, old configs won't error but silently ignore new fields
 - Recommendation: Implement a simple schema validation utility (even lightweight: check for required keys and types) and log warnings when config doesn't match expected shape
 ---
 ## Race Conditions in Metrics Bridge
 **Context Metrics Between Statusline and Monitor Hooks**:
 - Issue: Two separate hooks read/write to `/tmp/claude-ctx-{sessionId}.json` without file locking
 - Files: `/.claude/hooks/gsd-statusline.js` (line 40-47 writes), `/.claude/hooks/gsd-context-monitor.js` (line 63-70 reads)
 - Risk: On high-frequency tool use, write and read can race, causing monitor hook to read stale metrics or corrupted JSON
 - Current mitigation: Both have try-catch around JSON.parse(), stale metrics are detected by timestamp (line 74)
 - Recommendation: Use atomic writes (write-to-temp-then-rename pattern) for metrics file, or switch to a simpler shared state mechanism
 ---
 ## Missing Logging Infrastructure
 **No Structured Logging**:
 - Issue: Hooks only log to stdout via process.stdout.write() for hook outputs. No persistent logs for troubleshooting
 - Files: All hook files (`/.claude/hooks/*.js`)
 - Impact: When hooks fail silently, no audit trail exists to debug issues. Users cannot see what hooks detected or why they exited
 - Recommendation: Create optional debug logs in `.planning/hooks-debug.log` (only when env var `GSD_DEBUG=1`), append structured JSON records with timestamp, hook name, and outcome
 ---
 ## Unbounded Memory in Warning State File
 **Context Monitor Warning Debounce**:
 - Issue: Warning state tracked in `/tmp/claude-ctx-{sessionId}-warned.json` accumulates indefinitely
 - Files: `/.claude/hooks/gsd-context-monitor.js` (lines 87-117)
 - Risk: Temporary directory might not clean this up, causing stale state from previous sessions to affect new sessions
 - Current mitigation: State is per-session (uses sessionId), so scope is limited
 - Recommendation: Add timestamp to warning state and treat state older than 1 hour as stale (auto-reset)
 ---
 ## Regex Pattern Complexity in Prompt Guard
 **Prompt Injection Detection Patterns**:
 - Issue: 12 regex patterns for injection detection (lines 18-32 in `gsd-prompt-guard.js`) are not anchored and may be fragile
 - Files: `/.claude/hooks/gsd-prompt-guard.js` (lines 18-32)
 - Risk: Some patterns (e.g., `/you\s+are\s+now\s+/i`) could match benign documentation text about "You are now ready to..." and trigger false warnings
 - Impact: While warnings are advisory-only, frequent false positives degrade user experience
 - Recommendation: Review patterns for false positive risk, consider context (e.g., only in code blocks, not in comments), or add allowlist for common false positives
 ---
 ## Inconsistent Hook Version Across Environments
 **Multi-Environment Hook Duplication**:
 - Issue: Identical hooks duplicated across `.claude/`, `.agent/`, `.gemini/`, `.opencode/` directories
 - Files: 4x each of `gsd-prompt-guard.js`, `gsd-context-monitor.js`, `gsd-workflow-guard.js`, `gsd-statusline.js`, `gsd-check-update.js`
 - Risk: If one environment's hooks are updated, others can drift out of sync. Version check in `gsd-check-update.js` detects this (line 81-82) but doesn't auto-fix
 - Impact: Users with multiple agent environments may see inconsistent behavior
 - Recommendation: Consolidate hooks to a shared location or implement auto-sync mechanism in installer
 ---
 ## Resource Leaks in Timeouts
 **Stdin Timeout Cleanup**:
 - Issue: `setTimeout()` created for stdin timeout in all hooks, relies on `clearTimeout()` to clean up
 - Files: `/.claude/hooks/gsd-prompt-guard.js`, `/.claude/hooks/gsd-context-monitor.js`, `/.claude/hooks/gsd-workflow-guard.js`, `/.claude/hooks/gsd-statusline.js`
 - Risk: If process exits before reaching `process.stdin.on('end')`, timeout continues running until expiry (3-10 seconds)
 - Current state: Process exits on timeout with code 0, but spawned processes inherit this timeout
 - Recommendation: Add `unref()` call on timeout timers so they don't keep process alive
 ---
 ## Platform-Specific Path Separator
 **Windows Path Handling in Guards**:
 - Issue: Guards check for both `/` and `\\` in file paths (e.g., line 52 in `gsd-prompt-guard.js`)
 - Files: `/.claude/hooks/gsd-prompt-guard.js` (line 52), `/.claude/hooks/gsd-workflow-guard.js` (line 43)
 - Risk: Mixing separators when checking `.planning/` paths may not catch all variations on Windows (e.g., mixed slashes)
 - Recommendation: Normalize paths using `path.normalize()` before comparison, or use `path.sep` for platform detection
 ---
 ## Missing Config Directory Override Documentation
 **CLAUDE_CONFIG_DIR Environment Variable**:
 - Issue: Support for `CLAUDE_CONFIG_DIR` environment variable is implemented (line 18 in `gsd-check-update.js`, line 73 in `gsd-statusline.js`) but not documented
 - Files: `/.claude/hooks/gsd-check-update.js` (line 18), `/.claude/hooks/gsd-statusline.js` (line 73)
 - Impact: Users with custom config directories won't know this variable exists, potentially breaking hook functionality
 - Recommendation: Document in copilot-instructions.md or add reference in hook comments
 ---
 ## Temporary File Cleanup Strategy
 **Metric Files Never Cleaned**:
 - Issue: `/tmp/claude-ctx-{sessionId}.json` and `/tmp/claude-ctx-{sessionId}-warned.json` are never deleted
 - Files: `/.claude/hooks/gsd-statusline.js` (writes), `/.claude/hooks/gsd-context-monitor.js` (reads)
 - Risk: On long-running systems, /tmp fills up with stale session files
 - Recommendation: Implement cleanup logic to delete temp files older than 7 days, or hook into session cleanup to delete files on logout
 ---
 ## Package.json Missing Dependencies
 **Minimal Configuration**:
 - Issue: `.claude/package.json` only contains `{"type":"commonjs"}`, no dependencies listed
 - Files: `/.claude/package.json`
 - Risk: Hooks use built-in Node modules (fs, path, os, child_process), so this is correct, but appears incomplete
 - Current state: This is intentional (all hooks use only Node builtins), but unclear to maintainers
 - Recommendation: Add comment in package.json explaining that hooks intentionally use no external dependencies for portability
 ---
 ## Potential Memory Bloat in Large Outputs
 **No Stream Processing in Hooks**:
 - Issue: All hooks read entire stdin into memory before processing (`let input = ''; process.stdin.on('data', chunk => input += chunk)`)
 - Files: All hook files
 - Risk: If a tool call writes gigabytes of content (e.g., massive file read), the hook process could run out of memory
 - Current mitigation: Only tool writes/edits are inspected, and these are typically small
 - Recommendation: For hooks processing large content (especially prompt injection guard), implement streaming regex matching or line-by-line processing
 ---
 ## Test Coverage Gaps
 **No Unit Tests for Hooks**:
 - What's not tested: None of the 5 hook files have automated tests
 - Files: `/.claude/hooks/*.js` (all of them)
 - Risk: Changes to hook logic have no regression protection. Timeout tweaks, path logic, or regex patterns could break without detection
 - Impact: Hook failures are silent (by design), so broken hooks go unnoticed until users report issues
 - Priority: High — hooks are critical path for agent context management
 ---
 ## Missing Error Recovery in Executor
 **Deviation Rule Priority Conflicts**:
 - Issue: Executor auto-applies Rules 1-3 without clear priority when multiple rules could apply
 - Files: `/.github/agents/gsd-executor.agent.md` (line 150 mentions "RULE PRIORITY:")
 - Risk: When a task has multiple issues (e.g., bug AND missing critical functionality), executor might fix bug first, missing that missing-function blocking task completion
 - Recommendation: Clarify priority order: blocking issues (Rule 3) > missing critical functionality (Rule 2) > bugs (Rule 1)
 ---
 ## Subprocess Error Propagation in Background Checks
 **npm view Command Failure Silent**:
 - Issue: `execSync('npm view get-shit-done-cc version')` wrapped in try-catch, timeout 10s (line 96 in `gsd-check-update.js`)
 - Files: `/.claude/hooks/gsd-check-update.js` (lines 95-97)
 - Risk: If npm is not installed, offline, or slow, fails silently. Users won't know update check failed
 - Impact: Latest version is set to "unknown", update check becomes unreliable
 - Recommendation: Log to file when update check fails (optional debug log), or retry with exponential backoff
 ---
 ## Missing Instrumentation for Decision Points
 **No Audit Trail for Hook Decisions**:
 - Issue: When context monitor injects critical warning or workflow guard injects advisory, no record of decision
 - Files: `/.claude/hooks/gsd-context-monitor.js` (lines 125-142), `/.claude/hooks/gsd-workflow-guard.js` (lines 78-87)
 - Risk: If user behavior doesn't match warning, no way to audit what warning was shown or when
 - Recommendation: Write decision logs to `.planning/hooks-audit.log` with timestamp, hook name, decision, and reason (only in GSD active mode)
 ---
 ## Scalability of Hook Frequency
 **Hooks Run on Every Tool Use**:
 - Issue: Context monitor (PostToolUse) runs after EVERY tool call, reads file, parses JSON, checks thresholds
 - Files: `/.claude/hooks/gsd-context-monitor.js`
 - Risk: On high-frequency tool sessions (100+ tools), accumulated overhead could impact performance
 - Current mitigation: Debounce warnings (line 108), stale metric detection (line 74)
 - Recommendation: Profile hook execution time under load, consider batching metrics or reducing check frequency
 ---
 ## Unclear Behavior on Missing Files
 **Graceful Degradation Assumptions**:
 - Issue: When `.planning/STATE.md`, `.planning/config.json`, or todo files don't exist, hooks silently skip functionality
 - Files: All hooks that check for optional files
 - Risk: Unclear to users whether missing files are "normal" or indicate misconfiguration
 - Example: Statusline shows "no task" if todos not found, but user might think todos are lost
 - Recommendation: Distinguish between "feature not enabled" (e.g., no .planning/ = not a GSD project) vs. "feature broken" (e.g., config.json exists but unparseable)
 ---
 *Concerns audit: 2026-03-27*
--- a/.planning/codebase/CONVENTIONS.md
+++ b/.planning/codebase/CONVENTIONS.md
@@ -0,0 +1,179 @@
 # Coding Conventions
 **Analysis Date:** 2026-03-27
 ## Language & Runtime
 **Primary Language:** JavaScript (CommonJS)
 - Node.js environment (no TypeScript transpilation)
 - All hooks use `.js` extension with shebang: `#!/usr/bin/env node`
 **Module System:**
 - CommonJS (`require()` only, no ES6 imports)
 - Node.js built-in modules: `fs`, `path`, `os`, `child_process`
 - No external npm dependencies in hook files
 ## Naming Patterns
 **Files:**
 - Kebab-case: `gsd-hook-name.js`
 - Pattern: `gsd-` prefix + feature name + `.js` extension
 - Examples: `gsd-prompt-guard.js`, `gsd-context-monitor.js`, `gsd-statusline.js`
 **Functions:**
 - camelCase: `detectConfigDir()`, `clearTimeout()`, `writeFileSync()`
 - Single-letter shorthand acceptable for simple operations: `f` for file in loops
 **Constants:**
 - UPPER_SNAKE_CASE for immutable values: `WARNING_THRESHOLD`, `CRITICAL_THRESHOLD`, `STALE_SECONDS`, `DEBOUNCE_CALLS`
 - Inline comments after constants for clarity: `const WARNING_THRESHOLD = 35;  // remaining_percentage <= 35%`
 **Variables:**
 - camelCase: `input`, `stdinTimeout`, `data`, `filePath`, `findings`, `configPath`
 - Descriptive names: `remaining_percentage`, `callsSinceWarn`, `hookEventName`
 - Single-letter loop variables: `f`, `e` (for errors), `p` (for patterns)
 **Types/Objects:**
 - Object keys use snake_case: `tool_name`, `tool_input`, `file_path`, `hook_version`, `installed_version`
 - Array items plural: `staleHooks`, `findings`, `allowedPatterns`, `files`, `hookFiles`
 ## Code Style
 **Formatting:**
 - No linter configured (no eslintrc, prettier, or biome config files found)
 - Line length: typically 80-120 characters, no strict enforced limit observed
 - Indentation: 2 spaces consistently across all files
 **Comments:**
 - Single-line comments: `// comment`
 - Multi-line blocks: Multiple `//` lines stacked (no `/* */` blocks found)
 - Header comments with metadata: Version, purpose, triggers, behavior
  - Pattern: `// gsd-hook-version: X.Y.Z` as first comment after shebang
  - Purpose explanation follows immediately
 **String Formatting:**
 - Single quotes for regular strings: `'utf8'`, `'end'`
 - Template literals for interpolation: `` `${variable}` ``
 - Backticks for paths and code examples in comments: `` `${filePath}` ``
 ## Error Handling
 **Try-Catch Pattern:**
 - All file I/O and JSON parsing wrapped in try-catch
 - Silent failures preferred: catch blocks often empty or call `process.exit(0)`
 - Examples from codebase:
  - `try { const data = JSON.parse(input); } catch { process.exit(0); }`
  - `try { ... } catch (e) { // Silent fail on parse errors }`
 **Graceful Degradation:**
 - Never block operations with errors
 - Timeout guards prevent hanging: `const stdinTimeout = setTimeout(() => process.exit(0), 3000);`
 - File existence checks before operations: `if (fs.existsSync(configPath)) { ... }`
 - Return early on missing critical data: `if (!sessionId) { process.exit(0); }`
 **Error Recovery:**
 - Corrupted files reset to defaults: `catch (e) { warnData = { callsSinceWarn: 0, lastLevel: null }; }`
 - Optional chain operators for safe access: `data.tool_input?.file_path || ''`
 ## Type Coercion & Checks
 **Null/Undefined Handling:**
 - Null coalescing default values: `data.session_id || ''`, `data.cwd || process.cwd()`
 - Explicit null checks: `if (remaining != null)` (distinguishes null from undefined)
 - Undefined/null fallbacks: `|| 'unknown'`, `|| []`, `|| {}`
 **Truthiness Checks:**
 - Explicit boolean comparisons: `if (config.hooks?.workflow_guard) { ... }`
 - Array length checks: `if (files.length > 0) { ... }`, `if (findings.length === 0) { ... }`
 **Number Conversions:**
 - Explicit parsing: `Math.floor(Date.now() / 1000)`, `Math.round(100 - usableRemaining)`
 - Clamping with Math: `Math.max(0, value)`, `Math.min(100, value)`
 ## Imports & Requires
 **Order (when present):**
 1. Node.js built-in modules: `fs`, `path`, `os`, `child_process`
 2. Destructured imports grouped: `const { spawn } = require('child_process');`
 3. No external package requires in hooks
 **Require Pattern:**
 ```javascript
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const { spawn } = require('child_process');
 ```
 ## Object & Array Patterns
 **Object Creation:**
 - Literal syntax: `{ hookEventName: 'PreToolUse', additionalContext: message }`
 - Computed properties from template literals: `` { [key]: value } `` (not observed, uses direct literals)
 - Spread operators: Not used in codebase
 **Array Operations:**
 - `.filter()`: `files.filter(f => f.startsWith(session))`
 - `.map()`: `files.map(f => ({ name: f, mtime: fs.statSync(...) }))`
 - `.find()`: `todos.find(t => t.status === 'in_progress')`
 - `.some()`: `allowedPatterns.some(p => p.test(filePath))`
 - Arrow functions for callbacks: `chunk => input += chunk`
 **Sorting & Ordering:**
 - Reverse chronological: `files.sort((a, b) => b.mtime - a.mtime)`
 - File system operations ordered first, then filtering
 ## Output Patterns
 **JSON Output:**
 - All hook output is JSON: `process.stdout.write(JSON.stringify(output));`
 - Output structure includes `hookSpecificOutput` wrapper:
  ```javascript
  const output = {
    hookSpecificOutput: {
      hookEventName: 'PreToolUse',
      additionalContext: message
    }
  };
  ```
 **Process Exit:**
 - Success: `process.exit(0)` or implicit exit after writing output
 - Error: `process.exit(0)` (never `process.exit(1)` to avoid breaking workflows)
 - Cleanup: `clearTimeout()` called before operations
 ## File I/O Patterns
 **Synchronous Operations:**
 - `fs.readFileSync(path, 'utf8')` for reads
 - `fs.writeFileSync(path, JSON.stringify(data))` for writes
 - `fs.existsSync(path)` for checks
 - `fs.readdirSync(path)` for directory listing
 - `fs.statSync(path).mtime` for file metadata
 **Path Operations:**
 - `path.join()` for path concatenation: `path.join(cwd, '.planning', 'config.json')`
 - `path.basename(dir)` for extracting final component
 - `path.dirname()` for parent directory
 ## Regular Expressions
 **Pattern Definition:**
 - Captured in constants array at file top: `const INJECTION_PATTERNS = [ /pattern1/i, /pattern2/i ]`
 - Case-insensitive flag commonly used: `/pattern/i`
 - Multiline patterns use raw strings: `/[\u200B-\u200F]/` for Unicode detection
 **Pattern Testing:**
 - `.test()` method for boolean check: `if (pattern.test(content))`
 - `.match()` for capture groups: `const versionMatch = content.match(/\\/\\/ gsd-hook-version:\\s*(.+)/)`
 - `.source` property for pattern string: `findings.push(pattern.source)`
 ## No Additional Frameworks
 **Testing:** Not detected - no test files exist
 **Build Tools:** Not detected - runs directly as Node.js scripts
 **Linting/Formatting:** Not detected - no .eslintrc, .prettierrc, or similar configs
 ---
 *Convention analysis: 2026-03-27*
--- a/.planning/codebase/INTEGRATIONS.md
+++ b/.planning/codebase/INTEGRATIONS.md
@@ -0,0 +1,114 @@
 # External Integrations
 **Analysis Date:** 2026-03-27
 ## APIs & External Services
 **Web Search:**
 - Brave Search - Web search integration for research and discovery phases
  - SDK/Client: Native `fetch` API (Node.js built-in)
  - Auth: `BRAVE_API_KEY` environment variable or `~/.gsd/brave_api_key` file
  - Endpoint: `https://api.search.brave.com/res/v1/web/search`
  - Implementation: `cmdWebSearch()` in `/home/ys/family-repo/AgenticCode/.claude/get-shit-done/bin/lib/commands.cjs`
 **Web Scraping (Optional):**
 - Firecrawl - Web content extraction
  - Auth: `FIRECRAWL_API_KEY` environment variable or `~/.gsd/firecrawl_api_key` file
  - Status: Configuration detected, not actively used in codebase
 **Search Alternative (Optional):**
 - Exa Search - Alternative search API
  - Auth: `~/.gsd/exa_api_key` file
  - Status: Configuration detected, not actively used in codebase
 ## Data Storage
 **Repositories:**
 - Git - Primary version control system for all planning documents
  - Client: Git CLI via `child_process.execSync()` and `execFileSync()`
  - Operations: Commit, status, log, diff, tag management
  - Integration points: `execGit()` in `core.cjs`, phase operations in `phase.cjs`
 **File Storage:**
 - Local filesystem only
  - `.planning/` directory tree - All state, roadmaps, phases, requirements
  - `~/.gsd/` directory - User-level API key storage
  - Multi-workspace support via `.planning/config.json` sub_repos configuration
 **Caching:**
 - None detected
 ## Authentication & Identity
 **Auth Provider:**
 - Custom/API Key based
 - No centralized identity provider
 - Individual API keys per external service stored in files or environment variables
 - Git authentication via system SSH/credentials configured externally
 ## Monitoring & Observability
 **Error Tracking:**
 - None detected - errors handled via console output
 **Logs:**
 - Console output via `output()` and `error()` functions in `/home/ys/family-repo/AgenticCode/.claude/get-shit-done/bin/lib/core.cjs`
 - Support for structured JSON output via `--raw` flag
 - Context monitoring hooks in `.claude/hooks/gsd-context-monitor.js`
 ## CI/CD & Deployment
 **Hosting:**
 - Self-hosted Node.js CLI
 - IDE integration via Claude, Gemini, Agent, Cursor, OpenCode, Windsurf editors
 - Editor-specific hooks and commands in `./.[editor]/.claude/hooks/`
 **CI Pipeline:**
 - Git hooks integration via Claude settings
 - Post-tool-use monitoring: `gsd-context-monitor.js`
 - Pre-write guards: `gsd-prompt-guard.js`
 - Update checking: `gsd-check-update.js`
 ## Environment Configuration
 **Required env vars:**
 - `HOME` - User home directory (for API key storage and config)
 - `BRAVE_API_KEY` - (optional) Brave Search API key for web search functionality
 **Optional env vars:**
 - `FIRECRAWL_API_KEY` - Web scraping capability
 - `EXA_API_KEY` - Alternative search provider
 **Secrets location:**
 - Environment variables: `.env` or shell environment
 - File-based: `~/.gsd/brave_api_key`, `~/.gsd/firecrawl_api_key`, `~/.gsd/exa_api_key`
 - Git-ignored configuration: Not applicable (no local .env files in codebase)
 ## Webhooks & Callbacks
 **Incoming:**
 - None detected
 **Outgoing:**
 - Git commits via `execGit()` - Triggers CI/CD if configured
 - Status updates via stdio - Display progress to Claude/editor interface
 ## Git Integration
 **Operations Supported:**
 - `git status` - Check working tree state
 - `git add` - Stage files
 - `git commit` - Create planning commits with auto-generated messages
 - `git log` - Query commit history
 - `git diff` - Compare changes
 - `git tag` - Version marking for phases and milestones
 - Commit routing for multi-repo workspaces
 **Key Implementation:**
 - Location: `execGit()` in `/home/ys/family-repo/AgenticCode/.claude/get-shit-done/bin/lib/core.cjs`
 - Supports sub-repo commit routing via `commit-to-subrepo` command
 - Automatic message generation with structured frontmatter
 ---
 *Integration audit: 2026-03-27*
--- a/.planning/codebase/STACK.md
+++ b/.planning/codebase/STACK.md
@@ -0,0 +1,76 @@
 # Technology Stack
 **Analysis Date:** 2026-03-27
 ## Languages
 **Primary:**
 - JavaScript (Node.js) - Core framework and tooling
 - CommonJS (`.cjs`) - Module format for all library files
 - Markdown - Configuration, documentation, and state files
 ## Runtime
 **Environment:**
 - Node.js (version not explicitly specified, uses `#!/usr/bin/env node` shebang)
 **Package Manager:**
 - npm (inferred from package.json presence)
 - Lockfile: Not detected in codebase
 ## Frameworks
 **Core:**
 - Get Shit Done (GSD) Framework v1.29.0 - Agentic code orchestration and planning
 - Native Node.js APIs - `child_process`, `fs`, `path`
 **Search & Web:**
 - Brave Search API - Web search integration via HTTP fetch
 **Build/Dev:**
 - Node.js built-in utilities - No external build tool detected
 ## Key Dependencies
 **Critical:**
 - `child_process` - Subprocess execution for git commands and CLI operations
 - `fs` - File system operations for planning document management
 - `path` - Cross-platform path handling
 - `os` - Environment detection (home directory, temp directories)
 **Infrastructure:**
 - `fetch` API (native Node.js) - HTTP requests for Brave Search API
 ## Configuration
 **Environment:**
 - Stored in `~/.gsd/` directory with separate API key files
 - Environment variable overrides: `BRAVE_API_KEY`, `FIRECRAWL_API_KEY`, `EXA_API_KEY`
 **Key Configuration Files:**
 - `.planning/config.json` - Project-wide configuration and feature flags
 - `settings.json` - Agent-specific settings (per `./.agent/`, `./.claude/`, `./.gemini/`, etc.)
 - `.gsd-file-manifest.json` - File integrity tracking with SHA256 hashes
 **Configuration Features:**
 - Multi-repository workspace support
 - Model profile resolution
 - Milestone and workstream management
 - Phase numbering strategies (decimal or custom)
 ## Platform Requirements
 **Development:**
 - Node.js with built-in ES2020+ support
 - Git (for repository operations and commits)
 - Bash/Shell environment for command execution
 - File system with support for symlinks and deep directory structures
 **Production:**
 - Self-contained Node.js CLI tool
 - No external runtime required beyond Node.js
 - Execution via `node gsd-tools.cjs` or direct command invocation
 ---
 *Stack analysis: 2026-03-27*
--- a/.planning/codebase/STRUCTURE.md
+++ b/.planning/codebase/STRUCTURE.md
@@ -0,0 +1,217 @@
 # Codebase Structure
 **Analysis Date:** 2026-03-27
 ## Directory Layout
 ```
 /home/ys/family-repo/AgenticCode/
 ├── .agent/                             # Anthropic Agent-specific GSD setup
 │   ├── agents/                         # Agent definitions (symlinks or copies)
 │   ├── get-shit-done/                  # Workflows, templates, references
 │   ├── hooks/                          # Post-tool integration hooks
 │   ├── skills/                         # Project skills (agent instructions)
 │   └── package.json                    # CommonJS marker
 ├── .claude/                            # Claude Code / Claude Web setup
 │   ├── agents/                         # 18 agent definition files (master)
 │   ├── get-shit-done/                  # Master workflows, references, commands
 │   │   ├── bin/                        # gsd-tools.cjs CLI (~1000 lines)
 │   │   ├── commands/gsd/               # Command metadata (workstreams.md)
 │   │   ├── references/                 # Documentation and config specs
 │   │   ├── templates/                  # Scaffold templates for PLAN.md, SUMMARY.md
 │   │   └── workflows/                  # 56 orchestration workflows
 │   ├── commands/gsd/                   # Claude Code command overrides
 │   ├── hooks/                          # Post-tool hooks for linting/formatting
 │   ├── package.json                    # CommonJS marker
 │   └── settings.json                   # Per-runtime settings
 ├── .codex/                             # Codeium Codex setup (mirrors .claude/)
 ├── .cursor/                            # Cursor IDE setup (mirrors .claude/)
 ├── .gemini/                            # Google Gemini setup (mirrors .claude/)
 ├── .opencode/                          # OpenCode setup (mirrors .claude/)
 ├── .windsurf/                          # Codeium Windsurf setup (mirrors .claude/)
 ├── .github/                            # GitHub integration
 │   ├── gsd-file-manifest.json          # File integrity checksums
 │   └── get-shit-done/                  # GitHub action templates
 ├── .planning/                          # Project state and planning documents
 │   ├── codebase/                       # Analysis documents (STACK.md, ARCHITECTURE.md, etc.)
 │   ├── config.json                     # Project configuration (branching, model profiles)
 │   ├── STATE.md                        # Global project state (current phase, milestone, blockers)
 │   ├── ROADMAP.md                      # Full scope and phase definitions
 │   ├── REQUIREMENTS.md                 # Traceability for feature requirements
 │   └── phases/                         # Phase execution directories
 │       ├── 1/                          # Phase 1
 │       │   ├── CONTEXT.md              # User decisions for this phase
 │       │   ├── PLAN-01.md              # Task breakdown (plan 1 of N)
 │       │   ├── PLAN-02.md              # Task breakdown (plan 2 of N)
 │       │   ├── SUMMARY-01.md           # Execution results (for PLAN-01)
 │       │   ├── VERIFICATION.md         # Success criteria and quality gates
 │       │   └── WAITING.json            # Optional: pause signal for checkpoints
 │       ├── 1.1/                        # Sub-phase 1.1
 │       └── 2/                          # Phase 2
 ├── .git/                               # Git repository
 ├── .gitignore                          # Standard: excludes node_modules, .env, .planning (optional)
 ├── README.md                           # Project descriptor
 └── .gsd-file-manifest.json             # Root-level file integrity tracking
 ```
 ## Directory Purposes
 **`.claude/` (Master Directory):**
 - Purpose: Contains the canonical GSD system — agents, workflows, CLI tool, references
 - Contains: Agent role definitions (18 files), 56 workflows, gsd-tools.cjs, documentation
 - Key files: `agents/gsd-planner.md`, `agents/gsd-executor.md`, `agents/gsd-codebase-mapper.md`, `get-shit-done/bin/gsd-tools.cjs`
 **`.claude/agents/`:**
 - Purpose: Agent role definitions — instructions, tool access, execution patterns
 - Contains: 18 agent files (one per agent type)
 - File pattern: `gsd-{role-name}.md` (e.g., `gsd-planner.md`)
 - Size: Large files (10KB-45KB), front-loaded with role definition, process steps
 **`.claude/get-shit-done/workflows/`:**
 - Purpose: Orchestration logic — multi-step processes coordinating agents and user input
 - Contains: 56 markdown workflow files
 - Naming: workflow names map to commands (e.g., `execute-phase.md` → `/gsd:execute-phase`)
 - Pattern: Each workflow defines steps with conditional branching, gsd-tools.cjs calls, agent spawning
 **`.claude/get-shit-done/bin/`:**
 - Purpose: CLI tool providing centralized state/git operations
 - Contains: `gsd-tools.cjs` (main tool, ~1000 lines), `lib/` (supporting utilities)
 - Commands: 100+ subcommands for state, phases, roadmaps, validation, commits
 - Called from: Every workflow and agent via `node gsd-tools.cjs <command>`
 **`.claude/get-shit-done/references/`:**
 - Purpose: Documentation and configuration specifications
 - Contains: 15 reference files (model-profiles.md, planning-config.md, checkpoints.md, etc.)
 - Usage: Read by agents to understand patterns, by implementers to understand system
 **`.claude/get-shit-done/templates/`:**
 - Purpose: Scaffold templates for plan and summary generation
 - Contains: PLAN.md template, SUMMARY.md template, CONTEXT.md template
 - Usage: Developers fill templates when creating new phases
 **`.agent/`, `.gemini/`, `.codex/`, `.cursor/`, `.windsurf/`, `.opencode/`:**
 - Purpose: Per-IDE setup directories (mirrors of `.claude/`)
 - Contains: Symlinks or copies of agents/, workflows/, hooks/, settings.json
 - Why separate: Each IDE has own credential storage, hook integration points, settings
 **`.planning/`:**
 - Purpose: Global project state and phase-local planning documents
 - Contains: STATE.md (global), ROADMAP.md (full scope), config.json, phases/ directory tree
 - Key files: `STATE.md` (current position), `ROADMAP.md` (phase definitions), `config.json` (branching strategy, model profiles)
 **`.planning/phases/N/`:**
 - Purpose: Per-phase execution directory — holds decisions, plans, summaries
 - Contains: CONTEXT.md (user decisions), PLAN-*.md (task breakdowns), SUMMARY-*.md (results), VERIFICATION.md (success gates)
 - Naming: Phase directories use number (1, 1.1, 1.2, 2) corresponding to ROADMAP.md phases
 ## Key File Locations
 **Entry Points:**
 - `.claude/get-shit-done/workflows/*.md` - User command entry points
 - `.claude/agents/*.md` - Agent entry points (invoked by workflows)
 - `.claude/get-shit-done/bin/gsd-tools.cjs` - CLI tool entry point
 **Configuration:**
 - `.planning/config.json` - Project-wide configuration (branching, model profiles, search behavior)
 - `.claude/settings.json` - Per-runtime agent settings (model overrides, parallelization)
 - `~/.gsd/defaults.json` - User-global GSD defaults (read-only in repo)
 **Core Logic:**
 - `.claude/agents/gsd-planner.md` - Phase planning logic (45KB, ~700 lines)
 - `.claude/agents/gsd-executor.md` - Plan execution logic (21KB, ~450 lines)
 - `.claude/agents/gsd-codebase-mapper.md` - Project analysis for architecture/tech docs
 - `.claude/get-shit-done/bin/gsd-tools.cjs` - Centralized state/git operations
 **State & Decisions:**
 - `.planning/STATE.md` - Global state (current phase, milestone, workstream, blockers)
 - `.planning/ROADMAP.md` - Master scope (phase numbers, descriptions, order)
 - `.planning/phases/N/CONTEXT.md` - User decisions for phase N
 - `.planning/phases/N/PLAN-*.md` - Task breakdowns (executable prompts)
 **Execution & Verification:**
 - `.planning/phases/N/SUMMARY-*.md` - Execution results, commit hashes, artifacts
 - `.planning/phases/N/VERIFICATION.md` - Success criteria, quality gates, test requirements
 - `.planning/REQUIREMENTS.md` - Requirement IDs (REQ-01, etc.) for traceability
 **Documentation & References:**
 - `.claude/get-shit-done/references/model-profiles.md` - Agent model selection strategies
 - `.claude/get-shit-done/references/planning-config.md` - Configuration options spec
 - `.claude/get-shit-done/references/checkpoints.md` - Pause point definition and usage
 ## Naming Conventions
 **Files:**
 - Workflows: kebab-case (e.g., `execute-phase.md`, `plan-phase.md`)
 - Agents: kebab-case with gsd- prefix (e.g., `gsd-planner.md`, `gsd-executor.md`)
 - Phase documents: UPPERCASE with phase number (e.g., `PLAN-01.md`, `SUMMARY-02.md`)
 - Config files: lowercase (e.g., `config.json`, `settings.json`)
 - State files: UPPERCASE (e.g., `STATE.md`, `ROADMAP.md`)
 **Directories:**
 - Hidden IDE-specific: dot-prefixed (`.claude`, `.agent`, `.gemini`)
 - Planning: `.planning` with phase structure (phases/1/, phases/1.1/, etc.)
 - Tools/resources: lowercase (agents, workflows, bin, lib, references, templates)
 **Phase Numbering:**
 - Integer phases: 1, 2, 3 (major phases)
 - Decimal sub-phases: 1.1, 1.2, 1.3 (sub-divisions of phase 1)
 - Directory structure mirrors numbering: `.planning/phases/1/`, `.planning/phases/1.1/`
 ## Where to Add New Code
 **New Agent:**
 1. Create ``.claude/agents/gsd-{agent-name}.md`` with role definition, process steps, tools
 2. Size: Keep under 50KB (agents are consumed whole as context)
 3. Register: List in agent registry within workflow files and orchestrator
 4. Mirror: Copy to `.agent/agents/`, `.gemini/agents/`, etc. after validation
 **New Workflow:**
 1. Create `.claude/get-shit-done/workflows/{workflow-name}.md`
 2. Define: `<purpose>`, `<process>` with numbered steps, subprocess calls to gsd-tools.cjs
 3. Commands: If user-facing, add metadata entry in `.claude/commands/gsd/`
 4. Routing: Document how workflow invokes agents (inline vs spawned via Task())
 **New Reference Documentation:**
 1. Create `.claude/get-shit-done/references/{topic}.md`
 2. Purpose: Explain system patterns, configuration options, validation rules
 3. Read by: Agents when implementing features, developers understanding system
 4. Update: Link from agent files or workflow documentation
 **New Phase (during project execution):**
 1. Create phase directory: `.planning/phases/{N}/` (where N is next phase number)
 2. Create CONTEXT.md (template in references/)
 3. Planner creates PLAN-*.md files
 4. Add phase to ROADMAP.md with description
 5. Update STATE.md current_phase field
 **Phase Documents (during planning):**
 - PLAN.md: Created by gsd-planner agent (follows template in templates/)
 - VERIFICATION.md: User creates to define success criteria (template available)
 - CONTEXT.md: Created by gsd-discuss-phase agent from user decisions
 ## Special Directories
 **`.planning/codebase/`:**
 - Purpose: Analysis documents for executor reference (STACK.md, ARCHITECTURE.md, CONVENTIONS.md, TESTING.md, CONCERNS.md)
 - Generated: By gsd-codebase-mapper agent via `/gsd:map-codebase`
 - Committed: Yes, documents tracked in git for future reference
 **`.planning/phases/N/`:**
 - Purpose: Execution workspace for phase N (isolated state)
 - Generated: Directories created by gsd-tools.cjs during phase setup
 - Committed: Yes, all planning docs committed (unless .planning/ in .gitignore)
 **`.claude/get-shit-done/bin/lib/`:**
 - Purpose: Supporting utilities for gsd-tools.cjs
 - Contents: Shared functions for JSON parsing, git operations, file I/O
 - Generated: No, part of GSD system
 - Committed: Yes, part of codebase
 **`node_modules/`:**
 - Purpose: NPM dependencies (if any)
 - Generated: Yes, by `npm install`
 - Committed: No, excluded via .gitignore
 ---
 *Structure analysis: 2026-03-27*
--- a/.planning/codebase/TESTING.md
+++ b/.planning/codebase/TESTING.md
@@ -0,0 +1,209 @@
 # Testing Patterns
 **Analysis Date:** 2026-03-27
 ## Test Framework
 **Status:** Not detected
 - No test files (*.test.js, *.spec.js) found in codebase
 - No test runner configured (no jest.config.js, vitest.config.js, or mocha configuration)
 - No test dependencies listed in package.json files
 **Code Context:**
 - The codebase consists of 5 Node.js hook scripts (579 total lines across `.claude/hooks/`)
 - Each hook is a standalone CLI tool that reads JSON from stdin and outputs JSON to stdout
 - Hooks are event-driven (SessionStart, PreToolUse, PostToolUse, AfterTool lifecycle events)
 - No application code beyond these hooks exists in the repository
 ## Script Type & Testing Approach
 **Current Architecture:**
 Each hook file (`gsd-*.js` in `/home/ys/family-repo/AgenticCode/.claude/hooks/`) follows the same structural pattern:
 - Shebang: `#!/usr/bin/env node`
 - Node.js built-in modules only (fs, path, os, child_process)
 - JSON stdin → processing → JSON stdout
 - Silent failure on errors (timeout guards, try-catch with exit(0))
 **Hook Files:**
 - `gsd-prompt-guard.js` (96 lines) - Detects prompt injection patterns in written files
 - `gsd-statusline.js` (119 lines) - Renders context usage and task status
 - `gsd-context-monitor.js` (156 lines) - Warns when context window is low
 - `gsd-workflow-guard.js` (94 lines) - Advises on workflow compliance
 - `gsd-check-update.js` (114 lines) - Checks for GSD updates in background
 ## Manual Testing Indicators
 **Integration Points (evidence of real-world testing):**
 - Comments referencing specific issues: `See #775`, `See #1162`, `See #870`, `See #884`
 - Platform-specific workarounds: `windowsHide: true` for child_process to prevent console flash on Windows
 - Timeout guards: `const stdinTimeout = setTimeout(() => process.exit(0), 3000);` prevents hanging on pipe issues
 - Git Bash compatibility: explicit handling of stdin timeout on Windows Git Bash
 **Behavioral Validation Patterns:**
 - Config file validation: reads `.planning/config.json`, catches parse errors gracefully
 - File existence checks before operations: `if (fs.existsSync(filePath))`
 - Stale data detection: `if ((now - metrics.timestamp) > STALE_SECONDS)`
 - Severity escalation tracking: debounce counter resets on warning level change
 ## Input Validation
 **JSON Parsing with Error Handling:**
 All hooks follow this pattern (example from `gsd-prompt-guard.js`):
 ```javascript
 let input = '';
 const stdinTimeout = setTimeout(() => process.exit(0), 3000);
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', chunk => input += chunk);
 process.stdin.on('end', () => {
  clearTimeout(stdinTimeout);
  try {
    const data = JSON.parse(input);
    // Process data
  } catch {
    // Silent fail — never block tool execution
    process.exit(0);
  }
 });
 ```
 **Defensive Checks:**
 - Field existence: `const toolName = data.tool_name;` then `if (toolName !== 'Write' && toolName !== 'Edit')`
 - Optional chaining: `data.tool_input?.file_path || ''`
 - Null checks: `if (!sessionId) { process.exit(0); }`
 - Default values: `data.cwd || process.cwd()`, `data.model?.display_name || 'Claude'`
 ## File I/O Testing
 **Patterns for Reliability:**
 - Synchronous I/O ensures order: `fs.readFileSync()` → process → `fs.writeFileSync()`
 - Directory existence checked before writing: `if (!fs.existsSync(cacheDir)) { fs.mkdirSync(cacheDir, { recursive: true }); }`
 - Try-catch wraps all file operations that could fail:
  ```javascript
  try {
    const bridgeData = JSON.stringify({ ... });
    fs.writeFileSync(bridgePath, bridgeData);
  } catch (e) {
    // Silent fail -- bridge is best-effort, don't break statusline
  }
  ```
 ## State Machine / Behavior Testing
 **Context Monitor Debounce Logic** (`gsd-context-monitor.js`):
 - Tracks warning state in file: `/tmp/claude-ctx-{session_id}-warned.json`
 - Debounce counter incremented: `warnData.callsSinceWarn = (warnData.callsSinceWarn || 0) + 1`
 - Severity escalation bypasses debounce: `if (severityEscalated) { // emit immediately }`
 - State reset on warn: `warnData.callsSinceWarn = 0`
 This pattern validates behavior without formal tests:
 ```javascript
 let warnData = { callsSinceWarn: 0, lastLevel: null };
 const isCritical = remaining <= CRITICAL_THRESHOLD;
 const currentLevel = isCritical ? 'critical' : 'warning';
 const severityEscalated = currentLevel === 'critical' && warnData.lastLevel === 'warning';
 if (!firstWarn && warnData.callsSinceWarn < DEBOUNCE_CALLS && !severityEscalated) {
  process.exit(0); // Suppress warning
 }
 ```
 ## Regex Pattern Testing
 **Prompt Injection Detection** (`gsd-prompt-guard.js`):
 Patterns tested against content without formal unit tests:
 ```javascript
 const INJECTION_PATTERNS = [
  /ignore\s+(all\s+)?previous\s+instructions/i,
  /override\s+(system|previous)\s+(prompt|instructions)/i,
  /you\s+are\s+now\s+(?:a|an|the)\s+/i,
  /(?:print|output|reveal|show|display|repeat)\s+(?:your\s+)?(?:system\s+)?(?:prompt|instructions)/i,
  /\[SYSTEM\]/i,
  /<<\s*SYS\s*>>/i,
 ];
 for (const pattern of INJECTION_PATTERNS) {
  if (pattern.test(content)) {
    findings.push(pattern.source);
  }
 }
 ```
 Unicode detection without regex: `if (/[\u200B-\u200F\u2028-\u202F\uFEFF\u00AD]/.test(content))`
 ## Environment & Configuration Testing
 **Configuration Loading Safety** (all hooks):
 - Try-catch with silent fail:
  ```javascript
  const configPath = path.join(cwd, '.planning', 'config.json');
  if (fs.existsSync(configPath)) {
    try {
      const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
      if (config.hooks?.context_warnings === false) {
        process.exit(0); // Feature disabled
      }
    } catch (e) {
      // Ignore config parse errors
    }
  }
  ```
 - Optional chaining for nested config: `config.hooks?.workflow_guard`, `config.hooks?.context_warnings`
 **Environment Variable Access:**
 ```javascript
 const envDir = process.env.CLAUDE_CONFIG_DIR;
 if (envDir && fs.existsSync(path.join(envDir, 'get-shit-done', 'VERSION'))) {
  return envDir; // Custom config dir detected
 }
 ```
 ## Performance & Resource Management
 **Timeout Guards (prevent resource leaks):**
 - All hooks implement stdin timeout: `const stdinTimeout = setTimeout(() => process.exit(0), 3000);`
 - Longer timeout for high-volume operations: `const stdinTimeout = setTimeout(() => process.exit(0), 10000);` in context-monitor
 - Always cleared before processing: `clearTimeout(stdinTimeout);`
 **Background Process Management** (`gsd-check-update.js`):
 - Child process spawned with `stdio: 'ignore'`: doesn't inherit parent's stdio
 - Process detached on Windows: `detached: true` (required for proper cleanup)
 - Parent calls `child.unref()`: parent doesn't wait for child to exit
 ```javascript
 const child = spawn(process.execPath, ['-e', `...inline script...`], {
  stdio: 'ignore',
  windowsHide: true,
  detached: true
 });
 child.unref();
 ```
 ## Test Coverage Gaps
 **Areas Without Formal Testing:**
 1. **Regex Pattern Accuracy** - Injection patterns untested against false positives/negatives
 2. **Debounce Counter Edge Cases** - Corruption recovery, counter reset logic
 3. **Platform-Specific Behavior** - Windows vs Linux path handling, process detachment
 4. **Concurrent Access** - Multiple hooks writing to same state files simultaneously
 5. **Large Input Handling** - No tests for multi-megabyte JSON on stdin
 6. **Stale File Cleanup** - No validation that temp files are properly removed
 7. **Spawn Child Behavior** - Background update check success/failure not validated
 ## Recommendation for Testing
 **Given the architecture (CLI hooks, not library code):**
 - Integration testing more valuable than unit tests
 - Manual testing via real Claude Code sessions is current primary validation
 - Would recommend:
  1. Snapshot tests for JSON output structure
  2. Mock file system for configuration loading paths
  3. Integration tests simulating tool use hook flow
  4. Platform-specific testing (Windows, macOS, Linux) for path handling
 **Lack of tests is acceptable for:**
 - Simple stdin/stdout data transformation scripts
 - Hooks deployed once per installation (not on every tool call)
 - Silent-fail-safe design (errors don't break workflows)
 - Real-world testing via 50+ GitHub issues and fixes
 ---
 *Testing analysis: 2026-03-27*