@c4a/context-cli 0.7.17 → 0.7.23

package/plugins/cursor/commands/c4a-context-inspect-search.md

@@ -1,175 +1,146 @@
 ---
-description: "Use only when the user explicitly invokes context-inspect-search to query a Context workspace's approved knowledge and trace answers to its registered documents or source code. Do not auto-start for ordinary coding, planning, debugging, or an active Context production workflow."
+description: "Use only when the user explicitly invokes context-inspect-search to query available Context knowledge packages or approved workspace knowledge and trace answers to their identified sources. A local workspace is optional. Do not auto-start for ordinary coding, planning, debugging, or an active Context production workflow."
 ---
 
 # Context Inspect Search
 
-Answer questions from a selected knowledge workspace, then investigate its
-sources when the answer needs verification. This is an independent query entry,
-not an Indexer or a production Route. Use the conversation language.
-
-## Invocation and scope
-
-Start only on the user's explicit command or named Skill invocation. Continue
-related follow-up questions without repeated invocation; stop applying this
-Skill when the user changes task. An existing workspace, error message, or
-knowledge-related phrase is not an activation signal.
-
-Locate the user-selected workspace. With the CLI available, use
-`context entry [project-dir] --format json` to identify it and its installed
-instructions. This is inspection: do not execute a returned production command
-just because it is actionable. If the CLI is unavailable or state inspection
-fails, readable files can still support a bounded answer; report what could not
-be checked. Do not initialize a replacement workspace or install tools silently.
-If several workspaces could match, resolve which one the user means.
-
-Keep all paths relative to that workspace. Read its `AGENTS.md` and relevant
-configuration before investigating. The presence of a `.tmp` directory alone
-does not establish a workspace. Querying must not clear caches, reset tasks,
-change checkouts, accept Review, or start Author or close. The one permitted
-query preparation build is described below.
-
-## Choose the query material
-
-**Prefer an existing usable dist.** Locate the package output from the workspace
-configuration and inspect its index and `context-build-inventory.json`. Choose
-the package matching the question; do not silently combine unrelated packages.
-A usable package has readable delivered pages, not just an existing directory.
-Read its bundled query Skill (usually `skills/knowledge-query/SKILL.md`, but
-business templates may use another name) and use its navigation and search
-instructions within that package. If it has no query Skill, use its readable
-indexes and pages; a missing Skill alone is not a reason to rebuild. Do not
-execute unrelated scripts merely because they are bundled.
-
-Do not build first when usable output exists. It represents its last successful
-build and selected scope, not necessarily the latest approved workspace content.
-A search miss does not make the package unusable or justify a rebuild. For a
-latest-content question or an apparent gap, inspect the corresponding approved
-knowledge and distinguish it from the delivered version.
-
-**If no usable output exists, try one build when allowed.** Inspect the current
-Route/status and configured package. Only use the normal CLI build action when
-its prerequisites are already satisfied and it will not advance an unrelated
-active delivery or revision. Do not create package configuration, approve a
-template, run close, recover production state or finish pending work just to
-make this query possible. When a safe build is available, run its current
-command once in the identified workspace, wait for the same invocation's exit
-and receipt, then inspect its actual output and query Skill. Do not launch a
-second writer or treat partial output as a completed package. There is no
-unverified promise that this takes less than 20 seconds.
-
-**Otherwise query approved knowledge directly.** If the CLI is unavailable,
-state cannot be checked, build is not allowed, or the attempt fails, briefly
-explain the limitation and continue from readable approved knowledge. Do not
-loop through build repairs. Use `knowledge/structure.yaml` to locate pages,
-collections and source associations; search selected `knowledge/` paths with
-Host file tools, trying domain terms, symbol names and synonyms. Read relevant
-sections in context. A search miss proves neither absence of knowledge nor
-absence of the underlying capability. Candidates and `.tmp` reports may explain
-pending work but are not approved knowledge. If approval cannot be established,
-state that limitation rather than treating arbitrary Markdown as approved.
-
-## Trace delivered answers to workspace sources
-
-For a dist hit, find its `dist_path` in the matching package inventory's
-`approved_knowledge.files` and follow that record's `approved_path` into the
-workspace. `approved_path` is relative to the workspace's `knowledge/` root,
-not the dist directory or workspace root; do not guess the mapping from similar filenames. Read that page and its source
-associations in `knowledge/structure.yaml`, then follow the registered sources.
-If the inventory or mapping is missing, still answer from readable package
-content where possible, but do not claim verified original-source attribution.
-
-The chain is: delivered page → build inventory mapping → approved knowledge and
-structure → registered raw material at its recorded version. The current
-approved page can have changed since build; describe differences rather than
-silently replacing one version with another. Dist and knowledge are two forms
-of the same content, not independent corroborating evidence. The bundled query
-Skill owns package-local retrieval; this explicitly invoked inspection Skill
-owns the subsequent, separately scoped workspace/source investigation. Cite
-which layer supports each claim.
-
-## Prepare only the sources needed for attribution
-
-Follow the relevant page's source references and `sources/*/index.yaml` records.
-Check the selected raw body, attachments or repository module and its recorded
-version before claiming deep attribution. This readiness check concerns the
-selected materials, not completion of the active production workflow.
-
-For repositories, `context source recovery-plan --format json` provides a
-read-only recovery plan. Reuse an accessible checkout only after checking its
-remote, pinned commit and module path. Inspect local changes as well: a matching
-HEAD does not prove a dirty file is the recorded source. Do not silently use the
-latest branch or reset a user's checkout.
-
-If material is missing, report what cannot be verified and offer the smallest
-necessary recovery. With the user's recovery authorization, follow the installed
-`repository-source-recovery.md` procedure and schema in the workflow bundle
-identified by entry, using the CLI's `source restore` contract. Recover only the
-selected source groups; never run `task prepare` or the whole workspace-reset
-procedure to enable a query. If a writer is active or recovery cannot safely
-coexist, keep the answer bounded and defer the write. Do not invent recovery
-payload fields when the installed schema is unavailable.
-
-For documents, notes and sessions, read their saved source bodies or summaries
-and necessary attachments. A summary is not a full conversation transcript.
-An external link is not evidence of its unread target. Fetch missing external
-material only within the user's authorized scope; current remote content is not
-proof of an older snapshot. If historical raw material is unavailable, identify
-the gap rather than reconstructing it from generated knowledge.
-
-## Explain and verify
-
-Trace from the approved claim to the relevant source location. Expand to
-adjacent definitions or tests only as necessary and within the selected source
-scope. Distinguish declared API, implementation behavior, test assertions and
-observed runtime behavior; reading code does not prove a runtime experiment.
-Apart from the bounded package build above, do not run repository builds, tests
-or arbitrary scripts merely to answer a query. If runtime validation is needed, explain the proposed check
-and obtain the user's authorization for that scope.
-
-Lead with the answer, then cite concrete page paths and source locations,
-including the version when it affects the conclusion. Separate confirmed facts,
-inferences and unavailable evidence. If source versions differ, describe the
-difference before deciding that a knowledge page is wrong. Do not dump runtime
-ids, long raw excerpts or a mandatory audit report into every answer.
-
-
-## Website links in the final summary
-
-After answering from the pages actually read, optionally append one or more
-related document links in the final summary. Read `context-site-map.json` from
-the selected package (or its sibling website output in a workspace). Match the
-read page to `pages[].package_path` or `approved_path`; use its `title` and resolve
-`site_path` relative to `site_url`. The URL already includes the deployment base
-path: do not prepend `base` again. Only cite matched articles, deduplicate links,
-and do not invent section anchors.
-
-This is a local formatting step, not retrieval or validation. Do not probe URLs,
-make HTTP/HEAD requests, open a browser, inspect a deployment platform, or check
-remote versions to add links. Never build, publish or update metadata for this
-purpose. If the map, URL or matching page is absent or malformed, keep the local
-citation and continue silently. A configured URL does not prove that the site
-contains the current local revision; do not claim online verification.
-
-## Suggest improvements and hand off
-
-When evidence supports a correction or worthwhile addition, briefly describe:
-
-- the affected page or missing topic and the reader's actual problem;
-- the supporting source location/version and what it establishes;
-- whether to revise an existing page, adjust discoverability, add a topic, or
-  obtain missing material first;
-- the bounded pages/sources involved and any uncertainty.
-
-Check the existing scope and neighboring pages before recommending new content.
-Do not create a page solely because a search missed it, and do not propose
-unsupported claims as a knowledge update. With insufficient raw evidence, give
-an actionable material request instead of forcing an update.
-
-A suggestion is not authorization to write. Only when the user accepts the
-update, hand the question, evidence, proposed change and scope to the installed
-`context` production Skill in the same workspace. Read its fresh Route; it owns
-candidate repair, approved-page revision and scheduling around active work.
-Do not clear state, reuse an earlier revision, directly edit knowledge, or build
-a second update workflow. If the production Skill/CLI is unavailable, provide
-the handoff information and state that no update has started.
+## Entry and boundaries
+
+Use on explicit invocation and related follow-up questions; use the conversation
+language. The invocation authorizes read-only investigation of the selected
+knowledge packages, available workspace and identified sources within that scope,
+including isolated source retrieval and bounded non-destructive checks. The Skill
+can run from a global installation with host-provided packages and no workspace.
+Resolve scope from the request, conversation and configuration before asking.
+Continue through non-blocking issues; ask only for missing access, genuinely
+unresolved scope or effects outside existing authorization.
+
+Start from the supplied package locations or workspace configuration. If a
+workspace exists, read its `AGENTS.md` and relevant configuration;
+`context entry [project-dir] --format json` may help locate instructions.
+Neither a workspace nor a working Context CLI is required for package retrieval;
+do not call entry in an arbitrary directory just to satisfy a prerequisite.
+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.
+
+A knowledge package may be workspace build output (usually `dist/`), a global
+installation, or an equivalent host-provided directory. Locate it from available
+configuration or installation metadata rather than assuming a fixed path.
+Select packages relevant to the question. Follow their bundled query Skill when
+present; otherwise search readable indexes and pages. Missing Skills or build
+inventories do not block retrieval or justify rebuilding. If a needed package is
+missing, use the host's configured, authorized package retrieval mechanism while
+other reading continues. Only check or prepare tools needed for the next actual
+operation; installation failure does not block independent local retrieval.
+
+For gaps or latest-content questions, also search approved knowledge when a workspace is available:
+use `knowledge/structure.yaml` and relevant `knowledge/` paths, trying business
+terms, symbols and synonyms, then read matching sections in context. Delivered
+content may lag approved knowledge; they are not independent corroboration.
+Candidates and temporary reports are not approved pages. A search miss does not
+prove a capability is absent. Do not build merely to answer a query; a separately
+authorized build must follow its own workflow without advancing unrelated work.
+
+When package or approved knowledge leaves a gap, directly trace relevant sources
+without asking whether to deepen the query. Use available document, code-search
+or extraction tools within the authorized scope, recording source identity and
+version. Prepare sources while continuing other reading.
+One failed source blocks only dependent claims. Answer when evidence is
+sufficient, without completing unnecessary preparation.
+
+## Trace and retrieve only relevant sources
+
+Without a workspace, use explicit source references in the package, its metadata
+or user configuration to identify relevant documents or repository paths and
+commits. Read or retrieve those sources directly within scope; the workspace
+registry is not a mandatory intermediate step. If the source identity or version
+cannot be established, retain package-grounded findings and qualify attribution;
+do not invent a repository or equate current source with the package's baseline.
+
+When a workspace and `context-build-inventory.json` are available, map a delivered page's
+`dist_path` through `approved_knowledge.files` to its `approved_path`, relative
+to the workspace's `knowledge/` root. Follow the approved page's associations in
+`knowledge/structure.yaml` and `sources/*/index.yaml`. Without a reliable mapping,
+continue package retrieval and follow explicit source references where available.
+Do not guess originals from similar filenames or claim attribution without
+checking the referenced material.
+
+Use the repository and recorded commit identified by the package or workspace
+as the source baseline.
+Reuse existing checkouts only after checking remote, commit, module coverage
+and local changes; do not reset them or change their sparse configuration.
+Missing code goes into a reusable query-owned path such as
+`.tmp/context-inspect/<host>/<repository-path>/<commit>/`, separate from user
+checkouts and production-managed sources. Use safe, credential-free path
+components and the full commit. Verify identity before reuse; never overwrite
+a mismatched directory. Deduplicate recovery and use one writer per checkout;
+that writer may append sparse paths without resetting existing files.
+
+Default to lightweight retrieval and sparse checkout:
+
+- Use shallow history (`--depth=1`) and deferred contents (`--filter=blob:none`)
+  where supported, with a complete partial-clone setup and named promisor remote.
+  Configure the sparse scope before checkout and verify the resulting commit.
+- Start from known module paths. If unclear, inspect
+  `git ls-tree -r --name-only <commit>` for candidates, then read code to confirm
+  their relevance. Expand along imports, calls and service routes as needed;
+  deepen history only when needed. A sparse search miss is not a whole-repository miss.
+- Read ready modules while other recovery proceeds. Allow sufficient command
+  time (for example 300 seconds or more), but investigate confirmed stalls
+  without waiting for timeout; silence alone is not a stall. If unsupported or
+  unsuccessful, try caches, commit-specific file retrieval or bounded shallow
+  retrieval; use a full clone only when necessary. Do not retry blindly or
+  silently substitute the default branch for an unavailable recorded commit.
+
+Query retrieval never runs `context source restore`, `task prepare` or production
+capture/recovery actions. Production recovery gates do not block this independent
+inspection. Preserve unavailable-evidence gaps rather than changing production
+state to get past them.
+
+Compare relevant baseline files with current code when accessible, including
+relevant local changes. Use actual diffs to assess impact; current code is not a
+substitute for the baseline. Mention a missing comparison only when it limits
+the answer. For documents, notes and sessions, read saved bodies and necessary
+attachments; fetch missing accessible material within scope. A summary is not a
+full transcript, an unread link is not evidence, and current remote content does
+not prove a historical snapshot.
+
+## Answer with evidence and hand off updates
+
+Lead with the conclusion and a concise evidence chain. 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.
+
+Link material actually read: source files at the inspected commit, knowledge
+website articles and original documents. If no reliable clickable link exists,
+give checkable local paths, symbols and short supporting excerpts with the
+limitation. Do not dump internal reasoning, runtime identifiers or routine
+version comparisons. Explain only differences affecting the answer; hashes may
+appear in source URLs without requiring a separate version audit in the prose.
+
+For website links, use `context-site-map.json` from the selected package or
+sibling website output. Match `pages[].package_path` or `approved_path`, and
+resolve `site_path` against `site_url` without prepending `base` again. Cite only
+matched pages, deduplicate links and do not invent anchors. If mapping is absent
+or invalid, retain local citations. Do not build, publish or probe remote sites
+just to format citations; a local map is not proof of the current online content.
+
+Suggest a knowledge update only with supporting evidence: identify the affected
+page or gap, proposed change and bounded source scope. Check neighboring content
+before proposing a new page. Only after user acceptance, hand the evidence and
+scope to the installed `context` production Skill in the selected workspace and
+its fresh Route. If no target workspace is known, resolve it at that handoff,
+not as a prerequisite to answering. Do not edit approved knowledge, clear state
+or reuse an earlier revision. If that entry
+is unavailable, provide the handoff and state that no update has started.

