archctx 0.5.3 → 0.5.5

package/assets/catalog.yaml

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "archcontext.practice-catalog-manifest/v1",
   "catalogVersion": "2026.06.0",
-  "productVersion": "0.5.3",
+  "productVersion": "0.5.5",
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "entries": [
     {
@@ -389,5 +389,5 @@
     "structurizr.dsl",
     "twelve-factor"
   ],
-  "catalogDigest": "sha256:22e027f21c1c9d5d3891bf20e49aeba02e0a19ff40c08d7835d5832774123c46"
+  "catalogDigest": "sha256:bb1b5d5eacd5faab73dfa99d6c5368ce70bdd1c0b99b0d7f8e1f13478a433beb"
 }

package/bin/archctx.mjs

@@ -1213,7 +1213,7 @@ function productVersionManifest() {
     }
   };
 }
-var ARCHCONTEXT_PRODUCT_NAME = "archctx", ARCHCONTEXT_PRODUCT_VERSION = "0.5.3", ARCHCONTEXT_PACKAGE_MANAGER = "bun@1.4.0", ARCHCONTEXT_NODE_RANGE = ">=22.22 <26", LOCAL_RUNTIME_RPC_SCHEMA_VERSION = "archcontext.runtime-rpc/v1", ARCHCONTEXT_SCHEMA_SET_VERSION = "2026-07-11.explorer-view-v2";
+var ARCHCONTEXT_PRODUCT_NAME = "archctx", ARCHCONTEXT_PRODUCT_VERSION = "0.5.5", ARCHCONTEXT_PACKAGE_MANAGER = "bun@1.4.0", ARCHCONTEXT_NODE_RANGE = ">=22.22 <26", LOCAL_RUNTIME_RPC_SCHEMA_VERSION = "archcontext.runtime-rpc/v1", ARCHCONTEXT_SCHEMA_SET_VERSION = "2026-07-11.explorer-view-v2";
 
 // packages/contracts/src/refactor.ts
 function refactorProposalDigest(proposal) {
@@ -2552,7 +2552,7 @@ var init_src2 = __esm(() => {
 
 // node_modules/.bun/@colbymchenry+codegraph@1.5.0/node_modules/@colbymchenry/codegraph/npm-sdk.js
 var require_npm_sdk = __commonJS(function(exports, module) {
-  var __dirname = "/Users/ancienttwo/Projects/arch-context/node_modules/.bun/@colbymchenry+codegraph@1.5.0/node_modules/@colbymchenry/codegraph";
+  var __dirname = "/private/tmp/archctx-book-freshness/node_modules/.bun/@colbymchenry+codegraph@1.5.0/node_modules/@colbymchenry/codegraph";
   var path = __require("path");
   var os = __require("os");
   var fs = __require("fs");
@@ -34403,9 +34403,16 @@ class ArchctxDaemon {
       });
     }
     if (command === "recommendations") {
+      const gitScope = await this.architectureLedgerGitScope(root);
       return okEnvelope("book.recommendations", {
         ...queryArchitectureLedgerBookRecommendations({ events: replay.events, openOnly: input.openOnly, explain: input.explain, ...budget }),
-        freshness,
+        freshness: {
+          ...freshness,
+          repository: gitScope.repository,
+          worktree: gitScope.worktree,
+          headSha: gitScope.worktree.headSha,
+          worktreeDigest: gitScope.worktree.worktreeDigest
+        },
         provenance
       });
     }
@@ -40191,7 +40198,7 @@ async function runCliUnchecked(command2 = "help", args2 = [], cwd, deps = {}) {
       case "status":
         return (await runtime()).runtimeStatus(cwd);
       case "projection":
-        return runProjectionProtocolCommand(args2, cwd, await runtime());
+        return await runProjectionProtocolCommand(args2, cwd, await runtime());
       case "repo": {
         const subcommand = args2[0] ?? "list";
         if (subcommand === "add") {
@@ -40218,7 +40225,7 @@ async function runCliUnchecked(command2 = "help", args2 = [], cwd, deps = {}) {
       case "ledger":
         return runLedgerCommand(args2, cwd, runtime);
       case "book":
-        return runBookCommand(args2, cwd, await runtime());
+        return await runBookCommand(args2, cwd, await runtime());
       case "recommendations":
         return runRecommendationsCommand(args2, cwd, await runtime());
       case "refactor":
@@ -41126,7 +41133,7 @@ function architectureProjectionProfile(args2) {
   }
   return profile;
 }
-async function runArchitectureDocsAdoptionCommand(args2, root, daemon, projection3, profile, generatedAt, acceptedChange) {
+async function runArchitectureDocsAdoptionCommand(args2, root, daemon, projection3, profile, generatedAt, acceptedChange, protocolRequest) {
   if (profile !== REPO_HARNESS_PROJECTION_PROFILE) {
     return errorEnvelope("docs.adopt", "AC_SCHEMA_INVALID", `docs adopt requires --profile ${REPO_HARNESS_PROJECTION_PROFILE}`);
   }
@@ -41165,15 +41172,20 @@ async function runArchitectureDocsAdoptionCommand(args2, root, daemon, projectio
     return errorEnvelope("docs.adopt", "AC_PRECONDITION_FAILED", "projection-adoption-preview-mismatch");
   }
   const simulatedByPath = new Map(projection3.loaded.existingFiles.map((file) => [file.path, file]));
-  for (const file of [...projection3.plan.files, ...adoption2.files])
+  for (const file of [...projection3.files, ...adoption2.files])
     simulatedByPath.set(file.path, file);
-  const canonicalFirst = buildArchitectureDocsProjection(root, generatedAt, profile, [...simulatedByPath.values()], acceptedChange);
+  const canonicalFirst = buildArchitectureDocsProjection(root, generatedAt, profile, [...simulatedByPath.values()]);
   const canonicalExistingByPath = new Map(simulatedByPath);
   for (const file of canonicalFirst.files)
     canonicalExistingByPath.set(file.path, file);
-  const canonical = buildArchitectureDocsProjection(root, generatedAt, profile, [...canonicalExistingByPath.values()], acceptedChange);
+  const canonical = buildArchitectureDocsProjection(root, generatedAt, profile, [...canonicalExistingByPath.values()]);
   if (!canonical.plan.drift.ok || canonical.plan.rejected.length > 0 || canonical.plan.projectionDigest !== canonicalFirst.plan.projectionDigest) {
-    return errorEnvelope("docs.adopt", "AC_PRECONDITION_FAILED", "projection-adoption-fixed-point-unproven");
+    const reasons = canonical.plan.rejected.map((entry) => entry.reasonCode).join(",") || "none";
+    const drift = canonical.plan.drift.diffs.map((entry) => `${entry.path}:${entry.reasonCode}`).join(",") || "none";
+    return errorEnvelope("docs.adopt", "AC_PRECONDITION_FAILED", `projection-adoption-fixed-point-unproven: drift=${drift}; rejected=${reasons}; digest=${canonical.plan.projectionDigest === canonicalFirst.plan.projectionDigest ? "stable" : "changed"}`);
+  }
+  if (protocolRequest) {
+    return applyProjectionProtocolFixedPoint(protocolRequest, projection3, canonical, adoption2.changeSetId, root, daemon);
   }
   const filesByPath = new Map;
   for (const file of canonical.files)
@@ -41197,6 +41209,93 @@ async function runArchitectureDocsAdoptionCommand(args2, root, daemon, projectio
     apply: applied.data
   });
 }
+async function applyProjectionProtocolFixedPoint(request, input, fixedPoint, changeSetId, root, daemon) {
+  const committedFiles = projectionProtocolFilesForExpectedOutput(root, fixedPoint);
+  const committedSignals = request.acceptedChange ? input.plan.refreshSignals.map((signal) => ({
+    ...signal,
+    resultingDigests: fixedPoint.plan.architectureDigests
+  })) : fixedPoint.plan.refreshSignals;
+  const applyIdentity = request.acceptedChange ? createProjectionApplyIdentity({
+    repositoryId: request.expected.repositoryId,
+    workspaceId: request.expected.workspaceId,
+    acceptedChange: request.acceptedChange,
+    changeSetId,
+    idempotencyKey: `idem_${changeSetId}`,
+    files: committedFiles,
+    refreshSignals: committedSignals
+  }) : undefined;
+  const appliedResult = projectionProtocolResult(request, input, "applied", fixedPoint, applyIdentity, {
+    files: committedFiles,
+    refreshSignals: committedSignals
+  });
+  let recoveryBinding;
+  if (applyIdentity) {
+    try {
+      recoveryBinding = createProjectionApplyRecoveryBinding(request, fixedPoint, appliedResult);
+    } catch (error) {
+      return errorEnvelope("projection.run", "AC_PRECONDITION_FAILED", error instanceof Error ? error.message : String(error));
+    }
+  }
+  const applyReceipt = applyIdentity ? {
+    schemaVersion: "archcontext.projection-apply-receipt/v1",
+    identity: applyIdentity,
+    result: appliedResult,
+    recovery: recoveryBinding
+  } : undefined;
+  const planned = await daemon.planUpdate(root, {
+    id: changeSetId,
+    reason: { taskSessionId: request.requestId },
+    operations: [architectureDocsRenderProjectionOperation(root, fixedPoint.files)],
+    worktreeDigestPrecondition: {
+      profile: "architecture-documentation-projection",
+      expectedDigest: request.expected.worktreeDigest
+    }
+  });
+  if (!planned.ok)
+    return planned;
+  const applied = await daemon.applyUpdate(root, {
+    id: changeSetId,
+    approved: true,
+    expectedWorktreeDigest: request.expected.worktreeDigest,
+    worktreeDigestProfile: "architecture-documentation-projection",
+    ...applyReceipt ? { projectionApplyReceipt: applyReceipt } : {}
+  });
+  if (!applied.ok)
+    return applied;
+  if (!applyReceipt)
+    return projectionProtocolResultEnvelope(appliedResult);
+  let postApplyMatches = false;
+  try {
+    postApplyMatches = architectureDocumentationProjectionWorktreeDigest(root, loadNativeModelFromArchContext(root)) === request.expected.worktreeDigest;
+    if (!postApplyMatches) {
+      process.stderr.write(`warning: projection post-apply worktree digest diverged from the accepted snapshot; refresh delivery deferred to reconcile
+`);
+    }
+  } catch (error) {
+    process.stderr.write(`warning: projection post-apply verification failed: ${error instanceof Error ? error.message : String(error)}
+`);
+    postApplyMatches = false;
+  }
+  if (!postApplyMatches) {
+    return projectionProtocolResultEnvelope(projectionResultDelivery(appliedResult, "applied-reconcile-required", []));
+  }
+  const delivery = await daemon.recoverProjectionApply(root, {
+    schemaVersion: PROJECTION_APPLY_RECOVERY_INTENT_SCHEMA_VERSION,
+    requestId: request.requestId,
+    profile: REPO_HARNESS_PROJECTION_PROFILE,
+    receipt: {
+      lookupKey: applyReceipt.identity.lookupKey,
+      applyId: applyReceipt.identity.applyId
+    }
+  });
+  if (!delivery.ok)
+    return delivery;
+  const delivered = delivery.data;
+  if (delivered.found !== true || delivered.refreshSignalsDelivered !== true) {
+    return errorEnvelope("projection.run", "AC_PRECONDITION_FAILED", "committed projection apply receipt was not available for first delivery");
+  }
+  return projectionProtocolResultEnvelope(projectionResultDelivery(appliedResult, "applied", delivered.receipt.result.refreshSignals, request.requestId));
+}
 async function runProjectionProtocolCommand(args2, cwd, daemon) {
   const subcommand = args2[0] ?? "run";
   if (subcommand === "recover")
@@ -41254,19 +41353,10 @@ async function runProjectionProtocolCommand(args2, cwd, daemon) {
       expectedWorktreeDigest,
       "--task-session-id",
       request.requestId
-    ], root, daemon, projection3, REPO_HARNESS_PROJECTION_PROFILE, generatedAt, request.acceptedChange);
+    ], root, daemon, projection3, REPO_HARNESS_PROJECTION_PROFILE, generatedAt, request.acceptedChange, request);
     if (!adopted.ok)
       return adopted;
-    let output;
-    try {
-      output = buildArchitectureDocsProjection(root, generatedAt, REPO_HARNESS_PROJECTION_PROFILE, undefined, request.acceptedChange);
-      if (!output.plan.drift.ok || output.plan.rejected.length > 0) {
-        return errorEnvelope("projection.run", "AC_PRECONDITION_FAILED", "projection adoption did not reach the architecture-docs fixed point");
-      }
-    } catch (error) {
-      return errorEnvelope("projection.run", "AC_PRECONDITION_FAILED", error instanceof Error ? error.message : String(error));
-    }
-    return projectionProtocolEnvelope(request, projection3, "applied", output);
+    return adopted;
   }
   if (request.mode === "apply" && !projection3.plan.drift.ok) {
     const changeSetId = `changeset.docs-projection-${projection3.plan.projectionDigest.replace(/^sha256:/, "").slice(0, 16)}`;
@@ -41279,91 +41369,7 @@ async function runProjectionProtocolCommand(args2, cwd, daemon) {
     } catch (error) {
       return errorEnvelope("projection.run", "AC_PRECONDITION_FAILED", error instanceof Error ? error.message : String(error));
     }
-    const committedFiles = projectionProtocolFilesForExpectedOutput(root, fixedPointProjection);
-    const committedSignals = request.acceptedChange ? projection3.plan.refreshSignals.map((signal) => ({
-      ...signal,
-      resultingDigests: fixedPointProjection.plan.architectureDigests
-    })) : fixedPointProjection.plan.refreshSignals;
-    const applyIdentity = request.acceptedChange ? createProjectionApplyIdentity({
-      repositoryId: request.expected.repositoryId,
-      workspaceId: request.expected.workspaceId,
-      acceptedChange: request.acceptedChange,
-      changeSetId,
-      idempotencyKey: `idem_${changeSetId}`,
-      files: committedFiles,
-      refreshSignals: committedSignals
-    }) : undefined;
-    const appliedResult = projectionProtocolResult(request, projection3, "applied", fixedPointProjection, applyIdentity, {
-      files: committedFiles,
-      refreshSignals: committedSignals
-    });
-    let recoveryBinding;
-    if (applyIdentity) {
-      try {
-        recoveryBinding = createProjectionApplyRecoveryBinding(request, fixedPointProjection, appliedResult);
-      } catch (error) {
-        return errorEnvelope("projection.run", "AC_PRECONDITION_FAILED", error instanceof Error ? error.message : String(error));
-      }
-    }
-    const applyReceipt = applyIdentity ? {
-      schemaVersion: "archcontext.projection-apply-receipt/v1",
-      identity: applyIdentity,
-      result: appliedResult,
-      recovery: recoveryBinding
-    } : undefined;
-    const planned = await daemon.planUpdate(root, {
-      id: changeSetId,
-      reason: { taskSessionId: request.requestId },
-      operations: [architectureDocsRenderProjectionOperation(root, fixedPointProjection.files)],
-      worktreeDigestPrecondition: {
-        profile: "architecture-documentation-projection",
-        expectedDigest: request.expected.worktreeDigest
-      }
-    });
-    if (!planned.ok)
-      return planned;
-    const applied = await daemon.applyUpdate(root, {
-      id: changeSetId,
-      approved: true,
-      expectedWorktreeDigest: request.expected.worktreeDigest,
-      worktreeDigestProfile: "architecture-documentation-projection",
-      ...applyReceipt ? { projectionApplyReceipt: applyReceipt } : {}
-    });
-    if (!applied.ok)
-      return applied;
-    if (!applyReceipt)
-      return projectionProtocolResultEnvelope(appliedResult);
-    let postApplyMatches = false;
-    try {
-      postApplyMatches = architectureDocumentationProjectionWorktreeDigest(root, loadNativeModelFromArchContext(root)) === request.expected.worktreeDigest;
-      if (!postApplyMatches) {
-        process.stderr.write(`warning: projection post-apply worktree digest diverged from the accepted snapshot; refresh delivery deferred to reconcile
-`);
-      }
-    } catch (error) {
-      process.stderr.write(`warning: projection post-apply verification failed: ${error instanceof Error ? error.message : String(error)}
-`);
-      postApplyMatches = false;
-    }
-    if (!postApplyMatches) {
-      return projectionProtocolResultEnvelope(projectionResultDelivery(appliedResult, "applied-reconcile-required", []));
-    }
-    const delivery = await daemon.recoverProjectionApply(root, {
-      schemaVersion: PROJECTION_APPLY_RECOVERY_INTENT_SCHEMA_VERSION,
-      requestId: request.requestId,
-      profile: REPO_HARNESS_PROJECTION_PROFILE,
-      receipt: {
-        lookupKey: applyReceipt.identity.lookupKey,
-        applyId: applyReceipt.identity.applyId
-      }
-    });
-    if (!delivery.ok)
-      return delivery;
-    const delivered = delivery.data;
-    if (delivered.found !== true || delivered.refreshSignalsDelivered !== true) {
-      return errorEnvelope("projection.run", "AC_PRECONDITION_FAILED", "committed projection apply receipt was not available for first delivery");
-    }
-    return projectionProtocolResultEnvelope(projectionResultDelivery(appliedResult, "applied", delivered.receipt.result.refreshSignals, request.requestId));
+    return applyProjectionProtocolFixedPoint(request, projection3, fixedPointProjection, changeSetId, root, daemon);
   }
   const status = projection3.plan.drift.ok ? "noop" : "planned";
   return projectionProtocolEnvelope(request, projection3, status);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archctx",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "Local architecture context CLI for agentic coding workflows.",
   "private": false,
   "type": "module",