paqad-ai 1.46.0 → 1.46.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # paqad-ai
 
+## 1.46.1
+
+### Patch Changes
+
+- c0e7efa: Fix #310: the feature-development stage gate blocked documentation-only work and could deadlock unclearably.
+
+  - **Scope.** The pre-mutation and completion stage gates now govern **feature development only**. A documentation-only change (`docs/**`, markdown) or a framework-internal change (`.paqad/**`) is no longer forced through the planning → specification → … → checks stages. The check is language-agnostic (an exclude list, not a `src/` allowlist), so it holds for any onboarded stack (Laravel `app/*.php`, Python, Go, …), and it keeps full teeth on real source edits.
+  - **No deadlock.** The live writer no longer stamps a stage (e.g. `development`/`documentation_sync`) before the pre-code stages are recorded — that phantom used to poison stage ordering so `planning` could never be recorded again. The recorder no longer rejects an out-of-order earlier `stage_start`; ordering is judged non-destructively by the completion fold, so the stages the gate demands can always be recorded and the same-turn marker remediation actually clears the block.
+  - **Consistent predicate.** An `end` with no matching `start` is now `inconclusive`, not silently `complete`, so the pre-mutation gate and the completion verifier agree a stage needs a start.
+  - **Reachable remedy.** Editing `.paqad/configs/.config.policy` (the `stages_mode` escape hatch) is no longer blocked by the gate it configures.
+
 ## 1.46.0
 
 ### Minor Changes

package/dist/cli/index.js

