qiansc · Oct 28, 2026 · Oct 28, 2026 · Oct 28, 2026 · Oct 28, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,11 @@
 
 All notable changes to Context are documented here.
 
+## 0.7.88 - 2026-10-28
+
+- `context update --pending` processes registered repositories whose commit moved past the version approved knowledge was processed at, such as after `context source add repo --ref <sha>`. Only pages whose cited text changed become update candidates, listed with their sections in `changed_references`; the update still asks for one scope decision covering additions and shared dependencies, and the new commit settles, with moved citations updating their locations, only after that decision. The workspace Route runs it before the idle task gate, `source add repo` returns a `next` hint for it, and `verify` warnings point to it when a cited repository moved.
+- Reading earlier settled commits works in shallow and partial checkouts: each commit is checked once and fetched once when missing, concurrent references share one reader and read one file at a time per checkout, and a commit the remote no longer has fails every read at once instead of retrying per file.
+
 ## 0.7.87 - 2026-10-26
 
 - Each website article now ends with its sources as a map. The article's sections sit in the middle and the documents they cite sit around them in flat blobs, grouped by where each document comes from: a repository directory, Lark documents or notes. Sections are purple; repository files are green, Skills magenta, Lark documents blue and notes orange. Hovering a section or document highlights what it is linked to and shows the cited line ranges; clicking a document opens the cited lines and clicking a section scrolls to it. A List view shows the same documents by group, and narrow screens show only the list. Other articles citing the same documents are linked below. The map is computed during `context build` from the recorded references, registered sources and committed snapshots, so it needs no agent step. Set `site.sourceMap: false` to keep the plain source list.

