@c4a/context-cli 0.7.8 → 0.7.9

package/providers/context/resources/procedures/homogeneous-source-review.md

@@ -0,0 +1,123 @@
+---
+id: procedure.homogeneous-source-review
+kind: procedure
+mediaType: text/markdown
+---
+
+# Review large homogeneous source groups before bulk work
+
+Apply during source exploration, the work-start report, Provider selection and
+before advancing into parser preparation, including an existing workspace's
+resume. Reuse confirmed decisions; this is the existing conversational scope
+review, not a new CLI approval flag or a semantic classifier in the CLI.
+
+## Find a real group, not just a large repository
+
+More than 100 files in a candidate group triggers a bounded homogeneity check,
+not automatic exclusion or a count-only stop. Use the supplied source inventory
+or authorized read-only file listing. Do not run symbol extraction to discover
+whether symbol extraction is needed. Record the source/repository and pinned
+revision, actual module/directory boundaries, counted paths, bytes when available,
+and representative file paths. Distinguish tracked source, captured copies,
+generated files and externally resolved dependencies; a path containing another
+repository name does not prove a new external checkout.
+
+Read a small diverse sample across relevant subdirectories, sizes and naming
+families. Establish a shared structure, generator, schema, repeated role or
+mechanical pattern from content. Examples include IDL definitions, schema-based
+configuration, generated clients/models, repeated migrations, and ordinary
+handwritten adapters or handlers with the same structural pattern. A common
+extension, a directory label, age, or boilerplate header alone is not sufficient.
+Do not call every TypeScript file homogeneous or treat all configuration as
+low-value. If samples differ substantially, split by evidenced characteristics
+or proceed normally; report uncertainty instead of claiming full inspection.
+
+For a confirmed group above 100 files with an unsettled treatment, pause before
+dependent bulk reading/parsing. Combine all currently known groups into one scope
+proposal. Do not ask per file or create 100-file approval batches. Groups below
+this threshold can still warrant discussion when their size or cost is material;
+file count is not a memory safety limit.
+
+## Present one concrete choice per group
+
+Show a compact directory tree and table with:
+
+- Repository/source, revision, exact directory or file-set boundary and whether
+  it is the whole source or a subset; physical file count versus distinct items.
+- Observed shared characteristics and two or three linked sample files with
+  short descriptions of their content. State sampling coverage honestly.
+- Connection to this task's questions, known callers/consumers and unresolved
+  dependencies; distinguish a recommendation from a confirmed exclusion.
+- Likely output, reading/parsing cost and the evidence for any estimate.
+
+Offer these treatments together, recommending one based on the user's task:
+
+| Choice | Consequence |
+| --- | --- |
+| Full indexing | Normal extraction, planning and writing over the selected group. It may yield multiple articles. Explain the extra work without asserting it is always low-value. |
+| Overview and lookup entry | List the boundary, inspect representative content and entrypoints, and plan one overview with directory/file lookup routes and concrete search instructions. Defer detailed extraction of the rest. Never first parse every file and then summarize it. |
+| Omit the source | Remove the entire source from this task's required production scope through the supported requirement/configuration flow. Do not delete captured files, caches or accepted knowledge. |
+| Exclude this subset | Keep the repository but exclude the explicitly selected directories/files from production scope. Clarify whether any are still required as supporting dependencies. |
+
+Only show subset exclusion as applicable when it is a subset; do not make the
+user distinguish two identical choices for a whole-source group. Users can give
+one policy for several groups or different choices per group. Record the exact
+scope of a shared answer. Generic managed/no-review authorization, source-read
+permission and permission to skip report feedback do not select a treatment.
+Reuse an explicit applicable treatment or explicit delegation of this scope
+choice. Otherwise ask and wait; elapsed time is not approval. Independent work
+outside the affected scope can continue if the current workflow supports it.
+
+Do not invent "one minute per group", token savings or a cost-benefit score.
+When comparable measurements exist, state the measured phase, input size,
+cold/cache conditions and uncertainty; separate parsing from Agent reading,
+writing and review. Without them state that duration is not reliably estimated.
+
+## Carry the answer into real execution
+
+Update the existing work-start report with the group boundaries, sample evidence,
+chosen treatment, user authorization and next action. Reuse that report and the
+conversation on retry; it is not itself a runtime execution receipt. Persist
+scope changes only through the existing requirement/configuration Actions and
+schemas. Exact exclusions use repository-relative paths, not invented wildcard
+fields. Retain unrelated requirements and accepted work. A source required by
+another requirement may remain active; disclose that instead of promising it
+will no longer be parsed.
+
+For full indexing, continue the current Route. For overview, resolve the actual
+production boundary and suitable existing Provider before proceeding: the
+selected entrypoints and samples support the overview; the remaining group is
+for lookup, not an exhaustive production target. Use directory-scoped routes
+when a per-file list would dominate the article. Include purpose, observed
+patterns, representative examples, source version, lookup/search procedure,
+limits of what was read and the next evidence request. Keep symbol/API facts
+unread as unknown. Do not forge a complete deep inventory, hand-write approved
+knowledge, or silently relabel the full scope as a summary profile.
+
+Check the resulting configuration before a command that prepares parser facts.
+In particular, contract-led profiles can still parse their entire registered
+boundary before article planning. Merely asking for one article does not reduce
+that work. If the current configuration route cannot express the selected
+narrow boundary or overview treatment, describe that concrete limitation and
+keep the affected bulk action paused; do not revert to full indexing or edit
+runtime receipts to make the choice appear applied.
+
+On continuation, unchanged groups with explicit decisions do not prompt again.
+New large groups, expansion beyond the agreed directory/file set, or changed
+characteristics/cost that invalidate the decision warrant a focused amendment.
+A content hash change within the agreed scope is not by itself a new question.
+If first discovered while a command is running, report the observation and
+safely interrupt the owned process when possible, preserve state and consult
+the latest Route before continuing. Do not launch a competing run or delete
+state. An uninterruptible stage must be reported, not called paused already.
+
+## Report progress with the correct denominator
+
+Keep source capture, module exploration, parser capability entries, file batches
+and delivered articles separate. A seven-file JSON entry does not mean that an
+IDL repository now contains seven relevant files. Report both the source and
+capability for each count; merging four results is not four completed modules.
+Only use completed/total modules when module boundaries and their completion
+have been observed. Before that, say module boundaries are being identified.
+Never infer percentage or scope reduction from time or RSS. RSS is not Node heap
+usage and being below a previous failure measurement does not establish safety.

