paqad-ai 1.44.1 → 1.46.1

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # 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
+
+- 944f52f: Stages gate: same-turn unblock that actually works, sentinel bootstrap un-deadlocked, and stage narration everywhere (#307).
+
+  - `paqad:stage` markers are now parsed at the pre-mutation seam too, so markers emitted earlier in the same turn clear the block-forward gate immediately — not only after Stop.
+  - New `paqad-ai stage <start|end> <stage>` CLI verb replaces the never-shipped `scripts/se-mark.ts` as the shell escape hatch; the block message, framework bootstrap, and decision-skill docs now name only remediations that exist on an onboarded project.
+  - The write of `.paqad/.agent-entry-loaded` is exempt from both the agent-entry gate and the stages gate: turn one can complete the bootstrap it is being asked to perform.
+  - Narration and ledger are both non-negotiable: every stage-evidence row minted from markers (pre-mutation sweep, Stop parse, CLI) is narrated back to the developer as a `▸ paqad` line via the host's user-message channel; allow-path advisories use `systemMessage` instead of invisible stdout.
+  - Guardrails: a packaging-truth test suite pins that every runnable path/verb named in user-facing remediation surfaces resolves in the published package, and `src/stage-evidence/**` now holds a 100% coverage floor (statements, branches, functions, lines).
+  - Completion-backstop over-block fixed (decision `D-01KWYDTDZ24CV802R2HGDS4RH4`), removing two false blocks that hit every onboarded repo's first code change: (1) an implementation-drift canonical doc that does not exist on disk is no longer treated as an unresolved obligation — a code change cannot stale a framework-assumed doc (`docs/maintainers/architecture-map.md`, `docs/modules/README.md`) the project never created; existing drift docs are still flagged and required per-module docs stay enforced; (2) test-evidence strength is a provider-workflow concern the agent-independent backstop cannot collect, so at backstop origins it now escalates (visibly) instead of hard-blocking — in-session and CI still enforce it.
+
+## 1.45.0
+
+### Minor Changes
+
+- b07dc02: Decision Pause now mints packets on more of the forks that matter (#300, option B2):
+
+  - **Self-arm broadened to architecture-path.** Alongside create-vs-reuse (0.92), the opt-in self-arm minter now also arms on a new tight `explicit-path-fork` detector signal (0.90) — two distinct file paths offered as alternatives ("live in X or Y", "X vs Y"). The pre-existing broad architecture-path signals (a bare "or", two paths merely mentioned) stay at 0.64 and never clear the arming bar, so a stray "or" cannot mint a pause. Self-arm remains OFF by default.
+  - **spec.change now has a deterministic minter.** A new always-on, no-opt-in spec-change guard runs at the pre-mutation seam: when a persisted frozen spec's source markdown has moved since freeze (`isFrozenSpecStale`), it mints one `spec.change` pause via `buildSpecChangePacket`. It is naturally inert until a spec is frozen and its sidecar persisted (`writeFrozenSpec`), so nothing changes for projects that do not use the spec-freeze lifecycle. Both minters only write a pending packet; the existing decision-pause gate still owns the block on the next edit.
+
+  Cross-provider: the architecture-path leg inherits self-arm's existing transcript-based provider coverage (parity with `HOOK_COVERAGE_MATRIX`); the spec-change guard is provider-independent (it reads spec files on disk, not the turn transcript).
+
+  Also fixes `buildSpecChangePacket` copy that could never pass `lintDecisionCopy` (banned word "invariant", non-approved label verb, em dashes), which had silently blocked the packet from ever being written to the pending store.
+
 ## 1.44.1
 
 ### Patch Changes

package/dist/cli/index.js

@@ -9772,7 +9772,7 @@ import { pathToFileURL } from "url";
 
 // src/cli/program.ts
 init_esm_shims();
-import { Command as Command23 } from "commander";
+import { Command as Command24 } from "commander";
 
 // src/index.ts
 init_esm_shims();
@@ -16072,8 +16072,8 @@ function isPlaceholder(tokens) {
   return tokens.$comment === DESIGN_TOKENS_PLACEHOLDER_NOTE;
 }
 var DesignTokenService = class {
-  constructor(validator3 = new SchemaValidator()) {
-    this.validator = validator3;
+  constructor(validator4 = new SchemaValidator()) {
+    this.validator = validator4;
   }
   async seed(projectRoot) {
     const target = join53(projectRoot, PATHS.DESIGN_TOKENS_FILE);
@@ -18302,7 +18302,7 @@ var HealthChecker = class {
   }
   checkFrameworkArtifacts(projectRoot) {
     const required = [PATHS.PROJECT_PROFILE, PATHS.FRAMEWORK_PATH];
-    const missing = required.filter((relative24) => !existsSync32(join58(projectRoot, relative24)));
+    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(", ")}`,
@@ -22714,8 +22714,8 @@ function loadDeliveryPolicy(projectRoot) {
         ]
       };
     }
-    const validator3 = new SchemaValidator();
-    const validation = validator3.validate("delivery-policy", parsed);
+    const validator4 = new SchemaValidator();
+    const validation = validator4.validate("delivery-policy", parsed);
     if (!validation.valid) {
       return {
         policy: withDetection(projectRoot, defaults),
@@ -23700,8 +23700,8 @@ var OnboardingOrchestrator = class {
       options.projectRoot
     );
     profile.intelligence = applyRagSelection(profile.intelligence, void 0);
-    const validator3 = new SchemaValidator();
-    const validation = validator3.validate("project-profile", profile);
+    const validator4 = new SchemaValidator();
+    const validation = validator4.validate("project-profile", profile);
     const modules = await discoverModules(options.projectRoot);
     if (!validation.valid) {
       throw new Error(validation.errors.map((error) => error.message).join("; "));
@@ -23937,8 +23937,8 @@ var OnboardingOrchestrator = class {
       options.projectRoot
     );
     profile.intelligence = applyRagSelection(profile.intelligence, void 0);
-    const validator3 = new SchemaValidator();
-    const validation = validator3.validate("project-profile", profile);
+    const validator4 = new SchemaValidator();
+    const validation = validator4.validate("project-profile", profile);
     if (!validation.valid) {
       throw new ValidationError(validation.errors.map((error) => error.message).join("; "), {
         projectRoot: options.projectRoot
@@ -25904,9 +25904,68 @@ import Ajv5 from "ajv";
 // src/stage-evidence/types.ts
 init_esm_shims();
 var STAGE_EVIDENCE_DOC_TYPE = "paqad.stage-evidence";
+var STAGE_EVIDENCE_SCHEMA_VERSION = 1;
 
 // src/stage-evidence/schema.ts
+var nullableString3 = { type: ["string", "null"] };
+var STAGE_EVIDENCE_SCHEMA = {
+  $id: "paqad://schemas/stage-evidence.json",
+  type: "object",
+  additionalProperties: false,
+  required: [
+    "schema_version",
+    "doc_type",
+    "kind",
+    "session_id",
+    "conversation_ordinal",
+    "ts",
+    "adapter",
+    "content_hash"
+  ],
+  properties: {
+    schema_version: { type: "integer", const: 1 },
+    doc_type: { const: STAGE_EVIDENCE_DOC_TYPE },
+    kind: { enum: ["open", "stage_start", "stage_end", "verify", "close"] },
+    session_id: { type: "string", minLength: 1 },
+    conversation_ordinal: { type: "integer", minimum: 1 },
+    ts: { type: "string", minLength: 1 },
+    adapter: { type: "string", minLength: 1 },
+    stage: nullableString3,
+    event_status: {
+      type: ["string", "null"],
+      enum: ["started", "completed", "skipped", "failed", "redone", "inferred", null]
+    },
+    evidence_source: {
+      type: ["string", "null"],
+      enum: ["live-mark", "inferred-artifact", "inferred-git", "redo", null]
+    },
+    artifact_paths: { type: ["array", "null"], items: { type: "string" } },
+    artifact_digest: nullableString3,
+    subject_digest: nullableString3,
+    lane: { type: ["string", "null"], enum: ["fast", "graduated", "full", null] },
+    note: nullableString3,
+    content_hash: { type: "string", minLength: 1 }
+  }
+};
 var ajv4 = new Ajv5({ allErrors: true, allowUnionTypes: true });
+var compiled3;
+function validator3() {
+  if (!compiled3) {
+    compiled3 = ajv4.compile(STAGE_EVIDENCE_SCHEMA);
+  }
+  return compiled3;
+}
+function formatValidationError(error) {
+  return `${error.instancePath || "(root)"} ${error.message ?? "invalid"}`;
+}
+function validateStageEvidenceRow(row) {
+  const validate = validator3();
+  if (validate(row)) {
+    return [];
+  }
+  const errors = validate.errors;
+  return errors.map(formatValidationError);
+}
 
 // src/stage-evidence/recorder.ts
 init_session();
@@ -25914,6 +25973,108 @@ init_session();
 // src/stage-evidence/stages.ts
 init_esm_shims();
 var STAGE_EVIDENCE_STAGES = [...STAGE_ORDER];
+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);
+}
+
+// src/stage-evidence/recorder.ts
+var APPEND_OPTS3 = (now) => ({
+  schemaVersion: STAGE_EVIDENCE_SCHEMA_VERSION,
+  validate: (row) => validateStageEvidenceRow(row),
+  now
+});
+function changeKey(sessionId, ordinal) {
+  return `${sessionId}#${ordinal}`;
+}
+function openStageEvidence(projectRoot, ctx) {
+  const sessionId = resolveSessionId(projectRoot, ctx.sessionId);
+  const { ordinal } = openSessionDoc(
+    projectRoot,
+    STAGE_EVIDENCE_DOC_TYPE,
+    sessionId,
+    { adapter: ctx.adapter, lane: ctx.lane ?? null },
+    APPEND_OPTS3(ctx.now)
+  );
+  return { sessionId, ordinal, changeKey: changeKey(sessionId, ordinal) };
+}
+function resolveOrdinal2(projectRoot, sessionId, ctx) {
+  if (ctx.ordinal && ctx.ordinal > 0) {
+    return ctx.ordinal;
+  }
+  const current = currentOrdinal(projectRoot, STAGE_EVIDENCE_DOC_TYPE, sessionId);
+  if (current > 0) {
+    return current;
+  }
+  return openStageEvidence(projectRoot, ctx).ordinal;
+}
+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);
+  return append(projectRoot, sessionId, ordinal, ctx, {
+    kind: "stage_start",
+    stage,
+    event_status: "started",
+    evidence_source: "live-mark"
+  });
+}
+function endStage(projectRoot, stage, input3, 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 artifactPaths = input3.artifactPaths ?? [];
+  const artifactDigest = artifactPaths.length > 0 ? hashArtifacts(projectRoot, artifactPaths) : null;
+  const subjectDigest = stage === "development" ? input3.subjectDigest ?? artifactDigest : input3.subjectDigest ?? null;
+  return append(projectRoot, sessionId, ordinal, ctx, {
+    kind: "stage_end",
+    stage,
+    event_status: "completed",
+    evidence_source: "live-mark",
+    artifact_paths: artifactPaths.length > 0 ? artifactPaths : null,
+    artifact_digest: artifactDigest,
+    subject_digest: subjectDigest,
+    note: input3.note ?? null
+  });
+}
+function hashArtifacts(projectRoot, artifactPaths) {
+  const perFile = [...artifactPaths].sort().map((rel) => {
+    const abs = join129(projectRoot, rel);
+    let bytes;
+    try {
+      bytes = readFileSync56(abs);
+    } catch {
+      return `${rel}:absent`;
+    }
+    return `${rel}:${createHash29("sha256").update(bytes).digest("hex")}`;
+  });
+  return `sha256-${createHash29("sha256").update(perFile.join("\n")).digest("hex")}`;
+}
+function append(projectRoot, sessionId, ordinal, ctx, fields) {
+  return appendSessionEvent(
+    projectRoot,
+    STAGE_EVIDENCE_DOC_TYPE,
+    sessionId,
+    ordinal,
+    { conversation_ordinal: ordinal, adapter: ctx.adapter, lane: ctx.lane ?? null, ...fields },
+    APPEND_OPTS3(ctx.now)
+  );
+}
 
 // src/stage-evidence/finalize.ts
 init_session();
@@ -25933,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();
 
@@ -26080,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();
 
@@ -26122,7 +26287,7 @@ init_cancelled_error();
 init_events();
 
 // src/index.ts
-var VERSION = "1.44.1";
+var VERSION = "1.46.1";
 
 // src/cli/commands/audit.ts
 init_esm_shims();
@@ -27121,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";
 
@@ -27219,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) {
@@ -27257,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) {
@@ -29116,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, relative24, 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 = relative24 === "" ? entry.name : `${relative24}/${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);
@@ -29129,7 +29294,7 @@ function buildNode(absolute, relative24, name) {
       children.push({ path: childRelative, name: entry.name, type: "file" });
     }
   }
-  return { path: relative24, name, type: "directory", children };
+  return { path: relative26, name, type: "directory", children };
 }
 function listInstructionsTree(projectRoot) {
   const root = join148(projectRoot, PATHS.INSTRUCTIONS_DIR);
@@ -29242,7 +29407,7 @@ function counted(count, singular, plural, zero) {
 }
 function buildInventory(projectRoot, options = {}) {
   const paqadHome = options.paqadHome ?? join149(homedir10(), ".paqad-ai");
-  const at = (relative24) => join149(projectRoot, relative24);
+  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;
@@ -29764,7 +29929,7 @@ function dirHasEntries(path11) {
   }
 }
 function buildOnboardingChecklist(projectRoot) {
-  const at = (relative24) => join150(projectRoot, relative24);
+  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));
@@ -32514,14 +32679,14 @@ data: ${JSON.stringify(data)}
       return;
     }
     if (instructionsFileMatch && req.method === "PUT") {
-      const relative24 = 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}/${relative24}`,
+          relativePath: `${PATHS.INSTRUCTIONS_DIR}/${relative26}`,
           content: body.content,
           baseHash: typeof body.baseHash === "string" ? body.baseHash : null,
           action: "dashboard.instructions.write"
@@ -32837,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 = [
@@ -33037,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 = [
@@ -33888,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();
@@ -34875,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 {
@@ -35326,10 +35491,95 @@ function resolveChangedFiles(projectRoot, contextChangedFiles) {
   }
 }
 
+// src/cli/commands/stage.ts
+init_esm_shims();
+import { Command as Command21 } from "commander";
+init_session();
+
+// src/stage-evidence/live-writer.ts
+init_esm_shims();
+init_ledger();
+init_session();
+import { isAbsolute as isAbsolute7, relative as relative25 } from "pathe";
+function recordMarkedStage(projectRoot, input3) {
+  if (!isKnownStage(input3.stage)) return false;
+  const ctx = {
+    sessionId: input3.sessionId,
+    adapter: input3.adapter ?? "claude-code",
+    now: input3.now
+  };
+  try {
+    if (input3.phase === "start") {
+      startStage(projectRoot, input3.stage, ctx);
+    } else {
+      endStage(projectRoot, input3.stage, { artifactPaths: input3.artifactPaths ?? [] }, ctx);
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/stage-evidence/narration.ts
+init_esm_shims();
+init_ledger();
+init_session();
+var STAGE_NARRATION = {
+  ticket_intake: "picking up the ticket and reading what it needs",
+  planning: "planning this out, checking which module it touches",
+  specification: "writing the spec before any code",
+  development: "building it to the spec",
+  review: "reviewing the change for regressions",
+  checks: "running the gates: format, tests, build, rules",
+  documentation_sync: "syncing the docs this change touched",
+  delivery: "delivering per the branch and PR conventions"
+};
+function stageNarrationLine(stage) {
+  const text = STAGE_NARRATION[stage];
+  return text ? `\u25B8 paqad \xB7 ${text}` : "";
+}
+function markerNarrationLine(stage, phase) {
+  if (!STAGE_NARRATION[stage]) return "";
+  if (phase === "start") return stageNarrationLine(stage);
+  return `\u25B8 paqad \xB7 ${stage.replace(/_/g, " ")} done \u2014 evidence recorded in the ledger`;
+}
+
+// src/cli/commands/stage.ts
+function createStageCommand() {
+  return new Command21("stage").description(
+    "Mark a feature-development stage boundary in the stage-evidence ledger (clears the pre-code block for planning/specification)"
+  ).argument("<phase>", "'start' or 'end'").argument("<stage>", `one of: ${STAGE_ORDER.join(", ")}`).option("--project-root <path>", "Project root", process.cwd()).option(
+    "--session <id>",
+    "Session id to record under (defaults to SE_SESSION / CLAUDE_SESSION_ID, then the shared ledger-session cache)"
+  ).action((phase, stage, options) => {
+    if (phase !== "start" && phase !== "end") {
+      console.error(`unknown phase "${phase}" \u2014 use 'start' or 'end'`);
+      process.exitCode = 1;
+      return;
+    }
+    const root = options.projectRoot;
+    const sessionId = resolveSessionId(
+      root,
+      options.session ?? process.env.SE_SESSION ?? process.env.CLAUDE_SESSION_ID ?? null
+    );
+    const recorded = recordMarkedStage(root, { sessionId, stage, phase });
+    if (!recorded) {
+      console.error(
+        `could not record "${stage} ${phase}" \u2014 unknown stage "${stage}". Stages, in order: ${STAGE_ORDER.join(", ")}`
+      );
+      process.exitCode = 1;
+      return;
+    }
+    const line = markerNarrationLine(stage, phase);
+    if (line) console.log(line);
+    console.log(JSON.stringify({ recorded: true, stage, phase }));
+  });
+}
+
 // src/cli/commands/status.ts
 init_esm_shims();
 import { resolve as resolve14 } from "path";
-import { Command as Command21 } from "commander";
+import { Command as Command22 } from "commander";
 init_reconciler();
 function collectDriftSignals(projectRoot) {
   const drift = readDriftReport(projectRoot);
@@ -35349,7 +35599,7 @@ function driftSignalsTrip(signals) {
   return signals.mmFindings > 0 || signals.staleModules.length > 0 || signals.expiredDecisions.length > 0 || signals.mmDocMissing > 0 || signals.blocked !== null;
 }
 function createStatusCommand() {
-  return new Command21("status").description("Print a one-shot dashboard report (Markdown or JSON)").option("--format <fmt>", "Output format: markdown | json", "markdown").option("--project-root <path>", "Project root", process.cwd()).option(
+  return new Command22("status").description("Print a one-shot dashboard report (Markdown or JSON)").option("--format <fmt>", "Output format: markdown | json", "markdown").option("--project-root <path>", "Project root", process.cwd()).option(
     "--fail-on-drift",
     "Exit non-zero when module-map drift, stale module-health, expired MD-XXXX decisions, or MM-DOC-MISSING findings are present",
     false
@@ -35391,9 +35641,9 @@ function createStatusCommand() {
 
 // src/cli/commands/update.ts
 init_esm_shims();
-import { Command as Command22 } from "commander";
+import { Command as Command23 } from "commander";
 function createUpdateCommand() {
-  return new Command22("update").description("Update framework-managed artifacts").option("--project-root <path>", "Project root", process.cwd()).option("--silent", "Suppress output; write results to audit log only").action(async (options) => {
+  return new Command23("update").description("Update framework-managed artifacts").option("--project-root <path>", "Project root", process.cwd()).option("--silent", "Suppress output; write results to audit log only").action(async (options) => {
     try {
       const report = await new FrameworkUpdater().run(options.projectRoot);
       if (!options.silent) {
@@ -35417,7 +35667,7 @@ function createUpdateCommand() {
 
 // src/cli/program.ts
 function createProgram() {
-  const program = new Command23();
+  const program = new Command24();
   program.name("paqad-ai").description("AI Agency Framework for software agencies").version(VERSION).showSuggestionAfterError(true);
   program.addCommand(createInstallCommand());
   program.addCommand(createCapabilitiesCommand());
@@ -35440,6 +35690,7 @@ function createProgram() {
   program.addCommand(createRagEvidenceCommand());
   program.addCommand(createUpdateCommand());
   program.addCommand(createPatternsCommand());
+  program.addCommand(createStageCommand());
   program.addCommand(createStatusCommand());
   return program;
 }