package/plugins/cursor/commands/c4a-context.md

@@ -94,13 +94,16 @@ settings. Reuse explicit answers and defaults; ask only for unresolved items.
 
 Use focused dialogue, not additional source reading, until every required start
 condition is resolved. Then write and present the complete work-start report
-supplied by the source-boundary Route and wait for the user's feedback. Do not
+supplied by the source-boundary Route. Apply the confirmation policy below: a
+specific earlier user request can approve an unchanged, bounded scope; otherwise
+wait for feedback when confirmation is required. Do not
 present an unresolved draft as the report that authorizes production. The report
 or checklist is task guidance, not a source unless the user explicitly asks to
 ingest it. Before the complete report has been presented, do not write a
 source-registration payload, start capture or extraction, configure Indexers,
 or begin knowledge writing. A
-managed-mode choice does not waive this first reading opportunity. After feedback,
+managed-mode choice does not waive this first reading opportunity. After the
+applicable scope decision,
 use the exact current Route and include its work-start report reference in the
 source batch payload. Existing workspace updates follow their current update Route
 and do not recreate this first-task intake unless they start a new production task.
@@ -140,7 +143,9 @@ Follow the returned `next_action.command`:
 
 - `enter-workspace` and `evaluate-workflow` are read-only.
 - `initialize-workspace` may run immediately if the user requested initialization;