package/providers/context/resources/procedures/knowledge-updates.md

@@ -22,18 +22,116 @@ and continues through Review and delivery. Expression-only changes need no
 source capture or Parser. Preserve prior confirmed contributions; distinguish
 actual behavior, a confirmed decision, and a proposal that is not implemented.
 
-## Edit one section or review part of a batch
+## First-task intake budget
+
+Before registration and capture, the Agent uses the user's task instructions and
+reads batch metadata titles across the explicitly supplied document list. Lark
+metadata requests accept at most 200 entries each, not 200 words or 200 documents
+overall. H1/H2 may be reused only when metadata returns them without
+body retrieval; Lark batch metadata returns titles, not headings. Batch failure
+falls back to at most 10 unresolved document title lookups total, unless a shared
+authentication failure makes those calls redundant. The Agent does not fetch
+source bodies, outlines, images or attachments. Missing title metadata is
+optional: preserve the original URL without falling back to body retrieval or
+changing credentials. Resolve intent from the conversation; refine provisional
+chapters and module boundaries from evidence after formal capture.
+
+## Workspace versions and changelog
+
+`package.json.version` is the workspace SemVer. At completed-scope delivery the
+workflow asks the Agent to inspect formal changes and record an increasing version
+with a concise changelog. Added modules or expanded material coverage increment
+minor; corrections, existing-module updates, navigation and persistent status
+changes increment patch. Major requires an explicit user instruction. Temporary
+progress under `.tmp/` never causes a version increase.
+
+Version recording runs at completed-scope delivery after Review, Close and package
+configuration/template approval, before the final build. The record response
+returns the next workspace Route, so no extra status call is needed. Build retries
+reuse the recorded version when formal content is unchanged. Intermediate batches
+do not each receive a version.
+
+The workspace AGENTS.md and version-writing instructions require each entry's
+details to stay within 1500 visible characters, including punctuation across the
+title, changes, trigger descriptions and actor display name, excluding protocol
+keys, version and date. The Agent compresses longer drafts before submission,
+preserving main changes, impact and triggers instead of truncating text or splitting
+the iteration into extra versions. This is an Agent writing rule, not a prose-quality
+CLI gate.
+
+`context version inspect --format json` returns changed paths and a digest. The
+coordinator submits `context version record --input <file> --format json` with:
+
+```yaml
+expected_digest: "<digest returned by inspect>"
+version: 0.2.0
+title: Add module recovery guidance
+changes:
+  - Document recovery conditions and the supported retry flow.
+triggers:
+  - kind: module
+    description: Additional module material requested in this iteration.
+actor:
+  kind: lark
+  name: Example User
+```
 
