@c4a/context-cli 0.6.1 → 0.6.3

package/plugins/codex/skills/continue/references/internal-procedures/skill-source-scope.md

@@ -1,525 +0,0 @@
----
-name: skill-source-scope
-description: >
-  Internal procedure invoked by the public Context continuation entry; not a user slash command.
-  Handles source registration, monorepo source boundaries, extract phase
-  declaration, no-write scope preview, and the pre-extraction confirmation gate.
-tools:
-  - Bash
----
-
-# skill-source-scope
-
-Choose and validate what may become draft knowledge.
-
-## TL;DR
-
-- Missing source means the next product action is "add a knowledge source".
-  Explain that in user-facing language before showing any CLI command.
-- Ask what source the user wants to add: local code repo/package, remote Git
-  repo/package, local Markdown/MDX document/folder, article/documentation repo as a
-  file source, or Lark/Feishu document. Current CLI can execute repo sources,
-  local file sources, and Lark document capture through the declared flow.
-- Treat source registration as a knowledge-boundary decision, not a parameter
-  prompt. Repo, file, and Lark sources use today's date as a batch. Multiple
-  modules or documents share that date; never auto-append `-A/-B/-C` or ask for
-  a second flat date name. File/Lark modules may be supplied with `--module`;
-  otherwise the CLI derives a safe module from the local path or opaque
-  document identity.
-- When the user supplies multiple sources together, register them with one
-  `context source add batch [YYYYMMDD] --input <yaml|json|->` command. Never run
-  multiple mutating `context source add` commands in parallel. Single-source
-  commands use the same project write lock and must be retried serially when
-  the CLI reports that the lock is held.
-- Do not infer a source from cwd, parent directories, package names, monorepo
-  layout, or git remote.
-- In monorepos, inspect the package tree, then register each selected
-  package/subdirectory as a module under the same date. Do not extract an
-  ambiguous parent module.
-- `extractTs.include` filters files inside the selected source; it is not a
-  package/module selector.
-- Do not ask users to add `exports`, `main`, `bin`, or a new entry file to the
-  source repository solely for extraction. Standard package entries are
-  auto-detected; non-standard API roots belong in Context-owned
-  `extractTs.entries`. When the confirmed scope is all declarations in matched
-  files, use `mode: "scan"` instead of inventing an entry.
-- Empty or undetected entries must return `NO_ENTRY_DETECTED`; never treat an
-  empty extraction as success. Configure `entries`, or choose scan mode only
-  when every matched file is the intended scope.
-- TypeScript extraction follows tsconfig/jsconfig `extends`, `baseUrl`, and
-  `paths`. Aliases such as `@/` do not require changes to the source repository.
-- Use `context source inspect <date>/<module> --format json` for module choices.
-- Before first real extraction, generate a no-write preview and show module
-  counts plus `knowledgeTree` / `knowledgePathExamples` to the user. Use
-  `--dry-run` only in the command you execute, not as the user-facing label.
-- In explicit current-conversation fully managed mode, an evidence-backed
-  collection recommendation and a valid no-write extraction preview may be
-  accepted without another question. This never permits inventing a source
-  boundary or reading a file/Lark body the user did not authorize.
-- During a declared multi-module extraction round, treat
-  `next_action.human_gate=false` as mechanical continuation: finish every
-  pending extract phase before opening one combined Review page.
-- When captured file/Lark sources coexist with an unprocessed repo source,
-  process code first while document structure is still untouched. Follow the
-  `ready-to-extract` route and explain that document align resumes after the
-  code extraction/review round. Do not interrupt a document structure or
-  compile gate that has already started.
-- Human-facing explanations must describe the extraction impact first: what code
-  files are read, what symbols become draft knowledge, what is skipped, and what
-  review gate follows. Do not lead with `extractTs`, `include`, `exportedOnly`,
-  or `reviewValidity`.
-- Document capture has its own gate. After a file or Lark source is registered,
-  ask for permission before reading the source body, then show the capture
-  summary before handing off to material investigation and structure drafting.
-  If the user explicitly asked to capture, ingest, fetch, read, or include the
-  exact path/URL, that request already grants read permission; do not ask again
-  after registration. Mere mention, source discussion, and register-only
-  requests do not grant permission, and an explicit refusal always wins.
-  When the user requested several documents together, that confirmation covers
-  those explicit modules: declare them all, then execute every capture command
-  returned by `context status` before asking another source question.
-  Do not default to one page per document, and do not create final draft pages
-  directly from capture.
-- For capture routing, output handling, missing dependency recovery, and final
-  reporting discipline, read the source capture procedure at
-  [skill-source-scope/references/capture-source.md](skill-source-scope/references/capture-source.md). Its judgment
-  rules use only the declared source/capture phase flow in this skill.
-- Do not use unsupported source lifecycle shortcuts. There is no direct
-  source deletion or purge command in this workflow, and agents must not delete
-  `sources/`, `knowledge/`, `unapproved/`, `dist/`, or `.tmp` to simulate one.
-  If the user asks to retract, remove, or purge a source, stop and explain that
-  the current plugin exposes no approved gate for that operation.
-
-<reference>
-
-## Source Type Guide
-
-When the workspace has no source, do not ask with a raw placeholder command.
-Ask for a knowledge source in plain language and map it to the supported path:
-
-| User source | What to ask for | Current handling |
-|---|---|---|
-| Local code repo | date batch, concrete module name, and local repo/package path | Register with `context source add repo [YYYYMMDD] --module <module> --local <path>`. CLI records git root + optional `subpath`; when the Context workspace and source share a Git root, an absolute input is stored relative to the workspace. `sources/repo/YYYYMMDD/<module>` becomes an ignored relative symlink to that module view. |
-| Local monorepo package/module | which concrete packages/subdirs belong to this batch | Register every confirmed boundary as a module under the same date. Do not create `YYYYMMDD-A/B/C`, and do not use `extractTs.include` as a package selector. |
-| Remote Git repo | knowledge boundary, remote URL, pinned commit/ref, desired package/subdir, and permission to clone | CLI does not clone automatically. After explicit user approval, the agent may clone/checkout to an ignored local path, then register that local checkout. Cloned source content must not be committed. |
-| Local Markdown / document file or folder | date batch, document module boundary, local path, include glob or include-list if needed, and permission to read the source body | Register with `context source add file [YYYYMMDD] --module <module> --local <path>`; `--module` may be omitted when the path-derived name is sufficient. Documents from the same date are written as sibling files under `sources/file/YYYYMMDD/` and share that date's `manifest.json`. |
-| Lark / Feishu document | date batch, document module, URL/token, and permission to read remotely | Register each document with `context source add lark [YYYYMMDD] --module <module>` plus exactly one identity flag. Documents from the same date are written as sibling files under `sources/lark/YYYYMMDD/` and share that date's `manifest.json`. Omit `--module` when the CLI-derived opaque identity is acceptable. Choose the mainline collection only after capture investigation. |
-
-When status reaches `captured-ready-to-classify`, run every immediate
-collection-neutral investigation command first. Then ask for a document
-mainline collection with an evidence-backed recommendation; do not ask only
-"which collection?" or infer it from registration metadata. Explain relevant
-options in product language:
-
-| Collection | Use when the source is mainly about |
-|---|---|
-| `business` | 业务域、业务对象、行业/组织概念、非技术的领域知识 |
-| `product` | PRD、用户故事、产品行为、需求说明、验收口径 |
-| `architecture` | 系统架构、组件/模块设计、技术方案、工具链、平台能力 |
-| `sop` | SOP、操作流程、排障步骤、oncall/runbook、巡检维护 |
-| `faq` | 问答集合、常见问题、按问题检索的解释和处理建议 |
-| `standards` | 规范、标准、约束、检查清单、合规/质量规则 |
-| `decision` | 明确的方案选择、取舍理由、ADR、决策记录 |
-| `incident` | 事故复盘、故障时间线、影响面、根因、处置和预防措施 |
-| `test` | 测试计划、测试场景、验证矩阵、验收用例 |
-
-Do not offer `codegraph` or `feats` for prose document alignment. `codegraph`
-comes from code extraction, and `feats` is a later feature namespace.
-
-</reference>
-
-<procedures>
-
-### Step 1 — Register Only User-Chosen Sources
-
-If no source is registered, tell the user that the next step is adding a
-knowledge source. Use the user's language and explain that this is a boundary
-choice:
-
-```text
-You are choosing which code modules belong to one dated source batch.
-The date is the source directory/batch; each concrete module has its own
-extraction, source ref, phase id, and stable codegraph subtree. The date is not
-part of the knowledge path.
-
-If the source is one package:
-knowledge/codegraph/<module>/...
-repo:YYYYMMDD/<module>#symbol:...
-
-If the source is one document source:
-knowledge/architecture/entity/example.md
-file:YYYYMMDD/getting-started/index.md#span:...
-align:file:YYYYMMDD/getting-started:architecture
-dist/<name>-kb/
-
-If the date batch contains several repo modules, outputs are shaped like:
-knowledge/codegraph/module-a/...
-knowledge/codegraph/module-b/...
-```
-
-Every repo source has both levels, even when the batch contains only one module.
-The date groups capture work; the module is the extraction boundary and
-project-wide codegraph identity. Do not register the same repo module name under
-another date; refresh it through its existing date/module selector.
-
-When the user has already provided a path, describe the current interpretation
-and use the CLI date default:
-
-```text
-I am treating this path as the source boundary:
-<path>
-
-If this path is one package/module, it will be registered under today's date
-and use refs such as repo:YYYYMMDD/<module>#...
-
-If this path contains multiple modules, I will show the detected tree and
-register each selected module under the same date. Knowledge paths stay stable:
-knowledge/codegraph/<module-name>/...
-
-Extraction will still run separately for each module.
-```
-
-Then ask for one of:
-
-- local code repo or package path;
-- remote Git repo URL plus pinned commit/ref and target package/subdir;
-- local document path;
-- Lark/Feishu document URL.
-
-Do not ask "what is the source name?" as the first or only question. Ask what
-they want the knowledge source to cover, then use the date default. For repo
-sources, ask which concrete module/package is being registered.
-
-Good user-facing wording:
-
-```text
-Next we need to add a knowledge source.
-
-If you only want a manual for the component package, choose that package
-directory as the source boundary, for example:
-batch: YYYYMMDD
-module: component-lib
-path: /repo/packages/component-lib
-
-The date is one batch, not one module. The concrete selector appears in refs
-and phases such as repo:YYYYMMDD/component-lib#... and
-extract:YYYYMMDD/component-lib:codegraph.
-
-One date can group multiple registered modules while knowledge omits the date:
-knowledge/codegraph/module-a/...
-knowledge/codegraph/module-b/...
-
-Extraction still runs per concrete module. If a path contains several packages,
-I will show the module tree first and register each chosen package under this
-same date before reading code.
-```
-
-Mention the CLI command only as an implementation detail after the user chooses
-a supported repo source.
-
-For a local repo source, ask for:
-
-- source boundary;
-- local repo or package/subdirectory path;
-- remote/ref only when not inferable or when the user wants an explicit pin.
-
-After the user provides the choice, run:
-
-```bash
-context source add repo [YYYYMMDD] --module <module> --local <repo-or-subdir>
-context source ensure [YYYYMMDD|YYYYMMDD/module]
-```
-
-For several repo/file/Lark modules confirmed in one request, prefer one batch
-payload instead of parallel commands:
-
-```yaml
-sources:
-  - type: repo
-    module: module-a
-    local: ../monorepo/packages/module-a
-  - type: repo
-    module: module-b
-    local: ../monorepo/packages/module-b
-  - type: lark
-    url: https://example.larksuite.com/wiki/example
-```
-
-```bash
-context source add batch [YYYYMMDD] --input <sources.yaml|json|-> --format json
-```
-
-The CLI validates batch identities, holds one project write lock, and writes
-registries atomically. It processes items in payload order. If a runtime item
-fails, the error reports completed items; fix it and rerun the same payload,
-because source registration is idempotent. Do not patch registry YAML manually.
-Repo items require `module`. File and Lark items may omit it; the CLI returns a
-derived lowercase path-safe module. If derived identities collide, provide
-explicit distinct modules and rerun the unchanged batch boundary.
-
-The repo batch must be a valid calendar date. The CLI rejects suffixes such as
-`YYYYMMDD-A`. A date-only `source ensure` or `source inspect` selector operates
-on every repo module registered in that batch; append `/module` to target one.
-If `--local` is absolute but the selected module and Context workspace belong
-to the same Git repository, expect the registry to store the Git root relative
-to the workspace plus `subpath`. The materialized source symlink also uses a
-relative target, so moving the repository as a unit keeps it valid. A source in
-a different Git repository may retain its absolute checkout root.
-
-Add `--remote` / `--ref` only when the user gave explicit values.
-
-For a remote Git repo source, ask for permission before clone/checkout. If the
-user approves, clone to an ignored local path, checkout the requested commit,
-then register that local checkout with `context source add repo`. Do not commit
-cloned source content.
-
-For local Markdown/MDX document sources, after the user confirms the boundary, run:
-
-```bash
-context source add file [YYYYMMDD] --module <module> --local <file-or-folder>
-```
-
-The date is the batch and the module is the concrete document boundary. Multiple
-file modules may share one date. `--module` may be omitted when the CLI-derived
-path slug is adequate; do not stop merely because another document already uses
-today's date.
-
-Default file capture handles Markdown. If `context source add file`,
-`context source inspect`, `context status`, or capture output reports that the
-source looks like an MDX documentation site, stop at the source boundary gate
-and ask the user to confirm that interpretation before changing `src/index.ts`.
-For MDX documentation sites that use `_meta.json` route metadata, declare
-`captureFile({ source: source("<date>", "<module>", { type: "file" }), processor: mdxJsonDocs() })` in
-`src/index.ts`; included `_meta.json` files are route metadata, and the CLI
-generates `__context_route_metadata.md` as mechanical route evidence. Use
-`--include` only when the approved boundary is narrower than the folder. For a
-long fixed batch, prefer `--include-list <file>` with one include per line;
-blank lines and `#` comments are ignored. Then explain that the next operation
-reads the approved document files and writes sibling files in one date batch.
-The CLI manages their shared capture metadata. After the user confirms read permission, summarize the
-`src/index.ts` change or show an equivalent diff summary, and run the capture
-phase.
-Apply [skill-source-scope/references/capture-source.md](skill-source-scope/references/capture-source.md) for route
-selection, dependency recovery, output handling, and final reporting, using the
-current capture phase command returned by `context status`.
-
-For Lark/Feishu document sources, register every requested document under the
-same date batch but do not fetch content
-with ad hoc scripts. Explain which remote document or wiki token will be read,
-that each document is written under `sources/lark/YYYYMMDD/` beside the other documents in that date batch, that one shared `manifest.json` tracks them, that committed
-snapshots enable offline verify and fresh-clone reproduction, that whether to
-add extra ignore rules is a business repository decision, and that access
-credentials are not written to the workspace. Use the declared capture/align
-flow only after the user confirms remote reading. After declaring
-`captureLark({ source: source("<date>", "<module>", { type: "lark" }) })`, summarize the `src/index.ts`
-change or show an equivalent diff summary.
-When the user adds more documents to an already confirmed batch and says they
-belong together, inherit the confirmed mainline collection and read permission
-for those explicitly supplied URLs. Register and declare all modules before
-capture; do not ask for another date name or repeat the same collection gate.
-If `context status --format json` returns multiple items in
-`routing.command_plan` while state is `needs-capture`, run every
-`after-human-confirmation` item in order after the current conversation contains
-permission. After one module completes, status should retain only the
-uncaptured modules; do not reopen the batch boundary gate between them.
-Apply [skill-source-scope/references/capture-source.md](skill-source-scope/references/capture-source.md) for route
-selection, dependency recovery, output handling, and final reporting, using the
-current capture phase command returned by `context status`.
-
-### Step 2 — Handle Monorepos
-
-If a registered source may contain multiple packages, run:
-
-```bash
-context source inspect <date>/<module> --format json
-```
-
-Present the detected module/package paths from that CLI output as a tree. Explain
-the choices without exposing internal API names first:
-
-- register each chosen package/subdirectory as a module in the current date
-  batch;
-- extraction, Review, and verification remain independent per concrete module.
-
-Wait for the user to choose. If the user chooses `packages/button`, register it
-as another module in the same date batch:
-
-```bash
-context source add repo <date> --module button --local <repo>/packages/button
-```
-
-Do not model a monorepo package choice as `include: ["packages/button/src/**"]`
-on the parent source.
-
-### Step 3 — Review Captured Document Summary
-
-When status is `captured-ready-to-investigate`, or after a capture phase
-completes, do not immediately create draft pages or compile actions. Present
-the capture summary first:
-
-- document count;
-- title tree, heading tree, or source span distribution from the CLI output;
-- available reading budget and evidence views;
-- flat document path under `sources/file|lark/YYYYMMDD/` and the date-level `manifest.json`;
-- the fact that approved pages are planned through
-  `unapproved/structure.yaml` before compile;
-- whether the source is local file/folder evidence or Lark/Feishu evidence.
-
-Then explain the next semantic gate in user-facing terms:
-
-```text
-The source body has been captured into a committed snapshot.
-
-Next we investigate the material and propose a structure draft:
-- which knowledge pages should exist;
-- which source spans support each section;
-- which relationships are supported by evidence;
-- what remains unresolved or weak.
-
-No approved Markdown is written at this point. Compile can start only after the
-structure is validated and you confirm it.
-```
-
-If the user wants to influence the shape before the Agent drafts it, ask a
-small semantic question with host-native multi-choice support when available:
-
-- Continue material investigation and propose a structure draft.
-- First add a reference structure or preference, such as expected domains,
-  page naming, or relationship focus.
-- Narrow or correct the captured source before planning.
-
-Do not use SDK factory names as user-facing option labels. If the user asks for
-one page per source document, represent that as a degenerate structure draft
-and still route through structure confirmation plus compile. Then follow
-`skill-prose-align.md`.
-
-### Step 4 — Declare Extract And Review
-
-Read the SDK guide before editing:
-
-```text
-node_modules/@c4a/context/docs/guides/agent-dialogue.md
-node_modules/@c4a/context/docs/guides/agent-guide.md
-node_modules/@c4a/context/docs/reference/project-api.md
-```
-
-Before editing, explain the proposed extraction in product terms. Use wording
-like:
-
-```text
-The source is ready and resolves to one package/module.
-
-Proposed extraction:
-- read TypeScript/TSX files under `src/`;
-- include exported symbols such as components, functions, types, and props;
-- create draft candidates for human review;
-- write no approved Markdown until the review payload is applied.
-
-This skips files outside `src/` and non-exported/internal helpers. If you want
-docs, tests, examples, or internal APIs included, say that before extraction.
-
-I will first generate a preview without writing candidates. The preview will
-show counts plus the planned `knowledge/` tree.
-```
-
-Only after the user confirms this product-level scope, declare the chosen repo
-module with `source("YYYYMMDD", "<module>")`, add the TypeScript extraction phase, and add
-the human review phase. Use `include` only for a file-level filter within the
-chosen source boundary. If the package has no standard detected entry, keep the
-source repository unchanged and ask whether its intended knowledge surface is:
-
-- a public API graph rooted at specific files — configure source-relative
-  `entries` that are also matched by `include`; or
-- all declarations in the matched files — configure `mode: "scan"`, which uses
-  no entries and includes internal symbols by default.
-
-Mention the internal API names only in code-change summaries, or when the user
-asks for implementation details.
-
-When the user confirms several modules as one extraction round, declare all of
-their source-specific extract phases before writing candidates. Preview every
-phase first, summarize the combined scope once, and ask for one scope
-confirmation for that round.
-
-### Step 5 — Show The Pre-extraction Preview
-
-Before real extraction, run the CLI no-write preview:
-
-```bash
-context run <extract-phase-id> --dry-run --format json
-```
-
-Show the user:
-
-- resolved source and module/package list;
-- discovered, AST-analyzed, skipped, symbol, relation, and candidate estimate
-  counts, including each skipped reason;
-- `knowledgeTree`;
-- several `knowledgePathExamples`.
-
-Explain that approved pages will land under paths derived from collection,
-containment, and slug; NodeRef/ViewRef are identity fields, not path strings:
-
-```text
-knowledge/<collection>/<containment>/<slug>.md
-```
-
-If date batch, module name, module list, candidate estimate, or path shape is
-not what the user expects, stop and repair the source boundary or module registration
-before extraction.
-
-For code sources, `knowledge/codegraph/<module>/...` is the expected shape;
-the date remains in source refs and phase ids. An additional repeated package segment below `<module>` may indicate an
-over-broad boundary; stop if the preview shows that unexpectedly.
-
-Do not present this as a CLI option or as "Context default options" to the
-user. Present it as the actual proposed knowledge impact: code area read,
-exported-symbol policy, candidate count, and final path shape. The user-facing
-phrase is "preview without writing".
-
-### Step 6 — Run Extraction Only After Scope Is Clear
-
-If the user already confirmed the exact source/scope and the no-write preview
-matches it, run:
-
-```bash
-context run <extract-phase-id>
-```
-
-Read the structured result before routing. A codegraph phase that produces
-candidates returns `continue-codegraph-batch` with `human_gate=false`; run the
-returned status command and continue any remaining confirmed extract phases.
-Only when status has no `pendingExtractPhases` and returns `needs-review` should
-the Agent open one collection-level Codegraph Review. The first round includes
-all candidates across the confirmed modules; later rounds include only
-added/updated/removed symbols, while unchanged approved symbols stay approved.
-Do not open Review after each module.
-
-Only when the user explicitly requests a non-interactive CI/CD codegraph sync,
-run:
-
-```bash
-context run <extract-phase-id> --auto-promote --format json
-```
-
-This applies deterministic codegraph deltas, refreshes deterministic close when
-needed, and verifies the result. Read `autoPromotion.close` and
-`autoPromotion.verify`; a nonzero exit or close/verification issue is a pipeline
-failure. Run `context build` separately when the pipeline publishes packages.
-Never use `--auto-promote` for prose or semantic collections.
-
-If the preview reports modules outside the confirmed source boundary, do not
-run extraction. Ask the user to choose the corrected source boundary.
-
-### Step 7 — Self-verify Checklist
-
-- [ ] Source choice came from the user, not inference. If not, return to
-  **Step 1**.
-- [ ] Monorepo package selection is represented as source boundary. If not,
-  return to **Step 2**.
-- [ ] Captured document summary was shown before structure/compile. If not, return to
-  **Step 3**.
-- [ ] No-write tree/path preview was shown before first real extraction. If not,
-  return to **Step 5**.
-
-</procedures>