@tekyzinc/gsd-t 4.20.11 → 5.0.11

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [5.0.11] - 2026-07-12
+
+### Fixed — architect hook now ships + installs; de-flaked its test
+
+The M101/v5.0.10 architect-oversight hook existed only in `~/.claude/scripts/` — it was never copied into the repo, so `install`/`update-all` would not propagate it to other machines (the "propagate a tool without shipping it = silent no-op" class). This release ships it properly and hardens it.
+
+- `scripts/gsd-t-architect-oversight-guard.js`: the hook now lives in the repo (ships with the package). Added an unref'd 1500ms watchdog + a stdin `error` handler so the hook can NEVER hang and block a Write/Edit (fail-open guaranteed even if stdin never EOFs).
+- `bin/gsd-t.js`: `configureArchitectHook()` registers the PreToolUse `Write|Edit` hook via the global-package command pattern (same as the graph/read-intercept hooks); wired into `install`; removed on `uninstall`. Exported for tests.
+- `test/m101-architect-oversight-hook.test.js`: replaced the two spawn-per-assertion fail-open tests (which false-failed under full-suite CPU starvation, not a hook bug) with a source-guard assertion + installer idempotency/coexistence tests. Test resolves the repo hook copy.
+- `.gsd-t/contracts/graph-metrics-contract.md`: refreshed the `doMetrics` line citation (shifted by the installer addition).
+
+## [5.0.10] - 2026-07-12
+
+### Added — `/gsd-t-architect`: run the Architect's Oversight pass on demand
+
+A standalone command that runs the M101 Six-Stage Pass (Objective → Conflict → Reuse → Simplicity → Reuse-forecast → Risk) on **existing** work — an already-frozen plan, a messy subsystem, or a pasted tangle of problems — and produces the simplest correct solution as plain-English pseudocode, plus the traps each stage surfaces and what's already reusable. Major bump: this is the on-demand front door to design-first, reuse-first development, not an incremental command. Where the plan/milestone workflow runs the pass *while generating* a plan, this runs it as a standalone audit over work that already exists.
+
+- `commands/gsd-t-architect.md`: prose-driven command — spawns one opus analysis subagent, reasons from the code graph (reuse/duplication) and real code, not memory. Default = plan-only then offers to build; `--build` auto-builds the simplest fix; `--chat-only` skips writing a file. Always prints a findings + plan summary to the session, even in auto-build. Reuses the existing prose-command + Task-subagent pattern (`/gsd-t-status`, `/gsd-t-impact`) — no new workflow file (the doctrine obeying its own Stage 3/4).
+- `README.md` + `commands/gsd-t-help.md`: command documented.
+- `test/filesystem.test.js`: command counts 54→55 / 48→49.
+
 ## [4.20.11] - 2026-07-12
 
 ### Added — M101: Architect's Oversight Doctrine

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v4.20.11** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v5.0.11** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
 
 **Eliminates context rot** — task-level fresh dispatch (one subagent per task, ~10-20% context each) means compaction never triggers.
 **Compaction-proof debug loops** — `gsd-t headless --debug-loop` runs test-fix-retest cycles as separate `claude -p` sessions. A JSONL debug ledger persists all hypothesis/fix/learning history across fresh sessions. Anti-repetition preamble injection prevents retrying failed hypotheses. Escalation tiers (sonnet → opus → human) and a hard iteration ceiling enforced externally.
@@ -200,6 +200,7 @@ This will replace changed command files, back up your CLAUDE.md if customized, a
 | `/gsd-t-partition` | Decompose into domains + contracts | In wave |
 | `/gsd-t-plan` | Create atomic task lists per domain (tasks auto-split to fit one context window) | In wave |
 | `/gsd-t-impact` | Analyze downstream effects | In wave |
+| `/gsd-t-architect` | Run the Architect's Oversight Six-Stage Pass on existing work — finds the simplest solution + reuse + traps, as plain-English pseudocode (plan-only; `--build` to auto-build) | Manual |
 | `/gsd-t-execute` | Run tasks — task-level fresh dispatch, worktree isolation, adaptive replanning | In wave |
 | `/gsd-t-test-sync` | Sync tests with code changes | In wave |
 | `/gsd-t-qa` | QA agent — test generation, execution, gap reporting | Auto-spawned |