-For a reading-directory-only change, use the existing `context task adjust
---input <file|-> --format json` action with `reading_structure`. Supply its
+`actor` is optional; omit it to use local Git `user.name` when configured. Use a
+Lark display name only when explicitly known from the conversation. Trigger kinds
+are `initial`, `note`, `sessions`, `mr`, `module`, `document`, `navigation`,
+`repair`, `dist`, and `other`. Agent-written fields describe the actual diff and
+conversation; they must not expose credentials, raw transcripts or private IDs.
+
+The CLI writes `changelog.yaml`, generated `CHANGELOG.md`, `package.json` and the
+`.context-version.json` content baseline together. Keep these formal files with
+the workspace; do not hand-edit generated baselines. Git-managed and unignored
+new files are compared (without Git, non-runtime workspace files are compared).
+Version metadata itself, `dist`, `.tmp` and dependencies do not cause changes.
+
+Successful builds record version and per-package hashes in `.context-builds.json`.
+They do not increase versions. Before publishing, `context version publish-check
+--format json` compares against `.context-published.json`. A same-version changed
+output requires a patch using `version inspect --publish` and a `dist` trigger,
+then a rebuild. Record `version published --hash <checked-hash> --receipt
+<successful-publication-reference> --format json` only after external success.
+No command commits, tags or uploads automatically.
+
+Website history is available at `changelog.html`: cards are newest first, the
+latest three expanded and older cards collapsed. The History button beside the
+theme switch and footer update timestamps link there. KB and LLMS outputs carry
+the same workspace version and changelog.
+
+## Customize the knowledge map at any time
+
+For a knowledge-map-only change, use the existing `context task adjust
+--input <file|-> --format json` action with `knowledge_map`. Supply its
 current `expected_revision`, explicit `upsert` entries and `remove` keys. Each
 entry retains its stable key, parent, title and order; optional targets use
 article identity and section key. The current structure preview supplies those
-identities. Use `expected_revision: null` only when no reading structure exists.
+identities. Read the persistent `src/knowledge-map.yaml`; use
+`expected_revision: null` only when no knowledge map exists.
 After adjustment, follow status to rebuild affected packages. This changes the
 reading organization without capturing sources or rewriting approved prose.
 Do not directly edit generated package navigation or use titles as identities.
 
+Users can ask in conversation to move a topic, rename a directory, change order,
+or organize the same articles for another reader task. Handle this during ongoing
+production or after completion through the same adjustment; no active Indexer
+task, source recapture or new mode choice is required. Finish or revoke active
+worker assignments before changing the map. Preserve unrelated entries and page
+identities. The map controls website navigation and LLMS organization together.
+
+For each new or changed article, the Agent decides whether to retain its current
+placement, add another placement, move it, or create a warranted category. Check
+these choices against the user's settled organization before structure approval
+and delivery. New articles must be bound even if the map revision has not changed;
+modifying a title alone is not a reason to change article identity. Never satisfy
+coverage by mechanically placing every new page under an unrelated catch-all.
+Build reports missing bindings for the Agent to resolve; it does not classify
+content. Moving a menu entry does not change the article URL.
+
+## Edit one section or review part of a batch
+
 The current approved-revision Route accepts either full `markdown` or explicit
 `sections` edits. Use an existing `writing_context.current_sections` ID and an
 ordered `content` list of `{ "markdown": "new text" }` and/or

package/providers/context/resources/procedures/package-output.md

@@ -6,11 +6,14 @@ mediaType: text/markdown
 
 # Package output
 
+Before editing, read `context.sdk.package-outputs`, especially its Agent configuration
+and delivery recipe. It contains the concrete SDK declarations and preview steps.
+
 Package selection decides how approved knowledge is presented to downstream
 agents or text consumers. Explain the available Context package kinds and their
 directory shape before asking the user to choose.
 
-After confirmation, declare the package in `src/index.ts` using the SDK schema
+Using the settled multi-select choice or current session authority, declare the packages in `src/index.ts` using the SDK schema
 resource. The current Route's `configuration.contract` lists the supported
 output choices, required fields, mechanical defaults, and follow-up status
 command; do not infer another factory or hidden default. Templates may customize presentation, but they must not overwrite
