archctx-contracts 0.7.0 → 0.7.2

package/fixtures/valid/archctx-capabilities.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "archcontext.capabilities/v1",
-  "package": { "name": "archctx", "version": "0.7.0" },
+  "package": { "name": "archctx", "version": "0.7.2" },
   "protocols": {
     "projectionRequest": "archcontext.projection-request/v1",
     "projectionResult": "archcontext.projection-result/v2",
@@ -10,5 +10,5 @@
     "architectureDocs": "archcontext.docs-renderer/v5",
     "agentContext": "archcontext.agent-context-renderer/v1"
   },
-  "features": ["architecture-change-capabilities-v1", "architecture-docs-renderer-v2", "architecture-refresh-signal-v1", "changeset-entity-operations-v1", "code-facts-unavailable-error-v1", "module-statistics-v1", "projection-apply-readback-v1", "projection-apply-receipt-v1", "projection-apply-recovery-v1", "projection-apply-replay-v1", "projection-check-freshness-v1", "projection-manifest-contract-v2", "projection-observed-major-change-acceptance-v1", "projection-orphan-review-v1", "projection-preview-v1", "projection-prior-committed-applies-v1", "projection-protocol-v2", "recommendation-scan-decision-v1", "recommendation-v3", "refactor-assessment-v1", "refactor-observation-evidence-v1", "refactor-resolution-v1", "refactor-scan-limits-v1"]
+  "features": ["architecture-change-capabilities-v1", "architecture-docs-renderer-v2", "architecture-refresh-signal-v1", "capability-dependencies-v1", "changeset-entity-operations-v1", "changeset-ownership-delta-v1", "code-facts-unavailable-error-v1", "docs-anchors-v1", "flow-selector-check-v1", "module-statistics-v1", "projection-apply-readback-v1", "projection-apply-receipt-v1", "projection-apply-recovery-v1", "projection-apply-replay-v1", "projection-check-freshness-v1", "projection-manifest-contract-v2", "projection-observed-major-change-acceptance-v1", "projection-orphan-review-v1", "projection-preview-v1", "projection-prior-committed-applies-v1", "projection-protocol-v2", "recommendation-scan-decision-v1", "recommendation-v3", "refactor-assessment-v1", "refactor-observation-evidence-v1", "refactor-resolution-v1", "refactor-scan-limits-v1", "refactor-scan-untracked-count-v1"]
 }

package/fixtures/valid/capability-dependencies.json

@@ -0,0 +1,35 @@
+{
+  "schemaVersion": "archcontext.capability-dependencies/v1",
+  "ownershipRule": "parent-chain",
+  "filter": { "from": null, "into": "capability.billing" },
+  "capabilities": ["capability.billing", "capability.checkout"],
+  "matrix": [
+    { "from": "capability.checkout", "to": "capability.billing", "imports": 2, "calls": null }
+  ],
+  "imports": {
+    "coverage": "complete",
+    "reasonCodes": [],
+    "truncated": false,
+    "importNodeCount": 14,
+    "importNodeLimit": 50000,
+    "importNodeLimitExceeded": false,
+    "edgeCount": 3,
+    "unresolvedCount": 0,
+    "unattributed": { "unownedEndpoint": 1, "contestedEndpoint": 0, "noCapabilityEndpoint": 0 }
+  },
+  "calls": { "coverage": "unknown", "reasonCodes": ["call-edges-not-exposed"] },
+  "edges": {
+    "limit": 200,
+    "count": 2,
+    "omittedCount": 0,
+    "items": [
+      { "fromPath": "src/checkout/cart.ts", "toPath": "src/billing/invoice.ts", "fromCapability": "capability.checkout", "toCapability": "capability.billing" },
+      { "fromPath": "src/checkout/pay.ts", "toPath": "src/billing/invoice.ts", "fromCapability": "capability.checkout", "toCapability": "capability.billing" }
+    ]
+  },
+  "worktree": {
+    "headSha": "0123456789abcdef0123456789abcdef01234567",
+    "worktreeDigest": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
+  },
+  "privacy": { "writes": "none" }
+}

package/fixtures/valid/docs-anchors.json

@@ -0,0 +1,105 @@
+{
+  "schemaVersion": "archcontext.docs-anchors/v1",
+  "profile": "repo-harness/v1",
+  "codeGraph": {
+    "availability": "ready"
+  },
+  "summary": {
+    "nodes": 3,
+    "documents": 2,
+    "citations": 6,
+    "findings": 4,
+    "unchecked": 1,
+    "byKind": {
+      "line-moved": 1,
+      "line-out-of-range": 1,
+      "missing-path": 1,
+      "missing-symbol": 1
+    }
+  },
+  "nodes": [
+    {
+      "nodeId": "capability.runtime-harness.evals-checks",
+      "documentPath": "docs/architecture/modules/runtime-harness/evals-checks.md",
+      "citationCount": 2,
+      "findings": [
+        {
+          "kind": "missing-symbol",
+          "origin": {
+            "kind": "node-responsibility",
+            "index": 0
+          },
+          "citation": {
+            "text": "is_evidence_producer_command()",
+            "symbol": "is_evidence_producer_command"
+          }
+        }
+      ],
+      "unchecked": []
+    },
+    {
+      "nodeId": "capability.runtime-harness.hook-adapters",
+      "documentPath": "docs/architecture/modules/runtime-harness/hook-adapters.md",
+      "citationCount": 4,
+      "findings": [
+        {
+          "kind": "line-moved",
+          "origin": {
+            "kind": "document",
+            "path": "docs/architecture/modules/runtime-harness/hook-adapters.md",
+            "line": 41
+          },
+          "citation": {
+            "text": "route-registry.ts:52",
+            "path": "route-registry.ts",
+            "resolvedPath": "src/hooks/route-registry.ts",
+            "line": 52,
+            "symbol": "registerRoute"
+          },
+          "currentLines": [
+            54
+          ]
+        },
+        {
+          "kind": "line-out-of-range",
+          "origin": {
+            "kind": "document",
+            "path": "docs/architecture/modules/runtime-harness/hook-adapters.md",
+            "line": 44
+          },
+          "citation": {
+            "text": "src/hooks/runtime.ts:410",
+            "path": "src/hooks/runtime.ts",
+            "line": 410
+          },
+          "lineCount": 362
+        },
+        {
+          "kind": "missing-path",
+          "origin": {
+            "kind": "node-summary"
+          },
+          "citation": {
+            "text": "src/hooks/legacy-adapter.ts",
+            "path": "src/hooks/legacy-adapter.ts"
+          }
+        }
+      ],
+      "unchecked": [
+        {
+          "reasonCode": "path-ambiguous",
+          "origin": {
+            "kind": "document",
+            "path": "docs/architecture/modules/runtime-harness/hook-adapters.md",
+            "line": 50
+          },
+          "citation": {
+            "text": "index.ts:12",
+            "path": "index.ts",
+            "line": 12
+          }
+        }
+      ]
+    }
+  ]
+}

