agileflow 4.0.0-alpha.1 → 4.0.0-alpha.3

package/CHANGELOG.md

@@ -3,6 +3,85 @@
 All notable changes to `agileflow` v4 are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [4.0.0-alpha.3] — 2026-04-20
+
+Flow audit fixes for the alpha.2 wizard + install path. Wiring/persistence
+came back PASS; this patch closes the test gap and fixes the safety +
+feedback gaps the audit surfaced.
+
+### Fixed
+
+- **P0 test gap** (`tests/unit/config/writer.test.js`): the per-field
+  round-trip block tests every other config field but skipped
+  `behaviors`. A future PR that drops the `behaviors:` line from
+  `writer.js`'s payload would have shipped silently. Added explicit
+  mixed-shape round-trip test (not all-true, not all-false) so the
+  serializer-loader pair is contractually pinned.
+- **P1 damage-control silent fail-open**
+  (`damage-control-bash.js`/`-edit.js`/`-write.js`): when
+  `damage-control-patterns.yaml` is missing or unreadable, all three
+  hooks used to `process.exit(0)` silently — guards disabled, no
+  signal to the user. Now emit a stderr WARNING with the error code
+  and the path. Repeated warnings on every Bash/Edit/Write are
+  intentional: they signal "fix this or disable the preset". Hooks
+  still fail-open (the contract is "block dangerous things, don't
+  block legit work just because we can't read our own config").
+- **P1 missing behaviors visibility**:
+  - `setup --yes` console output now prints `behaviors enabled: ...`
+    after the plugin list, gated on `caps.hooks` so non-Claude-Code
+    IDEs don't see a noisy line. Listed-as-CSV in the order: any
+    `loadContext, babysitDefault, damageControl, preCompactState`
+    that are `true`.
+  - Interactive `prompts.outro` now includes `behaviors active: ...`
+    or `behaviors active: (none — no hooks will run; re-run setup to
+enable)`. A user who deselected all four behaviors no longer
+    finishes the wizard celebrating "X plugins enabled" while
+    actually getting zero hooks.
+  - `agileflow update` console output mirrors the same pattern.
+  - Install spinner message changed from `Installing N plugin(s)` to
+    `Installing N plugin(s) — writing hooks, skills, mirrors` so
+    first-time users have a clearer mental model of what `.agileflow/`
+    will contain.
+- **P2 fresh-project context-loader / pre-compact-state**: when
+  `docs/09-agents/status.json` is absent (brand new project), both
+  hooks used to silently omit the stories section. Now emit
+  `(no story tracker yet — docs/09-agents/status.json not found)` so
+  Claude knows the section was reached, not skipped due to error. Also
+  surfaces `(none in progress, none ready)` when status.json exists
+  but is empty.
+
+### Tests
+
+- 305 passing (+1 from alpha.2's 304).
+
+## [4.0.0-alpha.2] — 2026-04-20
+
+Curated behavior presets — first hooks ship, but never as a free-for-all.
+
+### Added
+
+- **Behavior presets in `agileflow.config.json`** (`behaviors: { loadContext, babysitDefault, damageControl, preCompactState }`). Each preset maps 1:N to hooks declared in plugin manifests via a new `behavior: <key>` field. Disabling a preset excludes its hooks from the generated `.agileflow/hook-manifest.yaml` — the script literally does not run.
+- **Wizard step**: `pickBehaviors()` (`src/cli/wizard/behaviors-picker.js`) — Clack multiselect with all four presets pre-checked. Only shown for IDEs that support hooks (claude-code today; cursor/windsurf/codex skip it).
+- **Six behavior-gated hooks in the `core` plugin**:
+  - `context-loader` (SessionStart, gated by `loadContext`) — lean v4 replacement for v3's 79KB welcome banner. Prints stories, dirty files, and recent commits.
+  - `babysit-mentor-injector` (SessionStart, gated by `babysitDefault`) — HARD mode mentor injection. Claude defaults to the `/agileflow:babysit` mentor pattern without explicit invocation.
+  - `damage-control-bash` / `-edit` / `-write` (PreToolUse, gated by `damageControl`, `skipOnError: false`) — pattern-driven safety net (`damage-control-patterns.yaml`). Blocks `rm -rf /`, `dd to /dev/sda`, fork bombs, writes to `.env`/`.ssh/`, and similar.
+  - `pre-compact-state` (PreCompact, gated by `preCompactState`) — dumps active stories, current command, and dirty git state so they survive Claude's compaction summary.
+- **Schema + loader + writer updates**: `behaviors` is now a first-class config section. `mergeConfig` deep-merges across one level so partial user overrides don't wipe defaults.
+- **Aggregator behavior gating**: `buildHookManifest(orderedPlugins, behaviors)` filters hooks where `behaviors[entry.behavior] === false`. Missing keys treated as enabled (preserves intent of partial configs).
+- **15 new tests** covering behaviors filtering in the aggregator, behaviors-picker pure helpers, and the install-time integration test that asserts the manifest reflects the toggle map. Total: **304 passing** (+15 from alpha.1).
+
+### Changed
+
+- `installPlugins(options)` accepts a `behaviors` option threaded through to `writeAggregatedManifest`.
+- `agileflow setup` now includes a behaviors step after personalization for hook-capable IDEs.
+- `agileflow update` re-reads `behaviors` from the saved config so manual edits to `agileflow.config.json` propagate without re-running the wizard.
+- `defaultConfig()` ships with all four behaviors enabled. Users opt **out** at the wizard, never opt in.
+
+### Why curated, not free configuration
+
+Per user feedback in alpha.1: "I don't want it to be super customizable. Users would be able to customize pretty much anything." Free hook configuration (declare any event + any matcher + any script) is technically possible via the `hooks:` map, but the wizard surface is restricted to four presets. This keeps the install path predictable and prevents the v3-era anti-pattern of every plugin author shipping their own SessionStart welcome banner.
+
 ## [4.0.0-alpha.1] — Unreleased
 
 v4 Phase 1 skeleton. Not yet publishable.
@@ -254,6 +333,7 @@ The path from "green test suite" to "user can `npm i agileflow@alpha`" closes he
 - **Verified `npm pack --dry-run`** from `apps/cli/`: ships 52 files (bin/, src/, content/, README.md, LICENSE, CHANGELOG.md) — 65 KB tarball, 210 KB unpacked. Tests + vitest config + node_modules excluded.
 
 **To ship `4.0.0-alpha.1` now**:
+
 ```bash
 cd apps/cli && npm version 4.0.0-alpha.1 --no-git-tag-version
 git commit -am "release(v4): 4.0.0-alpha.1"

package/content/plugins/core/hooks/babysit-mentor-injector.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * Core hook: babysit-mentor-injector (SessionStart, HARD mode).
+ *
+ * Pre-loads the babysit mentor pattern into the session by printing
+ * its operating rules to stdout. Claude Code includes this in the
+ * session context, so Claude defaults to mentor behavior (smart
+ * AskUserQuestion at every decision point, plan mode for non-trivial
+ * tasks, expert delegation, task tracking, audits) without the user
+ * needing to type "walk me through".
+ *
+ * Disable this hook in agileflow.config.json if you want quick-edit
+ * mode by default — the agileflow-babysit-mentor skill still
+ * activates on its keyword triggers when needed.
+ *
+ * Always exits 0.
+ */
+process.stdout.write(`## AgileFlow Mentor Mode (default-on)
+
+This session has the babysit-mentor pattern enabled. Apply these
+rules unless the user explicitly opts out for a specific request:
+
+1. **Smart AskUserQuestion at every decision point.** When the work
+   reaches a meaningful choice (which task, which approach, whether
+   to commit), end the response with the AskUserQuestion tool —
+   specific options with one marked (Recommended). Never generic
+   "Continue?" / "What next?".
+
+2. **Plan mode for non-trivial implementation.** Call EnterPlanMode
+   for anything more than a typo/one-liner. Explore 3–5 files,
+   write the plan, ExitPlanMode. Skip for trivial fixes.
+
+3. **Delegate complex work to domain experts.** Use the Task tool
+   with appropriate subagent_type (database / api / ui / testing /
+   security / etc.) for complex single-domain work. Use the
+   orchestrator for multi-domain features. Use multi-expert for
+   review/analysis questions.
+
+4. **Track progress.** TaskCreate for any task with 3+ steps.
+   TaskUpdate as each completes. Don't batch.
+
+5. **Suggest a logic audit after every implementation.** After tests
+   pass, present "🔍 Run logic audit on modified files" as
+   (Recommended). 5 analyzers catch edge cases tests miss.
+
+6. **Suggest a flow audit when user-flows changed.** Plans for
+   non-trivial features must include a "Verify flow integrity"
+   step. After tests pass on flow-touching code, suggest
+   "🔄 Run flow audit" before commit.
+
+To disable mentor mode entirely: edit agileflow.config.json,
+set hooks.babysit-mentor-injector.enabled to false, run
+\`agileflow update\`.
+`);
+process.exit(0);

package/content/plugins/core/hooks/context-loader.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+/**
+ * Core hook: context-loader (SessionStart).
+ *
+ * Prints a compact project snapshot to stdout so Claude Code includes
+ * it in the session prompt. Lean v4 implementation (~200 lines, vs.
+ * v3's 79KB welcome banner). Output is pure text — no ANSI colors.
+ *
+ * Sections (ordered by load-bearing-ness for Claude):
+ *   1. Project header (cwd, agileflow version, ide)
+ *   2. Active story / epic (from docs/09-agents/status.json if present)
+ *   3. Ready stories (top 5 by priority)
+ *   4. Git state (branch, dirty files)
+ *   5. Recent commits (last 5)
+ *   6. Hook health (last 3 entries from hook-execution.jsonl)
+ *
+ * Fail-open: any read error becomes a one-line "(unavailable)" note.
+ * The hook always exits 0; orchestrator-side `skipOnError: true` is
+ * defensive belt-and-suspenders.
+ */
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const agileflowDir = path.join(projectDir, ".agileflow");
+
+/** Read JSON file, returning null on any error. */
+function readJSON(p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Run a git command; return its stdout trimmed, or null on error. */
+function git(args) {
+  try {
+    return execSync(`git ${args}`, {
+      cwd: projectDir,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/** Tail the last N JSONL entries from a file. */
+function tailJSONL(p, n) {
+  try {
+    const lines = fs.readFileSync(p, "utf8").trim().split("\n");
+    return lines
+      .slice(-n)
+      .map((l) => {
+        try {
+          return JSON.parse(l);
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+const lines = [];
+const out = (s = "") => lines.push(s);
+
+out("## AgileFlow project context");
+out("");
+
+// 1. Project header
+const config = readJSON(path.join(projectDir, "agileflow.config.json")) || {};
+const enabledPlugins = Object.entries(config.plugins || {})
+  .filter(([, v]) => v && v.enabled)
+  .map(([id]) => id);
+out(`cwd:      ${projectDir}`);
+out(`ide:      ${(config.ide && config.ide.primary) || "claude-code"}`);
+out(`plugins:  ${enabledPlugins.join(", ") || "(none)"}`);
+out(
+  `tone:     ${(config.personalization && config.personalization.tone) || "concise"}`,
+);
+out("");
+
+// 2. Active story / epic
+const status = readJSON(path.join(projectDir, "docs/09-agents/status.json"));
+if (!status) {
+  // Fresh project — no story tracker yet. Tell Claude explicitly so it
+  // knows the section was reached, not silently skipped due to error.
+  out("## Stories");
+  out("  (no story tracker yet — docs/09-agents/status.json not found)");
+  out("");
+} else if (status.stories) {
+  const inProgress = Object.entries(status.stories)
+    .filter(([, s]) => s && s.status === "in_progress")
+    .map(([id, s]) => ({ id, ...s }));
+  if (inProgress.length) {
+    out("## In progress");
+    for (const s of inProgress) {
+      out(
+        `  ${s.id} ${s.title || ""} (owner: ${s.owner || "?"}, est: ${s.estimate || "?"})`,
+      );
+    }
+    out("");
+  }
+
+  // 3. Ready stories — top 5 by priority then estimate
+  const ready = Object.entries(status.stories)
+    .filter(([, s]) => s && s.status === "ready")
+    .map(([id, s]) => ({ id, ...s }))
+    .sort((a, b) => {
+      const pa = parseInt(String(a.priority || "P9").replace("P", ""), 10);
+      const pb = parseInt(String(b.priority || "P9").replace("P", ""), 10);
+      if (pa !== pb) return pa - pb;
+      return (a.estimate || 99) - (b.estimate || 99);
+    })
+    .slice(0, 5);
+  if (ready.length) {
+    out("## Ready (top 5)");
+    for (const s of ready) {
+      out(
+        `  ${s.id} [${s.priority || "P?"} · ${s.estimate || "?"}pts] ${s.title || ""}`,
+      );
+    }
+    out("");
+  }
+
+  if (!inProgress.length && !ready.length) {
+    out("## Stories");
+    out("  (none in progress, none ready)");
+    out("");
+  }
+}
+
+// 4. Git state
+const branch = git("rev-parse --abbrev-ref HEAD");
+const dirty = git("status --short");
+if (branch) {
+  out("## Git");
+  out(`  branch:   ${branch}`);
+  if (dirty) {
+    const lines2 = dirty.split("\n").slice(0, 10);
+    out(
+      `  changes:  ${lines2.length} file(s)${dirty.split("\n").length > 10 ? " (showing first 10)" : ""}`,
+    );
+    for (const l of lines2) out(`    ${l}`);
+  } else {
+    out("  changes:  (clean)");
+  }
+  out("");
+}
+
+// 5. Recent commits
+const log = git("log --oneline -5");
+if (log) {
+  out("## Recent commits");
+  for (const l of log.split("\n")) out(`  ${l}`);
+  out("");
+}
+
+// 6. Hook health
+const hookLog = tailJSONL(
+  path.join(agileflowDir, "logs/hook-execution.jsonl"),
+  3,
+);
+if (hookLog.length) {
+  out("## Recent hook runs");
+  for (const e of hookLog) {
+    const status = e.status === "ok" ? "OK" : e.status.toUpperCase();
+    out(
+      `  ${e.timestamp || "?"} [${status}] ${e.event}/${e.hookId} (${e.durationMs || 0}ms)`,
+    );
+  }
+  out("");
+}
+
+process.stdout.write(lines.join("\n") + "\n");
+process.exit(0);

package/content/plugins/core/hooks/damage-control-bash.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * Core hook: damage-control-bash (PreToolUse, matcher: Bash).
+ *
+ * Reads damage-control-patterns.yaml and rejects Bash commands that
+ * match an `error`-severity pattern of kind `bash`. `warn`-severity
+ * patterns log but do not block.
+ *
+ * Stdin payload (Claude Code-shaped):
+ *   { tool_name: "Bash", tool_input: { command: "...", description: "..." } }
+ *
+ * Exit codes:
+ *   0  allow (default)
+ *   2  block (Claude Code surfaces stderr to the user)
+ */
+const fs = require("fs");
+const path = require("path");
+const yaml = require("js-yaml");
+
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const patternsPath = path.join(
+  projectDir,
+  ".agileflow/plugins/core/hooks/damage-control-patterns.yaml",
+);
+
+async function readStdin() {
+  const chunks = [];
+  for await (const c of process.stdin) chunks.push(c);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+async function main() {
+  const raw = await readStdin();
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    process.exit(0); // No payload, nothing to gate.
+  }
+  const command =
+    payload &&
+    payload.tool_input &&
+    typeof payload.tool_input.command === "string"
+      ? payload.tool_input.command
+      : "";
+  if (!command) process.exit(0);
+
+  let patterns = [];
+  try {
+    const parsed = yaml.load(fs.readFileSync(patternsPath, "utf8"));
+    patterns = Array.isArray(parsed && parsed.patterns) ? parsed.patterns : [];
+  } catch (err) {
+    // Fail open, but warn loudly: a missing/unreadable patterns file
+    // means every dangerous command will go through unblocked, and
+    // the user MUST notice. Repeated warnings on every Bash call are
+    // intentional — they signal "damageControl is broken, fix it or
+    // disable the preset in agileflow.config.json".
+    process.stderr.write(
+      `agileflow damage-control: WARNING — patterns file unreadable (${err.code || err.name}: ${patternsPath}). Bash safety guards are DISABLED until this is fixed.\n`,
+    );
+    process.exit(0);
+  }
+
+  for (const p of patterns) {
+    if (p.kind !== "bash") continue;
+    let re;
+    try {
+      re = new RegExp(p.regex, "i");
+    } catch {
+      continue;
+    }
+    if (re.test(command)) {
+      if (p.severity === "error") {
+        process.stderr.write(
+          `agileflow damage-control: BLOCKED — ${p.reason}\n  pattern: ${p.regex}\n  command: ${command.slice(0, 200)}\n`,
+        );
+        process.exit(2);
+      }
+      // severity: warn — log, do not block
+      process.stderr.write(`agileflow damage-control: WARN — ${p.reason}\n`);
+    }
+  }
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/content/plugins/core/hooks/damage-control-edit.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/**
+ * Core hook: damage-control-edit (PreToolUse, matcher: Edit).
+ *
+ * Reads damage-control-patterns.yaml and rejects Edit operations whose
+ * file_path matches an `error`-severity pattern of kind `edit`.
+ *
+ * Stdin payload:
+ *   { tool_name: "Edit", tool_input: { file_path: "...", old_string, new_string } }
+ *
+ * Exit codes: 0 allow, 2 block.
+ */
+const fs = require("fs");
+const path = require("path");
+const yaml = require("js-yaml");
+
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const patternsPath = path.join(
+  projectDir,
+  ".agileflow/plugins/core/hooks/damage-control-patterns.yaml",
+);
+
+async function readStdin() {
+  const chunks = [];
+  for await (const c of process.stdin) chunks.push(c);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+async function main() {
+  const raw = await readStdin();
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    process.exit(0);
+  }
+  const filePath =
+    payload &&
+    payload.tool_input &&
+    typeof payload.tool_input.file_path === "string"
+      ? payload.tool_input.file_path
+      : "";
+  if (!filePath) process.exit(0);
+
+  let patterns = [];
+  try {
+    const parsed = yaml.load(fs.readFileSync(patternsPath, "utf8"));
+    patterns = Array.isArray(parsed && parsed.patterns) ? parsed.patterns : [];
+  } catch (err) {
+    process.stderr.write(
+      `agileflow damage-control: WARNING — patterns file unreadable (${err.code || err.name}: ${patternsPath}). Edit safety guards are DISABLED until this is fixed.\n`,
+    );
+    process.exit(0);
+  }
+
+  for (const p of patterns) {
+    if (p.kind !== "edit") continue;
+    let re;
+    try {
+      re = new RegExp(p.regex, "i");
+    } catch {
+      continue;
+    }
+    if (re.test(filePath)) {
+      if (p.severity === "error") {
+        process.stderr.write(
+          `agileflow damage-control: BLOCKED edit — ${p.reason}\n  path: ${filePath}\n`,
+        );
+        process.exit(2);
+      }
+      process.stderr.write(
+        `agileflow damage-control: WARN — ${p.reason} (path: ${filePath})\n`,
+      );
+    }
+  }
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/content/plugins/core/hooks/damage-control-patterns.yaml

@@ -0,0 +1,100 @@
+# Damage control pattern library.
+#
+# The pre-Bash / pre-Edit / pre-Write hooks load this file and reject
+# tool invocations whose payload matches any pattern below. Each entry
+# explains WHY it's blocked so the error message can cite the rule.
+#
+# Pattern syntax:
+#   - `regex`: JS RegExp source (used with `new RegExp(pattern, 'i')`)
+#   - `kind`:  one of bash | edit | write — which hook applies the rule
+#   - `severity`: error (block, exit 2) | warn (allow but log warning)
+#   - `reason`: human-readable rationale shown in the block message
+#
+# Adding a pattern: keep it surgical. False positives are worse than
+# missed catches because they train users to bypass the guard.
+
+patterns:
+  # --- Catastrophic filesystem operations ---
+  - regex: 'rm\s+-[a-zA-Z]*r[a-zA-Z]*f[a-zA-Z]*\s+(/|~|\$HOME)\b'
+    kind: bash
+    severity: error
+    reason: rm -rf on / or $HOME is almost certainly a mistake — refuse outright
+
+  - regex: 'rm\s+-[a-zA-Z]*[rfRF][a-zA-Z]*\s+/\*'
+    kind: bash
+    severity: error
+    reason: rm -rf /* deletes the entire filesystem
+
+  - regex: '\bdd\s+if=.*\s+of=/dev/(sd|nvme|hd)'
+    kind: bash
+    severity: error
+    reason: dd to a raw block device wipes the disk
+
+  - regex: '\bmkfs\.\w+\s+/dev/'
+    kind: bash
+    severity: error
+    reason: mkfs on a device formats it — destroys all data
+
+  - regex: '>\s*/dev/(sd|nvme|hd)\w+'
+    kind: bash
+    severity: error
+    reason: writing directly to a block device corrupts the disk
+
+  - regex: ':\(\)\{\s*:\|:\&\s*\};:'
+    kind: bash
+    severity: error
+    reason: classic fork bomb
+
+  # --- Risky git operations ---
+  - regex: 'git\s+push\s+.*--force(\s|$)'
+    kind: bash
+    severity: warn
+    reason: force push can rewrite shared history — confirm intent
+
+  - regex: 'git\s+(reset|checkout)\s+.*--hard'
+    kind: bash
+    severity: warn
+    reason: --hard discards uncommitted work — confirm before running
+
+  - regex: 'git\s+clean\s+-[a-zA-Z]*[fdx]+'
+    kind: bash
+    severity: warn
+    reason: git clean -fdx removes untracked files including .gitignored — confirm
+
+  # --- Edit / Write path scope ---
+  # The edit/write hooks evaluate the file_path payload, not the command.
+  - regex: "^/etc/(passwd|shadow|sudoers)$"
+    kind: edit
+    severity: error
+    reason: editing system credential files would compromise the host
+
+  - regex: "^/etc/(passwd|shadow|sudoers)$"
+    kind: write
+    severity: error
+    reason: writing to system credential files would compromise the host
+
+  - regex: '\.ssh/(id_[a-z]+|authorized_keys|known_hosts)$'
+    kind: edit
+    severity: warn
+    reason: editing SSH credentials — confirm this is intentional
+
+  - regex: '\.ssh/(id_[a-z]+|authorized_keys|known_hosts)$'
+    kind: write
+    severity: warn
+    reason: writing to SSH credentials — confirm this is intentional
+
+  - regex: '\.env(\.|$)'
+    kind: write
+    severity: warn
+    reason: writing to a .env file — confirm it does not commit secrets
+
+  # --- npm / pnpm risk ---
+  - regex: 'npm\s+publish(\s|$)'
+    kind: bash
+    severity: warn
+    reason: npm publish ships to a public registry — confirm version + auth
+
+  - regex: 'rm\s+-rf?\s+(node_modules|\.git)\b'
+    kind: bash
+    severity: warn
+    reason: nuking node_modules / .git is recoverable but slow — confirm

package/content/plugins/core/hooks/damage-control-write.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * Core hook: damage-control-write (PreToolUse, matcher: Write).
+ *
+ * Mirror of damage-control-edit.js for the Write tool. Same patterns
+ * file (kind: write entries). Blocks writing system credential files,
+ * warns on writes to .ssh/ and .env*.
+ */
+const fs = require("fs");
+const path = require("path");
+const yaml = require("js-yaml");
+
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const patternsPath = path.join(
+  projectDir,
+  ".agileflow/plugins/core/hooks/damage-control-patterns.yaml",
+);
+
+async function readStdin() {
+  const chunks = [];
+  for await (const c of process.stdin) chunks.push(c);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+async function main() {
+  const raw = await readStdin();
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    process.exit(0);
+  }
+  const filePath =
+    payload &&
+    payload.tool_input &&
+    typeof payload.tool_input.file_path === "string"
+      ? payload.tool_input.file_path
+      : "";
+  if (!filePath) process.exit(0);
+
+  let patterns = [];
+  try {
+    const parsed = yaml.load(fs.readFileSync(patternsPath, "utf8"));
+    patterns = Array.isArray(parsed && parsed.patterns) ? parsed.patterns : [];
+  } catch (err) {
+    process.stderr.write(
+      `agileflow damage-control: WARNING — patterns file unreadable (${err.code || err.name}: ${patternsPath}). Write safety guards are DISABLED until this is fixed.\n`,
+    );
+    process.exit(0);
+  }
+
+  for (const p of patterns) {
+    if (p.kind !== "write") continue;
+    let re;
+    try {
+      re = new RegExp(p.regex, "i");
+    } catch {
+      continue;
+    }
+    if (re.test(filePath)) {
+      if (p.severity === "error") {
+        process.stderr.write(
+          `agileflow damage-control: BLOCKED write — ${p.reason}\n  path: ${filePath}\n`,
+        );
+        process.exit(2);
+      }
+      process.stderr.write(
+        `agileflow damage-control: WARN — ${p.reason} (path: ${filePath})\n`,
+      );
+    }
+  }
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));