-  otherwise confirm the target. Preserve any `init-target-nonempty` confirmation.
+  otherwise confirm the target. For `context.gate.workspace_initialize_nonempty`,
+  reuse the user's explicit target choice; ask if the nonempty target was not
+  clearly selected.
 - After initialization, execute its exact setup command, enter the project root,
   read the generated `AGENTS.md`, then run the entry again.
 
@@ -157,6 +162,50 @@ Reuse an explicit review/managed choice across capture and continuation. Neither
 mode settles unclear purpose, missing permissions or non-delegatable decisions.
 Status, discussion and save-only requests need no production-mode question.
 
+## Confirmation policy
+
+The `context.gate.*` IDs below are stable Agent policy switches, not CLI flags or
+workflow authority IDs. Keep the existing Route gate ID, command and payload
+unchanged. An instance-specific Bot may override a switch; precedence is Bot >
+fully managed > ordinary. Reuse a decision already made for the same scope.
+
+| Policy ID | Ordinary default | Fully managed default | Existing Route gate, if any |
+| --- | --- | --- | --- |
+| `context.gate.production_entry` | Ask only if intent is unclear. | Same. | Context entry |
+| `context.gate.workspace_initialize_nonempty` | Proceed if the user already selected this target; otherwise ask before initializing a nonempty directory. | Same. | Context entry `init-target-nonempty` |
+| `context.gate.work_start_scope` | Present the report; ask only if the scope is complex **and** affects more than five new or revised articles. A matching request for 1–3 documents or one MR-triggered note needs no repeat question. | Same. | `production-work-start-report`, `indexer-semantic-structure-review` |
+| `context.gate.source_boundary` | Use the user's selected source scope; ask only for missing boundaries. | Same. | `source-boundary` |
+| `context.gate.source_read` | A user-supplied source authorizes reading it for the requested task; do not ask again. | Same. | `source-read-permission` |
+| `context.gate.repository_clone` | Ask before cloning a missing repository. Other authorized recovery needs no repeat question. | Restore within the selected scope without asking. | Repository restore authority |
+| `context.gate.indexer_extra_action` | Ask only if the operation blocks the requested result and no authorized alternative works. | Resolve eligible operations without asking. | Indexer authorization Routes |
+| `context.gate.image_handling` | Ask once when the task has more than 30 distinct images and no prior handling choice. | Same. | Work-start report |
+| `context.gate.top_level_directory` | Confirm the concrete structure. | Same. | Knowledge map guidance |
+| `context.gate.knowledge_review` | Ask for a decision on the current HTML report. | Delegate when the Route permits. | `knowledge-review` |
+| `context.gate.deletion_scope` | A user-approved deletion of exact sources or approved pages needs no second question after the CLI preview; ask only before deleting additional objects outside that scope. | Same. | Source remove / article retirement preview |
+| `context.gate.force_review_approval` | If the user explicitly says `强制批准` after the report is inaccessible, execute the current force-approval Route without another question. | Same. | `knowledge-review` recovery |
+| `context.gate.package_output` | Ask. | Choose within the requested delivery scope. | `package-output` |
+| `context.gate.package_template` | Ask. | Choose within the requested delivery scope. | `package-template-review` |
+| `context.gate.git_delivery` | Ask before commit, push or MR. | Same. | Host Git delivery |
+| `context.gate.publication` | Ask before publishing. | Same. | Distribution tool |
+| `context.gate.remote_target_create` | Ask before creating a remote target. | Same. | Distribution tool |
+| `context.gate.workspace_reset_restore` | An explicit clear or historical restore request needs no second confirmation when target and losses are clear; clarify either if ambiguous. | Same. | Workspace prepare/restore |
+| `context.gate.exceptional_recovery` | Ask only for a P0 blocker that prevents action and affects the requested result. | Same. | Current recovery Route |
+
+`context.gate.work_start_scope` and `context.gate.knowledge_review` are separate
+decisions; the latter uses the HTML report. Follow the current Route's payload and
+revision. If a Route requires a human decision despite this policy, stop at that
+Gate and report the mismatch instead of fabricating approval. For extra Indexer
+operations that are not blocking, skip the optional operation rather than
+granting its authority implicitly. Fully managed mode does not authorize
+modifying source code or bypassing a non-delegatable Gate.
+
+If an instance sets `context.gate.knowledge_review: ask` while using fully
+managed mode, do not start a `--managed --until blocked-or-complete` loop that
+could cross Review. At Review, evaluate without managed review authority and
+follow the ordinary HTML report and user-decision Route. Force approval remains
+available only after the user's exact Route-required reply; the override itself
+never authorizes it.
+
 Enable debug only when requested: use `entry --debug` for initialization or
 `context debug enable` in an existing workspace. It records diagnostics under
 `.tmp/context-runtime/debug/`; it grants no authority and is not source evidence.
