@curdx/flow 2.2.0 → 2.2.3

package/cli/doctor.js

@@ -8,6 +8,7 @@ import {
 } from "./utils.js";
 import { buildDoctorReport } from "./lib/doctor-report.js";
 import {
+  applyDoctorFixes,
   collectDoctorData,
   createDoctorContext,
   printDoctorSummary,
@@ -21,6 +22,13 @@ export async function doctor(args = []) {
   log.title("🏥 CurdX-Flow Health Check");
 
   const doctorData = await collectDoctorData();
+  if (context.fix) {
+    log.info("Applying safe fixes...");
+    const fixes = await applyDoctorFixes(doctorData);
+    if (fixes.length === 0) {
+      log.info("No automatic fixes available for the current environment");
+    }
+  }
   const report = buildDoctorReport(doctorData);
 
   renderReportLines(report.lines);

package/cli/help.js

@@ -17,6 +17,8 @@ ${color.bold("COMMANDS")}
                              when the plugin body is bundled)
 
   ${color.cyan("doctor")}    Check health (claude CLI, plugin, MCPs, recommended)
+            --fix            Apply safe runtime fixes (bun/uv PATH symlinks)
+            --verbose        Show raw plugin list details
 
   ${color.cyan("upgrade")}   Update curdx-flow and recommended plugins to latest
 

package/cli/lib/doctor-report.js

@@ -12,6 +12,110 @@ function pluginErrorDetails(plugin) {
   return Array.isArray(plugin?.errors) ? plugin.errors : [];
 }
 
+function projectSettingsWarningDetails(warning) {
+  if (warning?.scope === "local") {
+    if (warning.kind === "invalid-local-setting") {
+      return [
+        "settings.local.json is the highest-precedence repo-scoped settings surface on this machine",
+        "fix the JSON shape or remove the local override if Claude behaves unexpectedly",
+      ];
+    }
+
+    if (warning.kind === "required-plugin-disabled") {
+      return [
+        "settings.local.json overrides project and user plugin preferences on this machine",
+        "remove the false entry or enable the required companion plugin locally",
+      ];
+    }
+
+    if (warning.kind === "flow-runtime-blocker") {
+      return [
+        "settings.local.json has higher precedence than .claude/settings.json and can break CurDX-Flow only on this machine",
+        "remove the local blocker or add explicit exceptions for curdx-flow workflows",
+      ];
+    }
+
+    return [
+      "settings.local.json overrides shared project settings on this machine",
+      "fix or remove the local override if Claude behaves differently from the rest of the team",
+    ];
+  }
+
+  if (!warning?.kind) {
+    return [
+      "project settings are shared with collaborators",
+      "prefer deny rules for .env/secrets and avoid bypassPermissions defaults",
+    ];
+  }
+
+  if (warning.kind === "ignored-project-setting" || warning.kind === "managed-only-setting") {
+    return [
+      "Claude Code will ignore this at project scope or only honor it from managed settings",
+      "move it to user settings, settings.local.json, or managed settings as appropriate",
+    ];
+  }
+
+  if (warning.kind === "invalid-project-setting") {
+    return [
+      "Claude Code expects this setting to follow the official settings.json shape",
+      "fix the value shape or remove the key from shared project settings",
+    ];
+  }
+
+  if (warning.kind === "required-plugin-disabled") {
+    return [
+      "project enabledPlugins has higher precedence than user plugin preferences",
+      "remove the false entry or enable the required companion plugin for this project",
+    ];
+  }
+
+  if (
+    warning.kind === "shared-script-setting" ||
+    warning.kind === "shared-env-setting" ||
+    warning.kind === "shared-mcp-auto-approve" ||
+    warning.kind === "shared-hook-policy" ||
+    warning.kind === "shared-sandbox-policy"
+  ) {
+    return [
+      "project settings are shared with collaborators",
+      "avoid shared settings that run scripts, inject env vars, narrow hooks, or change sandbox behavior for every collaborator",
+    ];
+  }
+
+  if (warning.kind === "skill-shell-disabled") {
+    return [
+      "Claude Code replaces inline skill shell output with a disabled placeholder when this policy is active",
+      "keep it only if your team intentionally bans dynamic shell-backed skill content",
+    ];
+  }
+
+  if (warning.kind === "low-effort-project-setting") {
+    return [
+      "project effortLevel applies to main-thread planning and review turns",
+      "prefer high/xhigh for CurDX-Flow planning and verification-heavy workflows",
+    ];
+  }
+
+  if (warning.kind === "flow-runtime-blocker") {
+    return [
+      "CurDX-Flow relies on Claude Code hooks, Agent dispatch, AskUserQuestion, Monitor plus Bash/Read/Edit tooling, and sonnet/opus model aliases",
+      "move restrictive policy to a narrower scope or add explicit exceptions for curdx-flow workflows",
+    ];
+  }
+
+  if (warning.kind === "deprecated-setting") {
+    return [
+      "deprecated settings are still accepted for compatibility but should be migrated",
+      "prefer the current official replacement before the old key is removed",
+    ];
+  }
+
+  return [
+    "project settings are shared with collaborators",
+    "prefer deny rules for .env/secrets and avoid bypassPermissions defaults",
+  ];
+}
+
 export function buildDoctorReport({
   claudeVersionValue,
   nodeVersion,
@@ -20,8 +124,12 @@ export function buildDoctorReport({
   mcps = [],
   userMcpConfig,
   runtimeStatus,
+  runtimeEnvironment,
   cwd,
   projectState,
+  projectMcpConfig,
+  projectTeamConfig,
+  projectClaudeSettings,
 }) {
   const lines = [];
   const sections = [];
@@ -191,6 +299,16 @@ export function buildDoctorReport({
     for (const [name, status] of Object.entries(runtimeStatus)) {
       if (status.status === "ok") {
         pushSectionLine(runtimeSection, "ok", `${name.padEnd(22)} visible on PATH`);
+      } else if (status.status === "linkable") {
+        pushSectionLine(
+          runtimeSection,
+          "warn",
+          `${name.padEnd(22)} installed but not on PATH`,
+          [
+            `detected at ${status.path}`,
+            "run: npx @curdx/flow doctor --fix",
+          ]
+        );
       } else if (status.status === "linked") {
         pushSectionLine(runtimeSection, "ok", `${name.padEnd(22)} auto-linked ${status.link} → ${status.path}`);
       } else if (status.status === "missing") {
@@ -206,12 +324,27 @@ export function buildDoctorReport({
           runtimeSection,
           "err",
           `${name.padEnd(22)} installed but not on PATH`,
-          [`add export PATH="${dir}:$PATH" to your shell rc`]
+          [
+            `add export PATH="${dir}:$PATH" to your shell rc`,
+            "then rerun: npx @curdx/flow doctor",
+          ]
         );
       }
     }
   }
 
+  if (runtimeEnvironment?.entries?.length > 0) {
+    const runtimeEnvSection = createSection("Runtime environment:");
+    for (const entry of runtimeEnvironment.entries) {
+      pushSectionLine(
+        runtimeEnvSection,
+        entry.level || "info",
+        entry.text,
+        entry.details || []
+      );
+    }
+  }
+
   const localProjectSection = createSection("Local project:");
   if (projectState?.exists) {
     pushSectionLine(localProjectSection, "ok", `.flow/                ${cwd}`);
@@ -224,5 +357,127 @@ export function buildDoctorReport({
     pushSectionLine(localProjectSection, "info", ".flow/                not a curdx-flow project (run: curdx-flow init)");
   }
 
+  const projectMcpSection = createSection("Project MCP config:");
+  if (projectMcpConfig?.misplacedExists) {
+    pushSectionLine(
+      projectMcpSection,
+      projectMcpConfig.exists ? "warn" : "err",
+      `.claude/.mcp.json      ignored by Claude Code`,
+      [
+        "project MCP config must live at repo root as .mcp.json",
+        "move .claude/.mcp.json → .mcp.json, then reopen /mcp or rerun doctor",
+      ]
+    );
+  }
+
+  if (projectMcpConfig?.exists) {
+    if (projectMcpConfig.invalid) {
+      pushSectionLine(
+        projectMcpSection,
+        "err",
+        `.mcp.json            invalid JSON`,
+        [
+          projectMcpConfig.parseError,
+          "fix the JSON syntax, then run /mcp or npx @curdx/flow doctor again",
+        ]
+      );
+    } else if (projectMcpConfig.shapeError) {
+      pushSectionLine(
+        projectMcpSection,
+        "err",
+        `.mcp.json            unsupported shape`,
+        [
+          projectMcpConfig.shapeError,
+          'expected: { "mcpServers": { "<name>": { ... } } }',
+        ]
+      );
+    } else {
+      pushSectionLine(
+        projectMcpSection,
+        "ok",
+        `.mcp.json            ${projectMcpConfig.serverCount} server(s) declared`
+      );
+
+      for (const warning of projectMcpConfig.relativePathWarnings || []) {
+        pushSectionLine(
+          projectMcpSection,
+          "warn",
+          `${warning.serverName.padEnd(22)} relative path in ${warning.field}`,
+          [
+            `value: ${warning.value}`,
+            "Claude Code resolves relative MCP paths against the launch directory, not .mcp.json",
+            "use an absolute path or a PATH executable such as npx / uvx",
+            "debug: claude --debug mcp",
+          ]
+        );
+      }
+    }
+  } else if (!projectMcpConfig?.misplacedExists) {
+    pushSectionLine(projectMcpSection, "info", ".mcp.json            not present");
+  }
+
+  const projectTeamsSection = createSection("Project agent teams:");
+  if (projectTeamConfig?.exists) {
+    pushSectionLine(
+      projectTeamsSection,
+      "warn",
+      `.claude/teams/teams.json ignored by Claude Code`,
+      [
+        "official agent-teams docs say project directories do not have a recognized team config surface",
+        "remove the file or move team configuration to the supported user-level agent-teams runtime",
+      ]
+    );
+  } else {
+    pushSectionLine(projectTeamsSection, "info", ".claude/teams/teams.json not present");
+  }
+
+  const projectSettingsSection = createSection("Project Claude settings:");
+  if (projectClaudeSettings?.exists) {
+    if (projectClaudeSettings.invalid) {
+      pushSectionLine(
+        projectSettingsSection,
+        "err",
+        `.claude/settings.json invalid JSON`,
+        [projectClaudeSettings.parseError]
+      );
+    } else if ((projectClaudeSettings.warnings || []).length > 0) {
+      pushSectionLine(projectSettingsSection, "warn", ".claude/settings.json needs review");
+      for (const warning of projectClaudeSettings.warnings) {
+        pushSectionLine(
+          projectSettingsSection,
+          "warn",
+          warning.message,
+          projectSettingsWarningDetails(warning)
+        );
+      }
+    } else {
+      pushSectionLine(projectSettingsSection, "ok", ".claude/settings.json conservative");
+    }
+  } else {
+    pushSectionLine(projectSettingsSection, "info", ".claude/settings.json not present");
+  }
+
+  if (projectClaudeSettings?.localExists) {
+    pushSectionLine(projectSettingsSection, "info", ".claude/settings.local.json present (local overrides)");
+    if (projectClaudeSettings.localInvalid) {
+      pushSectionLine(
+        projectSettingsSection,
+        "err",
+        ".claude/settings.local.json invalid JSON",
+        [projectClaudeSettings.localParseError]
+      );
+    } else if ((projectClaudeSettings.localWarnings || []).length > 0) {
+      pushSectionLine(projectSettingsSection, "warn", ".claude/settings.local.json affects the local runtime");
+      for (const warning of projectClaudeSettings.localWarnings) {
+        pushSectionLine(
+          projectSettingsSection,
+          "warn",
+          warning.message,
+          projectSettingsWarningDetails(warning)
+        );
+      }
+    }
+  }
+
   return { lines, sections, errors, warnings };
 }

package/cli/lib/frontmatter.js

@@ -0,0 +1,44 @@
+import { readFileSync } from "node:fs";
+import YAML from "yaml";
+
+function formatYamlErrors(errors) {
+  return errors.map((error) => error.message).join("; ");
+}
+
+export function extractFrontmatterBlock(text, sourceLabel = "frontmatter") {
+  const match = text.match(/^---\n([\s\S]*?)\n---(?:\n|$)/);
+  if (!match) {
+    throw new Error(`${sourceLabel}: missing YAML frontmatter`);
+  }
+
+  return match[1];
+}
+
+export function parseFrontmatterBlock(block, sourceLabel = "frontmatter") {
+  const document = YAML.parseDocument(block, {
+    strict: true,
+    uniqueKeys: true,
+  });
+
+  if (document.errors.length > 0) {
+    throw new Error(`${sourceLabel}: invalid YAML (${formatYamlErrors(document.errors)})`);
+  }
+
+  const value = document.toJS();
+  if (value == null) return {};
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${sourceLabel}: frontmatter must parse to an object`);
+  }
+
+  return value;
+}
+
+export function readFrontmatter(filePath) {
+  const text = readFileSync(filePath, "utf-8");
+  const block = extractFrontmatterBlock(text, filePath);
+  return parseFrontmatterBlock(block, filePath);
+}
+
+export function readFrontmatterFields(filePath) {
+  return Object.keys(readFrontmatter(filePath));
+}

package/cli/lib/json-schema.js

@@ -0,0 +1,57 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import Ajv from "ajv";
+
+const ajv = new Ajv({
+  allErrors: true,
+  allowUnionTypes: true,
+  strict: false,
+});
+
+const validatorCache = new Map();
+
+function formatParams(params = {}) {
+  if (params.missingProperty) return ` missingProperty=${params.missingProperty}`;
+  if (params.additionalProperty) return ` additionalProperty=${params.additionalProperty}`;
+  return "";
+}
+
+export function readJsonFile(filePath) {
+  return JSON.parse(readFileSync(filePath, "utf-8"));
+}
+
+export function formatAjvErrors(errors = []) {
+  return errors.map((error) => {
+    const where = error.instancePath || error.schemaPath || "(root)";
+    return `${where}: ${error.message}${formatParams(error.params)}`;
+  });
+}
+
+function getSchemaValidator(schemaPath) {
+  const absPath = resolve(schemaPath);
+  if (validatorCache.has(absPath)) return validatorCache.get(absPath);
+
+  const schema = readJsonFile(absPath);
+  const validate = ajv.compile(schema);
+  const entry = { absPath, schema, validate };
+  validatorCache.set(absPath, entry);
+  return entry;
+}
+
+export function validateAgainstSchemaFile(schemaPath, data) {
+  const { validate } = getSchemaValidator(schemaPath);
+  const valid = Boolean(validate(data));
+  return {
+    valid,
+    errors: valid ? [] : formatAjvErrors(validate.errors),
+  };
+}
+
+export function validateSchemaFile(schemaPath) {
+  const schema = readJsonFile(resolve(schemaPath));
+  const valid = ajv.validateSchema(schema);
+  return {
+    valid,
+    errors: valid ? [] : formatAjvErrors(ajv.errors),
+  };
+}

package/cli/lib/runtime.js

@@ -52,15 +52,18 @@ function findSymlinkDir() {
   return null;
 }
 
-export function ensureRuntimeInPath(cmd, candidates) {
+function getRuntimeStatus(cmd, candidates, { repair = false } = {}) {
   if (has(cmd)) return { status: "ok" };
-
   const realPath = findRuntime(candidates);
   if (!realPath) return { status: "missing" };
 
   const linkDir = findSymlinkDir();
   if (!linkDir) return { status: "path-unwritable", path: realPath };
 
+  if (!repair) {
+    return { status: "linkable", path: realPath, link: join(linkDir, cmd) };
+  }
+
   const linkPath = join(linkDir, cmd);
   if (existsSync(linkPath)) {
     try {
@@ -81,6 +84,21 @@ export function ensureRuntimeInPath(cmd, candidates) {
   }
 }
 
+export function inspectRuntimeInPath(cmd, candidates) {
+  return getRuntimeStatus(cmd, candidates, { repair: false });
+}
+
+export function ensureRuntimeInPath(cmd, candidates) {
+  return getRuntimeStatus(cmd, candidates, { repair: true });
+}
+
+export function inspectClaudeMemRuntimes() {
+  return {
+    bun: inspectRuntimeInPath("bun", BUN_CANDIDATES),
+    uv: inspectRuntimeInPath("uv", UV_CANDIDATES),
+  };
+}
+
 export function ensureClaudeMemRuntimes() {
   return {
     bun: ensureRuntimeInPath("bun", BUN_CANDIDATES),

package/cli/utils.js

@@ -32,4 +32,9 @@ export {
   parsePluginListJson,
   readUserMcpConfig,
 } from "./lib/claude.js";
-export { ensureClaudeMemRuntimes, ensureRuntimeInPath } from "./lib/runtime.js";
+export {
+  ensureClaudeMemRuntimes,
+  ensureRuntimeInPath,
+  inspectClaudeMemRuntimes,
+  inspectRuntimeInPath,
+} from "./lib/runtime.js";

package/gates/adversarial-review-gate.md

@@ -17,7 +17,7 @@ depends_on: []
 
 - /curdx-flow:review command
 - Before Phase transitions (requirements → design, design → tasks)
-- Before code merge (/curdx-flow:ship)
+- Before code merge or human PR/release handoff
 - Enabled by default in Enterprise mode
 
 ---

package/gates/security-gate.md

@@ -14,7 +14,7 @@ depends_on: []
 ## Trigger Timing
 
 - When the `security-audit` skill runs
-- Before `/curdx-flow:ship` (auto-triggered, Phase 6+)
+- Before human PR/release handoff, after `/curdx-flow:verify` and `/curdx-flow:review`
 - When committing specs involving auth / payments / PII
 
 ---
@@ -154,7 +154,7 @@ pnpm audit
 
 ### Blocking Items
 
-- If SR-01 ~ SR-05 are found → block immediately, prohibit `/curdx-flow:ship`
+- If SR-01 ~ SR-05 are found → block immediately; do not hand off for PR/release
 - Must fix or explicitly exempt (record in STATE.md as tech debt + commitment to fix before release)
 
 ### Warning Items

package/gates/test-quality-gate.md

@@ -0,0 +1,59 @@
+---
+gate: test-quality-gate
+category: standard-mode
+severity: blocking
+depends_on: []
+---
+
+# Test Quality Gate
+
+A green test suite is not enough. Tests must exercise real behavior and fail for the right reason.
+
+## Blocking Findings
+
+Flag as blocking when a test is the only evidence for an FR/AC and any of these hold:
+
+1. **Mock-only behavior**
+   - Assertions only check mock calls (`toHaveBeenCalled`, `calledWith`, spy counts).
+   - The real module/function under test is never invoked.
+   - The test would still pass if the production implementation were empty.
+
+2. **Mock setup dominates evidence**
+   - Mock/stub/spy setup lines are more than 3x real behavioral assertions.
+   - The test mostly restates fixture wiring instead of asserting output, state, persistence, or user-visible behavior.
+
+3. **Skipped or inert tests**
+   - `it.skip`, `describe.skip`, `test.skip`, `xit`, `pending`, or equivalent on covered behavior.
+   - Test has no assertions and no meaningful side-effect check.
+
+4. **Implementation-biased regression**
+   - Test was added after implementation without evidence of RED failure when the task claims TDD.
+   - Test asserts internal private structure instead of externally observable behavior.
+
+5. **Missing cleanup for stateful mocks**
+   - Stateful mocks/spies are used across tests without `afterEach` cleanup (`restoreAllMocks`, `clearAllMocks`, sandbox restore, etc.).
+   - Shared mock state can leak between tests.
+
+## Acceptable Mock Usage
+
+Mocks are acceptable when they isolate a boundary and the assertion still verifies real behavior:
+
+- Network/payment/email provider mocked, but service logic and error handling are real.
+- Clock/randomness mocked to make deterministic assertions.
+- Database mocked only when a separate integration test covers persistence behavior.
+
+## Evidence Checklist
+
+For each FR/AC test evidence, record:
+
+- Test file and test name.
+- What real code path is invoked.
+- What behavioral assertion proves the requirement.
+- Whether the test was observed RED before GREEN when TDD is claimed.
+- Whether mocks are boundary-only or behavior-replacing.
+
+## Verdicts
+
+- `PASS`: Tests exercise real behavior with meaningful assertions.
+- `WARN`: Mock-heavy but supported by separate integration/e2e coverage.
+- `FAIL`: Mock-only/skipped/no-assertion test is used as primary evidence.

package/hooks/hooks.json

@@ -5,7 +5,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/session-start.sh"
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/session-start.sh",
+            "statusMessage": "Loading CurDX-Flow project context"
           }
         ]
       },
@@ -14,7 +15,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/inject-karpathy.sh"
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/inject-karpathy.sh",
+            "statusMessage": "Injecting CurDX-Flow engineering baseline"
           }
         ]
       }
@@ -29,6 +31,18 @@
         ]
       }
     ],
+    "SubagentStop": [
+      {
+        "matcher": "flow-(architect|brownfield-analyst|debugger|edge-hunter|executor|product-designer|planner|qa-engineer|researcher|reviewer|security-auditor|triage-analyst|ui-researcher|ux-designer|verifier|adversary)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/subagent-artifact-guard.sh",
+            "statusMessage": "Checking curdx-flow artifact landing"
+          }
+        ]
+      }
+    ],
     "PreToolUse": [
       {
         "matcher": "AskUserQuestion",

package/hooks/scripts/common.sh

@@ -33,3 +33,7 @@ emit_stop_block() {
   local reason="${1:-}"
   printf '{"decision":"block","reason":%s}\n' "$(json_escape "$reason")"
 }
+
+emit_subagentstop_block() {
+  emit_stop_block "${1:-}"
+}

package/hooks/scripts/session-start.sh

@@ -3,6 +3,7 @@
 # Duties:
 #   1. Daily dependency check — nudge user to `npx @curdx/flow install --all` if recommended plugins missing
 #   2. Load active spec progress into session context
+#   3. Persist stable CurDX-Flow environment hints for this session
 #
 # Design notes:
 #   - Idempotent: marker file tracks last check date
@@ -45,12 +46,15 @@ if [ "$LAST_CHECK" != "$TODAY" ]; then
     ADDITIONAL_CONTEXT+="## CurDX-Flow Recommended Plugins Check\n\nThe following recommended plugins were not detected: **${JOINED}**\n\nRun \`npx @curdx/flow install --all\` for interactive one-shot install. Run \`npx @curdx/flow doctor\` for the full health report.\n\n"
   fi
 
-  echo "$TODAY" > "$MARKER" 2>/dev/null || true
+  { echo "$TODAY" > "$MARKER"; } 2>/dev/null || true
 fi
 
 # ---------- 2. Load .flow/ state (if project is a flow project) ----------
 if [ -d ".flow" ]; then
   ADDITIONAL_CONTEXT+="## CurDX-Flow Project Active\n\n"
+  ADDITIONAL_CONTEXT+="- Plugin root: \`${CLAUDE_PLUGIN_ROOT:-unknown}\`\n"
+  ADDITIONAL_CONTEXT+="- Plugin data: \`${CLAUDE_PLUGIN_DATA:-$DATA_DIR}\`\n"
+  ADDITIONAL_CONTEXT+="- Best practice: write long agent artifacts to disk first; keep final assistant summaries short.\n\n"
 
   if [ -f ".flow/PROJECT.md" ]; then
     ADDITIONAL_CONTEXT+="### Project Vision\n$(head -80 .flow/PROJECT.md)\n\n"
@@ -67,7 +71,18 @@ if [ -d ".flow" ]; then
   fi
 fi
 
-# ---------- 3. Emit hook output ----------
+# ---------- 3. Persist session environment hints ----------
+if [ -n "${CLAUDE_ENV_FILE:-}" ]; then
+  {
+    printf 'export CURDX_FLOW_PLUGIN_ROOT=%s\n' "$(json_escape "${CLAUDE_PLUGIN_ROOT:-}")"
+    printf 'export CURDX_FLOW_PLUGIN_DATA=%s\n' "$(json_escape "${CLAUDE_PLUGIN_DATA:-$DATA_DIR}")"
+    if [ -f ".flow/.active-spec" ]; then
+      printf 'export CURDX_FLOW_ACTIVE_SPEC=%s\n' "$(json_escape "$(cat .flow/.active-spec 2>/dev/null)")"
+    fi
+  } >> "$CLAUDE_ENV_FILE" 2>/dev/null || true
+fi
+
+# ---------- 4. Emit hook output ----------
 if [ -n "$ADDITIONAL_CONTEXT" ]; then
   emit_session_start_context "$ADDITIONAL_CONTEXT"
 fi