@c4a/context-cli 0.7.26 → 0.7.29

package/plugins/skills/context-inspect-search/SKILL.md

@@ -25,14 +25,35 @@ Do not execute returned production actions, initialize a replacement workspace,
 or install tools without existing authorization. Querying must not alter source
 registrations, snapshots, tasks, approvals or user checkouts.
 
-## Search available material concurrently
-
-Check relevant knowledge packages, the workspace and reusable source checkouts
-in parallel. Search each as soon as it is readable; tool checks and authorized
-upgrades must not block independent reading. If a missing configured workspace
-is needed for further attribution, recover it into an isolated directory while
-package retrieval continues. Without a configured workspace, investigate the
-available packages directly; do not request or create one merely to start.
+Resolve `CONTEXT_QUERY_SOURCE_MODE` from the host or Bot instance configuration
+before choosing the first retrieval path. Supported values are:
+
+- `repo-first` (default): inspect the configured knowledge workspace and
+  authorized repository sources first. Use an available package only when the
+  repository path is unavailable or leaves a material gap.
+- `package-first`: inspect the selected package first, then use its recorded
+  workspace or repository sources for missing, stale or disputed evidence.
+- `dual`: inspect the package and repository paths concurrently, then reconcile
+  relevant differences before answering.
+
+An unknown or empty value is `repo-first`; do not invent a fourth mode. The
+mode changes retrieval order, not authorization or evidence standards. It does
+not make a missing secondary source mandatory: continue with readable configured
+sources and identify only gaps that affect the answer.
+
+## Search available material according to the configured mode
+
+Apply `CONTEXT_QUERY_SOURCE_MODE` before starting retrieval. In `repo-first`,
+start with the configured workspace and reusable source checkouts; do not fetch
+or install a package merely to begin the query. In `package-first`, start with
+the selected readable package. In `dual`, start both paths concurrently. Search
+each selected path as soon as it is readable; tool checks and authorized
+upgrades must not block independent reading. If a configured primary path is
+missing, continue with the readable fallback instead of stopping. If a missing
+configured workspace is needed for further attribution, recover it into an
+isolated directory while other selected retrieval continues. Without a
+configured workspace, investigate available packages directly; do not request
+or create one merely to start.
 
 A knowledge package may be workspace build output (usually `dist/`), a global
 installation, or an equivalent host-provided directory. Locate it from available
@@ -118,7 +139,21 @@ not prove a historical snapshot.
 
 ## Answer with evidence and hand off updates
 
-Lead with the conclusion and a concise evidence chain. Distinguish implementation,
+Answer the user's question directly, keeping conditions that change the conclusion
+beside it. For complex questions, explain the mechanism that determines the result,
+not just the verdict and source links. Explain its practical meaning before using
+a short code excerpt or concrete rule when that helps the reader verify or act.
+Keep decisive evidence beside the claim it supports; separate supplementary facts
+from the proof. State where a local rule applies rather than generalizing it to
+the whole system, and do not infer presentation or behavior from data retrieval
+alone without checking the controlling logic.
+
+Adapt depth and structure to the question: keep simple answers short; use short
+headings and, where supported, separators between major semantic sections in
+longer answers. Do not impose a fixed outline, separate every paragraph, repeat
+the conclusion, or remove necessary explanation just to shorten the answer.
+Keep conditions affecting the answer prominent and supplementary reading secondary.
+Distinguish implementation,
 declared contracts, test assertions, runtime observations and inferences. Perform
 bounded non-destructive validation only when useful; inspect its effects first
 and do not run unrelated scripts, builds or tests.

package/providers/context/graphs/indexer.yaml

@@ -36,6 +36,10 @@ nodes:
     kind: action
     reasonCode: route.production.planning-required
     action: actions/work-production-stage.yaml
+    resources:
+      recommended:
+        - resources/procedures/document-code-investigation.md
+        - resources/procedures/repository-source-recovery.md
     satisfiedBy:
       - path: production.planning_complete
         equals: true

package/providers/context/manifest.json