package/bin/gsd-t.js

@@ -485,6 +485,15 @@ const READ_INTERCEPT_HOOK_MARKER = "gsd-t-read-intercept";
 const READ_INTERCEPT_HOOK_COMMAND =
   'bash -c \'[ -f "$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-read-intercept.js" ] && node "$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-read-intercept.js" || true\'';
 
+// M101 — architect-oversight PreToolUse hook on Write|Edit. Same global-package
+// pattern as the intercept hooks: runs the script from the globally-installed
+// package, and the script fails-open (no-op) in non-GSD-T projects / prose writes,
+// so it is safe to register globally with a Write|Edit matcher. It reminds the model
+// to run the Architect's Oversight Six-Stage Pass before writing code (M101).
+const ARCHITECT_HOOK_MARKER = "gsd-t-architect-oversight-guard";
+const ARCHITECT_HOOK_COMMAND =
+  'bash -c \'[ -f "$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-architect-oversight-guard.js" ] && node "$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-architect-oversight-guard.js" || true\'';
+
 // Append entries to {projectDir}/.gitignore. Each entry added only if absent.
 // Idempotent. Returns true if any entries were added, false otherwise.
 function ensureGitignoreEntries(projectDir, entries) {
@@ -928,6 +937,60 @@ function configureReadInterceptHook(settingsPath) {
   return { installed: true, action };
 }
 
+// M101 — register the architect-oversight PreToolUse hook (matcher "Write|Edit").
+// Idempotent: find-by-marker, refresh stale command, else add. Mirrors the M98
+// read-intercept installer but on PreToolUse. The script fails-open so this is
+// safe globally (silent in non-GSD-T projects and on prose/doc writes).
+function configureArchitectHook(settingsPath) {
+  const targetPath = settingsPath || SETTINGS_JSON;
+  let settings = {};
+  if (fs.existsSync(targetPath)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(targetPath, "utf8"));
+      if (!settings || typeof settings !== "object") settings = {};
+    } catch {
+      warn("settings.json has invalid JSON — cannot configure architect hook");
+      return { installed: false, action: "noop" };
+    }
+  }
+  if (!settings.hooks) settings.hooks = {};
+  if (!Array.isArray(settings.hooks.PreToolUse)) settings.hooks.PreToolUse = [];
+
+  const cmd = ARCHITECT_HOOK_COMMAND;
+  let action = "noop";
+  let found = false;
+  for (const entry of settings.hooks.PreToolUse) {
+    if (!entry || !Array.isArray(entry.hooks)) continue;
+    for (const h of entry.hooks) {
+      if (!h || typeof h.command !== "string") continue;
+      if (h.command === cmd || h.command.includes(ARCHITECT_HOOK_MARKER)) {
+        found = true;
+        if (h.command !== cmd) { h.command = cmd; action = "updated"; }
+        if (entry.matcher !== "Write|Edit") { entry.matcher = "Write|Edit"; action = action === "noop" ? "updated" : action; }
+      }
+    }
+  }
+  if (!found) {
+    settings.hooks.PreToolUse.push({
+      matcher: "Write|Edit",
+      hooks: [{ type: "command", command: cmd }],
+    });
+    action = "added";
+  }
+  if (action === "noop") return { installed: true, action: "noop" };
+  if (isSymlink(targetPath)) {
+    warn("Skipping settings.json write — target is a symlink");
+    return { installed: false, action: "noop" };
+  }
+  try {
+    fs.writeFileSync(targetPath, JSON.stringify(settings, null, 2));
+  } catch (e) {
+    warn(`Failed to write settings.json: ${e.message}`);
+    return { installed: false, action: "noop" };
+  }
+  return { installed: true, action };
+}
+
 // M98 — remove the GSD-T intercept PostToolUse hooks (grep + read) from settings.json.
 // Used during uninstall. Marker-based; leaves all other hooks intact. Idempotent.
 function removeInterceptHooks(settingsPath) {
@@ -941,17 +1004,28 @@ function removeInterceptHooks(settingsPath) {
     warn("settings.json has invalid JSON — cannot remove intercept hooks");
     return false;
   }
-  if (!settings.hooks || !Array.isArray(settings.hooks.PostToolUse)) return false;
+  if (!settings.hooks) return false;
 
-  const markers = [GRAPH_INTERCEPT_HOOK_MARKER, READ_INTERCEPT_HOOK_MARKER];
-  const before = settings.hooks.PostToolUse.length;
-  settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter((entry) => {
-    if (!entry || !Array.isArray(entry.hooks)) return true;
-    return !entry.hooks.some(
-      (h) => h && typeof h.command === "string" && markers.some((m) => h.command.includes(m))
-    );
-  });
-  if (before - settings.hooks.PostToolUse.length === 0) return false;
+  const postMarkers = [GRAPH_INTERCEPT_HOOK_MARKER, READ_INTERCEPT_HOOK_MARKER];
+  const preMarkers = [ARCHITECT_HOOK_MARKER];
+  let removed = 0;
+
+  const stripByMarkers = (arr, markers) => {
+    if (!Array.isArray(arr)) return arr;
+    const before = arr.length;
+    const out = arr.filter((entry) => {
+      if (!entry || !Array.isArray(entry.hooks)) return true;
+      return !entry.hooks.some(
+        (h) => h && typeof h.command === "string" && markers.some((m) => h.command.includes(m))
+      );
+    });
+    removed += before - out.length;
+    return out;
+  };
+
+  settings.hooks.PostToolUse = stripByMarkers(settings.hooks.PostToolUse, postMarkers);
+  settings.hooks.PreToolUse = stripByMarkers(settings.hooks.PreToolUse, preMarkers);
+  if (removed === 0) return false;
 
   if (isSymlink(targetPath)) {
     warn("Skipping settings.json write — target is a symlink");
@@ -1915,6 +1989,13 @@ async function doInstall(opts = {}) {
     else info("Read-intercept hook already configured");
   }
 
+  const archHook = configureArchitectHook(SETTINGS_JSON);
+  if (archHook.installed) {
+    if (archHook.action === "added") success("Architect-oversight hook added (Six-Stage Pass reminder before writing code — M101)");
+    else if (archHook.action === "updated") success("Architect-oversight hook refreshed");
+    else info("Architect-oversight hook already configured");
+  }
+
   heading("Graph Engine (CGC)");
   installCgc();
 
@@ -4909,6 +4990,7 @@ module.exports = {
   // M97/M98: intercept hook installers
   configureGraphInterceptHook,
   configureReadInterceptHook,
+  configureArchitectHook,
   removeInterceptHooks,
   promptForApiKeyIfMissing,
   resolveApiKeyEnvVar,

package/commands/gsd-t-architect.md

@@ -0,0 +1,135 @@
+# GSD-T: Architect — Run the Architect's Oversight Six-Stage Pass on Existing Work
+
+You are the **architect**. You assess a plan, a subsystem, or a tangle of problems the user
+points you at, and you find the **simplest correct solution** — reusing what already exists,
+surfacing the traps, and writing the answer in plain-English pseudocode the user can approve
+BEFORE any code is written.
+
+This is a standalone, on-demand run of the **Architect's Oversight Doctrine** (see the project
+`CLAUDE.md` / `~/.claude/CLAUDE.md` § Architect's Oversight, and
+`.gsd-t/contracts/architects-oversight-contract.md`). Use it when a plan already exists (or is
+half-formed) and you want it interrogated for simplicity + reuse before building.
+
+Unlike the plan/milestone workflow (which runs the Six-Stage Pass *while generating* a plan),
+this command runs it as a **standalone pass over existing work** — an already-frozen plan, a
+messy subsystem, or a pasted description of problems.
+
+---
+
+## Argument Parsing
+
+Parse `$ARGUMENTS`:
+- **First positional** = `$TARGET` — what to assess. Either a plain-English description
+  ("the feed scanning stalls — image watcher, completeness, comment finder"), a file/dir path,
+  or "the current plan" (→ read `.gsd-t/domains/*/tasks.md` + `.gsd-t/progress.md` Current Milestone).
+- **`--build`** — after producing the plan, AUTO-BUILD the simplest solution in the same run
+  (do not stop to ask). Default (no flag): produce the plan, then OFFER to build.
+- **`--chat-only`** — report in the session only; do NOT write a pseudocode file to disk.
+  Default: write the pseudocode artifact to `.gsd-t/pseudocode/`.
+
+If `$TARGET` is empty, ask the user what to assess. Do not guess.
+
+---
+
+## Behavior contract (what the user asked for)
+
+1. **Default = plan, then offer to build.** Produce the assessment + plan, then end by asking
+   "Build the simplest solution now?" — unless `--build` was passed, in which case auto-build.
+2. **`--build` = auto-build after planning.** Assess → plan → implement the simplest solution,
+   without pausing — BUT still print the findings + plan summary to the session first.
+3. **ALWAYS print a session summary** — even in auto-build mode. The user scans the conversation
+   for anything that catches their eye while it keeps moving. Never silently proceed.
+
+---
+
+## Step 1: Launch the architect via a Task subagent
+
+Give the assessment a fresh context window. Spawn ONE Task subagent (`model: opus`) — this is
+high-stakes design judgment, top tier. Pass it the target and this protocol.
+
+**Before spawning**, gather evidence sources so the subagent reasons from facts, not memory:
+- If a code graph exists (`.gsd-t/graph.db`), the subagent uses `gsd-t graph` for reuse/caller
+  queries (Stage 3 + Stage 5 duplication check). If absent, it greps/reads and says so LOUDLY
+  (reuse-detection is reduced — never a silent "nothing found").
+- Read the relevant code the target names (or the plan files).
+
+---
+
+## Step 2: The subagent runs the Six-Stage Pass (with EVIDENCE, never conviction)
+
+The subagent works through the six stages IN ORDER. Each can kill or reshape the plan. Every
+"am I sure?" is answered by looking (grep / Read / graph), not by asserting.
+
+1. **OBJECTIVE** — What is the core objective, in one plain sentence? Why is it the objective?
+   (Often the traps shrink once this is pinned down.)
+2. **CONFLICT** — Does solving this conflict with another objective? Must a previously-built
+   piece be re-examined/re-planned?
+3. **REUSE** — Have I already accomplished any piece of this? Can I reuse the **process**, or
+   the **output** (a value already computed/stored)? *Query the graph, not memory.* This is the
+   stage that kills redundant work (e.g. re-deriving a value already stored locally).
+   **Also — is this the SAME pattern repeated elsewhere?** If the target is one instance of a
+   bug, search for the other instances (one fix for a class beats N fixes for N instances).
+4. **SIMPLICITY** — What is the simplest, most efficient solution? Prove it's simplest.
+5. **REUSE FORECAST & DUPLICATION** — For anything new: HIGH reuse likelihood (core entity /
+   recurs / pure transform) → build clean + extractable; LOW → simplest inline. If a similar
+   thing exists: same JOB → extract a shared core (do NOT mutate the working original); if
+   stability forbids touching it → build new BUT register the duplication (a "reuse-candidate"
+   note) so it's visible, never a silent rogue twin.
+6. **RISK** — Does the proposed fix create security or stability/scalability risk? **And prove
+   the simpler fix actually works** — if the plan says "handled elsewhere / picked up later,"
+   VERIFY that's true; do not assert self-healing you haven't checked. (This is the trap that
+   hides inside a simplification.)
+
+A stage the subagent cannot answer with evidence is a HALT — surface it as an open question for
+the user, do not paper over it with a guess.
+
+---
+
+## Step 3: The subagent produces the output
+
+**A — Plain-English pseudocode** (the artifact), in the house style — title + one-line purpose,
+`CURRENT` (what it does today) and `PROPOSED` (the simplest fix) blocks, `# plain comment` inline,
+a summary table, near-zero preamble. For each CURRENT block, say **why it does what it does now**
+— and flag explicitly if it's a "got complicated over time" accretion (mechanisms stacked by
+successive fixes). Unless `--chat-only`, write it to `.gsd-t/pseudocode/PseudoCode-<Target>.md`.
+
+**B — Session summary** (always printed, even under `--build`):
+- **Core objective** (one line)
+- **Is this a "complicated over time" issue?** (yes/no + the accretion history if yes)
+- **What's reusable** (process or a stored output already available)
+- **Same pattern elsewhere?** (other instances of the bug/design found)
+- **Simplest solution** (one paragraph)
+- **Traps surfaced** (each stage's kill/risk finding — especially the Stage-6 "does the fix
+  really self-heal?" check)
+- **Open questions** (any HALT stages needing the user)
+
+---
+
+## Step 4: Build decision
+
+- **No `--build` flag (default):** end with the plain-English summary and ask:
+  *"Build the simplest solution now?"* — offer it, do not proceed.
+- **`--build` flag:** proceed to implement the simplest solution immediately (still after
+  printing the summary). Follow the normal build discipline — smallest change that hits the
+  crux, Pre-Commit Gate, run affected tests. Report what was built.
+
+---
+
+## Document Ripple
+
+The underlying assessment updates (when it writes / when a build follows):
+- `.gsd-t/pseudocode/PseudoCode-<Target>.md` — the plain-English design (unless `--chat-only`).
+- `.gsd-t/progress.md` Decision Log — one line recording the architect run + verdict.
+- If `--build` produced code: the standard Pre-Commit Gate ripple (contracts, docs, tests) for
+  whatever the build touched.
+
+---
+
+## Notes
+
+- **This command plans; it does not force a build.** The default keeps the architect a pure
+  "think before build" gate. `--build` is the explicit opt-in to act on its own conclusion.
+- **Reuse over rebuild** (the doctrine obeying itself): this command is prose-driven and spawns
+  a single analysis subagent — it does NOT add a new workflow file. It reuses the existing
+  prose-command + Task-subagent pattern (like `/gsd-t-status`, `/gsd-t-impact`).
+- Standalone command — no successor in the Next-Up map.

package/commands/gsd-t-help.md

@@ -241,6 +241,13 @@ Use these when user asks for help on a specific command:
 - **Creates**: `.gsd-t/impact-report.md`
 - **Use when**: Before making changes, to understand what might break
 
+### architect
+- **Summary**: Run the Architect's Oversight Six-Stage Pass (Objective → Conflict → Reuse → Simplicity → Reuse-forecast → Risk) on existing work — an already-frozen plan, a messy subsystem, or a pasted tangle of problems. Finds the simplest correct solution, what's already reusable (process or a stored value), and the traps each stage surfaces — written as plain-English pseudocode you can approve before any code.
+- **Auto-invoked**: No (standalone, on-demand)
+- **Args**: `/gsd-t-architect "<what to assess>"` — plus `--build` (auto-build the simplest fix after planning) and `--chat-only` (report in session, don't write a pseudocode file).
+- **Creates**: `.gsd-t/pseudocode/PseudoCode-<Target>.md` (unless `--chat-only`)
+- **Use when**: A plan already exists (or is half-formed) and you want it interrogated for simplicity + reuse before building; or a subsystem "got complicated over time" and you want the simplest version. Default is plan-only, then it offers to build.
+
 ### execute
 - **Summary**: Run tasks from plan, solo or with agent teams
 - **Auto-invoked**: Yes (in wave, after impact)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "4.20.11",
+  "version": "5.0.11",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 54 slash commands with headless-by-default workflow spawning, unattended supervisor relay with event stream, graph-powered code analysis, real-time agent dashboard, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/scripts/gsd-t-architect-oversight-guard.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * GSD-T PreToolUse hook (Write|Edit) — Architect's Oversight trigger (M101).
+ *
+ * The Architect's Oversight Doctrine lives in ~/.claude/CLAUDE.md, but a doctrine
+ * carried in context can be MISSED under load. This hook fires the TRIGGER at the
+ * exact moment it matters — right before code is written/edited — and injects a
+ * ONE-LINE pointer back to the doctrine. It carries NO nuance (that stays in
+ * CLAUDE.md); it only guarantees the Six-Stage Pass is CONSIDERED before a build.
+ *
+ * Design (mirrors the doctrine's §Enforcement three-layer split):
+ *   - CLAUDE.md  = the definition (what the doctrine IS)
+ *   - THIS hook  = the trigger    (don't forget it right now, no context bloat)
+ *   - workflow   = the execution  (actually run the stages, with evidence)
+ *
+ * Receives JSON on stdin: { tool_name, tool_input: { file_path, ... }, cwd, ... }
+ * Emits (stdout, PreToolUse additionalContext): a single reminder line, or nothing.
+ *
+ * NON-NEGOTIABLE: fail-open. Never block the tool, never throw, never exit non-zero.
+ * A malformed payload, missing field, or any error → silent pass-through (exit 0,
+ * no output). This hook can only ADD a reminder; it can never stop a write.
+ *
+ * Scope gates (emit ONLY when all hold), to avoid noise:
+ *   1. GSD-T project — cwd contains .gsd-t/ (matches the auto-route/profile gate).
+ *   2. The target is CODE, not prose — skip .md / .txt / pseudocode / docs, since
+ *      the doctrine's own artifacts (CLAUDE.md, pseudocode, contracts) are writes
+ *      too, and reminding while writing the reminder is noise. Code = the moment
+ *      the Binvoice waste would have been caught.
+ *
+ * Zero-dep by design: runs from ~/.claude/scripts where the package may be absent.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+// One line. A pointer, not the doctrine. Keeps context cost ~nil.
+const REMINDER =
+  "[GSD-T ARCHITECT] About to write/edit code — run the Architect's Oversight " +
+  "Six-Stage Pass FIRST (Objective → Conflict → Reuse[query the graph] → " +
+  "Simplicity → Reuse-forecast → Risk), each answered with evidence not conviction. " +
+  "Is this the simplest design, and does something reusable already exist? " +
+  "See ~/.claude/CLAUDE.md § Architect's Oversight Doctrine.";
+
+// File extensions that are PROSE/config, not code — skip the reminder for these.
+// (The doctrine's own artifacts are markdown; reminding while authoring them is noise.)
+const PROSE_EXT = new Set([
+  ".md", ".markdown", ".txt", ".rst", ".adoc",
+  ".json", ".yaml", ".yml", ".toml", ".lock",
+  ".csv", ".tsv", ".svg", ".png", ".jpg", ".jpeg", ".gif", ".pdf",
+]);
+
+/**
+ * Decide whether to emit the reminder for a given cwd + target file.
+ * Pure + total: never throws, returns a boolean.
+ * @param {string} cwd
+ * @param {string} filePath — the Write/Edit target
+ * @returns {boolean}
+ */
+function shouldRemind(cwd, filePath) {
+  try {
+    if (!cwd || typeof cwd !== "string") return false;
+    // Gate 1 — GSD-T project only.
+    if (!fs.existsSync(path.join(cwd, ".gsd-t"))) return false;
+    // No target path → can't classify → stay quiet (fail-open toward silence).
+    if (!filePath || typeof filePath !== "string") return false;
+
+    const lower = filePath.toLowerCase();
+    const ext = path.extname(lower);
+
+    // Gate 2 — skip prose/config/asset writes (incl. the doctrine's own artifacts).
+    if (PROSE_EXT.has(ext)) return false;
+    // Skip anything under a docs/ or pseudocode/ tree even if code-extensioned.
+    if (/[\\/](docs|pseudocode)[\\/]/.test(lower)) return false;
+
+    return true;
+  } catch (_) {
+    return false; // fail-open: any error → no reminder, never block
+  }
+}
+
+if (require.main === module) {
+  let input = "";
+  let done = false;
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (c) => { input += c; });
+
+  const finish = () => {
+    if (done) return; // run once — whichever of end/error/watchdog fires first
+    done = true;
+    try {
+      let data = null;
+      try { data = JSON.parse(input); } catch (_) { process.exit(0); }
+      if (!data || typeof data !== "object") process.exit(0);
+
+      const cwd = (typeof data.cwd === "string" && data.cwd) ? data.cwd : process.cwd();
+      const ti = data.tool_input && typeof data.tool_input === "object" ? data.tool_input : {};
+      const filePath = typeof ti.file_path === "string" ? ti.file_path : "";
+
+      if (shouldRemind(cwd, filePath)) {
+        process.stdout.write(REMINDER + "\n");
+      }
+    } catch (_) {
+      // Belt-and-suspenders: never block a write.
+    }
+    process.exit(0);
+  };
+
+  process.stdin.on("end", finish);
+  process.stdin.on("error", finish); // stdin read error → fail-open, never hang
+  // Watchdog: if stdin never delivers EOF (spawn-under-load edge, closed pipe),
+  // proceed anyway with whatever we have. A hook must NEVER hang and block a write.
+  const wd = setTimeout(finish, 1500);
+  if (wd.unref) wd.unref(); // don't keep the event loop alive solely for the watchdog
+}
+
+module.exports = { shouldRemind, REMINDER };