agileflow 4.0.0-alpha.2 → 4.0.0-alpha.3

package/CHANGELOG.md

@@ -3,6 +3,57 @@
 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.

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

@@ -87,7 +87,13 @@ out("");
 
 // 2. Active story / epic
 const status = readJSON(path.join(projectDir, "docs/09-agents/status.json"));
-if (status && status.stories) {
+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 }));
@@ -121,6 +127,12 @@ if (status && status.stories) {
     }
     out("");
   }
+
+  if (!inProgress.length && !ready.length) {
+    out("## Stories");
+    out("  (none in progress, none ready)");
+    out("");
+  }
 }
 
 // 4. Git state

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

@@ -49,8 +49,16 @@ async function main() {
   try {
     const parsed = yaml.load(fs.readFileSync(patternsPath, "utf8"));
     patterns = Array.isArray(parsed && parsed.patterns) ? parsed.patterns : [];
-  } catch {
-    process.exit(0); // No patterns file, fail open.
+  } 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) {

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

@@ -46,7 +46,10 @@ async function main() {
   try {
     const parsed = yaml.load(fs.readFileSync(patternsPath, "utf8"));
     patterns = Array.isArray(parsed && parsed.patterns) ? parsed.patterns : [];
-  } catch {
+  } 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);
   }
 

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

@@ -42,7 +42,10 @@ async function main() {
   try {
     const parsed = yaml.load(fs.readFileSync(patternsPath, "utf8"));
     patterns = Array.isArray(parsed && parsed.patterns) ? parsed.patterns : [];
-  } catch {
+  } 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);
   }
 

package/content/plugins/core/hooks/pre-compact-state.js

@@ -43,7 +43,13 @@ out.push("## Pre-compaction state preservation");
 out.push("");
 
 const status = readJSON(path.join(projectDir, "docs/09-agents/status.json"));
-if (status && status.stories) {
+if (!status) {
+  // Fresh project — no story tracker yet. Say so explicitly so the
+  // post-compaction prompt knows the section was reached, not silently
+  // skipped due to an error.
+  out.push("Active stories: (none yet — docs/09-agents/status.json not found)");
+  out.push("");
+} else if (status.stories) {
   const inProgress = Object.entries(status.stories)
     .filter(([, s]) => s && s.status === "in_progress")
     .map(([id, s]) => `${id} ${s.title || ""}`);
@@ -51,6 +57,9 @@ if (status && status.stories) {
     out.push("Active stories:");
     for (const s of inProgress) out.push(`  - ${s}`);
     out.push("");
+  } else {
+    out.push("Active stories: (none in progress)");
+    out.push("");
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agileflow",
-  "version": "4.0.0-alpha.2",
+  "version": "4.0.0-alpha.3",
   "description": "AI-driven agile development toolkit for Claude Code — skills-first architecture with opt-in plugins (v4)",
   "keywords": [
     "agile",

package/src/cli/commands/setup.js

@@ -203,6 +203,15 @@ async function setup(options = {}) {
     );
     // eslint-disable-next-line no-console
     console.log(`  plugins enabled: ${enabled.join(", ")}`);
+    if (caps.hooks) {
+      const activeBehaviors = Object.entries(next.behaviors || {})
+        .filter(([, v]) => v)
+        .map(([k]) => k);
+      // eslint-disable-next-line no-console
+      console.log(
+        `  behaviors enabled: ${activeBehaviors.length ? activeBehaviors.join(", ") : "(none — no hooks will run)"}`,
+      );
+    }
     // eslint-disable-next-line no-console
     console.log(
       `  installed: created=${installResult.ops.created} updated=${installResult.ops.updated} unchanged=${installResult.ops.unchanged} preserved=${installResult.ops.preserved} removed=${installResult.ops.removed}`,
@@ -262,7 +271,9 @@ async function setup(options = {}) {
     .map(([id]) => id);
 
   const installSpinner = prompts.spinner();
-  installSpinner.start(`Installing ${enabledList.length} plugin(s)`);
+  installSpinner.start(
+    `Installing ${enabledList.length} plugin(s) — writing hooks, skills, mirrors`,
+  );
   const installResult = await runInstallWithFeedback(
     enabledList,
     cwd,
@@ -274,14 +285,27 @@ async function setup(options = {}) {
     `Installed: created=${installResult.ops.created} updated=${installResult.ops.updated} unchanged=${installResult.ops.unchanged} preserved=${installResult.ops.preserved} removed=${installResult.ops.removed}`,
   );
 
+  // Surface behaviors state in the outro. With behaviors gated, a user
+  // who deselected all four ends up with zero hooks running — they
+  // need to know that explicitly, not infer it from "X plugins enabled".
+  const activeBehaviors = ideCaps.hooks
+    ? Object.entries(behaviors || {})
+        .filter(([, v]) => v)
+        .map(([k]) => k)
+    : [];
+  const behaviorsLine = ideCaps.hooks
+    ? activeBehaviors.length
+      ? `behaviors active: ${activeBehaviors.join(", ")}`
+      : "behaviors active: (none — no hooks will run; re-run setup to enable)"
+    : `hooks not supported by ${ide} — behaviors skipped`;
+
   prompts.outro(
     [
       `${enabledList.length} plugin(s) enabled: ${enabledList.join(", ")}`,
+      behaviorsLine,
       installResult.ops.preserved
         ? `${installResult.ops.preserved} file(s) preserved (your edits) — review .agileflow/_cfg/updates/`
         : "",
-      "",
-      "Phase 3+ will land hooks, Core content, and the publish pipeline.",
     ]
       .filter(Boolean)
       .join("\n"),

package/src/cli/commands/update.js

@@ -18,6 +18,7 @@ const pkg = require("../../../package.json");
 const { loadConfig } = require("../../runtime/config/loader.js");
 const { discoverPlugins } = require("../../runtime/plugins/registry.js");
 const { installPlugins } = require("../../runtime/installer/install.js");
+const { capabilitiesFor } = require("../../runtime/ide/capabilities.js");
 
 /**
  * @param {{ force?: boolean }} options
@@ -68,6 +69,18 @@ async function update(options = {}) {
 
   // eslint-disable-next-line no-console
   console.log(`✓ Updated ${enabled.length} plugin(s): ${enabled.join(", ")}`);
+
+  const caps = capabilitiesFor(existing.config.ide.primary);
+  if (caps.hooks) {
+    const activeBehaviors = Object.entries(existing.config.behaviors || {})
+      .filter(([, v]) => v)
+      .map(([k]) => k);
+    // eslint-disable-next-line no-console
+    console.log(
+      `  behaviors enabled: ${activeBehaviors.length ? activeBehaviors.join(", ") : "(none — no hooks will run)"}`,
+    );
+  }
+
   // eslint-disable-next-line no-console
   console.log(
     `  created=${result.ops.created} updated=${result.ops.updated} unchanged=${result.ops.unchanged} preserved=${result.ops.preserved} removed=${result.ops.removed}`,