package/fixtures/valid/flow-selector-check.json

@@ -0,0 +1,50 @@
+{
+  "schemaVersion": "archcontext.flow-selector-check/v1",
+  "ok": false,
+  "codeGraph": { "availability": "ready", "version": "1.6.1" },
+  "summary": { "selectors": 2, "proven": 1, "unproven": 1, "usedUnproven": 1 },
+  "selectors": [
+    {
+      "nodeId": "capability.runtime.hooks",
+      "entrypointId": "entrypoint.hook.stop",
+      "sourcePath": "src/hook.ts",
+      "sourceSymbol": "runHook",
+      "sinkId": "sink.hook.journal",
+      "sinkPath": "src/journal.ts",
+      "sinkSymbol": "writeEvent",
+      "status": "proven",
+      "callSites": [{ "path": "src/hook.ts", "line": 12 }],
+      "referenceSites": [],
+      "rejectedBuiltinCallSites": [],
+      "flowSteps": [{ "flowId": "flow.runtime.hooks.stop", "stepId": "persist" }]
+    },
+    {
+      "nodeId": "capability.runtime.hooks",
+      "entrypointId": "entrypoint.hook.stop",
+      "sourcePath": "src/hook.ts",
+      "sourceSymbol": "runHook",
+      "sinkId": "sink.hook.resolve",
+      "sinkPath": "src/paths.ts",
+      "sinkSymbol": "resolve",
+      "status": "false-builtin-call",
+      "callSites": [],
+      "referenceSites": [],
+      "rejectedBuiltinCallSites": [{ "path": "src/hook.ts", "line": 7 }],
+      "flowSteps": [{ "flowId": "flow.runtime.hooks.stop", "stepId": "resolve" }]
+    }
+  ],
+  "capabilities": [
+    {
+      "capabilityId": "capability.runtime.hooks",
+      "p2Status": "unprovable",
+      "diagnostics": [
+        {
+          "code": "selector-evidence-unmatched",
+          "flowId": "flow.runtime.hooks.stop",
+          "stepId": "resolve",
+          "detail": "entrypoint.hook.stop runHook sink.hook.resolve"
+        }
+      ]
+    }
+  ]
+}

package/fixtures/valid/product-version-manifest.json

@@ -2,7 +2,7 @@
   "schemaVersion": "archcontext.product-version-manifest/v1",
   "product": {
     "name": "archctx",
-    "version": "0.7.0",
+    "version": "0.7.2",
     "distribution": "one-package"
   },
   "packageManager": "bun@1.4.3",
@@ -12,25 +12,25 @@
   "surfaces": {
     "cli": {
       "packageName": "@archcontext/surfaces",
-      "version": "0.7.0",
+      "version": "0.7.2",
       "entrypoint": "archctx"
     },
     "daemon": {
       "packageName": "@archcontext/local-runtime",
-      "version": "0.7.0",
+      "version": "0.7.2",
       "entrypoint": "archctx daemon start",
       "rpcSchemaVersion": "archcontext.runtime-rpc/v1"
     },
     "mcp": {
       "packageName": "@archcontext/surfaces",
-      "version": "0.7.0",
+      "version": "0.7.2",
       "entrypoint": "archctx mcp",
       "transport": "stdio"
     }
   },
   "schemas": {
     "schemaSetVersion": "2026-06-25.al0-ledger",
-    "contractsPackageVersion": "0.7.0",
+    "contractsPackageVersion": "0.7.2",
     "reviewChallenge": "archcontext.review-challenge/v2",
     "attestation": "archcontext.attestation/v2",
     "deviceIdentity": "archcontext.device-identity/v1",

package/fixtures/valid/runtime-refactor-scan.json

@@ -19,6 +19,7 @@
     }
   },
   "trackedFileCount": 9,
+  "untrackedExcludedCount": 0,
   "snapshot": {
     "schemaVersion": "archcontext.module-statistics/v1",
     "repository": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archctx-contracts",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",

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

@@ -43,7 +43,7 @@
         "type": "string",
         "pattern": "^[a-z0-9]+(-[a-z0-9]+)*-v[0-9]+$",
         "description": "One feature flag: a lowercase kebab-case name that ends in a version suffix (-v1, -v2, ...). The pattern is open, so a validator built from this schema accepts flags that a later archctx adds. A consumer must ignore a flag it does not know. examples lists the flags this schema version knows.",
-        "examples": ["architecture-change-capabilities-v1", "architecture-docs-renderer-v2", "architecture-refresh-signal-v1", "changeset-entity-operations-v1", "code-facts-unavailable-error-v1", "module-statistics-v1", "projection-apply-readback-v1", "projection-apply-receipt-v1", "projection-apply-recovery-v1", "projection-apply-replay-v1", "projection-check-freshness-v1", "projection-manifest-contract-v2", "projection-observed-major-change-acceptance-v1", "projection-orphan-review-v1", "projection-preview-v1", "projection-prior-committed-applies-v1", "projection-protocol-v2", "recommendation-scan-decision-v1", "recommendation-v3", "refactor-assessment-v1", "refactor-observation-evidence-v1", "refactor-resolution-v1", "refactor-scan-limits-v1"]
+        "examples": ["architecture-change-capabilities-v1", "architecture-docs-renderer-v2", "architecture-refresh-signal-v1", "capability-dependencies-v1", "changeset-entity-operations-v1", "changeset-ownership-delta-v1", "code-facts-unavailable-error-v1", "docs-anchors-v1", "flow-selector-check-v1", "module-statistics-v1", "projection-apply-readback-v1", "projection-apply-receipt-v1", "projection-apply-recovery-v1", "projection-apply-replay-v1", "projection-check-freshness-v1", "projection-manifest-contract-v2", "projection-observed-major-change-acceptance-v1", "projection-orphan-review-v1", "projection-preview-v1", "projection-prior-committed-applies-v1", "projection-protocol-v2", "recommendation-scan-decision-v1", "recommendation-v3", "refactor-assessment-v1", "refactor-observation-evidence-v1", "refactor-resolution-v1", "refactor-scan-limits-v1", "refactor-scan-untracked-count-v1"]
       }
     }
   }

package/schemas/runtime/capability-dependencies.schema.json