@@ -2,14 +2,14 @@
   "schema": "agent-graph.bundle.v1",
   "provider": {
     "id": "c4a/context",
-    "version": "0.7.26"
+    "version": "0.7.29"
   },
   "providerManifest": "provider.yaml",
   "graphs": [
     {
       "id": "indexer",
       "path": "graphs/indexer.yaml",
-      "digest": "sha256:4992b548a9d19c6d7fd25a5dc0ae6b78a4a494ce39d37633144d389362f21122"
+      "digest": "sha256:d52242180fbe1afea09946bb223a698f7e0637f81d619d9245acb74732f2409e"
     },
     {
       "id": "workspace",
@@ -290,6 +290,11 @@
       "path": "resources/procedures/document-capture.md",
       "digest": "sha256:9d0d1b9187bbe540a4afffb366cd549385dbf61bfaffa96ae51de848b2dd5460"
     },
+    {
+      "id": "procedure.document-code-investigation",
+      "path": "resources/procedures/document-code-investigation.md",
+      "digest": "sha256:eff8e54b9e1c1139c5df82a0685a365bce902dfb4a19c17e380967ee1c1762f5"
+    },
     {
       "id": "procedure.homogeneous-source-review",
       "path": "resources/procedures/homogeneous-source-review.md",
@@ -343,7 +348,7 @@
     {
       "id": "procedure.repository-source-recovery",
       "path": "resources/procedures/repository-source-recovery.md",
-      "digest": "sha256:024f6e2947ef421b9a5f5e138c9af65a054d676a7f484dbf80b43a620ee2c95d"
+      "digest": "sha256:20a8112df985a20481e914a564c64c231218c73c1630d74cd46d72987e54f714"
     },
     {
       "id": "procedure.runtime-event-delivery",
@@ -562,7 +567,7 @@
     },
     {
       "path": "graphs/indexer.yaml",
-      "digest": "sha256:4992b548a9d19c6d7fd25a5dc0ae6b78a4a494ce39d37633144d389362f21122"
+      "digest": "sha256:d52242180fbe1afea09946bb223a698f7e0637f81d619d9245acb74732f2409e"
     },
     {
       "path": "graphs/workspace.yaml",
@@ -570,7 +575,7 @@
     },
     {
       "path": "provider.yaml",
-      "digest": "sha256:7e5a25e5636983a6fb881621e826c102680f44cde9d21086c627861e119d1f7a"
+      "digest": "sha256:0a21f82483186c4fe1f6f450923d0d336300274fb95e2c7ee3569700ba922372"
     },
     {
       "path": "resources/contracts/indexer-provider-guide.yaml",
@@ -692,6 +697,10 @@
       "path": "resources/procedures/document-capture.md",
       "digest": "sha256:9d0d1b9187bbe540a4afffb366cd549385dbf61bfaffa96ae51de848b2dd5460"
     },
+    {
+      "path": "resources/procedures/document-code-investigation.md",
+      "digest": "sha256:eff8e54b9e1c1139c5df82a0685a365bce902dfb4a19c17e380967ee1c1762f5"
+    },
     {
       "path": "resources/procedures/homogeneous-source-review.md",
       "digest": "sha256:e9746b45351f3c58f1eca90f786fa5ddef06b19024f4ba5539a0c21e0a1508da"
@@ -734,7 +743,7 @@
     },
     {
       "path": "resources/procedures/repository-source-recovery.md",
-      "digest": "sha256:024f6e2947ef421b9a5f5e138c9af65a054d676a7f484dbf80b43a620ee2c95d"
+      "digest": "sha256:20a8112df985a20481e914a564c64c231218c73c1630d74cd46d72987e54f714"
     },
     {
       "path": "resources/procedures/runtime-event-delivery.md",
@@ -862,12 +871,12 @@
     },
     {
       "path": "skills/work-production-stage/SKILL.md",
-      "digest": "sha256:b7aa28c032e00f93f67d3c9dc3589cf1513451456f589262e22ad7f73d265de7"
+      "digest": "sha256:676289693df57b5887f104d751dd9c8cc73fb1c903e4df7088f110ef6147388a"
     }
   ],
   "graphDependencies": {
     "indexer": [],
     "workspace": []
   },
-  "digest": "sha256:3f380c5b4a1adbc92847189b7072ec7515990dce621785bf25469268f9bbb252"
+  "digest": "sha256:3e0f9fc6f81571381dced3a8d02b20624022183e924c7b99c16430c8924d624d"
 }

package/providers/context/provider.yaml

