@c4a/context-cli 0.7.5 → 0.7.9

package/providers/context/resources/procedures/sessions.md

@@ -0,0 +1,56 @@
+---
+id: procedure.sessions
+kind: procedure
+mediaType: text/markdown
+---
+
+# Prepare a conversation-summary source
+
+Use sessions for a bounded summary formed from an authorized conversation:
+requirements, design, troubleshooting, operational or general knowledge.
+Code association is optional. An Agent or external supplier prepares the summary
+before import. Do not scan host history, ingest the full transcript, invent a
+conversation from a diff, or move an unrelated conversation into note merely
+because it lacks a commit.
+
+Keep the problem, confirmed decisions, useful reasons, constraints and open
+questions. Remove repetitive turns, tool logs and abandoned attempts unless they
+explain a current limit. Preserve whether each statement was proposed, agreed,
+implemented or verified. If only a supplied summary is available, say so; do not
+claim to have read the original. Do not make up speakers, dates or approval.
+A session with no reusable information can remain outside the workspace.
+
+Save through `context source import --input <file> --format json`, using
+`type: sessions`, `name: YYYYMMDD/topic.md` and the prepared `markdown` string.
+Choose the actual conversation date, or collection date if unknown, and retain
+the same path for corrections. The summary needs no mandatory body headings.
+
+Optional `changes` associates one or several code changes. Each row accepts
+`commit` (full 40/64 hexadecimal Git SHA), `mr` (HTTP(S) MR/PR URL), and optional
+`repository`. At least commit or mr is needed per row; omit the entire field
+for unrelated sessions. Use actual known identifiers, never fabricated hashes.
+A reference does not prove merge, deployment, tests or authorize fetching code.
+The CLI stores this field in the source's YAML frontmatter, discovers it from
+that same file, and does not introduce a sidecar or separate registry.
+
+For example, an import may have `changes: [{mr: "https://git.example.org/team/project/merge_requests/42"}]`.
+This is an illustrative URL, not a lookup target. The same payload without
+changes imports an independent requirements discussion normally. Use the current
+base_digest to change text or associations; explicit `changes: []` clears the
+associations. Omission leaves the source's inline changes intact. When replacing
+only the summary body, preserve existing associations unless explicitly removed.
+Do not duplicate commit/MR fields into knowledge frontmatter.
+
+Saving alone does not start indexing. Select a compatible Sessions Provider for
+an independent reader topic, or keep an existing page's Code/Markdown primary
+and include the summary in its authorized evidence/read scope. If specialized
+interpretation is needed, explicitly select an extension from the Sessions or
+business Provider. Knowledge turns useful conclusions into answers, explanations
+and procedures, not a meeting recap. Existing structure.yaml source references
+connect each relevant page/section to the saved summary and its optional changes.
+
+Correct a faulty summary through source import with current base_digest and task
+adjustment for pinned inputs. If the summary is accurate but the page is wrong,
+revise the approved page. A new topic goes through structure review then normal
+Author/Review. Neither knowledge approval nor source storage approves an upstream
+change. A failed update retains source and approved knowledge for recovery.

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
@@ -31,7 +42,19 @@ conversation contains the required confirmation, write one JSON payload
 matching the selected schema to that exact path. Do not run the command before confirmation and do not replace
 it with a command remembered from another route.
 
-Context source identity has two parts:
+For an already saved `note` or `sessions` source, the batch registration schema
+is not applicable. After the user selects that material for new knowledge work,
+add its exact typed reference to `sources` in `src/index.ts`, preserving existing
+sources, phases and packages. For example, import `source` from the project's
+Context SDK and use `source("20260908/selected.md", { type: "note" })`; use
+`type: "sessions"` for a saved conversation summary. Use the actual saved name,
+not the example. Re-evaluate with `context status --format json` to obtain the
+initial requirement configuration Route. Do not create a capture phase or a
+second source registry for saved text. Saving alone is not this selection;
+material only supporting an existing page stays in that page's authorized
+reading scope.
+
+For repo/file/lark registration, source identity has two parts:
 
 - a calendar date identifies one capture batch and directory;
 - a module identifies one concrete repository, local document boundary, or

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/source-update.md

@@ -0,0 +1,50 @@
+---
+id: procedure.source-update
+kind: procedure
+mediaType: text/markdown
+---
+
+# Check source changes against current knowledge
+
+Read the fixed source versions and confirmed requirement scopes in the action.
+Use the host's existing repository or document tools to inspect the change and
+relevant current material. A missing previous version means unknown history;
+inspect the confirmed scope without pretending the latest acquisition was
+already incorporated into knowledge. Do not fetch material already acquired.
+
+The listed pages are candidates to inspect, not an instruction to rewrite all
+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.
+
+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
+collection, `title`, registered `source_refs` and an `instruction` describing the
+reader task and material to use. Reuse the established purpose and page forms.
+Use an empty list only when existing pages cover the change or the additions
+are outside the confirmed purpose. New pages go through the same writing and
+review process as revisions; a new topic is not a no-change decision.
+
+The CLI keeps the previous processed version until every requested page has
+been approved, closed and built. If temporary progress is lost, inspect again
+from that version and preserve the pages already approved. A saved report or
+acquisition receipt does not prove that the knowledge update was completed.
+
+If a revision needs a newly supplied note or development summary, include its
+exact `supporting_sources` on that page decision. These must already belong to
+the confirmed evidence scope. Do not attach redundant summaries or turn an
+auxiliary source into an independent production target. Code unchanged plus
+new explanation still needs an impact decision; it does not require another
+Parser run.
+
+A renamed subject does not automatically need a new page identity. Revise its
+title and explanation in place unless the user chooses a different path; an
+explicit path move uses `context revise --move-to` after the current page work
+is closed. For retirement, explain what disappeared or became inapplicable,
+which readers are affected and any supported replacement. Do not silently
+delete same-source pages. Include referring pages that need navigation or
+wording changes in this update's decisions.
+
+For selected `note` inputs, read [note guidance](note.md). For `sessions`,
+read [sessions guidance](sessions.md). Read only the applicable source guide.

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.