@ktpartners/dgs-platform 2.6.2

package/deliver-great-systems/workflows/write-spec.md

@@ -0,0 +1,450 @@
+<purpose>
+Draft a structured PRD spec from pending ideas, send through cross-LLM review, and finalize. Supports interactive mode (collaborative drafting with user) and auto mode (idea IDs required, no interaction). Covers the full spec lifecycle: idea selection, PRD generation, review loop, and finalization.
+</purpose>
+
+<context_tier>planning</context_tier>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="initialize" priority="first">
+Load planning context:
+
+```bash
+INIT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs init milestone-op)
+```
+
+Extract: `project_root` as needed by the workflow.
+
+Load planning-tier context files:
+
+```bash
+TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" context load-tier planning --raw 2>/dev/null)
+```
+</step>
+
+<step name="parse_arguments">
+Check `$ARGUMENTS` for flags and positional arguments.
+
+- If `--auto` detected: set `mode = auto`
+- Otherwise: set `mode = interactive`
+- Extract positional numbers as `selected_ids` (e.g., `1 3 5` from `/dgs:write-spec 1 3 5 --auto`)
+
+Examples:
+- `/dgs:write-spec` -> interactive mode, no pre-selected ideas
+- `/dgs:write-spec 1 3` -> interactive mode, ideas 1 and 3 pre-selected
+- `/dgs:write-spec 1 3 --auto` -> auto mode, ideas 1 and 3
+</step>
+
+<step name="load_ideas">
+Fetch pending ideas:
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs ideas list --state pending --orphan-check
+```
+
+Parse JSON result for `ideas` array and `counts`.
+
+If no pending ideas exist:
+```
+No pending ideas found. Run /dgs:add-idea to capture ideas first.
+```
+Stop execution.
+</step>
+
+<step name="select_ideas">
+**If `selected_ids` provided from args:**
+- Filter the loaded ideas to those matching the provided IDs.
+- Validate each ID exists and is in pending state. Error if any ID not found.
+
+**If `mode = interactive` and no IDs provided:**
+- Display pending ideas in a numbered list:
+  ```
+  ## Pending Ideas
+
+  | # | ID | Title | Tags |
+  |---|-----|-------|------|
+  | 1 | 001 | Auto review reminders | automation, reviews |
+  | 2 | 003 | Dashboard analytics | analytics, ui |
+  ```
+- Use AskUserQuestion: "Which ideas should this spec cover? (enter numbers, comma-separated, e.g. 1,3,5)"
+- Parse response into selected idea IDs.
+
+**If `mode = auto` and no IDs provided:**
+- Error: "Auto mode requires idea IDs as arguments. Usage: /dgs:write-spec 1 3 --auto"
+- Stop execution.
+
+**Bundle size warning (interactive mode only):**
+If more than 5 ideas selected, warn:
+```
+You selected N ideas. Specs with more than 5 source ideas tend to be too broad. Continue? (yes/no)
+```
+Use AskUserQuestion. If "no", return to selection.
+
+**Read full content** of each selected idea file for use in PRD generation.
+
+**Load enrichment context** for each selected idea:
+
+For each selected idea, after reading its full content:
+a. Check if the idea file contains a `## Discussion Log` section. If so, extract that section content as discussion context. Count the number of `### ` entries within it as `discussion_session_count`.
+b. Check if the idea file contains a `## Research Log` section. If so, extract that section content as research context. Count the number of `### ` entries within it as `research_run_count`. Also look for `**Document:**` references in the Research Log entries.
+c. For each `**Document:**` path found (the value after the `**Document:**` label), use the Read tool to load the full research document. The detailed comparison tables and feasibility analysis in research documents produce a richer PRD. If the research document does not exist on disk, skip it gracefully (no error).
+d. Store the enrichment context (discussion content, research content, research documents) per idea for use in the `clarify_and_draft` step.
+
+If none of the selected ideas have a Discussion Log or Research Log section, display:
+```
+Tip: Run /dgs:develop-idea first to discuss and research ideas for a richer spec.
+```
+Then proceed normally. Only show this tip when ALL selected ideas lack enrichment. If at least one idea has enrichment, skip the tip.
+
+**Load supporting documents** from each selected idea's `docs/` directory:
+
+For each selected idea:
+a. Derive the idea's docs path: `${project_root}/ideas/pending/{idea_slug}/docs/` where `idea_slug` is derived from the idea filename (strip numeric prefix and .md suffix, e.g., `005-retry-logic.md` -> `retry-logic`).
+   Alternative path: check if ideas use a flat structure where docs are at `${project_root}/docs/ideas/pending/{slug}-*.md`.
+b. If the docs/ directory exists, list all files in it:
+   ```bash
+   ls "${IDEA_DOCS_DIR}/" 2>/dev/null
+   ```
+c. For each file found:
+   - **Text files** (.md, .txt, .json, .yaml, .yml): Read using the Read tool and store as idea doc context.
+   - **Image files** (.png, .jpg, .jpeg, .gif, .svg, .webp): Read using the Read tool directly -- Claude can process these as multimodal input. Cap at 5 images per idea to manage context size.
+   - **PDF files** (.pdf): Check for a `.txt` sidecar first (e.g., `report.pdf` -> `report.txt`). If sidecar exists, read the sidecar. If no sidecar, read up to 5 pages of the PDF directly using the Read tool with pages parameter.
+   - **Other files**: Skip silently.
+d. If docs/ directory does not exist: silent skip -- no docs is normal.
+e. If any file in docs/ is unreadable: skip silently.
+
+Store the loaded doc content per idea. In the `clarify_and_draft` step, use idea docs as additional source material: idea docs are loaded first (source material), then spec docs (refinements).
+
+**Check for already-covered ideas:**
+
+For each selected idea, check if it appears as a source idea in any approved (final-status) spec:
+
+```bash
+APPROVED_SPECS=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" specs list --status final --raw 2>/dev/null || echo '{"specs":[]}')
+```
+
+For each approved spec in the JSON result, check its `source_ideas` array. If any selected idea's filename matches a source_idea in an approved spec:
+
+```
+Note: The following selected ideas are already covered by approved specs:
+- Idea #{id} "{title}" is a source for spec "{spec_title}" ({spec_filename})
+
+These ideas may already be addressed. Proceeding with spec creation.
+```
+
+Detection uses exact idea ID/filename match only -- only warn if the same idea ID appears as a source in an approved spec. No fuzzy matching.
+
+This is a warning only -- do not block spec creation. Proceed normally after displaying the warning.
+</step>
+
+<step name="load_codebase_context">
+Read all codebase analysis documents:
+
+```bash
+ls ${project_root}/codebase/*.md 2>/dev/null
+```
+
+For each `.md` file found in the codebase directory, read it using the Read tool. This replaces the previous 3-file hardcoded list and ensures all codebase docs (including CONCERNS.md, TESTING.md, INTEGRATIONS.md, CONVENTIONS.md, etc.) are loaded when they exist.
+
+If the codebase directory does not exist or contains no `.md` files, proceed without codebase context.
+
+These provide context for the Technical Considerations section of the spec.
+
+Additionally, load all markdown files from `${project_root}/docs/product/` (if the directory exists) to inform the spec with product-level context such as target architecture and product summary:
+
+```bash
+ls ${project_root}/docs/product/*.md 2>/dev/null
+```
+
+Read each markdown file found. These provide product-level context (target architecture, product summary, design guidelines, etc.) that should inform Problem, Goals, Requirements, and Technical Considerations sections of the spec. If the directory does not exist or contains no markdown files, proceed without it.
+</step>
+
+<step name="clarify_and_draft">
+Generate the PRD spec using selected idea content and codebase context.
+
+**Interactive mode:**
+Before writing each major section, Claude may ask the user clarifying questions via AskUserQuestion to fill gaps in the idea descriptions. For example:
+- "The idea mentions 'auto-review' -- should this cover only automated code reviews or also manual review reminders?"
+- "Any specific metrics you care about for Success Metrics?"
+
+Use judgment on which sections need clarification vs. can be inferred from the idea text.
+
+**Auto mode:**
+Generate all sections without asking clarifying questions. Infer missing details from the idea text and codebase context.
+
+**The spec body MUST include all these sections in order:**
+
+1. `## Problem` -- synthesized from idea problem statements
+2. `## Goals` -- concrete goals derived from ideas
+3. `## Non-Goals` -- explicit boundaries (important for review auto-rejection)
+4. `## User Stories` -- "As a [user], I want [X] so that [Y]" format
+5. `## Requirements` with subsections:
+   - `### P0 (Must Have)`
+   - `### P1 (Should Have)`
+   - `### P2 (Nice to Have)`
+6. `## Success Metrics` -- measurable outcomes
+7. `## Open Questions` -- unknowns to resolve
+8. `## Technical Considerations` -- informed by codebase analysis
+9. `## Review History` -- empty initially, populated by review loop
+
+**Enrichment Context (when available):**
+
+If selected ideas have Discussion Log and/or Research Log content:
+- Weave discussion insights naturally into Problem, Goals, and Requirements sections
+- Use research findings to inform Technical Considerations and identify implementation approaches
+- Discussion decisions should be reflected as requirements (P0 or P1) unless there's good reason to diverge
+- Research recommendations inform Technical Considerations but are not automatically locked decisions
+- If discussion and research findings contradict each other, flag the conflict explicitly in Open Questions and note both positions
+- Add a metadata line at the bottom of the PRD body: `Informed by: Discussion (N sessions), Research (N runs)` with actual counts from the enrichment data. Omit this line entirely if no enrichment was available
+
+Generate a title for the spec that captures the overall scope of the selected ideas.
+
+Set `title`, `body` (the full PRD markdown), and `source_ideas` (list of idea filenames like "001-slug.md").
+</step>
+
+<step name="save_draft">
+Save the draft spec via dgs-tools:
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs specs create --title "$title" --body "$body" --source-ideas "$source_ideas_comma_separated"
+```
+
+Parse JSON result to get `id`, `filename`, `path`.
+
+Add the initial Refinement Log entry:
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs specs add-log-entry --id "$id" --date "$(date +%Y-%m-%d)" --version "1.0" --action Created --summary "Drafted from ideas $idea_ids via /dgs:write-spec"
+```
+
+Commit the draft:
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: draft $id from ideas $idea_ids" --files ${project_root}/specs/$filename
+```
+
+Store `SPEC_ID` and `FILENAME` for subsequent steps.
+</step>
+
+<step name="auto_search">
+After the draft is saved, run an automatic search to surface related content.
+
+**1. Build search query:**
+Use Claude's judgment to extract the best search signal from the spec. Good sources: spec title, key terms from the Problem section, or P0 requirement keywords. Construct a concise search query (2-4 words) that captures the core topic.
+
+**2. Run search with tight result cap:**
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs search "QUERY" --max-per-type 3 --include-rejected --raw
+```
+
+Note: Use `--include-rejected` for auto-search so rejected ideas with similar topics are surfaced (they may have been rejected for good reason -- useful context).
+
+**3. Check for matches:**
+Parse JSON result. If `total_matches === 0`: skip display entirely (no empty block). Proceed to review_draft step.
+
+**4. Check for duplicate specs:**
+In the specs results, compare each spec title against the current spec title. If a spec with very similar title or overlapping content exists (and it is not the spec just created), flag it:
+```
+Warning: This may overlap with existing spec: "{spec_title}" ({spec_path})
+```
+
+**5. Display related content block (only if matches found):**
+
+```
+## Related Content Found
+
+The following existing content may be relevant to this spec:
+
+### Ideas
+- **{title}** -- {one-line snippet}
+
+### Specs
+- **{title}** ({status}) -- {one-line snippet}
+
+### Documents
+- **{title}** -- {one-line snippet}
+```
+
+Only show type sections that have results. No counts header -- go straight to grouped results. Showing top 3 per type.
+
+**6. User action (interactive mode only):**
+Use AskUserQuestion: "Review the related content above. Type **continue** to proceed as-is, or **revise** to update the spec based on these findings."
+
+If **revise**: Claude applies user-directed changes to the spec, rewrites the file, commits, then returns to this step to re-run search with updated content.
+If **continue** (or auto mode): proceed to review_draft step.
+</step>
+
+<step name="review_draft" condition="mode = interactive">
+**Skipped in auto mode.**
+
+Display the draft spec content to the user for review.
+
+Use AskUserQuestion: "Review the draft spec above. Type **approve** to send to reviewers, or describe changes you'd like."
+
+- If **approved**: proceed to Step 9 (run_review_loop).
+- If **changes requested**: Claude applies the requested edits to the spec body, rewrites the file on disk, re-displays the updated spec, and asks for approval again. Loop until approved.
+
+After approval, commit any changes:
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: revise draft $SPEC_ID" --files ${project_root}/specs/$FILENAME
+```
+</step>
+
+<step name="run_review_loop">
+Load the review loop reference for detailed mechanics:
+@~/.claude/deliver-great-systems/references/spec-review-loop.md
+
+**1. Load review config:**
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs review-config
+```
+
+Parse JSON result. If `has_any_key = false`: warn "No review API keys configured. Edit review-keys.json in your planning root to add OpenAI or Gemini keys. Skipping review." and proceed to finalization step.
+
+**2. Update spec status to review:**
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs specs update-status --id "$SPEC_ID" --status review
+```
+
+**3. Initialize tracking:**
+
+- `round = 0`
+- `total_tokens = { openai: { prompt: 0, completion: 0 }, gemini: { prompt: 0, completion: 0 } }`
+- `rejected_items_history = []` (for convergence detection across rounds)
+
+**4. Loop** (while round < max_rounds):
+
+   a. Increment round.
+   b. Read current spec content from disk (it may have changed from prior round edits).
+   c. Send to available reviewers in parallel using the API call patterns from the reference doc. Issue both curl commands via parallel Bash tool calls.
+   d. Handle failures per reference doc error handling rules (retry once, then mark failed).
+   e. Parse feedback items from each reviewer's response. Each item: section, severity, feedback text, reviewer name.
+   f. **Auto-reject Non-Goal contradictions:** read the `## Non-Goals` section, reject any feedback that suggests adding something explicitly listed as a Non-Goal. Disposition: `rejected-non-goal`.
+   g. **Check convergence:** compare rejected items against `rejected_items_history`. If an item (or substantially similar item) was rejected in the previous round too, move the concern to `## Open Questions` tagged as "From review: [concern]". Disposition: `moved-to-open-questions`.
+   h. **Apply accepted feedback:** Claude reads each remaining item and decides whether to apply it by modifying the spec body. Disposition: `accepted` (with change description) or `no-action` (with reason).
+   i. Build round history entry with all dispositions in the review history table format.
+   j. Append review history to spec:
+   ```bash
+   node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs specs append-review --id "$SPEC_ID" --entry "$HISTORY_MD"
+   ```
+   k. Update token totals from response usage metadata.
+   l. **Check exit conditions:**
+      - No changes applied (all items rejected, no-action, or moved-to-open-questions) -> EXIT
+      - Green-only (all reviewers responded "LGTM" or no actionable feedback) -> EXIT
+      - Max rounds reached -> EXIT
+   If none met: continue to next round.
+
+**5. Display token/cost summary:**
+
+```
+Review complete (N rounds).
+Tokens: OpenAI [X prompt + Y completion] | Gemini [X prompt + Y completion]
+Estimated cost: ~$X.XX
+```
+
+**6. Commit updated spec:**
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: review $SPEC_ID (N rounds)" --files ${project_root}/specs/$FILENAME
+```
+</step>
+
+<step name="finalize">
+
+### User Approval (interactive mode only)
+
+If `mode = interactive`:
+
+1. Display the final spec content to the user (after review loop has completed).
+2. Use AskUserQuestion: "The spec is ready for finalization. Review above and choose:\n- **approve** -- finalize the spec\n- **reject** -- send back for another review round"
+3. If **reject**: go back to Step 9 (run_review_loop) for one more round, then return here.
+4. If **approve**: proceed to finalization.
+
+If `mode = auto`: skip approval, proceed directly to finalization.
+
+### Execute Finalization
+
+1. Finalize the spec via dgs-tools:
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs specs finalize --id "$SPEC_ID"
+```
+
+Parse JSON result: `{ id, filename, status, ideas_moved, ideas_failed, research_docs_moved }`.
+
+2. If any `ideas_failed`: warn user "Note: Some source ideas could not be moved to done: [list]. They may already be in done state or were deleted."
+
+3. If any `research_docs_moved`: mention it in the summary: "Research documents moved to done: [list]"
+
+4. The finalize command auto-commits. No separate commit needed.
+
+### Post-Finalization Routing
+
+Display a summary and routing options:
+
+```
+Spec finalized: $TITLE
+Status: final
+Source ideas moved to done: $IDEAS_MOVED
+Research documents moved to done: $RESEARCH_DOCS_MOVED (if any)
+
+What would you like to do next?
+1. Create a new project from this spec -> /dgs:new-project
+2. Add a milestone to an existing project -> /dgs:new-milestone
+3. Nothing for now -- the spec is saved and ready when you are
+```
+
+In interactive mode, use AskUserQuestion: "Choose 1, 2, or 3 (or just press enter to defer):"
+
+- If **1**: Tell user "Run `/dgs:new-project` and reference spec `$FILENAME` during project creation."
+- If **2**: Tell user "Run `/dgs:new-milestone` and reference spec `$FILENAME` during milestone creation."
+- If **3** or empty/enter: Output "Spec saved. You can find it at `${project_root}/specs/$FILENAME`."
+
+In `--auto` mode: skip the routing question, just output the summary with the three options listed for reference.
+</step>
+
+</process>
+
+<auto_mode_summary>
+## Auto Mode Flow (`--auto`)
+
+When invoked with `--auto` and idea IDs (e.g., `/dgs:write-spec 1 3 --auto`):
+
+1. Ideas selected from args (no interactive selection)
+2. PRD drafted without clarifying questions
+3. Draft saved without user review
+4. Auto-search runs and displays related content (no user prompt)
+5. Review loop runs normally (same as interactive)
+6. Spec finalized without user approval
+7. Summary displayed with routing options (no interactive prompt)
+
+Auto mode still runs the full review loop -- only user interaction steps are skipped.
+</auto_mode_summary>
+
+<success_criteria>
+- [ ] Arguments parsed correctly (idea IDs, --auto flag)
+- [ ] Pending ideas loaded and validated
+- [ ] Idea selection works in both interactive and auto modes
+- [ ] Bundle size warning shown for >5 ideas (interactive only)
+- [ ] Codebase context loaded for Technical Considerations
+- [ ] PRD includes all 9 required sections in order
+- [ ] Draft saved via specs create with correct source_ideas
+- [ ] Draft committed to git
+- [ ] Auto-search surfaces related content after draft save
+- [ ] Auto-search only displays when matches found (no empty block)
+- [ ] Auto-search flags potential duplicate specs
+- [ ] Draft review loop works in interactive mode (approve/edit cycle)
+- [ ] Review loop sends to configured reviewers and processes feedback
+- [ ] Enrichment context loaded from Discussion Log, Research Log, and linked research documents
+- [ ] Enrichment tip shown only when all selected ideas lack enrichment
+- [ ] PRD metadata line shows enrichment source counts when available
+- [ ] Finalization sets status to final
+- [ ] Source ideas moved to done
+- [ ] Research documents moved to done alongside ideas
+- [ ] Post-finalization routing options presented
+</success_criteria>

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

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// Check for DGS 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();
+const cacheDir = path.join(homeDir, '.claude', 'cache');
+const cacheFile = path.join(cacheDir, 'dgs-update-check.json');
+
+// VERSION file locations (check project first, then global)
+const projectVersionFile = path.join(cwd, '.claude', 'deliver-great-systems', 'VERSION');
+const globalVersionFile = path.join(homeDir, '.claude', 'deliver-great-systems', 'VERSION');
+
+// Ensure cache directory exists
+if (!fs.existsSync(cacheDir)) {
+  fs.mkdirSync(cacheDir, { recursive: true });
+}
+
+// Run check in background (spawn background process, windowsHide prevents console flash)
+const child = spawn(process.execPath, ['-e', `
+  const fs = require('fs');
+  const { execSync } = require('child_process');
+
+  const cacheFile = ${JSON.stringify(cacheFile)};
+  const projectVersionFile = ${JSON.stringify(projectVersionFile)};
+  const globalVersionFile = ${JSON.stringify(globalVersionFile)};
+
+  // Check project directory first (local install), then global
+  let installed = '0.0.0';
+  try {
+    if (fs.existsSync(projectVersionFile)) {
+      installed = fs.readFileSync(projectVersionFile, 'utf8').trim();
+    } else if (fs.existsSync(globalVersionFile)) {
+      installed = fs.readFileSync(globalVersionFile, 'utf8').trim();
+    }
+  } catch (e) {}
+
+  let latest = null;
+  try {
+    latest = execSync('npm view @ktpartners/dgs-platform version', { encoding: 'utf8', timeout: 10000, windowsHide: true }).trim();
+  } catch (e) {}
+
+  const result = {
+    update_available: latest && installed !== latest,
+    installed,
+    latest: latest || 'unknown',
+    checked: Math.floor(Date.now() / 1000)
+  };
+
+  fs.writeFileSync(cacheFile, JSON.stringify(result));
+`], {
+  stdio: 'ignore',
+  windowsHide: true,
+  detached: true  // Required on Windows for proper process detachment
+});
+
+child.unref();

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

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+// 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 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 3s (e.g. pipe issues on
+// Windows/Git Bash), exit silently instead of hanging until Claude Code
+// kills the process and reports "hook error". See #775.
+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);
+    const sessionId = data.session_id;
+
+    if (!sessionId) {
+      process.exit(0);
+    }
+
+    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 DGS is active (has .planning/STATE.md in working directory)
+    const cwd = data.cwd || process.cwd();
+    const isDgsActive = fs.existsSync(path.join(cwd, '.planning', 'STATE.md'));
+
+    // Build advisory warning message (never use imperative commands that
+    // override user preferences — see #884)
+    let message;
+    if (isCritical) {
+      message = isDgsActive
+        ? `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Context is nearly exhausted. Do NOT start new complex work or write handoff files — ' +
+          'DGS state is already tracked in STATE.md. Inform the user so they can run ' +
+          '/dgs: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 = isDgsActive
+        ? `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);
+  }
+});