@@ -46,3 +49,19 @@ external links and accepts responsibility for publishing and access. Use a
 confirmed immutable HTTPS prefix where possible; do not infer or probe an
 unknown host convention. Explicit omission keeps unresolved links and must be
 described as such.
+
+For a new workspace without explicit output preferences, use KB + website. Enable
+`site: { title: <workspace title>, lang: <workspace language> }` on the same
+`kbPackage` in `src/index.ts`; selecting LLMS also adds `llmsPackage`. Omit `site`
+when the user deselects the website. Existing declarations are not automatically
+changed. A request to generate a documentation website follows this same route,
+including after initial delivery. Inspect existing declarations before editing;
+do not register the request itself as source material or re-index unchanged knowledge.
+
+Validate reading targets before build. Website navigation uses the approved reading
+structure; repair missing bindings through the current structure adjustment action.
+Build cost is rendering and local search generation, not another Indexer run.
+Report measured cost only; do not promise a fixed duration for all workspaces.
+Website failure preserves the previous package and requires repair or an explicit
+change of output choice. Publishing is a separate action handled by the user's
+chosen deployment tool; producing a website never authorizes deployment.

package/providers/context/resources/procedures/parallel-agent-batch.md

@@ -0,0 +1,140 @@
+---
+id: procedure.parallel-agent-batch
+kind: procedure
+mediaType: text/markdown
+---
+
+# Parallel Partition and Author tasks
+
+This procedure applies only to a current Partition or Author Action with
+`tasks[]`. The Host runs the workers; Context does not launch models. The current
+Route, required readings and output schema remain authoritative. Delegation does
+not grant source access, approve a Gate or change the accepted scope.
+
+## Choose execution once per batch
+
+Use available native Host delegation only when current user/Host permissions
+allow it, at least two independent tasks are ready, and workers can read the
+assigned material and return their result without writing files. Respect an
+explicit single-Agent preference and Host capacity or budget limits. Do not
+install another agent runner, start nested CLI sessions or request broader
+permissions just to parallelize. If these conditions are absent, continue the
+same batch sequentially without a new user question.
+
+Resolve any existing scope or human decision before dispatching dependent tasks.
+Permission to use multiple Agents does not waive that decision.
+
+Choose `min(4, ready task count, available worker slots)` concurrent workers,
+excluding the coordinator. Use parallel mode only when that value is at least
+two. Do not split one task or enlarge a CLI batch to fill slots. Schedule later
+tasks from the same batch as workers finish; never prepare the next batch while
+this one is active. Known dependencies between tasks require sequential handling
+by the coordinator. A worker result never becomes evidence for a peer.
+
+Tell the user briefly, in their language, how many planning or writing workers
+will run when first enabling delegation or changing its concurrency/mode. Reuse
+that announcement across unchanged batches. Report a fallback once when it happens. Worker completion is draft
+progress; only CLI receipts establish accepted production progress.
+
+## Single coordinator and read-only workers
+
+The coordinator reads the Route, output schema and shared instructions, resolves
+existing human decisions, and owns all Context commands, receipts and writes.
+Workers consume only their assigned task reading and its authorized shared/detail
+files and captured source access. Material requiring CLI preparation is requested
+from the coordinator. Never let a worker run `context status`, a materializer,
+preview, completion, capture, parser, review, close or build.
+
+Use a Host read-only worker/tool profile when available. Workers must not run
+shell commands, Git, scripts or other tools that can change files or external
+state, and must not spawn workers. If the Host cannot honor this boundary, use
+single-Agent execution. Workers return results through Host messages; they do
+not write even scratch files. If a task cannot fit a complete response within
+the Host's output budget, the coordinator handles it sequentially and writes
+the payload itself. Do not truncate a result or publish a stub to fit transport.
+
+The coordinator alone writes the final payload under the workspace's
+`.tmp/agent-payloads/`, using a new file for each submission attempt. Never edit
+runtime readings or ledgers. This prevents worker file collisions without
+depending on filenames, worktrees or the project write lock to isolate them.
+
+## Assign and collect
+
+Use `template.indexer-agent-worker` from the current Route. Bind each assignment
+in coordinator memory to the current Route revision, Action `input_digest`,
+task manifest, instruction/resource digests and a unique attempt identifier.
+Task keys repeat across batches, so `task_key` alone is not an assignment ID.
+Copy these values; never compute or repair authority values from prose.
+
+Send one task entry, its exact Route-provided reading location and applicable
+shared instructions, the relevant output schema, and settled reader/scope
+decisions. Give enough instruction content or exact resource locations for the
+worker to read independently. A parent's reading does not populate a worker's
+context or authorize an unread receipt. Do not broadcast the entire batch,
+conversation, live repository or sibling task readings.
+
+Keep a mapping from Host worker ID to assignment attempt. Before dispatch, choose
+a finite task deadline supported by the Host (default ten minutes; shorten to
+the remaining session budget). Wait using native completion notifications or
+bounded waits while continuing user progress updates. A deadline is a Host
+execution limit, not a statement that evidence is missing.
+
+Accept a reply only from the active attempt for that task and only after it is
+complete. The worker uses the template's Host reply envelope to echo assignment
+identifiers separately from its single `{task_key, result}` entry. Check the Host
+worker ID and that binding against the saved assignment;
+do not insert coordination metadata into the Context semantic Result. Retain
+successful drafts in coordinator memory until the batch is assembled.
+
+## Merge and submit
+
+Reconcile Partition proposals against the settled reader purpose and accepted
+subjects, especially overlapping identities, primary member ownership and
+unresolved cross-task boundaries. Do not silently rename a subject or discard a
+member to make proposals fit. Resolve disagreements from authorized material
+in the coordinator; use the current schema's unresolved outcome when necessary.
+
+For Author, review consistency with the accepted page plans, evidence boundaries
+and reader terminology. A task may contain several planned articles: assign the
+whole task, not independent writers for its sections or articles. CLI performs
+the existing schema, ownership, reference and coverage validation.
+
+Assemble one entry per current task in task-key order, keeping the normal
+single-Agent output shape. Use the current Author preview when needed, then
+submit the complete batch once through the saved revision-bound command. Do not
+submit as each worker finishes or turn Host errors into `unsupported`,
+`catalog-only` or empty semantic results. Resolve unfinished work locally first.
+
+Finish or revoke every active assignment before any command that may change the batch or its material.
+Do not poll status merely to check workers. The revision-bound CLI command is
+the final freshness check; if an external change is observed, invalidate the
+assignments and obtain the current Route before submitting.
+
+## Failures and sequential fallback
+
+| Event | Coordinator action |
+| --- | --- |
+| Delegation unavailable, denied, or capacity below two before dispatch | Execute the batch sequentially. Do not retry permission prompts or simulate workers. |
+| Spawn failure, rate limit, timeout, tool failure, context loss or truncated reply | Stop dispatching for this batch. Revoke the failed attempt, cancel/close it if supported, and finish that task and unassigned tasks sequentially. Let healthy read-only peers finish within their deadlines. |
+| Missing/foreign task key, wrong attempt/revision, malformed or incomplete result | Discard that reply; take over its task sequentially using the original authorized input. Do not repeatedly respawn or treat the draft as committed. |
+| Conflicting proposals | Reconcile affected tasks in the coordinator; preserve unaffected drafts. Unresolved scope decisions follow the existing human Gate. |
+| Worker attempts a write, unauthorized tool or source access | Revoke all workers and stop parallel dispatch. Inspect any reported effects before continuing. If workspace integrity or authority is uncertain, follow current recovery guidance or report the concrete blocker. |
+| Route, task set or material binding changes | Revoke old attempts; discard incompatible drafts and follow the fresh Route. Never relabel an old reply with new digests or task keys. |
+| CLI accepts only part of a submission | Read `outcomes` and the returned next Route/task-only retry. Preserve committed peers; repair only the returned unfinished tasks sequentially. |
+| Completion reply is lost or next preparation fails | Inspect current status or the supplied recovery command before retrying. Accepted tasks may already be saved; never blindly replay the payload. |
+| Project write lock is held | Wait for the active writer using existing recovery guidance. Never remove its lock or launch another writer. |
+
+Revocation means marking the attempt inactive before taking over. Ignore all late
+replies, even if cancellation is unsupported. Such workers remain read-only;
+do not reuse their slots until the Host confirms termination. Do not start a
+new parallel batch while revoked workers are still active. A revoked read-only
+worker does not block the coordinator's sequential takeover or completion;
+its obsolete reply can no longer be accepted. If its read-only boundary is in
+doubt, use the violation handling above instead. After any execution
+failure, keep the rest of this batch sequential and reassess capability only at
+the next fresh batch. A user request to stay single-Agent persists.
+
+Sequential fallback preserves evidence, scope, review and completion requirements.
+If the coordinator also cannot complete the task, retain drafts and report the
+actual missing material, permission or Host limit through the existing workflow.
+Do not clear runtime state, widen sources or lower coverage to force progress.

