moflo 4.11.10-rc.9 → 4.12.0

package/dist/src/cli/commands/doctor-checks-sdd.js

@@ -7,31 +7,49 @@
  * (via the doctor registry) and, transitively, by `/eldar` (which renders the
  * healer's JSON).
  *
+ * #1301 — the check used to demand ALL three gate tokens whenever EITHER toggle
+ * was on. Because `gates.verify_before_done` defaults to `true`, a consumer who
+ * opted OUT of SDD (`sdd.default: false`) was still forced to carry the SDD
+ * implement-gate (`check-before-implement`) and failed spuriously. The required
+ * set is now decoupled per feature (see `computeSddVerifyRequirements`), and a
+ * LOCKED hook block (`moflo.hooks.locked: true`) — which moflo deliberately
+ * won't rewrite — is reported as a warn with actionable reconciliations rather
+ * than a permanently-red fail that `init --fix` can never clear.
+ *
  * Cross-platform (Rule #1): all paths via path.join; no shelling out.
  */
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { findProjectRoot } from '../services/project-root.js';
 import { loadMofloConfig } from '../config/moflo-config.js';
+import { isHookBlockLocked } from '../services/hook-block-hash.js';
 import { errorDetail } from '../shared/utils/error-detail.js';
 const NAME = 'SDD + Verify Wiring';
-/** The gate cases + hook subcommands that must be present for the feature to work. */
-const REQUIRED_GATE_CASES = ['check-before-done', 'record-verify-run', 'check-before-implement'];
-const REQUIRED_HOOK_TOKENS = ['check-before-done', 'record-verify-run', 'check-before-implement'];
-export async function checkSddVerifyWiring() {
-    const projectDir = findProjectRoot();
+/**
+ * The SDD implement-gate — required only when `sdd.default === true`. This is
+ * the gate that pauses `/flo` at the implement step for a spec/plan checkpoint.
+ */
+const SDD_GATE_CASES = ['check-before-implement'];
+const SDD_HOOK_TOKENS = ['check-before-implement'];
+/**
+ * The verify-before-done gate — required only when
+ * `gates.verify_before_done === true`. `check-before-done` blocks `gh pr create`
+ * until a `/verify` run is recorded; `record-verify-run` is the PostToolUse
+ * half that records it.
+ */
+const VERIFY_GATE_CASES = ['check-before-done', 'record-verify-run'];
+const VERIFY_HOOK_TOKENS = ['check-before-done', 'record-verify-run'];
+/**
+ * Single source of truth for what SDD/verify wiring the consumer's toggles
+ * require and what is actually present. Shared by the health check and the
+ * `--fix` handler so the fixer can honestly re-verify its own work (#1301 — the
+ * old fixer reported `applied: true` on a locked block that it never touched).
+ *
+ * Pure read-only inspection — no file writes.
+ */
+export function computeSddVerifyRequirements(projectDir = findProjectRoot()) {
     const helperGate = join(projectDir, '.claude', 'helpers', 'gate.cjs');
     const settingsPath = join(projectDir, '.claude', 'settings.json');
-    // Uninitialised project — defer to `flo init`, don't hard-fail.
-    if (!existsSync(helperGate) && !existsSync(settingsPath)) {
-        return {
-            name: NAME,
-            status: 'warn',
-            message: '.claude/ not initialised — SDD/verify wiring absent',
-            fix: 'npx moflo init',
-        };
-    }
-    // Read the two opt-in toggles (best-effort; default false).
     let sddDefault = false;
     let verifyGate = false;
     try {
@@ -42,56 +60,132 @@ export async function checkSddVerifyWiring() {
     catch {
         /* config unreadable — treat as defaults (both off) */
     }
-    const issues = [];
-    // 1. Gate logic present in the installed helper gate.cjs.
+    // Decouple the required set per feature (#1301). SDD's implement-gate is
+    // required only under sdd.default; the verify hooks only under
+    // verify_before_done. A verify-only consumer no longer drags in the SDD gate.
+    const requiredHookTokens = [
+        ...(sddDefault ? SDD_HOOK_TOKENS : []),
+        ...(verifyGate ? VERIFY_HOOK_TOKENS : []),
+    ];
+    const requiredGateCases = [
+        ...(sddDefault ? SDD_GATE_CASES : []),
+        ...(verifyGate ? VERIFY_GATE_CASES : []),
+    ];
+    const uninitialised = !existsSync(helperGate) && !existsSync(settingsPath);
+    const structural = [];
+    const missingHooks = [];
+    const missingGateCases = [];
+    let locked = false;
+    // gate.cjs — the installed helper must carry the cases for enabled features.
     if (existsSync(helperGate)) {
         try {
             const gate = readFileSync(helperGate, 'utf8');
-            const missing = REQUIRED_GATE_CASES.filter((c) => !gate.includes(`case '${c}'`));
-            if (missing.length > 0)
-                issues.push(`gate.cjs missing: ${missing.join(', ')}`);
+            for (const c of requiredGateCases) {
+                if (!gate.includes(`case '${c}'`))
+                    missingGateCases.push(c);
+            }
         }
         catch (e) {
-            issues.push(`cannot read gate.cjs: ${errorDetail(e)}`);
+            structural.push(`cannot read gate.cjs: ${errorDetail(e)}`);
         }
     }
-    else {
-        issues.push('.claude/helpers/gate.cjs not found');
+    else if (!uninitialised) {
+        structural.push('.claude/helpers/gate.cjs not found');
     }
-    // 2. Hooks wired in settings.json.
+    // settings.json — the hook wiring plus the lock sentinel.
     if (existsSync(settingsPath)) {
         try {
-            const settings = readFileSync(settingsPath, 'utf8');
-            const missing = REQUIRED_HOOK_TOKENS.filter((t) => !settings.includes(t));
-            if (missing.length > 0)
-                issues.push(`settings.json missing hooks: ${missing.join(', ')}`);
+            const raw = readFileSync(settingsPath, 'utf8');
+            for (const t of requiredHookTokens) {
+                if (!raw.includes(t))
+                    missingHooks.push(t);
+            }
+            try {
+                locked = isHookBlockLocked(JSON.parse(raw));
+            }
+            catch {
+                /* unparseable JSON — leave locked=false; structural check below flags it */
+                structural.push('.claude/settings.json is not valid JSON');
+            }
         }
         catch (e) {
-            issues.push(`cannot read settings.json: ${errorDetail(e)}`);
+            structural.push(`cannot read settings.json: ${errorDetail(e)}`);
         }
     }
-    else {
-        issues.push('.claude/settings.json not found');
+    else if (!uninitialised) {
+        structural.push('.claude/settings.json not found');
     }
-    const toggles = `sdd.default=${sddDefault}, gates.verify_before_done=${verifyGate}`;
-    if (issues.length > 0) {
-        // Wiring is broken. Severity depends on whether the consumer opted in: a
-        // missing gate when verify is ON blocks nothing (fail-open) but breaks the
-        // promised enforcement, so it's a real fault. When both toggles are off the
-        // wiring is still expected (it ships inert), but a missing case only bites
-        // once someone opts in — warn.
-        const enforced = verifyGate || sddDefault;
+    return {
+        sddDefault,
+        verifyGate,
+        locked,
+        enforced: sddDefault || verifyGate,
+        uninitialised,
+        requiredHookTokens,
+        requiredGateCases,
+        missingHooks,
+        missingGateCases,
+        structural,
+    };
+}
+export async function checkSddVerifyWiring() {
+    const req = computeSddVerifyRequirements(findProjectRoot());
+    // Uninitialised project — defer to `flo init`, don't hard-fail.
+    if (req.uninitialised) {
         return {
             name: NAME,
-            status: enforced ? 'fail' : 'warn',
-            message: `SDD/verify wiring incomplete (${toggles}): ${issues.join('; ')}`,
-            fix: 'npx moflo init --fix   # re-syncs gate.cjs + settings.json hooks',
+            status: 'warn',
+            message: '.claude/ not initialised — SDD/verify wiring absent',
+            fix: 'npx moflo init',
+        };
+    }
+    const toggles = `sdd.default=${req.sddDefault}, gates.verify_before_done=${req.verifyGate}`;
+    const issues = [...req.structural];
+    if (req.missingGateCases.length > 0)
+        issues.push(`gate.cjs missing: ${req.missingGateCases.join(', ')}`);
+    if (req.missingHooks.length > 0)
+        issues.push(`settings.json missing hooks: ${req.missingHooks.join(', ')}`);
+    if (issues.length === 0) {
+        return {
+            name: NAME,
+            status: 'pass',
+            message: `SDD/verify wired (${toggles})${req.verifyGate ? ' — verify-before-done ENFORCED' : ''}`,
+        };
+    }
+    // Locked hook block: moflo won't rewrite it (init + launcher both skip on
+    // `isHookBlockLocked`), so pointing at `init --fix` is a dead-end and a hard
+    // fail is a permanently-red check the healer can never clear (#1301). When the
+    // ONLY outstanding problem is missing hook tokens in that locked block,
+    // downgrade to warn and hand over the two real reconciliations. gate.cjs and
+    // structural faults are unaffected by the lock, so they still fail normally.
+    if (req.locked &&
+        req.missingHooks.length > 0 &&
+        req.missingGateCases.length === 0 &&
+        req.structural.length === 0) {
+        const optOut = req.sddDefault && !req.verifyGate
+            ? 'set sdd.default: false'
+            : req.verifyGate && !req.sddDefault
+                ? 'set gates.verify_before_done: false'
+                : 'disable the SDD/verify toggles';
+        return {
+            name: NAME,
+            status: 'warn',
+            message: `SDD/verify wiring incomplete (${toggles}): settings.json missing hooks: ` +
+                `${req.missingHooks.join(', ')} — hook block is LOCKED (moflo.hooks.locked=true), ` +
+                `so moflo will not wire it`,
+            fix: `Reconcile: ${optOut} in moflo.yaml to match the locked block, OR remove ` +
+                `moflo.hooks.locked from .claude/settings.json and run npx moflo init --fix`,
         };
     }
+    // A missing required token means a feature the consumer turned ON isn't
+    // enforced — a real fault. With both toggles off, `requiredHookTokens`/
+    // `requiredGateCases` are empty, so only structural faults can reach here;
+    // those warn (the wiring ships inert until someone opts in).
     return {
         name: NAME,
-        status: 'pass',
-        message: `SDD/verify wired (${toggles})${verifyGate ? ' — verify-before-done ENFORCED' : ''}`,
+        status: req.enforced ? 'fail' : 'warn',
+        message: `SDD/verify wiring incomplete (${toggles}): ${issues.join('; ')}`,
+        fix: 'npx moflo init --fix   # re-syncs gate.cjs + settings.json hooks',
     };
 }
 //# sourceMappingURL=doctor-checks-sdd.js.map

package/dist/src/cli/commands/doctor-fixes.js

@@ -639,6 +639,77 @@ export async function autoFixCheck(check) {
         'Gate Health': async () => {
             return fixGateHealthHooks();
         },
+        // #1301 — SDD/verify hook wiring. The generic fall-through used to run
+        // `npx moflo init --fix` and report `applied: true` on its exit code alone,
+        // even when the hook block was LOCKED and init injected nothing — a false
+        // positive over a permanently-red check. This handler:
+        //   1. refuses (returns false) when the block is locked — moflo won't
+        //      rewrite it, so claiming a fix would be a lie;
+        //   2. grafts ONLY the missing SDD/verify reference entries additively
+        //      (`check-before-implement` lives in the reference block but NOT in
+        //      repairHookWiring's REQUIRED_HOOK_WIRING, so the generic repair could
+        //      never add it); and
+        //   3. re-verifies from disk and returns the honest result.
+        'SDD + Verify Wiring': async () => {
+            const projectDir = findProjectRoot();
+            const { computeSddVerifyRequirements } = await import('./doctor-checks-sdd.js');
+            const before = computeSddVerifyRequirements(projectDir);
+            // Uninitialised `.claude/` — the graft path below assumes settings.json +
+            // gate.cjs already exist, and every `missing*` array is empty when nothing
+            // is on disk. Run the check's own remediation (`npx moflo init`) instead,
+            // preserving the pre-#1301 generic-fallthrough behavior this named handler
+            // now intercepts.
+            if (before.uninitialised) {
+                return runFixCommand('npx moflo init');
+            }
+            if (before.missingHooks.length === 0 && before.missingGateCases.length === 0 && before.structural.length === 0) {
+                return true; // nothing outstanding
+            }
+            if (before.locked && before.missingHooks.length > 0) {
+                output.writeln(output.warning('  Hook block is LOCKED (moflo.hooks.locked=true) — moflo will not wire SDD/verify hooks. ' +
+                    'Set the matching toggle to false in moflo.yaml, or remove the lock and re-run.'));
+                // If the locked hooks are the only gap, there is genuinely nothing we
+                // can do — report honestly rather than a false success.
+                if (before.missingGateCases.length === 0 && before.structural.length === 0)
+                    return false;
+            }
+            // settings.json hook wiring — additively graft the missing SDD/verify
+            // reference entries (skip when locked; the block above already reported it).
+            const settingsPath = join(projectDir, '.claude', 'settings.json');
+            if (!before.locked && before.missingHooks.length > 0 && existsSync(settingsPath)) {
+                try {
+                    const { computeHookBlockDrift, applyAdditiveRegeneration } = await import('../services/hook-block-hash.js');
+                    const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+                    const report = computeHookBlockDrift((settings.hooks ?? {}));
+                    // Scope the graft to the tokens this check owns — leave unrelated
+                    // drift to the Hook Block Drift check/fixer.
+                    const wanted = before.requiredHookTokens;
+                    const scoped = {
+                        ...report,
+                        missing: report.missing.filter((m) => wanted.some((t) => m.command.includes(t))),
+                    };
+                    if (scoped.missing.length > 0) {
+                        applyAdditiveRegeneration(settings, scoped);
+                        // Atomic swap — settings.json is actively re-read by Claude Code, so
+                        // a concurrent reader must never see a truncated file (#1015).
+                        atomicWriteFileSync(settingsPath, JSON.stringify(settings, null, 2));
+                    }
+                }
+                catch (e) {
+                    output.writeln(output.warning(`  settings.json hook repair failed: ${errorDetail(e)}`));
+                    return false;
+                }
+            }
+            // gate.cjs case drift — reuse the gate-health repair (mirrors bin/helper).
+            if (before.missingGateCases.length > 0) {
+                await fixGateHealthHooks();
+            }
+            // Truth check — re-read from disk and confirm the required wiring landed.
+            const after = computeSddVerifyRequirements(projectDir);
+            return after.missingHooks.length === 0
+                && after.missingGateCases.length === 0
+                && after.structural.length === 0;
+        },
         // Refresh the consumer's CLAUDE.md MoFlo block in place using the
         // shared `applyInjectionReplacement` service. Idempotent: a re-run sees
         // `state === 'in-sync'` and the autoFix dispatcher skips this entry.

package/dist/src/cli/version.js

@@ -2,5 +2,5 @@
  * Auto-generated by build. Do not edit manually.
  * Source of truth: root package.json → scripts/sync-version.mjs
  */
-export const VERSION = '4.11.10-rc.9';
+export const VERSION = '4.12.0';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.11.10-rc.9",
+  "version": "4.12.0",
   "description": "MoFlo — AI agent orchestration for Claude Code. A standalone, opinionated toolkit with semantic memory, learned routing, gates, spells, and the /flo issue-execution skill.",
   "main": "dist/src/cli/index.js",
   "type": "module",
@@ -95,7 +95,7 @@
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "eslint": "^8.0.0",
-    "moflo": "^4.11.10-rc.8",
+    "moflo": "^4.11.10-rc.10",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"