diff --git a/bun.lock b/bun.lock
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "context",
-  "version": "0.7.87",
+  "version": "0.7.88",
   "packageManager": "bun@1.3.9",
   "repository": {
     "type": "git",

diff --git a/packages/context-cli/README.md b/packages/context-cli/README.md
@@ -331,6 +331,9 @@ they do not resume an earlier managed task before the new request is understood.
 - `context update --input <file>` accepts confirmed source/module scopes and fixed,
   already acquired versions. The current Route asks which existing pages need
   changes and whether additions need new pages.
+- `context update --pending` processes registered repositories whose commit moved
+  past the processed version. Only pages whose cited text changed become
+  candidates; the scope decision still covers additions before the commit settles.
 - `context revise <page> --instruction <text>` starts from the current approved
   body. `--move-to <path>` preserves its identity and updates Markdown navigation
   when the reviewed move is applied.

diff --git a/packages/context-cli/context-workflow/actions/process-source-update.yaml b/packages/context-cli/context-workflow/actions/process-source-update.yaml
@@ -0,0 +1,5 @@
+schema: agent-graph.action.v1
+id: process-source-update
+runner: command
+effect: write
+command: context update --pending --format json
diff --git a/packages/context-cli/context-workflow/codes.yaml b/packages/context-cli/context-workflow/codes.yaml
@@ -97,4 +97,5 @@ codes:
   - { code: route.indexer.candidate-review, kind: route-reason, summary: Review the exact current candidate set only after current mechanical validation passes. }
   - { code: route.indexer.approved-knowledge-close, kind: route-reason, summary: Atomically close approved Indexer structure after required material gaps are resolved. }
   - { code: route.indexer.source-update, kind: route-reason, summary: Inspect fixed source changes against current approved pages. }
+  - { code: route.source.update-pending, kind: route-reason, summary: A registered repository moved past the commit its approved knowledge was processed at; process the new commit before other work., document: resources/procedures/knowledge-updates.md }
   - { code: route.workspace.task-cleared, kind: route-reason, summary: No active production task; existing knowledge is retained and new production awaits explicit user intent., document: resources/procedures/workspace-prepare.md }
diff --git a/packages/context-cli/context-workflow/graphs/workspace.yaml b/packages/context-cli/context-workflow/graphs/workspace.yaml
@@ -147,6 +147,17 @@ nodes:
         - resources/procedures/source-capture-detailed.md
         - resources/manuals/guides/lark-resources.md
 
+  - id: process-source-update
+    kind: action
+    reasonCode: route.source.update-pending
+    action: actions/process-source-update.yaml
+    satisfiedBy:
+      - path: sources.update_pending
+        equals: false
+    resources:
+      recommended:
+        - resources/procedures/knowledge-updates.md
+
   - id: reopen-cleared-task
     kind: gate
     reasonCode: route.workspace.task-cleared
@@ -355,7 +366,8 @@ edges:
   - { from: choose-source-boundary, to: configure-document-capture, kind: gatedBy }
   - { from: configure-document-capture, to: authorize-document-capture }
   - { from: authorize-document-capture, to: capture-next, kind: gatedBy }
-  - { from: capture-next, to: reopen-cleared-task }
+  - { from: capture-next, to: process-source-update }
+  - { from: process-source-update, to: reopen-cleared-task }
   - { from: reopen-cleared-task, to: run-indexer-lifecycle, kind: gatedBy }
   - { from: run-indexer-lifecycle, to: review-current-batch }
   - { from: review-current-batch, to: close-approved-knowledge, kind: gatedBy }

diff --git a/packages/context-cli/context-workflow/provider.yaml b/packages/context-cli/context-workflow/provider.yaml
@@ -1,6 +1,6 @@
 schema: agent-graph.provider.v1
 id: c4a/context
-version: 0.7.87
+version: 0.7.88
 name: Context workflow
 description: Internal work contract for Context knowledge workspaces.
 graphs:

diff --git a/...ages/context-cli/context-workflow/resources/manuals/guides/knowledge-updates.md b/...ages/context-cli/context-workflow/resources/manuals/guides/knowledge-updates.md
@@ -425,6 +425,13 @@ also checking additions that have no old page reference. The scope is complete
 only after every required change is reviewed, closed and built, or after an
 explicit conclusion that it needs no knowledge changes.
 
+Moving a repository with `context source add repo --ref <sha>` only changes its
+registration. When approved knowledge was processed at the previous commit, run
+`context update --pending --format json`. Only pages whose cited text changed
+become candidates, listed in `changed_references`; still inspect the change for
+additions and shared dependencies before deciding. Moved citations update their
+locations when the update settles.
+
 Before importing a `note`, read [note source preparation](note.md).
 Before importing `sessions`, read [development summary preparation](sessions.md).
 Choose the reference for the actual input; do not read both by default.

diff --git a/packages/context-cli/context-workflow/resources/procedures/knowledge-updates.md b/packages/context-cli/context-workflow/resources/procedures/knowledge-updates.md
@@ -425,6 +425,13 @@ also checking additions that have no old page reference. The scope is complete
 only after every required change is reviewed, closed and built, or after an
 explicit conclusion that it needs no knowledge changes.
 
+Moving a repository with `context source add repo --ref <sha>` only changes its
+registration. When approved knowledge was processed at the previous commit, run
+`context update --pending --format json`. Only pages whose cited text changed
+become candidates, listed in `changed_references`; still inspect the change for
+additions and shared dependencies before deciding. Moved citations update their
+locations when the update settles.
+
 Before importing a `note`, read [note source preparation](note.md).
 Before importing `sessions`, read [development summary preparation](sessions.md).
 Choose the reference for the actual input; do not read both by default.

diff --git a/packages/context-cli/context-workflow/resources/procedures/source-update.md b/packages/context-cli/context-workflow/resources/procedures/source-update.md
@@ -17,6 +17,11 @@ of them. Read their current approved Markdown. Submit one decision per path:
 omit `instruction` if no correction is needed, or describe the concrete change
 to make. Preserve unrelated content and the reader's existing improvements.
 Include a short `scope_summary` explaining the scope-level conclusion.
+When the action lists `changed_references`, start from those sections: the
+cited text changed (`changed`) or could not be read (`unavailable`, such as a
+renamed or deleted file). For `context update --pending`, pages whose citations
+are unchanged or only moved are not candidates, so an empty list is possible;
+still check the change for additions before submitting the scope decision.
 
 Also inspect additions and shared dependencies in the source change. Existing
 page references cannot discover every new topic. List necessary new pages in `new_topics`, each with a readable `path` in an existing

diff --git a/packages/context-cli/context-workflow/tests/capture-configuration-missing.yaml b/packages/context-cli/context-workflow/tests/capture-configuration-missing.yaml
@@ -22,7 +22,7 @@ state:
       compile_complete: true
       knowledge_review_resolved: true
       review_gate_clear: true
-    sources: { registered: true, repositories_ready: true }
+    sources: { registered: true, repositories_ready: true, update_pending: false }
     capture: { declarations_complete: false, batch_digest: null, complete: false, route_satisfied: false }
 expect:
   statusCode: actionable

diff --git a/packages/context-cli/context-workflow/tests/capture-next.yaml b/packages/context-cli/context-workflow/tests/capture-next.yaml
@@ -18,7 +18,7 @@ state:
       compile_complete: true
       knowledge_review_resolved: true
       review_gate_clear: true
-    sources: { registered: true, repositories_ready: true }
+    sources: { registered: true, repositories_ready: true, update_pending: false }
     capture: { declarations_complete: true, batch_digest: null, complete: false, route_satisfied: false }
 expect:
   statusCode: actionable

diff --git a/packages/context-cli/context-workflow/tests/close-before-package.yaml b/packages/context-cli/context-workflow/tests/close-before-package.yaml
@@ -22,7 +22,7 @@ state:
       compile_complete: true
       knowledge_review_resolved: true
       review_gate_clear: true
-    sources: { registered: true, repositories_ready: true }
+    sources: { registered: true, repositories_ready: true, update_pending: false }
     capture: { declarations_complete: true, batch_digest: null, complete: true, route_satisfied: true }
     extract: { migration_required: false, declarations_complete: true, plans_complete: true, capability_clear: true, preview_current: true, ownership_clear: true, scale_clear: true, batch_digest: null, complete: true, audit_input_required: false, audit_guidance_required: false, audit_revision_required: false, audit_resolved: true }
     documents: { classified: true }

diff --git a/packages/context-cli/context-workflow/tests/complete.yaml b/packages/context-cli/context-workflow/tests/complete.yaml
@@ -23,7 +23,7 @@ state:
       structure_confirmation_resolved: true
       knowledge_review_resolved: true
       package_output_resolved: true
-    sources: { registered: true, repositories_ready: true }
+    sources: { registered: true, repositories_ready: true, update_pending: false }
     capture: { declarations_complete: true, batch_digest: null, complete: true, route_satisfied: true }
     extract: { migration_required: false, declarations_complete: true, plans_complete: true, capability_clear: true, preview_current: true, ownership_clear: true, scale_clear: true, batch_digest: null, complete: true, audit_input_required: false, audit_guidance_required: false, audit_revision_required: false, audit_resolved: true }
     documents: { classified: true }

diff --git a/packages/context-cli/context-workflow/tests/configure-package-output.yaml b/packages/context-cli/context-workflow/tests/configure-package-output.yaml
@@ -22,7 +22,7 @@ state:
       compile_complete: true
       knowledge_review_resolved: true
       review_gate_clear: true
-    sources: { registered: true, repositories_ready: true }
+    sources: { registered: true, repositories_ready: true, update_pending: false }
     capture: { declarations_complete: true, batch_digest: null, complete: true, route_satisfied: true }
     extract: { migration_required: false, declarations_complete: true, plans_complete: true, capability_clear: true, preview_current: true, ownership_clear: true, scale_clear: true, batch_digest: null, complete: true, audit_input_required: false, audit_guidance_required: false, audit_revision_required: false, audit_resolved: true }
     documents: { classified: true }

diff --git a/packages/context-cli/context-workflow/tests/document-acquisition-deferred.yaml b/packages/context-cli/context-workflow/tests/document-acquisition-deferred.yaml
@@ -23,7 +23,7 @@ state:
       structure_confirmation_resolved: true
       knowledge_review_resolved: true
       package_output_resolved: true
-    sources: { registered: true, repositories_ready: true }
+    sources: { registered: true, repositories_ready: true, update_pending: false }
     capture: { declarations_complete: true, batch_digest: null, complete: false, route_satisfied: true }
     extract: { migration_required: false, declarations_complete: true, plans_complete: true, capability_clear: true, preview_current: true, ownership_clear: true, scale_clear: true, batch_digest: null, complete: true, audit_input_required: false, audit_guidance_required: false, audit_revision_required: false, audit_resolved: true }
     documents: { classified: true }

diff --git a/packages/context-cli/context-workflow/tests/managed-package-template-review.yaml b/packages/context-cli/context-workflow/tests/managed-package-template-review.yaml
@@ -23,7 +23,7 @@ state:
       compile_complete: true
       knowledge_review_resolved: true
       review_gate_clear: true
-    sources: { registered: true, repositories_ready: true }
+    sources: { registered: true, repositories_ready: true, update_pending: false }
     capture: { declarations_complete: true, batch_digest: null, complete: true, route_satisfied: true }
     extract: { migration_required: false, declarations_complete: true, plans_complete: true, capability_clear: true, preview_current: true, ownership_clear: true, scale_clear: true, batch_digest: null, complete: true, audit_input_required: false, audit_guidance_required: false, audit_revision_required: false, audit_resolved: true }
     documents: { classified: true }

diff --git a/packages/context-cli/context-workflow/tests/managed-review.yaml b/packages/context-cli/context-workflow/tests/managed-review.yaml
@@ -23,7 +23,7 @@ state:
       compile_complete: true
       knowledge_review_resolved: false
       review_gate_clear: true
-    sources: { registered: true, repositories_ready: true }
+    sources: { registered: true, repositories_ready: true, update_pending: false }
     capture: { declarations_complete: true, batch_digest: null, complete: true, route_satisfied: true }
     extract: { migration_required: false, declarations_complete: true, plans_complete: true, capability_clear: true, preview_current: true, ownership_clear: true, scale_clear: true, batch_digest: null, complete: true, audit_input_required: false, audit_guidance_required: false, audit_revision_required: false, audit_resolved: true }
     documents: { classified: true }

diff --git a/packages/context-cli/context-workflow/tests/package-output-gate.yaml b/packages/context-cli/context-workflow/tests/package-output-gate.yaml
@@ -22,7 +22,7 @@ state:
       compile_complete: true
       knowledge_review_resolved: true
       review_gate_clear: true
-    sources: { registered: true, repositories_ready: true }
+    sources: { registered: true, repositories_ready: true, update_pending: false }
     capture: { declarations_complete: true, batch_digest: null, complete: true, route_satisfied: true }
     extract: { migration_required: false, declarations_complete: true, plans_complete: true, capability_clear: true, preview_current: true, ownership_clear: true, scale_clear: true, batch_digest: null, complete: true, audit_input_required: false, audit_guidance_required: false, audit_revision_required: false, audit_resolved: true }
     documents: { classified: true }

diff --git a/packages/context-cli/context-workflow/tests/package-stale.yaml b/packages/context-cli/context-workflow/tests/package-stale.yaml
@@ -23,7 +23,7 @@ state:
       compile_complete: true
       knowledge_review_resolved: true
       review_gate_clear: true
-    sources: { registered: true, repositories_ready: true }
+    sources: { registered: true, repositories_ready: true, update_pending: false }
     capture: { declarations_complete: true, batch_digest: null, complete: true, route_satisfied: true }
     extract: { migration_required: false, declarations_complete: true, plans_complete: true, capability_clear: true, preview_current: true, ownership_clear: true, scale_clear: true, batch_digest: null, complete: true, audit_input_required: false, audit_guidance_required: false, audit_revision_required: false, audit_resolved: true }
     documents: { classified: true }

diff --git a/packages/context-cli/context-workflow/tests/package-template-review.yaml b/packages/context-cli/context-workflow/tests/package-template-review.yaml
@@ -22,7 +22,7 @@ state:
       compile_complete: true
       knowledge_review_resolved: true
       review_gate_clear: true
-    sources: { registered: true, repositories_ready: true }
+    sources: { registered: true, repositories_ready: true, update_pending: false }
     capture: { declarations_complete: true, batch_digest: null, complete: true, route_satisfied: true }
     extract: { migration_required: false, declarations_complete: true, plans_complete: true, capability_clear: true, preview_current: true, ownership_clear: true, scale_clear: true, batch_digest: null, complete: true, audit_input_required: false, audit_guidance_required: false, audit_revision_required: false, audit_resolved: true }
     documents: { classified: true }

diff --git a/packages/context-cli/context-workflow/tests/repository-source-not-ready.yaml b/packages/context-cli/context-workflow/tests/repository-source-not-ready.yaml
@@ -22,7 +22,7 @@ state:
       compile_complete: true
       knowledge_review_resolved: true
       review_gate_clear: true
-    sources: { registered: true, repositories_ready: false }
+    sources: { registered: true, repositories_ready: false, update_pending: false }
     capture: { declarations_complete: true, complete: false, route_satisfied: false }
 expect:
   statusCode: actionable

diff --git a/packages/context-cli/context-workflow/tests/review-after-compile.yaml b/packages/context-cli/context-workflow/tests/review-after-compile.yaml
@@ -22,7 +22,7 @@ state:
       compile_complete: true
       knowledge_review_resolved: true
       review_gate_clear: true
-    sources: { registered: true, repositories_ready: true }
+    sources: { registered: true, repositories_ready: true, update_pending: false }
     capture: { declarations_complete: true, batch_digest: null, complete: true, route_satisfied: true }
     extract: { migration_required: false, declarations_complete: true, plans_complete: true, capability_clear: true, preview_current: true, ownership_clear: true, scale_clear: true, batch_digest: null, complete: true, audit_input_required: false, audit_guidance_required: false, audit_revision_required: false, audit_resolved: true }
     documents: { classified: true }