package/providers/context/resources/procedures/source-boundary.md

@@ -10,6 +10,17 @@ A source boundary is a user decision about which repositories, modules, or
 documents may become approved knowledge. It affects extraction scope,
 provenance, output paths, and freshness checks.
 
+For the first production task in a newly initialized workspace, source
+registration is the boundary after work-start intake. Read the required work-start
+procedure and template, treat a supplied checklist as task guidance, read batch
+metadata titles under that procedure's limits and fallback without fetching bodies
+or outlines, resolve the required information,
+present the completed report and wait for user feedback before preparing this
+action's payload. Do not start registration, capture or extraction while any start
+condition remains unresolved. The payload must carry the report path required by
+the current schema; the CLI verifies the report exists and records its digest but
+does not judge its prose or infer decisions from it.
+
 Do not infer this boundary by using the current directory, monorepo layout,
 package names, or Git remotes to select additional sources. Once the user has named a concrete local module
 or path, resolving its unique local directory and reading that checkout's Git

package/providers/context/resources/procedures/source-capture-detailed.md

@@ -14,6 +14,13 @@ tools:
 
 # Capture
 
+When repository exploration reveals a large group with a shared structural or
+generation pattern, follow [the homogeneous-source review](homogeneous-source-review.md)
+before dependent bulk parsing. Capturing a repository is not a decision to deeply
+index every file. Preserve explicit treatment choices for Provider selection and
+resume instead of asking again after capture.
+
+
 Current capture discipline for document sources. The executable path is source
 registration plus the declared capture phase flow:
 