@@ -0,0 +1,116 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://archcontext.dev/schemas/runtime/capability-dependencies.schema.json",
+  "title": "CapabilityDependenciesV1",
+  "description": "The data of `archctx deps`: a read-only capability x capability import matrix. Owners come from the parent-chain rule `refactor scan` uses, rolled up to the nearest capability. Call counts are not available in v1.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "ownershipRule", "filter", "capabilities", "matrix", "imports", "calls", "edges", "worktree", "privacy"],
+  "properties": {
+    "schemaVersion": { "const": "archcontext.capability-dependencies/v1" },
+    "ownershipRule": { "const": "parent-chain" },
+    "filter": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["from", "into"],
+      "properties": {
+        "from": { "type": ["string", "null"] },
+        "into": { "type": ["string", "null"] }
+      }
+    },
+    "capabilities": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+    "matrix": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["from", "to", "imports", "calls"],
+        "properties": {
+          "from": { "type": "string", "minLength": 1 },
+          "to": { "type": "string", "minLength": 1 },
+          "imports": { "type": "integer", "minimum": 1 },
+          "calls": { "type": "null" }
+        }
+      }
+    },
+    "imports": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["coverage", "reasonCodes", "truncated", "importNodeCount", "importNodeLimit", "importNodeLimitExceeded", "edgeCount", "unresolvedCount", "unattributed"],
+      "properties": {
+        "coverage": { "enum": ["complete", "partial", "unknown"] },
+        "reasonCodes": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "enum": ["code-facts-import-limit", "code-facts-stale", "code-facts-truncated", "code-facts-unavailable"] }
+        },
+        "truncated": { "type": "boolean" },
+        "importNodeCount": { "type": ["integer", "null"], "minimum": 0 },
+        "importNodeLimit": { "type": "integer", "minimum": 1 },
+        "importNodeLimitExceeded": { "type": "boolean" },
+        "edgeCount": { "type": "integer", "minimum": 0 },
+        "unresolvedCount": { "type": "integer", "minimum": 0 },
+        "unattributed": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["unownedEndpoint", "contestedEndpoint", "noCapabilityEndpoint"],
+          "properties": {
+            "unownedEndpoint": { "type": "integer", "minimum": 0 },
+            "contestedEndpoint": { "type": "integer", "minimum": 0 },
+            "noCapabilityEndpoint": { "type": "integer", "minimum": 0 }
+          }
+        }
+      }
+    },
+    "calls": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["coverage", "reasonCodes"],
+      "properties": {
+        "coverage": { "const": "unknown" },
+        "reasonCodes": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "const": "call-edges-not-exposed" } }
+      }
+    },
+    "edges": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["limit", "count", "omittedCount", "items"],
+      "properties": {
+        "limit": { "type": "integer", "minimum": 0 },
+        "count": { "type": "integer", "minimum": 0 },
+        "omittedCount": { "type": "integer", "minimum": 0 },
+        "items": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["fromPath", "toPath", "fromCapability", "toCapability"],
+            "properties": {
+              "fromPath": { "type": "string", "minLength": 1 },
+              "toPath": { "type": "string", "minLength": 1 },
+              "fromCapability": { "type": "string", "minLength": 1 },
+              "toCapability": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    },
+    "worktree": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["headSha", "worktreeDigest"],
+      "properties": {
+        "headSha": { "type": "string", "pattern": "^[a-f0-9]{40}$" },
+        "worktreeDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }
+      }
+    },
+    "privacy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["writes"],
+      "properties": {
+        "writes": { "const": "none" }
+      }
+    }
+  }
+}

package/schemas/runtime/docs-anchors.schema.json

@@ -0,0 +1,143 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://archcontext.dev/schemas/runtime/docs-anchors.schema.json",
+  "title": "DocsAnchorsReportV1",
+  "description": "Read-only result of `archctx docs anchors`: stale citations in human-owned module document regions and node prose. A signal, not a gate.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "profile", "codeGraph", "summary", "nodes"],
+  "properties": {
+    "schemaVersion": { "const": "archcontext.docs-anchors/v1" },
+    "profile": { "enum": ["default", "repo-harness/v1"] },
+    "codeGraph": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["availability"],
+          "properties": { "availability": { "const": "ready" } }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["availability", "reasonCode"],
+          "properties": {
+            "availability": { "const": "unavailable" },
+            "reasonCode": { "enum": ["index-missing", "index-open-failed"] }
+          }
+        }
+      ]
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["nodes", "documents", "citations", "findings", "unchecked", "byKind"],
+      "properties": {
+        "nodes": { "$ref": "#/$defs/count" },
+        "documents": { "$ref": "#/$defs/count" },
+        "citations": { "$ref": "#/$defs/count" },
+        "findings": { "$ref": "#/$defs/count" },
+        "unchecked": { "$ref": "#/$defs/count" },
+        "byKind": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["line-moved", "line-out-of-range", "missing-path", "missing-symbol"],
+          "properties": {
+            "line-moved": { "$ref": "#/$defs/count" },
+            "line-out-of-range": { "$ref": "#/$defs/count" },
+            "missing-path": { "$ref": "#/$defs/count" },
+            "missing-symbol": { "$ref": "#/$defs/count" }
+          }
+        }
+      }
+    },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["nodeId", "citationCount", "findings", "unchecked"],
+        "properties": {
+          "nodeId": { "type": "string", "minLength": 1 },
+          "documentPath": { "$ref": "#/$defs/repoPath" },
+          "citationCount": { "type": "integer", "minimum": 1 },
+          "findings": { "type": "array", "items": { "$ref": "#/$defs/finding" } },
+          "unchecked": { "type": "array", "items": { "$ref": "#/$defs/unchecked" } }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "count": { "type": "integer", "minimum": 0 },
+    "line": { "type": "integer", "minimum": 1 },
+    "repoPath": {
+      "type": "string",
+      "minLength": 1,
+      "not": { "anyOf": [{ "pattern": "^/" }, { "pattern": "\\\\" }, { "pattern": "(^|/)\\.\\.(/|$)" }] }
+    },
+    "origin": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "path", "line"],
+          "properties": {
+            "kind": { "const": "document" },
+            "path": { "$ref": "#/$defs/repoPath" },
+            "line": { "$ref": "#/$defs/line" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind"],
+          "properties": { "kind": { "const": "node-summary" } }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "index"],
+          "properties": {
+            "kind": { "const": "node-responsibility" },
+            "index": { "type": "integer", "minimum": 0 }
+          }
+        }
+      ]
+    },
+    "citation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["text"],
+      "properties": {
+        "text": { "type": "string", "minLength": 1 },
+        "path": { "type": "string", "minLength": 1 },
+        "resolvedPath": { "$ref": "#/$defs/repoPath" },
+        "line": { "$ref": "#/$defs/line" },
+        "endLine": { "$ref": "#/$defs/line" },
+        "symbol": { "type": "string", "minLength": 1 }
+      }
+    },
+    "finding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "origin", "citation"],
+      "properties": {
+        "kind": { "enum": ["line-moved", "line-out-of-range", "missing-path", "missing-symbol"] },
+        "origin": { "$ref": "#/$defs/origin" },
+        "citation": { "$ref": "#/$defs/citation" },
+        "lineCount": { "$ref": "#/$defs/count" },
+        "currentLines": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/line" } }
+      }
+    },
+    "unchecked": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["reasonCode", "origin", "citation"],
+      "properties": {
+        "reasonCode": { "enum": ["codegraph-unavailable", "language-unsupported", "path-ambiguous"] },
+        "origin": { "$ref": "#/$defs/origin" },
+        "citation": { "$ref": "#/$defs/citation" }
+      }
+    }
+  }
+}