@@ -18302,7 +18302,7 @@ var HealthChecker = class {
   }
   checkFrameworkArtifacts(projectRoot) {
     const required = [PATHS.PROJECT_PROFILE, PATHS.FRAMEWORK_PATH];
-    const missing = required.filter((relative25) => !existsSync32(join58(projectRoot, relative25)));
+    const missing = required.filter((relative26) => !existsSync32(join58(projectRoot, relative26)));
     return missing.length === 0 ? pass("Framework artifacts exist", "Framework artifacts are present") : fail(
       "Framework artifacts exist",
       `Missing framework artifacts: ${missing.join(", ")}`,
@@ -25973,16 +25973,21 @@ init_session();
 // src/stage-evidence/stages.ts
 init_esm_shims();
 var STAGE_EVIDENCE_STAGES = [...STAGE_ORDER];
-var COMPLETION_ANCHORED_STAGES = ["review"];
+var MANDATORY_STAGES = [
+  "planning",
+  "specification",
+  "development",
+  "review",
+  "checks",
+  "documentation_sync"
+];
+var PRE_CODE_STAGES = MANDATORY_STAGES.slice(
+  0,
+  MANDATORY_STAGES.indexOf("development")
+);
 function isKnownStage(stage) {
   return STAGE_EVIDENCE_STAGES.includes(stage);
 }
-function isCompletionAnchoredStage(stage) {
-  return COMPLETION_ANCHORED_STAGES.includes(stage);
-}
-function stageIndex(stage) {
-  return STAGE_EVIDENCE_STAGES.indexOf(stage);
-}
 
 // src/stage-evidence/recorder.ts
 var APPEND_OPTS3 = (now) => ({
@@ -26014,29 +26019,12 @@ function resolveOrdinal2(projectRoot, sessionId, ctx) {
   }
   return openStageEvidence(projectRoot, ctx).ordinal;
 }
-function highestStartedIndex(rows) {
-  let highest = -1;
-  for (const row of rows) {
-    if (row.kind === "stage_start" && typeof row.stage === "string") {
-      highest = Math.max(highest, stageIndex(row.stage));
-    }
-  }
-  return highest;
-}
 function startStage(projectRoot, stage, ctx) {
   if (!isKnownStage(stage)) {
     throw new Error(`Unknown stage "${stage}" \u2014 not in the feature-development registry.`);
   }
   const sessionId = resolveSessionId(projectRoot, ctx.sessionId);
   const ordinal = resolveOrdinal2(projectRoot, sessionId, ctx);
-  const rows = readSessionUnit(projectRoot, STAGE_EVIDENCE_DOC_TYPE, sessionId, ordinal);
-  const highest = highestStartedIndex(rows);
-  const index = stageIndex(stage);
-  if (!isCompletionAnchoredStage(stage) && highest >= 0 && index < highest) {
-    throw new Error(
-      `Out-of-order stage "${stage}": a later stage already started. Stages must run in registry order.`
-    );
-  }
   return append(projectRoot, sessionId, ordinal, ctx, {
     kind: "stage_start",
     stage,
@@ -26106,6 +26094,10 @@ init_session();
 init_esm_shims();
 init_framework_config();
 
+// src/stage-evidence/scope.ts
+init_esm_shims();
+import { isAbsolute as isAbsolute3, relative as relative22 } from "pathe";
+
 // src/verification/repository/verdict.ts
 init_esm_shims();
 
@@ -26253,7 +26245,7 @@ init_esm_shims();
 init_esm_shims();
 init_logger_registry();
 import { mkdir as mkdir45, writeFile as writeFile45 } from "fs/promises";
-import { join as join134, relative as relative22 } from "path";
+import { join as join134, relative as relative23 } from "path";
 init_paths();
 init_path_utils();
 
@@ -26295,7 +26287,7 @@ init_cancelled_error();
 init_events();
 
 // src/index.ts
-var VERSION = "1.46.0";
+var VERSION = "1.46.1";
 
 // src/cli/commands/audit.ts
 init_esm_shims();
@@ -27294,7 +27286,7 @@ function resolveRelativeSpec(projectRoot, spec) {
 init_esm_shims();
 init_paths();
 import { existsSync as existsSync98 } from "fs";
-import { dirname as dirname69, isAbsolute as isAbsolute3, join as join169, resolve as resolve10 } from "path";
+import { dirname as dirname69, isAbsolute as isAbsolute4, join as join169, resolve as resolve10 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 import { Command as Command4 } from "commander";
 
@@ -27392,7 +27384,7 @@ function buildNodeDetail(graph, nodeId, options) {
 init_esm_shims();
 import { existsSync as existsSync70 } from "fs";
 import { readFile as readFile69, readdir as readdir15, stat as stat8 } from "fs/promises";
-import { extname as extname8, join as join138, relative as relative23, sep as sep6 } from "path";
+import { extname as extname8, join as join138, relative as relative24, sep as sep6 } from "path";
 init_paths();
 var KNOWN_TIERS = /* @__PURE__ */ new Set(["green", "amber", "red", "unknown"]);
 function normaliseTier(value) {
@@ -27430,7 +27422,7 @@ function languageFromExtension(filePath) {
   return map[ext] ?? null;
 }
 function toProjectRelative2(projectRoot, absolutePath) {
-  const rel = relative23(projectRoot, absolutePath);
+  const rel = relative24(projectRoot, absolutePath);
   return rel === "" ? "." : rel.split(sep6).join("/");
 }
 function moduleNameForFile(relativePath, knownModules) {
@@ -29289,12 +29281,12 @@ import { existsSync as existsSync78, readdirSync as readdirSync15 } from "fs";
 import { join as join148 } from "path";
 import YAML19 from "yaml";
 var EDITABLE_EXTENSIONS = [".md", ".yml", ".yaml", ".json"];
-function buildNode(absolute, relative25, name) {
+function buildNode(absolute, relative26, name) {
   const entries = readdirSync15(absolute, { withFileTypes: true });
   const children = [];
   for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
     if (entry.name.startsWith(".")) continue;
-    const childRelative = relative25 === "" ? entry.name : `${relative25}/${entry.name}`;
+    const childRelative = relative26 === "" ? entry.name : `${relative26}/${entry.name}`;
     if (entry.isDirectory()) {
       const child = buildNode(join148(absolute, entry.name), childRelative, entry.name);
       if (child) children.push(child);
@@ -29302,7 +29294,7 @@ function buildNode(absolute, relative25, name) {
       children.push({ path: childRelative, name: entry.name, type: "file" });
     }
   }
-  return { path: relative25, name, type: "directory", children };
+  return { path: relative26, name, type: "directory", children };
 }
 function listInstructionsTree(projectRoot) {
   const root = join148(projectRoot, PATHS.INSTRUCTIONS_DIR);
@@ -29415,7 +29407,7 @@ function counted(count, singular, plural, zero) {
 }
 function buildInventory(projectRoot, options = {}) {
   const paqadHome = options.paqadHome ?? join149(homedir10(), ".paqad-ai");
-  const at = (relative25) => join149(projectRoot, relative25);
+  const at = (relative26) => join149(projectRoot, relative26);
   const profile = parseYamlFile(at(PATHS.PROJECT_PROFILE));
   const activeCapabilities = Array.isArray(profile?.active_capabilities) ? profile.active_capabilities : [];
   const intelligence = profile?.intelligence ?? null;
@@ -29937,7 +29929,7 @@ function dirHasEntries(path11) {
   }
 }
 function buildOnboardingChecklist(projectRoot) {
-  const at = (relative25) => join150(projectRoot, relative25);
+  const at = (relative26) => join150(projectRoot, relative26);
   const agentConnected = [PATHS.CLAUDE_MD, PATHS.AGENTS_MD, PATHS.ANTIGRAVITY_MD, PATHS.GEMINI_MD].some(
     (entry) => existsSync80(at(entry))
   ) && existsSync80(at(PATHS.ONBOARDING_MANIFEST));
@@ -32687,14 +32679,14 @@ data: ${JSON.stringify(data)}
       return;
     }
     if (instructionsFileMatch && req.method === "PUT") {
-      const relative25 = decodeURIComponent(instructionsFileMatch[1]);
+      const relative26 = decodeURIComponent(instructionsFileMatch[1]);
       await handleMutation(req, res, async () => {
         const body = await readJsonBody2(req);
         if (typeof body.content !== "string") {
           throw new Error("Body must include the file `content` as a string.");
         }
         return writeManagedFile(options.projectRoot, {
-          relativePath: `${PATHS.INSTRUCTIONS_DIR}/${relative25}`,
+          relativePath: `${PATHS.INSTRUCTIONS_DIR}/${relative26}`,
           content: body.content,
           baseHash: typeof body.baseHash === "string" ? body.baseHash : null,
           action: "dashboard.instructions.write"
@@ -33010,7 +33002,7 @@ function openBrowser(options) {
 var DEFAULT_PORT = 5372;
 function resolveStaticDir(override) {
   if (override) {
-    return isAbsolute3(override) ? override : resolve10(process.cwd(), override);
+    return isAbsolute4(override) ? override : resolve10(process.cwd(), override);
   }
   const here = dirname69(fileURLToPath3(import.meta.url));
   const candidates = [
@@ -33210,14 +33202,14 @@ function createEvidenceCommand() {
 init_esm_shims();
 init_paths();
 import { existsSync as existsSync99 } from "fs";
-import { dirname as dirname71, isAbsolute as isAbsolute4, join as join170, resolve as resolve12 } from "path";
+import { dirname as dirname71, isAbsolute as isAbsolute5, join as join170, resolve as resolve12 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 import { Command as Command9 } from "commander";
 var DEFAULT_PORT2 = 5372;
 var DEPRECATION_LINE = "paqad-ai graph has moved into the dashboard. Opening the dashboard on the Graph view. Run paqad-ai dashboard next time.";
 function resolveStaticDir2(override) {
   if (override) {
-    return isAbsolute4(override) ? override : resolve12(process.cwd(), override);
+    return isAbsolute5(override) ? override : resolve12(process.cwd(), override);
   }
   const here = dirname71(fileURLToPath4(import.meta.url));
   const candidates = [
@@ -34061,7 +34053,7 @@ function createPacksCommand() {
 init_esm_shims();
 init_project_intelligence();
 import { readFileSync as readFileSync76 } from "fs";
-import { isAbsolute as isAbsolute5, join as join174 } from "path";
+import { isAbsolute as isAbsolute6, join as join174 } from "path";
 import { confirm, input as input2, select as select3 } from "@inquirer/prompts";
 import { Command as Command18 } from "commander";
 init_framework_config();
@@ -35048,7 +35040,7 @@ function createRagCommand() {
         readFile: (path11) => {
           try {
             return readFileSync76(
-              isAbsolute5(path11) ? path11 : join174(options.projectRoot, path11),
+              isAbsolute6(path11) ? path11 : join174(options.projectRoot, path11),
               "utf8"
             );
           } catch {
@@ -35508,7 +35500,7 @@ init_session();
 init_esm_shims();
 init_ledger();
 init_session();
-import { isAbsolute as isAbsolute6, relative as relative24 } from "pathe";
+import { isAbsolute as isAbsolute7, relative as relative25 } from "pathe";
 function recordMarkedStage(projectRoot, input3) {
   if (!isKnownStage(input3.stage)) return false;
   const ctx = {
@@ -35573,7 +35565,7 @@ function createStageCommand() {
     const recorded = recordMarkedStage(root, { sessionId, stage, phase });
     if (!recorded) {
       console.error(
-        `could not record "${stage} ${phase}" \u2014 unknown stage or out-of-order boundary. Stages, in order: ${STAGE_ORDER.join(", ")}`
+        `could not record "${stage} ${phase}" \u2014 unknown stage "${stage}". Stages, in order: ${STAGE_ORDER.join(", ")}`
       );
       process.exitCode = 1;
       return;