@@ -169,6 +218,20 @@ npm install -g @c4a/context-cli@latest
 context plugin install
 ```
 
+For authorized local installation, `--local <path>` requires explicit `--agent`:
+- `claude`, `cursor`, `codex`: path is the repository root; install into its
+  `.claude`, `.cursor`, `.agents` directory respectively, without host detection.
+- `all`: install all three host layouts.
+- `auto-detect`: select existing host directories in that repository only,
+  never PATH or desktop applications; if none exist, use `.agents/skills`.
+- `standalone`: write all skills directly to `<path>/skills`, without commands.
+All combinations support `--dry-run`. Bare `--local` is rejected. Older explicit
+host installs took a host directory; now pass the repository root to avoid
+nesting. Check CLI help for support before using these options on older versions.
+Local entries have no plugin namespace and do not change global configuration.
+Preserve customized files on conflict; refresh the host after installation.
+Existing usable entries need no reinstall. Global installation is unchanged.
+
 Stop with that recovery. Do not run an installation preflight or auto-install;
 a normal Context `not found` diagnostic does not mean the executable is missing.
 
@@ -222,8 +285,9 @@ clear runtime state to force a transition. Explicit historical restoration may
 restore exact Git-saved workspace files after the preparation guide has ended
 old task state; it is not an alternative content-writing path. Do not infer sources, extraction
 scope, review decisions or package choices from surrounding files. Operations on
-source repositories—clone, checkout, reset, fetch, install, build or test—require
-explicit authorization for that scope.
+source repositories stay within the selected source scope. Ask before cloning in
+ordinary mode. Do not modify source code or run destructive recovery outside the
+user's authorization.
 
 ## Follow the current Route
 
@@ -235,7 +299,8 @@ explicit grant.
 
 After continuation is authorized or the new target is registered, both modes
 may use `context run --until blocked-or-complete` for consecutive mechanical
-steps. With explicit managed authorization:
+steps. With explicit managed authorization and no instance-specific Review
+override:
 
 ```bash
 context run --managed --until blocked-or-complete --format json
@@ -285,6 +350,12 @@ Mechanical blockers follow the returned repair/recovery action; advisory
 warnings do not independently require rewriting content. Migration also uses
 its returned command, not manual path renames.
 
+For Lark capture, use the available `lark-cli` without a session-wide version
+precheck. Only when the Context command reports a missing or incompatible CLI,
+follow its private-install recovery. Keep `CONTEXT_LARK_CLI_BIN` pointing to that
+private executable on subsequent Context commands that access Lark; do not
+upgrade or replace the host's global `lark-cli`.
+
 **Continue.** Read `next_route.file` for the full Route after a compact receipt;
 `result_file` is for full diagnostics. Otherwise use the returned workspace
 Route (`next`, `continuation.next` or `workflow.current`). Do not call status