@ai-is-gonna/get-tasks-done 0.2.0

package/get-tasks-done/workflows/work-task-issue.md

@@ -0,0 +1,249 @@
+<purpose>
+Work one exported GitHub task issue through the task-scoped PR flow.
+</purpose>
+
+<boundary>
+Task mode may mutate GitHub task labels/comments, create or reuse the task
+worktree and branch, spawn `gtd-task-executor`, push the task branch, and open
+or update the task PR.
+
+Forbidden:
+- Do not bypass the workability gate for explicit selectors.
+- Do not run implementation in the user's main checkout.
+- Do not create plan completion artifacts: `*-SUMMARY.md`, `.planning/STATE.md`,
+  `.planning/ROADMAP.md`, or requirements completion metadata.
+- Do not run reconciliation without explicit user permission.
+</boundary>
+
+<required_reading>
+@~/.claude/get-tasks-done/references/gates.md
+@~/.claude/get-tasks-done/references/worktree-path-safety.md
+</required_reading>
+
+<blocking_antipattern_check>
+Before taking any task action, check for `.continue-here.md`. If it contains
+`Critical Anti-Patterns` with any `blocking` entry, run a MANDATORY
+understanding check before proceeding.
+
+The check cannot be skipped. Answer:
+1. What is this anti-pattern?
+2. How did it manifest?
+3. What structural mechanism (not acknowledgment) prevents it?
+
+If the answers are missing or superficial, stop and report the blocker instead
+of selecting a task, reconciling, or finalizing a phase.
+</blocking_antipattern_check>
+
+<read_only_mode>
+If `$ARGUMENTS` contains `--read-only`, run:
+
+```bash
+gtd-sdk query work-task-issue $ARGUMENTS
+```
+
+Report the loaded manifest, preflight status, selected task or blocking state,
+and make clear that no implementation or PR creation happened.
+</read_only_mode>
+
+<phase_completion_mode>
+Use this mode only after every exported parent plan in the phase has completed
+reconciliation and has a canonical `*-SUMMARY.md`.
+
+Trigger command:
+
+```text
+/gtd:work-task-issue --complete-phase <phase> --execute
+```
+
+Compatibility CLI preflight:
+
+```bash
+gtd-sdk query work-task-issue $ARGUMENTS
+```
+
+If the result action is `phase_completion_blocked_missing_summaries`, stop and
+report the missing summary paths. Do not run finalization gates.
+
+If the result is ready and `$ARGUMENTS` does not contain `--execute`, report the
+preview and tell the user to run `work-task-issue --complete-phase <phase> --execute`.
+
+If the result is ready and `$ARGUMENTS` contains `--execute`, run only the
+post-phase finalization gates:
+
+1. code review gate
+2. regression gate
+3. schema drift gate
+4. codebase_drift_gate / codebase-drift gate
+5. `gtd-verifier` / `VERIFICATION.md`
+6. `phase.complete`
+7. update_roadmap
+8. close_phase_todos
+
+The codebase drift gate is non-blocking: continue on error or failure, report
+the drift finding, and leave remapping as follow-up work unless the helper
+returns an explicit safety blocker.
+
+This mode must not select child task issues, spawn `gtd-task-executor`, run
+parent reconciliation, or run implementation plans. It exists to finish the
+phase after the issue-driven task and reconciliation path has already produced
+all summaries.
+
+<step name="update_roadmap">
+After `phase.complete`, sync roadmap phase status through the SDK/helper result.
+</step>
+
+<step name="close_phase_todos">
+This never blocks phase completion. Best-effort close pending todos whose YAML
+frontmatter contains `resolves_phase: <phase>` by scanning
+`.planning/todos/pending`, creating `.planning/todos/completed`, and moving each
+matched file:
+
+```bash
+PHASE_ID="<phase>"
+PENDING_DIR=".planning/todos/pending"
+COMPLETED_DIR=".planning/todos/completed"
+mkdir -p "$COMPLETED_DIR"
+find "$PENDING_DIR" -type f -name "*.md" -print 2>/dev/null | while IFS= read -r TODO_FILE; do
+  TODO_PHASE=$(awk '/^---$/ {f++; next} f==1 && /^resolves_phase:/ {sub(/^resolves_phase:[[:space:]]*/, ""); print; exit}' "$TODO_FILE")
+  if [ "$TODO_PHASE" = "$PHASE_ID" ]; then
+    mv "$TODO_FILE" "$COMPLETED_DIR/"
+  fi
+done
+```
+</step>
+
+After `phase.complete` succeeds, report the next verification command from the
+helper result.
+</phase_completion_mode>
+
+<execution_flow>
+1. Run the selector and state preflight:
+
+```bash
+gtd-sdk query work-task-issue $ARGUMENTS
+```
+
+2. If the selected result is not a workable child task, stop and report the
+   concrete blocker labels, issue numbers, or source hashes.
+3. If a parent plan is ready for reconciliation, stop and ask for permission.
+   Do not reconcile in this step.
+4. Claim the task by adding `gtd:in-progress` and posting a claim comment with
+   the task branch.
+5. Create or reuse the isolated task worktree and branch
+   `gtd/task-{task_id}-{issue_number}`. Reuse the same branch and PR when
+   resuming requested changes, validation failure, or a rejected PR.
+6. Spawn `gtd-task-executor` in that worktree with:
+   - child issue body
+   - parent issue summary
+   - source plan path
+   - required read-first files
+   - allowed write scope and boundaries
+   - task action
+   - acceptance criteria
+   - validation contract
+   - task verification command
+   - existing PR review feedback, when present
+   - path-safety context from `references/worktree-path-safety.md`
+7. Wait for the executor result. The executor must commit task changes but must
+   not push or touch GitHub issues/PRs.
+8. Validate changed files against the declared diff scope and the GTD completion
+   artifact boundary.
+9. Run the validation contract. Automated checks must pass before a ready PR.
+   Manual checks become reviewer checklist items.
+10. If validation fails, relaunch `gtd-task-executor` with the findings once.
+11. Push the task branch.
+12. Open or update a ready PR only when automated validation passes. The ready
+    PR body must contain `Closes #{child_issue}` and no other closing issue
+    keyword.
+13. If useful changes remain but validation still fails, open or update a draft
+    PR and do not include `Closes #{child_issue}`.
+14. Update the child issue labels and comment with PR and validation status.
+</execution_flow>
+
+<reconciliation_flow>
+Use this mode only after the user explicitly approves reconciling a parent plan.
+Task execution and parent reconciliation are separate operations.
+
+1. Preview the selected parent plan:
+
+```bash
+gtd-sdk query work-task-issue $ARGUMENTS --reconcile --read-only
+```
+
+2. If the preview is not `preview_reconciliation_ready` or
+   `request_reconciliation_permission`, stop and report the concrete blockers:
+   open child issues, missing merged PRs, source drift, open reconciliation PRs,
+   or parent blockers.
+3. Run the reconciler only after approval:
+
+```bash
+gtd-sdk query work-task-issue $ARGUMENTS --reconcile --execute
+```
+
+4. The reconciler must verify the original plan-level `<verification>` command
+   before writing any canonical completion artifacts. If verification fails, it
+   labels/comments the parent as `gtd:reconcile-failed` and does not create
+   `*-SUMMARY.md`, update `.planning/STATE.md`, update `.planning/ROADMAP.md`,
+   or mark requirements complete.
+5. On success, report the reconciliation PR URL and summary path. The PR closes
+   only the parent plan issue. Child task issues are already closed by their
+   task/final PR path.
+6. After the reconciliation PR merges, rerun this workflow with no selector (or
+   the same parent selector) so the state sync can mark the parent issue
+   `gtd:complete` and recompute downstream readiness.
+7. If every plan in the phase now has a `SUMMARY.md`, finish the phase through
+   `work-task-issue --complete-phase <phase> --execute`. This completion path
+   runs only post-phase finalization gates: code review, regression,
+   schema drift, codebase drift, `gtd-verifier`/`VERIFICATION.md`, then
+   `phase.complete`. Only after that should `/gtd:verify-work {phase}` begin.
+</reconciliation_flow>
+
+<pr_body_safety>
+When opening or updating the task PR from the agent workflow, never pass a
+multi-line Markdown body through an inline shell argument. In particular, do
+not use `gh pr create --body "..."` or `gh pr edit --body "..."` for task PRs;
+Markdown backticks, `$`, and backslashes can be interpreted by the shell before
+GitHub receives the body.
+
+Write the exact PR body to a temporary Markdown file with the Write tool, then
+use:
+
+```bash
+gh pr create --body-file "$PR_BODY_FILE" ...
+gh pr edit "$PR_NUMBER" --body-file "$PR_BODY_FILE" ...
+```
+
+After creating or updating the PR, read it back:
+
+```bash
+gh pr view "$PR_NUMBER_OR_URL" --json body --jq .body
+```
+
+Before reporting success, verify the returned body still contains the selected
+task id, the source plan path, and the expected `Closes #{child_issue}` line
+when the PR is ready. Also verify it does not contain lone `\` placeholder
+lines such as `- Task ID: \` or `- Source plan: \`. If the check fails, rewrite
+the PR body from the temporary file with `gh pr edit --body-file` and recheck.
+</pr_body_safety>
+
+<cli_execution_helper>
+The SDK query command has an execution mode for deterministic runners:
+
+```bash
+gtd-sdk query work-task-issue $ARGUMENTS --execute
+```
+
+Use it only when the runtime provides a standalone `gtd-task-executor` command
+on `PATH`. In normal agent-capable runtimes, follow the flow above and spawn the
+`gtd-task-executor` agent directly.
+</cli_execution_helper>
+
+<output_contract>
+Report:
+- selected child task issue, task id, parent plan, branch, and PR URL
+- selected parent plan, reconciliation readiness, summary path, and reconciliation PR URL when `--reconcile` is used
+- whether the PR is ready or draft
+- validation checks that passed, failed, or require manual review
+- labels/comments normalized on the task issue
+- how to inspect or continue any failed draft work
+</output_contract>

package/hooks/dist/gtd-check-update-worker.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// gtd-hook-version: {{GTD_VERSION}}
+// Background worker spawned by gtd-check-update.js (SessionStart hook).
+// Checks for GTD updates and stale hooks, writes result to cache file.
+// Receives paths via environment variables set by the parent hook.
+//
+// Using a separate file (rather than node -e '<inline code>') avoids the
+// template-literal regex-escaping problem: regex source is plain JS here.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const cacheFile = process.env.GTD_CACHE_FILE;
+const projectVersionFile = process.env.GTD_PROJECT_VERSION_FILE;
+const globalVersionFile = process.env.GTD_GLOBAL_VERSION_FILE;
+
+// Compare semver: true if a > b (a is strictly newer than b)
+// Strips pre-release suffixes (e.g. '3-beta.1' → '3') to avoid NaN from Number()
+function isNewer(a, b) {
+  const pa = (a || '').split('.').map(s => Number(s.replace(/-.*/, '')) || 0);
+  const pb = (b || '').split('.').map(s => Number(s.replace(/-.*/, '')) || 0);
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] > pb[i]) return true;
+    if (pa[i] < pb[i]) return false;
+  }
+  return false;
+}
+
+// Check project directory first (local install), then global
+let installed = '0.0.0';
+let configDir = '';
+try {
+  if (fs.existsSync(projectVersionFile)) {
+    installed = fs.readFileSync(projectVersionFile, 'utf8').trim();
+    configDir = path.dirname(path.dirname(projectVersionFile));
+  } else if (fs.existsSync(globalVersionFile)) {
+    installed = fs.readFileSync(globalVersionFile, 'utf8').trim();
+    configDir = path.dirname(path.dirname(globalVersionFile));
+  }
+} catch (e) {}
+
+// Check for stale hooks — compare hook version headers against installed VERSION
+// Hooks are installed at configDir/hooks/ (e.g. ~/.claude/hooks/) (#1421)
+// Only check hooks that GTD currently ships — orphaned files from removed features
+// (e.g., gtd-intel-*.js) must be ignored to avoid permanent stale warnings (#1750)
+const MANAGED_HOOKS = [
+  'gtd-check-update-worker.js',
+  'gtd-check-update.js',
+  'gtd-context-monitor.js',
+  'gtd-graphify-update.sh',
+  'gtd-phase-boundary.sh',
+  'gtd-prompt-guard.js',
+  'gtd-read-guard.js',
+  'gtd-read-injection-scanner.js',
+  'gtd-session-state.sh',
+  'gtd-statusline.js',
+  'gtd-update-banner.js',
+  'gtd-validate-commit.sh',
+  'gtd-workflow-guard.js',
+];
+
+let staleHooks = [];
+if (configDir) {
+  const hooksDir = path.join(configDir, 'hooks');
+  try {
+    if (fs.existsSync(hooksDir)) {
+      const hookFiles = fs.readdirSync(hooksDir).filter(f => MANAGED_HOOKS.includes(f));
+      for (const hookFile of hookFiles) {
+        try {
+          const content = fs.readFileSync(path.join(hooksDir, hookFile), 'utf8');
+          // Match both JS (//) and bash (#) comment styles
+          const versionMatch = content.match(/(?:\/\/|#) gtd-hook-version:\s*(.+)/);
+          if (versionMatch) {
+            const hookVersion = versionMatch[1].trim();
+            if (isNewer(installed, hookVersion) && !hookVersion.includes('{{')) {
+              staleHooks.push({ file: hookFile, hookVersion, installedVersion: installed });
+            }
+          } else {
+            // No version header at all — definitely stale (pre-version-tracking)
+            staleHooks.push({ file: hookFile, hookVersion: 'unknown', installedVersion: installed });
+          }
+        } catch (e) {}
+      }
+    }
+  } catch (e) {}
+}
+
+let latest = null;
+try {
+  latest = execFileSync('npm', ['view', '@ai-is-gonna/get-tasks-done', 'version'], {
+    encoding: 'utf8',
+    timeout: 10000,
+    windowsHide: true,
+    // On Windows, 'npm' is distributed as npm.cmd. Node's execFileSync does
+    // not apply PATHEXT resolution and looks for a literal 'npm' binary,
+    // failing with ENOENT. Setting shell:true on Windows routes through
+    // cmd.exe which resolves npm.cmd via PATHEXT.
+    // POSIX (Linux/macOS) is left untouched — no shell spawn, no extra
+    // signal/exit-code semantics, no overhead.
+    shell: process.platform === 'win32',
+  }).trim();
+} catch (e) {}
+
+const result = {
+  update_available: latest && isNewer(latest, installed),
+  installed,
+  latest: latest || 'unknown',
+  checked: Math.floor(Date.now() / 1000),
+  stale_hooks: staleHooks.length > 0 ? staleHooks : undefined,
+};
+
+if (cacheFile) {
+  try { fs.writeFileSync(cacheFile, JSON.stringify(result)); } catch (e) {}
+}

package/hooks/dist/gtd-check-update.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// gtd-hook-version: {{GTD_VERSION}}
+// Check for GTD updates in background, write result to cache
+// Called by SessionStart hook - runs once per session
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn } = require('child_process');
+
+const homeDir = os.homedir();
+const cwd = process.cwd();
+
+// Detect runtime config directory (supports Claude, OpenCode, Kilo, Gemini)
+// Respects CLAUDE_CONFIG_DIR for custom config directory setups
+function detectConfigDir(baseDir) {
+  // Check env override first (supports multi-account setups)
+  const envDir = process.env.CLAUDE_CONFIG_DIR;
+  if (envDir && fs.existsSync(path.join(envDir, 'get-tasks-done', 'VERSION'))) {
+    return envDir;
+  }
+  for (const dir of ['.claude', '.gemini', '.config/kilo', '.kilo', '.config/opencode', '.opencode']) {
+    if (fs.existsSync(path.join(baseDir, dir, 'get-tasks-done', 'VERSION'))) {
+      return path.join(baseDir, dir);
+    }
+  }
+  return envDir || path.join(baseDir, '.claude');
+}
+
+const globalConfigDir = detectConfigDir(homeDir);
+const projectConfigDir = detectConfigDir(cwd);
+// Use a shared, tool-agnostic cache directory to avoid multi-runtime
+// resolution mismatches where check-update writes to one runtime's cache
+// but statusline reads from another (#1421).
+const cacheDir = path.join(homeDir, '.cache', 'gtd');
+const cacheFile = path.join(cacheDir, 'gtd-update-check.json');
+
+// VERSION file locations (check project first, then global)
+const projectVersionFile = path.join(projectConfigDir, 'get-tasks-done', 'VERSION');
+const globalVersionFile = path.join(globalConfigDir, 'get-tasks-done', 'VERSION');
+
+// Ensure cache directory exists
+if (!fs.existsSync(cacheDir)) {
+  fs.mkdirSync(cacheDir, { recursive: true });
+}
+
+// Run check in background via a dedicated worker script.
+// Spawning a file (rather than node -e '<inline code>') keeps the worker logic
+// in plain JS with no template-literal regex-escaping concerns, and makes the
+// worker independently testable.
+const workerPath = path.join(__dirname, 'gtd-check-update-worker.js');
+const child = spawn(process.execPath, [workerPath], {
+  stdio: 'ignore',
+  windowsHide: true,
+  detached: true,  // Required on Windows for proper process detachment
+  env: {
+    ...process.env,
+    GTD_CACHE_FILE: cacheFile,
+    GTD_PROJECT_VERSION_FILE: projectVersionFile,
+    GTD_GLOBAL_VERSION_FILE: globalVersionFile,
+  },
+});
+
+child.unref();

package/hooks/dist/gtd-context-monitor.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+// gtd-hook-version: {{GTD_VERSION}}
+// Context Monitor - PostToolUse/AfterTool hook (Gemini uses AfterTool)
+// Reads context metrics from the statusline bridge file and injects
+// warnings when context usage is high. This makes the AGENT aware of
+// context limits (the statusline only shows the user).
+//
+// How it works:
+// 1. The statusline hook writes metrics to /tmp/claude-ctx-{session_id}.json
+// 2. This hook reads those metrics after each tool use
+// 3. When remaining context drops below thresholds, it injects a warning
+//    as additionalContext, which the agent sees in its conversation
+//
+// Thresholds:
+//   WARNING  (remaining <= 35%): Agent should wrap up current task
+//   CRITICAL (remaining <= 25%): Agent should stop immediately and save state
+//
+// Debounce: 5 tool uses between warnings to avoid spam
+// Severity escalation bypasses debounce (WARNING -> CRITICAL fires immediately)
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawn } = require('child_process');
+
+const WARNING_THRESHOLD = 35;  // remaining_percentage <= 35%
+const CRITICAL_THRESHOLD = 25; // remaining_percentage <= 25%
+const STALE_SECONDS = 60;      // ignore metrics older than 60s
+const DEBOUNCE_CALLS = 5;      // min tool uses between warnings
+
+let input = '';
+// Timeout guard: if stdin doesn't close within 10s (e.g. pipe issues on
+// Windows/Git Bash, or slow Claude Code piping during large outputs),
+// exit silently instead of hanging until Claude Code kills the process
+// and reports "hook error". See #775, #1162.
+const stdinTimeout = setTimeout(() => process.exit(0), 10000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const sessionId = data.session_id;
+
+    if (!sessionId) {
+      process.exit(0);
+    }
+
+    // Reject session IDs that contain path traversal sequences or path separators.
+    // session_id is used to construct file paths in /tmp — an unsanitized value
+    // could escape the temp directory and read or write arbitrary files.
+    if (/[/\\]|\.\./.test(sessionId)) {
+      process.exit(0);
+    }
+
+    // Check if context warnings are disabled via config.
+    // Quick sentinel check: skip config read entirely for non-GTD projects (#P2.5).
+    const cwd = data.cwd || process.cwd();
+    const planningDir = path.join(cwd, '.planning');
+    if (fs.existsSync(planningDir)) {
+      try {
+        const configPath = path.join(planningDir, 'config.json');
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        if (config.hooks?.context_warnings === false) {
+          process.exit(0);
+        }
+      } catch (e) {
+        // Ignore config read/parse errors (config may not exist in .planning/)
+      }
+    }
+
+    const tmpDir = os.tmpdir();
+    const metricsPath = path.join(tmpDir, `claude-ctx-${sessionId}.json`);
+
+    // If no metrics file, this is a subagent or fresh session -- exit silently
+    if (!fs.existsSync(metricsPath)) {
+      process.exit(0);
+    }
+
+    const metrics = JSON.parse(fs.readFileSync(metricsPath, 'utf8'));
+    const now = Math.floor(Date.now() / 1000);
+
+    // Ignore stale metrics
+    if (metrics.timestamp && (now - metrics.timestamp) > STALE_SECONDS) {
+      process.exit(0);
+    }
+
+    const remaining = metrics.remaining_percentage;
+    const usedPct = metrics.used_pct;
+
+    // No warning needed
+    if (remaining > WARNING_THRESHOLD) {
+      process.exit(0);
+    }
+
+    // Debounce: check if we warned recently
+    const warnPath = path.join(tmpDir, `claude-ctx-${sessionId}-warned.json`);
+    let warnData = { callsSinceWarn: 0, lastLevel: null };
+    let firstWarn = true;
+
+    if (fs.existsSync(warnPath)) {
+      try {
+        warnData = JSON.parse(fs.readFileSync(warnPath, 'utf8'));
+        firstWarn = false;
+      } catch (e) {
+        // Corrupted file, reset
+      }
+    }
+
+    warnData.callsSinceWarn = (warnData.callsSinceWarn || 0) + 1;
+
+    const isCritical = remaining <= CRITICAL_THRESHOLD;
+    const currentLevel = isCritical ? 'critical' : 'warning';
+
+    // Emit immediately on first warning, then debounce subsequent ones
+    // Severity escalation (WARNING -> CRITICAL) bypasses debounce
+    const severityEscalated = currentLevel === 'critical' && warnData.lastLevel === 'warning';
+    if (!firstWarn && warnData.callsSinceWarn < DEBOUNCE_CALLS && !severityEscalated) {
+      // Update counter and exit without warning
+      fs.writeFileSync(warnPath, JSON.stringify(warnData));
+      process.exit(0);
+    }
+
+    // Reset debounce counter
+    warnData.callsSinceWarn = 0;
+    warnData.lastLevel = currentLevel;
+    fs.writeFileSync(warnPath, JSON.stringify(warnData));
+
+    // Detect if GTD is active (has .planning/STATE.md in working directory)
+    const isGtdActive = fs.existsSync(path.join(cwd, '.planning', 'STATE.md'));
+
+    // On CRITICAL with active GTD project, auto-record session state as a
+    // breadcrumb for /gtd:resume-work (#1974). Fire-and-forget subprocess —
+    // doesn't block the hook or the agent. Fires ONCE per CRITICAL session,
+    // guarded by warnData.criticalRecorded to prevent repeated overwrites
+    // of the "crash moment" record on every debounce cycle.
+    if (isCritical && isGtdActive && !warnData.criticalRecorded) {
+      try {
+        // Runtime-agnostic path: this hook lives at <runtime-config>/hooks/
+        // and gtd-tools.cjs lives at <runtime-config>/get-tasks-done/bin/.
+        // Using __dirname makes this work on Claude Code, OpenCode, Gemini,
+        // Kilo, etc. without hardcoding ~/.claude/.
+        const gtdTools = path.join(__dirname, '..', 'get-tasks-done', 'bin', 'gtd-tools.cjs');
+        // Coerce usedPct to a safe number in case bridge file is malformed
+        const safeUsedPct = Number(usedPct) || 0;
+        const stoppedAt = `context exhaustion at ${safeUsedPct}% (${new Date().toISOString().split('T')[0]})`;
+        spawn(
+          process.execPath,
+          [gtdTools, 'state', 'record-session', '--stopped-at', stoppedAt],
+          { cwd, detached: true, stdio: 'ignore' }
+        ).unref();
+        warnData.criticalRecorded = true;
+        // Persist the sentinel so subsequent debounce cycles don't re-fire
+        fs.writeFileSync(warnPath, JSON.stringify(warnData));
+      } catch { /* non-critical — don't let state recording break the hook */ }
+    }
+
+    // Build advisory warning message (never use imperative commands that
+    // override user preferences — see #884)
+    let message;
+    if (isCritical) {
+      message = isGtdActive
+        ? `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Context is nearly exhausted. Do NOT start new complex work or write handoff files — ' +
+          'GTD state is already tracked in STATE.md. Inform the user so they can run ' +
+          '/gtd:pause-work at the next natural stopping point.'
+        : `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Context is nearly exhausted. Inform the user that context is low and ask how they ' +
+          'want to proceed. Do NOT autonomously save state or write handoff files unless the user asks.';
+    } else {
+      message = isGtdActive
+        ? `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Context is getting limited. Avoid starting new complex work. If not between ' +
+          'defined plan steps, inform the user so they can prepare to pause.'
+        : `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Be aware that context is getting limited. Avoid unnecessary exploration or ' +
+          'starting new complex work.';
+    }
+
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: process.env.GEMINI_API_KEY ? "AfterTool" : "PostToolUse",
+        additionalContext: message
+      }
+    };
+
+    process.stdout.write(JSON.stringify(output));
+  } catch (e) {
+    // Silent fail -- never block tool execution
+    process.exit(0);
+  }
+});

package/hooks/dist/gtd-phase-boundary.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# gtd-hook-version: {{GTD_VERSION}}
+# gtd-phase-boundary.sh — PostToolUse hook: detect .planning/ file writes
+# Outputs a reminder when planning files are modified outside normal workflow.
+# Uses Node.js for JSON parsing (always available in GTD projects, no jq dependency).
+#
+# OPT-IN: This hook is a no-op unless config.json has hooks.community: true.
+# Enable with: "hooks": { "community": true } in .planning/config.json
+
+# Check opt-in config — exit silently if not enabled
+if [ -f .planning/config.json ]; then
+  ENABLED=$(node -e "try{const c=require('./.planning/config.json');process.stdout.write(c.hooks?.community===true?'1':'0')}catch{process.stdout.write('0')}" 2>/dev/null)
+  if [ "$ENABLED" != "1" ]; then exit 0; fi
+else
+  exit 0
+fi
+
+INPUT=$(cat)
+
+# Extract file_path from JSON using Node (handles escaping correctly)
+FILE=$(echo "$INPUT" | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{process.stdout.write(JSON.parse(d).tool_input?.file_path||'')}catch{}})" 2>/dev/null)
+
+# Emit a structured JSON envelope (#2974). additionalContext carries the
+# user-visible reminder text; the typed `planning_modified` boolean and
+# `file_path` let tests assert on the structured contract without grepping.
+PLANNING_MODIFIED="false"
+if [[ "$FILE" == *.planning/* ]] || [[ "$FILE" == .planning/* ]]; then
+  PLANNING_MODIFIED="true"
+fi
+
+if [ "$PLANNING_MODIFIED" = "true" ]; then
+  node -e '
+    const file = process.argv[1];
+    const additionalContext = ".planning/ file modified: " + file + "\n" +
+      "Check: Should STATE.md be updated to reflect this change?";
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PostToolUse",
+        additionalContext,
+        planning_modified: true,
+        file_path: file,
+      },
+    }));
+  ' "$FILE"
+fi
+
+exit 0