@@ -40,6 +47,26 @@ parallel. Repo batch items require `module`; file/Lark items may omit it and use
 the module returned by the CLI. A write-lock error means another Context mutation is active: wait for
 it to finish and retry rather than editing registry files.
 
+
+## Repository boundaries before bulk work
+
+Register the scope the user actually requested, not the containing monorepo merely
+because it is convenient to clone. Reuse one local checkout and register its
+confirmed module directories through the existing source registration command.
+Read that command's current schema for local path/subpath fields. Keep a source
+for each independently selected application/service boundary; names alone do not
+restrict filesystem reads. `modules: []` means no registered child boundary, not
+that the repository has no directories or cannot be narrowed.
+
+For protocol repositories, inspect the selected applications' maintained IDL
+configuration and import/include statements first. Register the referenced
+protocol directories and retain their required include dependencies as supporting
+material. Do not register every protocol in the repository solely to discover
+which ones the application uses. Unresolved dynamic references remain explicit
+material gaps with a next investigation; do not claim their absence or silently
+omit requested coverage. These inspections use existing read authorization and
+settled scope, not a new confirmation step.
+
 ---
 
 ## Workflow
@@ -123,9 +150,16 @@ Before choosing a local Markdown capture route, honor the surrounding task conte
   do not ask for `YYYYMMDD-2`. Declare
   `captureLark({ source: source("<date>", "<module>", { type: "lark" }) })`,
   then run `context run capture:lark:<date>/<module> --format json`.
