qualia-framework 3.3.1 → 3.3.2

package/bin/state.js

@@ -393,9 +393,15 @@ function cmdTransition(opts) {
     { ...opts, phase }
   );
   if (!check.ok) {
-    // Force only bypasses status-ordering errors (PRECONDITION_FAILED, GAP_CYCLE_LIMIT).
-    // Never bypass MISSING_FILE, MISSING_ARG, INVALID_PLAN — those cause broken state.
-    const forceableErrors = ["PRECONDITION_FAILED", "GAP_CYCLE_LIMIT"];
+    // Force bypasses status-ordering errors AND plan-content errors. The use case
+    // is retroactive bookkeeping: a phase was built without /qualia-plan and the
+    // user is catching STATE.md up to reality. `--force` never bypasses MISSING_FILE
+    // or MISSING_ARG — those would leave the state machine pointing at nothing.
+    const forceableErrors = [
+      "PRECONDITION_FAILED",
+      "GAP_CYCLE_LIMIT",
+      "INVALID_PLAN",
+    ];
     if (opts.force && forceableErrors.includes(check.error)) {
       console.error(`WARNING: Forcing transition despite: ${check.message}`);
     } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "3.3.1",
+  "version": "3.3.2",
   "description": "Claude Code workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"

package/tests/runner.js

@@ -774,14 +774,31 @@ waves: 1
     }
   });
 
-  it("--force does NOT bypass INVALID_PLAN", () => {
+  it("--force bypasses INVALID_PLAN (retroactive bookkeeping)", () => {
+    // Use case: a phase was built without /qualia-plan and the user is
+    // catching STATE.md up to reality. The plan file exists as documentation
+    // but lacks `**Done when:**` markers — that should not block --force.
     const tmpDir = makeProject();
     try {
       fs.writeFileSync(path.join(tmpDir, ".planning", "phase-1-plan.md"), "# No tasks here");
+      const r = runState(["transition", "--to", "planned", "--force"], tmpDir);
+      assert.equal(r.status, 0);
+      const out = JSON.parse(r.stdout);
+      assert.equal(out.ok, true);
+      assert.equal(out.status, "planned");
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("--force still rejects MISSING_FILE", () => {
+    // Sanity: --force unblocks plan-content errors but not "no plan at all".
+    const tmpDir = makeProject();
+    try {
       const r = runState(["transition", "--to", "planned", "--force"], tmpDir);
       assert.equal(r.status, 1);
       const out = JSON.parse(r.stdout);
-      assert.equal(out.error, "INVALID_PLAN");
+      assert.equal(out.error, "MISSING_FILE");
     } finally {
       fs.rmSync(tmpDir, { recursive: true, force: true });
     }