@@ -1,6 +1,6 @@
 schema: agent-graph.provider.v1
 id: c4a/context
-version: 0.7.26
+version: 0.7.29
 name: Context workflow
 description: Internal work contract for Context knowledge workspaces.
 graphs:

package/providers/context/resources/procedures/document-code-investigation.md

@@ -0,0 +1,45 @@
+---
+id: procedure.document-code-investigation
+kind: procedure
+mediaType: text/markdown
+---
+
+# Assess code needs during document investigation
+
+Register the requested document sources before preparing their article plan.
+Continue authorized document capture even when unrelated registered repositories
+are unavailable. Existing workspace coverage does not select the current task's
+code dependencies.
+
+After reading outlines, representative bodies and related approved articles,
+group the reader topics and assess whether code investigation is needed before
+submitting the plan and work-start report. Large collections can be investigated
+in batches while capture continues. If the expected production plan exceeds 30
+article tasks, explicitly perform this assessment before bulk writing. This is
+Agent guidance, not a CLI validation threshold. Wiki nodes, documents and article
+tasks are different counts; more than 30 document nodes calls for early batched
+investigation, not an assumption of 30 articles or automatic repository recovery.
+
+Code evidence is useful when the reader task requires implementation behavior,
+call chains, interface constraints or debugging entry points, or when incomplete
+or conflicting documents require checking code. Explicit file, symbol or API
+references strengthen that assessment. A repository link or service name alone
+does not establish a dependency. Keep document-supported topics independent.
+
+Use existing plan briefs or report prose to explain which reader questions need
+which registered modules and why; no separate assessment receipt, score or
+required schema field is needed. If code is needed, inspect its availability with
+`context source recovery-plan <registered-name> --format json`. Follow
+[repository source recovery](repository-source-recovery.md), reusing applicable
+authorization and local checkouts. Prefer the smallest sufficient registered
+module scope. Expand to a shared physical checkout or whole repository when
+cross-module calls, common dependencies or uncertain boundaries require it;
+do not substitute a different remote or pinned commit.
+
+If recovery is unavailable, continue independent document tasks. Keep questions
+requiring unread code pending, or narrow the article to supported document
+claims and explain its limits. Do not present inferred implementation as verified
+code, delete configured sources, or clear a stage to bypass unavailable evidence.
+After recovery, follow its returned preparation command and current task handles;
+retain accepted work instead of restarting the task. Reassess code needs when
+later reading exposes a dependency that the initial sample did not show.

package/providers/context/resources/procedures/repository-source-recovery.md

@@ -17,7 +17,9 @@ remote and pinned commit, so one physical checkout can restore every module in
 that group. Do not create one clone per module. Groups already marked `ready`
 need no decision; when every group is ready, the plan has no recovery action.
 
-For each missing physical checkout, ask the user to choose one option:
+For each missing physical checkout, reuse an applicable choice and authorization
+already supplied in the current task. If the recovery choice is unresolved, ask
+the user to choose one option:
 
 1. provide an existing local Git checkout;
 2. name a bounded directory that the Agent may scan, then choose one of the
@@ -43,3 +45,8 @@ Repository sources are ready only when every selected module resolves to the
 registered remote and pinned commit, every registered subpath exists, no local
 path was overwritten, Context materialization succeeds, and the selected recovery
 plan reports them ready.
+
+Recovery failure does not stop unrelated document capture or independent article
+tasks. Preserve pending code-dependent questions and follow the returned recovery
+diagnostic. After a successful restore, follow `next_action` to refresh affected
+production material; keep accepted articles and use the newly returned handles.

package/providers/context/skills/work-production-stage/SKILL.md

@@ -19,6 +19,10 @@ where needed to decide reader topics, source grouping and writing batches.
 Indexer guidance discovers a skeleton, not a mandatory deep parse or a ledger
 of every symbol. Declare relevant available skills and record planned uses;
 do not collect skill hashes, versions or article ownership credentials.
+After reading representative documents and grouping reader topics, apply
+[document and code investigation guidance](../../resources/procedures/document-code-investigation.md)
+before submitting the article plan. Revisit it when new implementation questions
+appear during writing. This assessment adds no approval gate or required field.
 Submit the plan before presenting the work-start report. Planning does not
 authorize writing or approve the report.