+- For a registered document batch with shared capture settings, use
+  [Batch capture from the source registry](../manuals/reference/project-api.md#batch-capture-from-the-source-registry)
+  to load the registry and generate typed references and phases. Do not transcribe
+  the full YAML module list into `src/index.ts`. Select only the intended entries;
+  use the entire registry only when all its documents are in scope. Preserve
+  existing phases/packages and keep processor or resource exceptions per document.
 - Mixed local document and Lark document batches are separate sources unless
-  the current CLI explicitly offers a combined source contract. Do not write an
-  Agent-side URL/file loop.
+  the current CLI explicitly offers a combined source contract. Mapping registered
+  entries into declarative SDK phases is supported; writing an Agent-side loop
+  that fetches URLs/files and creates snapshots outside the CLI is not.
 - Refresh or recapture request for an already registered file/Lark source →
   rerun the same declared capture phase. The CLI appends a new snapshot only
   when content changes and never overwrites prior snapshots.

package/providers/context/resources/procedures/task-recovery.md

@@ -0,0 +1,71 @@
+---
+id: procedure.task-recovery
+kind: procedure
+mediaType: text/markdown
+---
+
+# Recover a stuck task
+
+This is an independent internal recovery entry. Start with
+`context task recover --format json`; do not require normal status to succeed,
+initialize a second workspace, or replay a saved workflow revision. Read available
+areas even if another area is corrupt. Do not interpret elapsed time alone as a
+stalled process: wait for a currently running command's receipt and check whether
+its progress is changing. Never start a competing writer or delete a writer lock.
+
+## Choose the smallest applicable action
+
+- Wrong current payload: use the reported schema/evidence to correct it and refresh
+  the Route when available. A current candidate can use its ordinary revise action.
+- Interrupted transaction: preview `task recover --operation transactions`, inspect
+  the recorded effect, then apply its digest when completion of those writes is
+  authorized. This finishes prior writes and may touch approved knowledge; it is
+  not draft rollback. Invalid journals or unclear ownership require escalation.
+- Failed Author work: preview `task recover --operation author --workset <digest...>
+  --instruction <concrete correction> --format json`. Explicit article dependencies
+  can expand the affected worksets. Read the entire affected scope before applying.
+- Restore the active accepted planning baseline: use `--operation plan` with the
+  same selection/instruction arguments. The checkpoint contains references to the
+  already stored immutable requests, not copies of all source or parser data. It
+  is available only after structure acceptance and is removed by lifecycle cleanup.
+  A changed registered source/configuration/approved-knowledge baseline prevents
+  restoration; use normal revision or replan instead. It does not recover deleted
+  runtime data from Git or choose arbitrary historical versions.
+
+The preview lists affected worksets and discarded candidates. Within an explicit
+repair task or delegated authorization covering those unfinished drafts, explain
+that scope and apply without another ritual approval. Obtain a decision only if
+the expanded scope discards work outside that authorization. Never treat a digest
+as permission to undo published knowledge. CLI validates mechanical identities,
+references and transaction consistency; the Agent diagnoses prose and planning.
+
+A repair changes request identities, archives replaced local draft/projection state,
+and preserves approved pages, menu, sources and existing packages. Read the fresh
+Route after success; do not reuse old task keys/results. Unrelated accepted results
+stay valid. Rebuilding whole-batch projections is not re-authoring their content.
+Do not silently exclude a failing module, weaken evidence or mark unfinished work
+complete to escape an error.
+
+## Stop a repair loop and report
+
+If the same cause persists after a correction without new evidence, do not repeat
+the same operation. Try a different supported recovery only when its prerequisites
+and effect justify it. If the ledger/checkpoint is unreadable, ownership cannot be
+established, the baseline changed, or a CLI defect prevents safe recovery, retain
+current work and write `issue/YYYY-MM-DD-short-description.md` using
+[the issue template](../templates/recovery-issue.md). Use the user's local date and
+a short semantic filename; update an existing report for the same incident rather
+than producing one per retry. This grants report creation only, not arbitrary
+workspace/runtime edits. Do not overwrite an unrelated existing report.
+
+Read diagnostic context locally, then summarize and redact it. Replace people,
+private repositories, module names and absolute home paths with stable aliases;
+remove tokens, cookies, authorization headers, signed URL queries, personal data,
+and source/document/chat bodies. Keep error codes, schema names, stage, counts,
+anonymous dependency shapes and relevant version/platform facts. Command examples
+must use placeholders for private arguments and secrets. Do not attach full debug
+logs, environment dumps, checkpoint archives, payloads or source snapshots.
+Review the report for remaining sensitive content before showing its clickable
+path to the user. Share with Context developers only when the user authorizes it.
+State that the issue remains unresolved and identify preserved results and the
+specific next developer/user action. An issue report is not a recovery receipt.

package/providers/context/resources/procedures/verify-and-repair.md

@@ -29,3 +29,8 @@ replacement is not an approved-identity conflict.
 Do not delete candidates, approved pages, snapshots, or structure slots to make
 verification pass. Derived diagnostics should not be handled as independent
 root failures.
+
+If normal status/Route evaluation fails or supported repair makes no progress, use
+`context task recover --format json` and read its independent recovery Skill.
+Preserve the current workspace; follow its sanitized issue-report path if safe
+recovery is unavailable.