package/schemas/runtime/flow-selector-check.schema.json

@@ -0,0 +1,109 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://archcontext.dev/schemas/runtime/flow-selector-check.schema.json",
+  "title": "ArchitectureFlowSelectorCheckV1",
+  "description": "The data of `archctx flows check`: the P2 flow proof of every capability that declares a flow, and the proof status of every declared entrypoint-to-sink selector, computed without rendering. Consumers detect it through the flow-selector-check-v1 capability.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "ok", "codeGraph", "summary", "selectors", "capabilities"],
+  "properties": {
+    "schemaVersion": { "const": "archcontext.flow-selector-check/v1" },
+    "ok": { "type": "boolean", "description": "True when no capability that declares a flow has an unprovable P2 proof." },
+    "codeGraph": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["availability", "version"],
+      "properties": {
+        "availability": { "enum": ["ready", "unavailable"] },
+        "version": { "type": "string", "minLength": 1 }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["selectors", "proven", "unproven", "usedUnproven"],
+      "properties": {
+        "selectors": { "type": "integer", "minimum": 0 },
+        "proven": { "type": "integer", "minimum": 0 },
+        "unproven": { "type": "integer", "minimum": 0 },
+        "usedUnproven": { "type": "integer", "minimum": 0, "description": "Unproven selectors that a required-flow step names." }
+      }
+    },
+    "selectors": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["nodeId", "entrypointId", "sourcePath", "sourceSymbol", "sinkId", "sinkPath", "sinkSymbol", "status", "callSites", "referenceSites", "rejectedBuiltinCallSites", "flowSteps"],
+        "properties": {
+          "nodeId": { "type": "string", "minLength": 1 },
+          "entrypointId": { "type": "string", "minLength": 1 },
+          "sourcePath": { "type": "string", "minLength": 1 },
+          "sourceSymbol": { "type": "string", "minLength": 1 },
+          "sinkId": { "type": "string", "minLength": 1 },
+          "sinkPath": { "type": "string", "minLength": 1 },
+          "sinkSymbol": { "type": "string", "minLength": 1 },
+          "status": {
+            "enum": ["ambiguous-symbol", "evidence-missing", "evidence-truncated", "false-builtin-call", "no-direct-call", "only-references", "proven"],
+            "description": "Only proven binds a flow step."
+          },
+          "callSites": { "$ref": "#/$defs/sites" },
+          "referenceSites": { "$ref": "#/$defs/sites" },
+          "rejectedBuiltinCallSites": { "$ref": "#/$defs/sites" },
+          "flowSteps": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["flowId", "stepId"],
+              "properties": {
+                "flowId": { "type": "string", "minLength": 1 },
+                "stepId": { "type": "string", "minLength": 1 }
+              }
+            }
+          }
+        }
+      }
+    },
+    "capabilities": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["capabilityId", "p2Status", "diagnostics"],
+        "properties": {
+          "capabilityId": { "type": "string", "minLength": 1 },
+          "p2Status": { "enum": ["not-applicable", "proven", "unprovable"] },
+          "diagnostics": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["code", "detail"],
+              "properties": {
+                "code": { "type": "string", "minLength": 1 },
+                "flowId": { "type": "string", "minLength": 1 },
+                "stepId": { "type": "string", "minLength": 1 },
+                "detail": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "sites": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "line": { "type": "integer", "minimum": 1 }
+        }
+      }
+    }
+  }
+}

package/schemas/runtime/recommendation-v3.schema.json

