archctx 0.4.2 → 0.4.4

package/assets/catalog.yaml

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "archcontext.practice-catalog-manifest/v1",
   "catalogVersion": "2026.06.0",
-  "productVersion": "0.4.2",
+  "productVersion": "0.4.4",
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "entries": [
     {
@@ -389,5 +389,5 @@
     "structurizr.dsl",
     "twelve-factor"
   ],
-  "catalogDigest": "sha256:7fc97d6c05657eeeee604a302a22e0afe77dc2d0ffea89442de193e570d9b8bf"
+  "catalogDigest": "sha256:02457d42fb45b16f949b88355ec2ba83c53e8d7e74d32fba28500984d89e1b64"
 }

package/bin/archctx.mjs

@@ -919,7 +919,7 @@ function sortedUniqueIssues(label, values) {
   const expected = [...new Set(values)].sort();
   return expected.length === values.length && expected.every((value, index) => value === values[index]) ? [] : [`${label} must be sorted and unique`];
 }
-var PROJECTION_REQUEST_SCHEMA_VERSION = "archcontext.projection-request/v1", PROJECTION_RESULT_SCHEMA_VERSION = "archcontext.projection-result/v1", ARCHITECTURE_REFRESH_SIGNAL_SCHEMA_VERSION = "archcontext.architecture-refresh-signal/v1", ARCHCTX_CAPABILITIES_SCHEMA_VERSION = "archcontext.capabilities/v1", ARCHITECTURE_DOCS_RENDERER_VERSION = "archcontext.docs-renderer/v2", AGENT_CONTEXT_RENDERER_VERSION = "archcontext.agent-context-renderer/v1", PROJECTION_MODES, PROJECTION_TARGETS, ARCHITECTURE_MAJOR_CHANGE_REASON_CODES, ARCHCTX_FEATURES;
+var PROJECTION_REQUEST_SCHEMA_VERSION = "archcontext.projection-request/v1", PROJECTION_RESULT_SCHEMA_VERSION = "archcontext.projection-result/v1", ARCHITECTURE_REFRESH_SIGNAL_SCHEMA_VERSION = "archcontext.architecture-refresh-signal/v1", ARCHCTX_CAPABILITIES_SCHEMA_VERSION = "archcontext.capabilities/v1", ARCHITECTURE_DOCS_RENDERER_VERSION = "archcontext.docs-renderer/v4", AGENT_CONTEXT_RENDERER_VERSION = "archcontext.agent-context-renderer/v1", PROJECTION_MODES, PROJECTION_TARGETS, ARCHITECTURE_MAJOR_CHANGE_REASON_CODES, ARCHCTX_FEATURES;
 var init_projection = __esm(() => {
   init_schema();
   PROJECTION_MODES = ["check", "plan", "apply", "adopt"];
@@ -1000,7 +1000,7 @@ function productVersionManifest() {
     }
   };
 }
-var ARCHCONTEXT_PRODUCT_NAME = "archctx", ARCHCONTEXT_PRODUCT_VERSION = "0.4.2", ARCHCONTEXT_PACKAGE_MANAGER = "bun@1.3.10", ARCHCONTEXT_NODE_RANGE = ">=24 <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.4.4", ARCHCONTEXT_PACKAGE_MANAGER = "bun@1.3.10", ARCHCONTEXT_NODE_RANGE = ">=24 <26", LOCAL_RUNTIME_RPC_SCHEMA_VERSION = "archcontext.runtime-rpc/v1", ARCHCONTEXT_SCHEMA_SET_VERSION = "2026-07-11.explorer-view-v2";
 
 // packages/contracts/src/validator.ts
 function validateJsonSchema(schema, value) {
@@ -8042,21 +8042,28 @@ function renderArchitectureDocumentationProjection(input) {
     resulting: semanticState,
     acceptedChange: input.refreshContext?.acceptedChange
   });