@@ -578,6 +578,7 @@
               "items": {
                 "enum": [
                   "caller-coverage-unknown",
+                  "code-facts-import-limit",
                   "code-facts-missing",
                   "code-facts-truncated",
                   "major-change-detected",

package/schemas/runtime/runtime-recommendation-show.schema.json

@@ -470,6 +470,7 @@
               "items": {
                 "enum": [
                   "caller-coverage-unknown",
+                  "code-facts-import-limit",
                   "code-facts-missing",
                   "code-facts-truncated",
                   "major-change-detected",
@@ -1740,12 +1741,20 @@
               ],
               "minimum": 0
             },
+            "importNodeCount": {
+              "type": [
+                "integer",
+                "null"
+              ],
+              "minimum": 0
+            },
             "reasonCodes": {
               "type": "array",
               "uniqueItems": true,
               "items": {
                 "enum": [
                   "caller-coverage-unknown",
+                  "code-facts-import-limit",
                   "code-facts-missing",
                   "code-facts-truncated",
                   "major-change-detected",
@@ -2028,6 +2037,10 @@
         },
         "task": {
           "type": "string"
+        },
+        "importNodeLimit": {
+          "type": "integer",
+          "minimum": 1
         }
       }
     },
@@ -2272,6 +2285,7 @@
           "items": {
             "enum": [
               "caller-coverage-unknown",
+              "code-facts-import-limit",
               "code-facts-missing",
               "code-facts-truncated",
               "major-change-detected",

package/schemas/runtime/runtime-refactor-scan.schema.json

@@ -42,6 +42,11 @@
       "type": "integer",
       "minimum": 0
     },
+    "untrackedExcludedCount": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Worktree files that Git does not ignore and that the HEAD tree does not carry (untracked and newly staged files). The scan measures HEAD only, so it excludes them. Optional: a scan from an older archctx does not report it."
+    },
     "snapshot": {
       "$ref": "#/$defs/moduleStatisticsSnapshot"
     },
@@ -510,6 +515,7 @@
               "items": {
                 "enum": [
                   "caller-coverage-unknown",
+                  "code-facts-import-limit",
                   "code-facts-missing",
                   "code-facts-truncated",
                   "major-change-detected",
@@ -1780,12 +1786,20 @@
               ],
               "minimum": 0
             },
+            "importNodeCount": {
+              "type": [
+                "integer",
+                "null"
+              ],
+              "minimum": 0
+            },
             "reasonCodes": {
               "type": "array",
               "uniqueItems": true,
               "items": {
                 "enum": [
                   "caller-coverage-unknown",
+                  "code-facts-import-limit",
                   "code-facts-missing",
                   "code-facts-truncated",
                   "major-change-detected",
@@ -2068,6 +2082,10 @@
         },
         "task": {
           "type": "string"
+        },
+        "importNodeLimit": {
+          "type": "integer",
+          "minimum": 1
         }
       }
     },
@@ -2312,6 +2330,7 @@
           "items": {
             "enum": [
               "caller-coverage-unknown",
+              "code-facts-import-limit",
               "code-facts-missing",
               "code-facts-truncated",
               "major-change-detected",

package/schemas/runtime/structural-observation-payload.schema.json

@@ -470,6 +470,7 @@
               "items": {
                 "enum": [
                   "caller-coverage-unknown",
+                  "code-facts-import-limit",
                   "code-facts-missing",
                   "code-facts-truncated",
                   "major-change-detected",

package/src/architecture.ts

@@ -90,11 +90,14 @@ export type DependencyConstraintStatus = (typeof DEPENDENCY_CONSTRAINT_STATUSES)
 
 /**
  * Why a dependency result is not a complete observation: no index answered, the index attested
- * to a different worktree, the import dump hit its limit, a constrained file carries a
- * repository-local import that resolved to no file, or the workspace package map could not be
- * read, so no bare workspace specifier could be resolved.
+ * to a different worktree, the index holds more import nodes than the configured read limit
+ * (`code-facts-import-limit`), the read came back shorter than the population the index reported
+ * (`code-facts-truncated`), a constrained file carries a repository-local import that resolved to
+ * no file, or the workspace package map could not be read, so no bare workspace specifier could
+ * be resolved.
  */
 export const DEPENDENCY_CONSTRAINT_REASON_CODES = [
+  "code-facts-import-limit",
   "code-facts-stale",
   "code-facts-truncated",
   "code-facts-unavailable",

package/src/docs-anchors.ts

@@ -0,0 +1,126 @@
+/**
+ * `archctx docs anchors` (#298): a read-only signal for stale citations in human-owned text. It
+ * reads the human-owned regions of module documents and node prose (`summary`,
+ * `responsibilities`), and resolves each citation against the Git-visible tree and CodeGraph. It is
+ * a signal, not a gate: findings never change `ok`, freshness or the projection result.
+ */
+export const DOCS_ANCHORS_REPORT_SCHEMA_VERSION = "archcontext.docs-anchors/v1" as const;
+
+export const DOCS_ANCHOR_FINDING_KINDS = ["line-moved", "line-out-of-range", "missing-path", "missing-symbol"] as const;
+export type DocsAnchorFindingKind = (typeof DOCS_ANCHOR_FINDING_KINDS)[number];
+
+/** Why a citation was found but one of its checks could not run. */
+export const DOCS_ANCHOR_UNCHECKED_REASON_CODES = ["codegraph-unavailable", "language-unsupported", "path-ambiguous"] as const;
+export type DocsAnchorUncheckedReasonCode = (typeof DOCS_ANCHOR_UNCHECKED_REASON_CODES)[number];
+
+export const DOCS_ANCHOR_CODEGRAPH_UNAVAILABLE_REASON_CODES = ["index-missing", "index-open-failed"] as const;
+export type DocsAnchorCodeGraphUnavailableReasonCode = (typeof DOCS_ANCHOR_CODEGRAPH_UNAVAILABLE_REASON_CODES)[number];
+
+/** Where the citation is written: a human-owned document line, or a field of the node. */
+export type DocsAnchorOriginV1 =
+  | { kind: "document"; path: string; line: number }
+  | { kind: "node-summary" }
+  | { kind: "node-responsibility"; index: number };
+
+export interface DocsAnchorCitationV1 {
+  /** The inline code span as written, without the backticks. */
+  text: string;
+  /** The cited path as written. */
+  path?: string;
+  /** The Git-visible file or directory the path resolved to, when it differs from `path`. */
+  resolvedPath?: string;
+  line?: number;
+  endLine?: number;
+  symbol?: string;
+}
+
+export interface DocsAnchorFindingV1 {
+  kind: DocsAnchorFindingKind;
+  origin: DocsAnchorOriginV1;
+  citation: DocsAnchorCitationV1;
+  /** `line-out-of-range` only: the current line count of the cited file. */
+  lineCount?: number;
+  /** `line-moved` only: the current start lines of the cited symbol, sorted. */
+  currentLines?: number[];
+}
+
+export interface DocsAnchorUncheckedV1 {
+  reasonCode: DocsAnchorUncheckedReasonCode;
+  origin: DocsAnchorOriginV1;
+  citation: DocsAnchorCitationV1;
+}
+
+export interface DocsAnchorsNodeV1 {
+  nodeId: string;
+  /** The node's module document, when the active layout has one and it exists. */
+  documentPath?: string;
+  citationCount: number;
+  findings: DocsAnchorFindingV1[];
+  unchecked: DocsAnchorUncheckedV1[];
+}
+
+export type DocsAnchorsCodeGraphV1 =
+  | { availability: "ready" }
+  | { availability: "unavailable"; reasonCode: DocsAnchorCodeGraphUnavailableReasonCode };
+
+export interface DocsAnchorsReportV1 {
+  schemaVersion: typeof DOCS_ANCHORS_REPORT_SCHEMA_VERSION;
+  profile: "default" | "repo-harness/v1";
+  codeGraph: DocsAnchorsCodeGraphV1;
+  summary: {
+    /** Model nodes whose prose and module document were read. */
+    nodes: number;
+    /** Module documents read. */
+    documents: number;
+    citations: number;
+    findings: number;
+    unchecked: number;
+    byKind: Record<DocsAnchorFindingKind, number>;
+  };
+  /** Nodes with at least one citation, sorted by `nodeId`. */
+  nodes: DocsAnchorsNodeV1[];
+}
+
+export function docsAnchorsReportIssues(report: DocsAnchorsReportV1): string[] {
+  const issues: string[] = [];
+  const ids = report.nodes.map((node) => node.nodeId);
+  const sorted = [...new Set(ids)].sort();
+  if (sorted.length !== ids.length || sorted.some((id, index) => id !== ids[index])) issues.push("nodes.nodeId must be sorted and unique");
+  const findings = report.nodes.flatMap((node) => node.findings);
+  const unchecked = report.nodes.flatMap((node) => node.unchecked);
+  if (report.summary.citations !== report.nodes.reduce((total, node) => total + node.citationCount, 0)) issues.push("summary.citations must equal the sum of nodes[].citationCount");
+  if (report.summary.findings !== findings.length) issues.push("summary.findings must equal the number of findings");
+  if (report.summary.unchecked !== unchecked.length) issues.push("summary.unchecked must equal the number of unchecked citations");
+  for (const kind of DOCS_ANCHOR_FINDING_KINDS) {
+    if (report.summary.byKind[kind] !== findings.filter((finding) => finding.kind === kind).length) issues.push(`summary.byKind.${kind} must equal the number of ${kind} findings`);
+  }
+  for (const [index, node] of report.nodes.entries()) {
+    if (node.citationCount === 0) issues.push(`nodes[${index}] must have at least one citation`);
+    for (const [findingIndex, finding] of node.findings.entries()) {
+      issues.push(...docsAnchorFindingIssues(finding, `nodes[${index}].findings[${findingIndex}]`));
+    }
+  }
+  if (report.codeGraph.availability === "ready" && unchecked.some((entry) => entry.reasonCode === "codegraph-unavailable")) {
+    issues.push("codegraph-unavailable is reported only when codeGraph.availability is unavailable");
+  }
+  return issues;
+}
+
+function docsAnchorFindingIssues(finding: DocsAnchorFindingV1, prefix: string): string[] {
+  const issues: string[] = [];
+  const { citation } = finding;
+  if (finding.kind === "missing-path" && citation.path === undefined) issues.push(`${prefix} missing-path must name citation.path`);
+  if (finding.kind === "missing-symbol" && citation.symbol === undefined) issues.push(`${prefix} missing-symbol must name citation.symbol`);
+  if (finding.kind === "line-out-of-range" && (citation.line === undefined || finding.lineCount === undefined)) {
+    issues.push(`${prefix} line-out-of-range must name citation.line and lineCount`);
+  }
+  if ((finding.lineCount !== undefined) !== (finding.kind === "line-out-of-range")) issues.push(`${prefix}.lineCount is present only on line-out-of-range`);
+  if (finding.kind === "line-moved") {
+    const lines = finding.currentLines ?? [];
+    if (citation.line === undefined || citation.symbol === undefined) issues.push(`${prefix} line-moved must name citation.line and citation.symbol`);
+    if (lines.length === 0 || lines.some((line, index) => index > 0 && line <= lines[index - 1]!)) issues.push(`${prefix}.currentLines must be non-empty, sorted and unique`);
+  } else if (finding.currentLines !== undefined) {
+    issues.push(`${prefix}.currentLines is present only on line-moved`);
+  }
+  return issues;
+}

package/src/index.ts

@@ -1,8 +1,10 @@
 export * from "./control-plane-routes";
 export * from "./architecture";
+export * from "./docs-anchors";
 export * from "./external-docs";
 export * from "./github-governance";
 export * from "./ledger";
+export * from "./ownership-dependencies";
 export * from "./ports";
 export * from "./practices";
 export * from "./projection";

package/src/ownership-dependencies.ts

@@ -0,0 +1,129 @@
+import type { EvidenceCoverageLevelV2 } from "./ledger";
+
+// --- ChangeSet ownership delta (plan preview) ---
+//
+// `archctx plan` and `archcontext_plan_update` add `preview.ownershipDelta` when a planned
+// ChangeSet writes a node file. It compares file ownership before and after the planned model over
+// the files the HEAD tree carries, with the parent-chain rule `refactor scan` uses
+// (module-statistics `resolveOwnership`). It is read-only: nothing is written to compute it.
+
+export const CHANGESET_OWNERSHIP_DELTA_SCHEMA_VERSION = "archcontext.changeset-ownership-delta/v1" as const;
+/** Upper bound on the paths one ownership delta category lists. `count` always holds the full total. */
+export const CHANGESET_OWNERSHIP_DELTA_PATH_LIMIT = 50;
+
+export interface OwnershipDeltaSummaryV1 {
+  ownedFileCount: number;
+  /** Owned files whose claimants do not sit on one `parent` chain. */
+  multiplyOwnedFileCount: number;
+  /** Unclaimed files under a declared source root that no node excludes. */
+  unownedFileCount: number;
+}
+
+export interface OwnershipDeltaFileV1 {
+  path: string;
+  /** Owning node ids before the plan, sorted. More than one id means the claim is contested. */
+  before: string[];
+  /** Owning node ids after the plan, sorted. */
+  after: string[];
+}
+
+export interface OwnershipDeltaCategoryV1 {
+  /** Every file in this category. */
+  count: number;
+  /** The first `pathLimit` files, sorted by path. */
+  files: OwnershipDeltaFileV1[];
+  /** `count - files.length`. */
+  omittedCount: number;
+}
+
+export interface ChangeSetOwnershipDeltaComputedV1 {
+  schemaVersion: typeof CHANGESET_OWNERSHIP_DELTA_SCHEMA_VERSION;
+  status: "computed";
+  ownershipRule: "parent-chain";
+  fileUniverse: "head-tracked-files";
+  trackedFileCount: number;
+  /** Node ids whose `source.include`, `source.exclude` or `parent` differ, or that the plan creates or deletes. */
+  changedNodeIds: string[];
+  pathLimit: number;
+  before: OwnershipDeltaSummaryV1;
+  after: OwnershipDeltaSummaryV1;
+  /** Unowned before, owned by exactly one node after. */
+  becameOwned: OwnershipDeltaCategoryV1;
+  /** Not contested before, contested (multiply owned) after. */
+  becameContested: OwnershipDeltaCategoryV1;
+  /** Owned before, owned by a different node set after, and not newly contested. */
+  ownerChanged: OwnershipDeltaCategoryV1;
+  /** Owned before, unowned after. */
+  becameUnowned: OwnershipDeltaCategoryV1;
+}
+
+export interface ChangeSetOwnershipDeltaUnavailableV1 {
+  schemaVersion: typeof CHANGESET_OWNERSHIP_DELTA_SCHEMA_VERSION;
+  status: "unavailable";
+  /** Why no delta was computed, for example a planned node body that does not parse. */
+  reason: string;
+}
+
+export type ChangeSetOwnershipDeltaV1 = ChangeSetOwnershipDeltaComputedV1 | ChangeSetOwnershipDeltaUnavailableV1;
+
+// --- Capability dependency matrix (`archctx deps`) ---
+
+export const CAPABILITY_DEPENDENCIES_SCHEMA_VERSION = "archcontext.capability-dependencies/v1" as const;
+/** Default number of file-level edges `archctx deps` lists. `edges.count` always holds the full total. */
+export const CAPABILITY_DEPENDENCIES_EDGE_LIMIT = 200;
+/** The CodeGraph adapter has no bounded repository-wide call-edge read, so calls are not counted. */
+export const CAPABILITY_DEPENDENCIES_CALLS_UNAVAILABLE_REASON = "call-edges-not-exposed" as const;
+
+export interface CapabilityDependencyCellV1 {
+  /** Owning capability of the importing file. */
+  from: string;
+  /** Owning capability of the imported file. */
+  to: string;
+  /** Distinct file-to-file import edges from `from` into `to`. */
+  imports: number;
+  /** Always `null` in v1: call edges are not read (see `calls`). */
+  calls: null;
+}
+
+export interface CapabilityDependencyEdgeV1 {
+  fromPath: string;
+  toPath: string;
+  fromCapability: string;
+  toCapability: string;
+}
+
+export interface CapabilityDependenciesV1 {
+  schemaVersion: typeof CAPABILITY_DEPENDENCIES_SCHEMA_VERSION;
+  ownershipRule: "parent-chain";
+  /** `--from` / `--into` node ids, or `null`. A node matches a file when it or a descendant owns it. */
+  filter: { from: string | null; into: string | null };
+  /** Every `kind: capability` node id in the model, sorted. */
+  capabilities: string[];
+  /** Non-zero cells only, sorted by `from` then `to`. A cell with `from === to` counts edges inside one capability. */
+  matrix: CapabilityDependencyCellV1[];
+  imports: {
+    coverage: EvidenceCoverageLevelV2;
+    /** `code-facts-unavailable`, `code-facts-stale`, `code-facts-import-limit`, `code-facts-truncated`. */
+    reasonCodes: string[];
+    /** True when the index read is not the whole population for a reason other than the limit. */
+    truncated: boolean;
+    importNodeCount: number | null;
+    importNodeLimit: number;
+    importNodeLimitExceeded: boolean;
+    /** Distinct file-to-file edges that passed the filters, attributed or not. */
+    edgeCount: number;
+    /**
+     * Repository-local import specifiers (relative, or naming a workspace package) from filtered
+     * files that resolved to no repository file. Always 0 with `--into`: such an edge has no target.
+     */
+    unresolvedCount: number;
+    /** Edges left out of `matrix` because one endpoint has no single owning capability. */
+    unattributed: { unownedEndpoint: number; contestedEndpoint: number; noCapabilityEndpoint: number };
+  };
+  calls: {
+    coverage: "unknown";
+    reasonCodes: [typeof CAPABILITY_DEPENDENCIES_CALLS_UNAVAILABLE_REASON];
+  };
+  /** Attributed file-level edges behind `matrix`, sorted by path. */
+  edges: { limit: number; count: number; omittedCount: number; items: CapabilityDependencyEdgeV1[] };
+}

package/src/product-version.ts

@@ -1,5 +1,5 @@
 export const ARCHCONTEXT_PRODUCT_NAME = "archctx";
-export const ARCHCONTEXT_PRODUCT_VERSION = "0.7.0";
+export const ARCHCONTEXT_PRODUCT_VERSION = "0.7.2";
 export const ARCHCONTEXT_PACKAGE_MANAGER = "bun@1.4.3";
 export const ARCHCONTEXT_NODE_RANGE = ">=22.22 <26";
 export const LOCAL_RUNTIME_RPC_SCHEMA_VERSION = "archcontext.runtime-rpc/v1";

package/src/projection.ts

@@ -62,8 +62,12 @@ export const ARCHCTX_FEATURES = [
   "architecture-change-capabilities-v1",
   "architecture-docs-renderer-v2",
   "architecture-refresh-signal-v1",
+  "capability-dependencies-v1",
   "changeset-entity-operations-v1",
+  "changeset-ownership-delta-v1",
   "code-facts-unavailable-error-v1",
+  "docs-anchors-v1",
+  "flow-selector-check-v1",
   "module-statistics-v1",
   "projection-apply-readback-v1",
   "projection-apply-receipt-v1",
@@ -81,7 +85,8 @@ export const ARCHCTX_FEATURES = [
   "refactor-assessment-v1",
   "refactor-observation-evidence-v1",
   "refactor-resolution-v1",
-  "refactor-scan-limits-v1"
+  "refactor-scan-limits-v1",
+  "refactor-scan-untracked-count-v1"
 ] as const;
 
 /**
@@ -103,6 +108,69 @@ export const ARCHITECTURE_SEMANTIC_FACETS = [
 export const ARCHITECTURE_PROOF_P1_STATUSES = ["proven", "unprovable"] as const;
 export const ARCHITECTURE_PROOF_P2_STATUSES = ["not-applicable", "proven", "unprovable"] as const;
 
+export const ARCHITECTURE_FLOW_SELECTOR_CHECK_SCHEMA_VERSION = "archcontext.flow-selector-check/v1" as const;
+
+/**
+ * The proof status of one declared entrypoint→sink selector, as the P2 flow proof reads its
+ * evidence. Only `proven` can bind a flow step. `no-direct-call`: no `calls` edge from the source
+ * to the sink. `only-references`: no proving call, but the source references the sink by value.
+ * `false-builtin-call`: the only calls carry a runtime built-in name and the source file does not
+ * import the sink file. `ambiguous-symbol`: the source or the sink matches more than one indexed
+ * symbol. `evidence-missing`: no evidence was measured (for example, no CodeGraph index).
+ * `evidence-truncated`: the evidence producer could not enumerate every edge.
+ */
+export const ARCHITECTURE_FLOW_SELECTOR_PROOF_STATUSES = [
+  "ambiguous-symbol",
+  "evidence-missing",
+  "evidence-truncated",
+  "false-builtin-call",
+  "no-direct-call",
+  "only-references",
+  "proven"
+] as const;
+export type ArchitectureFlowSelectorProofStatus = typeof ARCHITECTURE_FLOW_SELECTOR_PROOF_STATUSES[number];
+
+export interface ArchitectureFlowSelectorSiteV1 {
+  path: string;
+  line?: number;
+}
+
+export interface ArchitectureFlowSelectorCheckEntryV1 {
+  nodeId: string;
+  entrypointId: string;
+  sourcePath: string;
+  sourceSymbol: string;
+  sinkId: string;
+  sinkPath: string;
+  sinkSymbol: string;
+  status: ArchitectureFlowSelectorProofStatus;
+  callSites: ArchitectureFlowSelectorSiteV1[];
+  referenceSites: ArchitectureFlowSelectorSiteV1[];
+  rejectedBuiltinCallSites: ArchitectureFlowSelectorSiteV1[];
+  /** The required-flow steps that name this selector as evidence. Empty for an unused selector. */
+  flowSteps: Array<{ flowId: string; stepId: string }>;
+}
+
+export interface ArchitectureFlowSelectorCheckCapabilityV1 {
+  capabilityId: string;
+  /** The same P2 status a projection records for this capability. */
+  p2Status: typeof ARCHITECTURE_PROOF_P2_STATUSES[number];
+  diagnostics: Array<{ code: string; flowId?: string; stepId?: string; detail: string }>;
+}
+
+/**
+ * `archctx flows check`: the P2 flow proof without rendering. Read-only. `ok` is true when no
+ * capability that declares a flow has an unprovable P2 proof.
+ */
+export interface ArchitectureFlowSelectorCheckV1 {
+  schemaVersion: typeof ARCHITECTURE_FLOW_SELECTOR_CHECK_SCHEMA_VERSION;
+  ok: boolean;
+  codeGraph: { availability: "ready" | "unavailable"; version: string };
+  summary: { selectors: number; proven: number; unproven: number; usedUnproven: number };
+  selectors: ArchitectureFlowSelectorCheckEntryV1[];
+  capabilities: ArchitectureFlowSelectorCheckCapabilityV1[];
+}
+
 /** `files[].preview.format`: a `create` carries the rendered body, an `update` or `delete` a unified diff. */
 export const PROJECTION_FILE_PREVIEW_FORMATS = ["body", "unified-diff"] as const;
 /** Upper bound, in UTF-8 bytes, on one `files[].preview.content`. */

package/src/refactor.ts

@@ -42,6 +42,7 @@ export const REFACTOR_VERIFICATION_REQUEST_KEYS = [
   "executionEvidenceRefs",
   "expectedHeadSha",
   "expectedWorktreeDigest",
+  "importNodeLimit",
   "recommendationId",
   "schemaVersion"
 ] as const;
@@ -62,6 +63,7 @@ export const REFACTOR_SCALES = [
 ] as const;
 export const REFACTOR_SCALE_REASON_CODES = [
   "caller-coverage-unknown",
+  "code-facts-import-limit",
   "code-facts-missing",
   "code-facts-truncated",
   "major-change-detected",
@@ -198,6 +200,11 @@ export interface RefactorRequestV1 {
   expectedHeadSha?: string;
   expectedWorktreeDigest?: string;
   task?: string;
+  /**
+   * The most CodeGraph import nodes the scan reads. Omitted means the runtime default. A larger
+   * index gives partial coverage with `code-facts-import-limit`, never `code-facts-truncated`.
+   */
+  importNodeLimit?: number;
 }
 
 /**
@@ -216,6 +223,11 @@ export interface RefactorVerificationRequestV1 {
   expectedHeadSha?: string;
   expectedWorktreeDigest?: string;
   executionEvidenceRefs?: RefactorExecutionEvidenceRefV1[];
+  /**
+   * The most CodeGraph import nodes the re-measure reads. Omitted means the limit the recorded
+   * baseline snapshot was measured with, so BEFORE and AFTER read the same import population.
+   */
+  importNodeLimit?: number;
 }
 
 export interface ModuleStatisticsV1 {
@@ -281,8 +293,18 @@ export interface ModuleStatisticsSnapshotV1 {
     binaryDigest: string;
     indexedWorktreeDigest: string | null;
     coverage: EvidenceCoverageLevelV2;
+    /**
+     * True only when the read is shorter than the population the index reported. A read cut by
+     * `edgeLimit` is not truncated: it reports `code-facts-import-limit` instead.
+     */
     truncated: boolean;
+    /** The import-node read limit the scan applied. */
     edgeLimit: number | null;
+    /**
+     * Import nodes the index reported, or `null` when no index gave a count. Absent on snapshots
+     * recorded before the field existed.
+     */
+    importNodeCount?: number | null;
     reasonCodes: RefactorScaleReasonCode[];
   };
   modules: ModuleStatisticsV1[];
@@ -594,6 +616,9 @@ export function refactorRequestInvariantIssues(request: RefactorRequestV1, prefi
     }
   }
   if (request.proposal) issues.push(...refactorProposalInvariantIssues(request.proposal, `${prefix}.proposal`));
+  if (request.importNodeLimit !== undefined && !(Number.isInteger(request.importNodeLimit) && request.importNodeLimit >= 1)) {
+    issues.push(`${prefix}.importNodeLimit must be a positive integer`);
+  }
   return issues;
 }
 
@@ -630,6 +655,9 @@ export function refactorVerificationRequestInvariantIssues(
   if (request.expectedWorktreeDigest !== undefined) {
     issues.push(...digestIssues(`${prefix}.expectedWorktreeDigest`, request.expectedWorktreeDigest));
   }
+  if (request.importNodeLimit !== undefined && !(Number.isInteger(request.importNodeLimit) && request.importNodeLimit >= 1)) {
+    issues.push(`${prefix}.importNodeLimit must be a positive integer`);
+  }
   if (request.executionEvidenceRefs !== undefined) {
     if (!Array.isArray(request.executionEvidenceRefs)) {
       issues.push(`${prefix}.executionEvidenceRefs must be an array`);
@@ -722,6 +750,15 @@ export function moduleStatisticsSnapshotInvariantIssues(snapshot: ModuleStatisti
     }
   }
   issues.push(...nonNegativeIntegerIssues(`${prefix}.codeFacts.edgeLimit`, snapshot.codeFacts.edgeLimit));
+  const importNodeCount = snapshot.codeFacts.importNodeCount ?? null;
+  issues.push(...nonNegativeIntegerIssues(`${prefix}.codeFacts.importNodeCount`, importNodeCount));
+  if (snapshot.codeFacts.reasonCodes.includes("code-facts-import-limit")) {
+    const { edgeLimit } = snapshot.codeFacts;
+    if (snapshot.codeFacts.coverage !== "partial") issues.push(`${prefix}.codeFacts.coverage must be partial when the import limit was reached`);
+    if (edgeLimit === null || (importNodeCount !== null && importNodeCount <= edgeLimit)) {
+      issues.push(`${prefix}.codeFacts.importNodeCount must exceed edgeLimit when the import limit was reached`);
+    }
+  }
   for (const [field, value] of Object.entries(snapshot.repositorySummary)) {
     issues.push(...nonNegativeIntegerIssues(`${prefix}.repositorySummary.${field}`, value));
   }