-  const entitySourceDigest = digestJson({
-    sourceDigest: input.sourceDigest,
-    sourceScaleSignals: [...scaleSignalsByNodeId.values()].sort((left, right) => left.nodeId.localeCompare(right.nodeId)),
-    semanticProofs: [...semanticCompilationsByNodeId.values()].map((compilation) => ({ capabilityId: compilation.capabilityId, proofDigest: compilation.proofDigest })).sort((left, right) => left.capabilityId.localeCompare(right.capabilityId))
-  });
   const targetDrafts = architectureDocumentationTargetDrafts(model, layout2);
   const declaresSourceByNodeId = new Map(model.nodes.map((node) => [node.id, (nativeNodeSource(node)?.include ?? []).length > 0]));
   const changeSinceStampByNodeId = new Map(input.sourceChangesSinceStamp.map((entry) => [entry.nodeId, entry]));
+  const priorStampByNodeId = previousProjectionManifestStamps(existingByPath.get("docs/architecture/.projection-manifest.json"));
   const notices = [];
   const rendered = targetDrafts.map((draft) => {
     const existing = existingByPath.get(draft.path);
     const nodeId = draft.type === "entity-summary" ? draft.scope.id : undefined;
+    const generatedBody = renderTargetGeneratedBody(draft, model, {
+      generatedAt,
+      scaleSignalsByNodeId,
+      semanticCompilationsByNodeId,
+      decisions: input.decisions ?? [],
+      timeline: input.timeline ?? [],
+      layout: layout2
+    });
+    let targetSourceDigest = input.sourceDigest;
     let targetVerifiedAgainst;
     if (nodeId !== undefined) {
-      const decision = stickyVerifiedAgainst(existing, draft.targetId, entitySourceDigest, {
+      targetSourceDigest = digestJson(generatedBody);
+      const decision = stickyVerifiedAgainst(existing, draft.targetId, targetSourceDigest, {
+        priorStamp: priorStampByNodeId.get(nodeId),
         nodeDeclaresSource: declaresSourceByNodeId.get(nodeId) === true,
         measurement: changeSinceStampByNodeId.get(nodeId)
       });
@@ -8072,22 +8079,12 @@ function renderArchitectureDocumentationProjection(input) {
       }
       targetVerifiedAgainst = decision.kind === "reuse" ? decision.verifiedAgainst : verifiedAgainst;
     }
-    const generatedBody = renderTargetGeneratedBody(draft, model, {
-      generatedAt,
-      verifiedAgainst: targetVerifiedAgainst ?? verifiedAgainst,
-      scaleSignalsByNodeId,
-      semanticCompilationsByNodeId,
-      decisions: input.decisions ?? [],
-      timeline: input.timeline ?? [],
-      layout: layout2
-    });
     const generatedBodyDigest = digestJson({ targetId: draft.targetId, body: generatedBody });
     const target = projectionTarget({
       ...draft,
       rendererVersion,
-      sourceDigest: draft.type === "entity-summary" ? entitySourceDigest : input.sourceDigest,
-      outputDigest: generatedBodyDigest,
-      ...targetVerifiedAgainst ? { verifiedAgainst: targetVerifiedAgainst } : {}
+      sourceDigest: targetSourceDigest,
+      outputDigest: generatedBodyDigest
     });
     const wrapped = wrapGeneratedRegion(target, generatedBody);
     const body = mergeGeneratedRegion(target, wrapped, existing, draft.skeleton);
@@ -8209,6 +8206,39 @@ function renderArchitectureDocumentationProjection(input) {
     notices
   };
 }
+function previousProjectionManifestStamps(body) {
+  const stamps = new Map;
+  if (body === undefined)
+    return stamps;
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    return stamps;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+    return stamps;
+  const targets = parsed.targets;
+  if (!Array.isArray(targets))
+    return stamps;
+  for (const entry of targets) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry))
+      continue;
+    const record2 = entry;
+    if (record2.type !== "entity-summary")
+      continue;
+    const scope = record2.scope;
+    const nodeId = scope && typeof scope === "object" && !Array.isArray(scope) ? scope.id : undefined;
+    if (typeof nodeId !== "string" || nodeId === "")
+      continue;
+    try {
+      stamps.set(nodeId, assertArchitectureProjectionVerifiedAgainst(record2.verifiedAgainst));
+    } catch {
+      continue;
+    }
+  }
+  return stamps;
+}
 function architectureProjectionSemanticBaseline(body) {
   if (body === undefined)
     return;
@@ -8353,6 +8383,30 @@ function countFileLines(absolute) {
   return content.endsWith(`
 `) ? newlines : newlines + 1;
 }
+function scaleMagnitudeBucketLabel(value) {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new Error(`architecture-docs-projection-scale-signal-not-a-count: ${value}`);
+  }
+  if (value === 0)
+    return "0";
+  const mantissas = [1, 2, 5];
+  let index = 0;
+  let magnitude = 1;
+  let lower = 1;
+  for (;; ) {
+    const nextIndex = (index + 1) % mantissas.length;
+    const nextMagnitude = nextIndex === 0 ? magnitude * 10 : magnitude;
+    const upper = mantissas[nextIndex] * nextMagnitude;
+    if (upper > value) {
+      const unit = lower >= 1e6 ? 1e6 : lower >= 1e4 ? 1000 : 1;
+      const suffix = unit === 1e6 ? "M" : unit === 1000 ? "k" : "";
+      return `${lower / unit}${suffix}–${upper / unit}${suffix}`;
+    }
+    index = nextIndex;
+    magnitude = nextMagnitude;
+    lower = upper;
+  }
+}
 function architectureDocumentationSourceDigest(input) {
   return digestJson({
     model: input.model,
@@ -8829,7 +8883,7 @@ function projectionTarget(input) {
     path: input.path,
     ownership: input.ownership,
     generatedRegion: {
-      startMarker: generatedStartMarker(input.targetId, input.sourceDigest, input.rendererVersion, input.outputDigest, input.verifiedAgainst),
+      startMarker: generatedStartMarker(input.targetId, input.sourceDigest, input.rendererVersion, input.outputDigest),
       endMarker: generatedEndMarker(input.targetId)
     },
     rendererVersion: input.rendererVersion,
@@ -8844,7 +8898,6 @@ function renderTargetGeneratedBody(target, model, input) {
   if (target.type === "entity-summary") {
     const node = model.nodes.find((entry) => entry.id === target.scope.id);
     return renderEntitySummary(node, model, {
-      verifiedAgainst: input.verifiedAgainst,
       scaleSignal: input.scaleSignalsByNodeId.get(node.id),
       semanticCompilation: input.semanticCompilationsByNodeId.get(node.id)
     });
@@ -8908,11 +8961,10 @@ function renderEntitySummary(node, model, input) {
   const localContracts = contractFilesForNode(node);
   const lines = [
     `> **狀態**:${node.status ? `\`${node.status}\`` : "未宣告(`status` 缺失)"}`,
-    `> **Verified against**:\`${input.verifiedAgainst.branch}@${input.verifiedAgainst.commit}\`(${input.verifiedAgainst.committedAt.slice(0, 10)})`,
     `> **Capability ID**:\`${node.id}\`(kind \`${node.kind}\`)`,
     `> **Matched Prefixes**:${include.length > 0 ? include.map((pattern) => `\`${pattern}\``).join("、") : "未宣告(`source.include` 缺失)"}`,
     `> **Local Contracts**:${localContracts.length > 0 ? localContracts.map((entry) => `\`${entry}\``).join("、") : "未宣告(`extensions.localContracts` 缺失)"}`,
-    "> **事實優先級**:倉庫當前狀態 > 本文檔機器區 > 本文檔人工區。機器區(引言、§1、§2)由 ArchContext 從架構模型與 Git 狀態投影生成,手改會在下次投影被覆蓋。",
+    "> **事實優先級**:倉庫當前狀態 > 本文檔機器區 > 本文檔人工區。機器區(引言、§1、§2)由 ArchContext 從架構模型與源碼度量投影生成,手改會在下次投影被覆蓋。本文檔不記錄出處;本次投影所驗證的 commit 見 `docs/architecture/.projection-manifest.json`。",
     ...node.summary ? ["", node.summary] : [],
     "",
     "## 1. P1:能力架構地圖",
@@ -8932,11 +8984,10 @@ function renderEntitySummary(node, model, input) {
     "### 1.3 規模信號",
     "",
     ...input.scaleSignal ? [
-      `- 文件數:\`${input.scaleSignal.fileCount}\``,
-      `- 總行數:\`${input.scaleSignal.lineCount}\``,
+      `- 規模量級:\`${scaleMagnitudeBucketLabel(input.scaleSignal.fileCount)}\` 個文件 / \`${scaleMagnitudeBucketLabel(input.scaleSignal.lineCount)}\` 行`,
       `- 匹配前綴:${input.scaleSignal.includePatterns.map((pattern) => `\`${pattern}\``).join("、")}`,
       ...input.scaleSignal.excludePatterns.length > 0 ? [`- 排除前綴:${input.scaleSignal.excludePatterns.map((pattern) => `\`${pattern}\``).join("、")}`] : [],
-      "- 復算:`archctx docs plan --json`(掃描 `source.include` 減 `source.exclude`,跳過 `.git/` 與 `node_modules/`)"
+      "- 推導:掃描 `source.include` 減 `source.exclude`,跳過 `.git/` 與 `node_modules/`,再按 1–2–5 階梯分桶。精確計數不入本文檔:量級足以回答「這個能力有多大」,而逐行計數會讓覆蓋範圍內任何一次源碼改動都改寫本文檔。"
     ] : ["- 未宣告 `source.include`,規模信號無法推導。"],
     "",
     "### 1.4 依賴邊界",
@@ -9197,44 +9248,22 @@ function parseGeneratedRegionMetadata(marker) {
   return {
     sourceDigest: marker.match(/sourceDigest="([^"]+)"/)?.[1],
     rendererVersion: marker.match(/rendererVersion="([^"]+)"/)?.[1],
-    outputDigest: marker.match(/outputDigest="([^"]+)"/)?.[1],
-    verifiedAgainst: marker.match(/verifiedAgainst="([^"]+)"/)?.[1]
+    outputDigest: marker.match(/outputDigest="([^"]+)"/)?.[1]
   };
 }
-function generatedStartMarker(targetId, sourceDigest, rendererVersion, outputDigest, verifiedAgainst) {
-  const stamp = verifiedAgainst ? serializeMarkerVerifiedAgainst(verifiedAgainst) : undefined;
-  return `${ARCHITECTURE_DOCS_GENERATED_BEGIN_PREFIX} target="${targetId}" sourceDigest="${sourceDigest}" rendererVersion="${rendererVersion}" outputDigest="${outputDigest}"${stamp ? ` verifiedAgainst="${stamp}"` : ""} -->`;
-}
-function serializeMarkerVerifiedAgainst(value) {
-  const stamp = `${value.branch}@${value.commit}@${value.committedAt}`;
-  return /["<>]/.test(stamp) ? undefined : stamp;
+function generatedStartMarker(targetId, sourceDigest, rendererVersion, outputDigest) {
+  return `${ARCHITECTURE_DOCS_GENERATED_BEGIN_PREFIX} target="${targetId}" sourceDigest="${sourceDigest}" rendererVersion="${rendererVersion}" outputDigest="${outputDigest}" -->`;
 }
-function parseMarkerVerifiedAgainst(value) {
-  if (!value)
-    return;
-  const parts = value.split("@");
-  if (parts.length < 3)
-    return;
-  try {
-    return assertArchitectureProjectionVerifiedAgainst({
-      branch: parts.slice(0, -2).join("@"),
-      commit: parts[parts.length - 2],
-      committedAt: parts[parts.length - 1]
-    });
-  } catch {
-    return;
-  }
-}
-function stickyVerifiedAgainst(existing, targetId, entitySourceDigest, node) {
+function stickyVerifiedAgainst(existing, targetId, nodeSourceDigest, node) {
   if (!existing)
     return { kind: "restamp" };
   const region = findGeneratedRegion(existing, targetId);
   if (!region)
     return { kind: "restamp" };
   const metadata = parseGeneratedRegionMetadata(region.startMarker);
-  if (metadata.sourceDigest !== entitySourceDigest)
+  if (metadata.sourceDigest !== nodeSourceDigest)
     return { kind: "restamp" };
-  const stamp = parseMarkerVerifiedAgainst(metadata.verifiedAgainst);
+  const stamp = node.priorStamp;
   if (!stamp)
     return { kind: "restamp" };
   if (!node.nodeDeclaresSource)
@@ -29884,8 +29913,8 @@ class ArchctxDaemon {
       ownerRegistry: loadPracticeWaiverOwnerRegistry(session.workspace.root),
       now: this.clock()
     }) : undefined;
-    const projectionDrift = this.completeTaskProjectionDrift(session.workspace.root);
-    const projectionFreshness = this.completeTaskProjectionFreshness(session.workspace.root);
+    const projectionDrift = completeTaskProjectionDrift(session.workspace.root);
+    const projectionFreshness = completeTaskProjectionFreshness(session.workspace.root);
     const reviewInput = {
       taskSessionId,
       posture: input.posture ?? "normal",
@@ -29906,12 +29935,6 @@ class ArchctxDaemon {
     await this.localStore.saveReviewResult(review.reviewId, review);
     return okEnvelope("complete_task", review);
   }
-  completeTaskProjectionDrift(root) {
-    return completeTaskProjectionDrift(root);
-  }
-  completeTaskProjectionFreshness(root) {
-    return completeTaskProjectionFreshness(root);
-  }
   manualExternalDocumentation() {
     if (this.externalDocumentationInjected)
       return this.externalDocumentation;
@@ -35484,8 +35507,8 @@ class ArchctxDaemon2 {
       ownerRegistry: loadPracticeWaiverOwnerRegistry(session.workspace.root),
       now: this.clock()
     }) : undefined;
-    const projectionDrift = this.completeTaskProjectionDrift(session.workspace.root);
-    const projectionFreshness = this.completeTaskProjectionFreshness(session.workspace.root);
+    const projectionDrift = completeTaskProjectionDrift2(session.workspace.root);
+    const projectionFreshness = completeTaskProjectionFreshness2(session.workspace.root);
     const reviewInput = {
       taskSessionId,
       posture: input.posture ?? "normal",
@@ -35506,12 +35529,6 @@ class ArchctxDaemon2 {
     await this.localStore.saveReviewResult(review.reviewId, review);
     return okEnvelope("complete_task", review);
   }
-  completeTaskProjectionDrift(root) {
-    return completeTaskProjectionDrift2(root);
-  }
-  completeTaskProjectionFreshness(root) {
-    return completeTaskProjectionFreshness2(root);
-  }
   manualExternalDocumentation() {
     if (this.externalDocumentationInjected)
       return this.externalDocumentation;

package/package.json

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

package/schemas/runtime/archctx-capabilities.schema.json

@@ -31,7 +31,7 @@
       "additionalProperties": false,
       "required": ["architectureDocs", "agentContext"],
       "properties": {
-        "architectureDocs": { "const": "archcontext.docs-renderer/v2" },
+        "architectureDocs": { "const": "archcontext.docs-renderer/v4" },
         "agentContext": { "const": "archcontext.agent-context-renderer/v1" }
       }
     },

package/schemas/runtime/projection-result.schema.json

@@ -42,7 +42,7 @@
         "codeGraphDigest": { "$ref": "#/$defs/digest" },
         "indexedWorktreeDigest": { "$ref": "#/$defs/nullableDigest" },
         "projectionInputDigest": { "$ref": "#/$defs/digest" },
-        "rendererVersion": { "const": "archcontext.docs-renderer/v2" },
+        "rendererVersion": { "const": "archcontext.docs-renderer/v4" },
         "layoutVersion": { "const": "archcontext.docs-layout/v1" },
         "generatedFrom": {
           "type": "object",