@c4a/context-cli 0.6.0-beta.5 → 0.6.0-beta.7

package/plugin/skills/skill-source-scope/SKILL.md

@@ -21,24 +21,21 @@ Choose and validate what may become draft knowledge.
   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. Do not invent semantic source names from paths, filenames, or source
-  body content. By default, omit the source name and let the CLI use today's
-  date (`YYYYMMDD`) as the source namespace. Explain that this namespace appears
-  in source refs, phase ids, and package naming; approved knowledge paths are
-  derived later from collection, containment, and slug.
-- If the default date source name already exists, stop and ask the user which
-  explicit date name to use. Do not auto-append sequence numbers and do not
-  summarize the source theme as a fallback.
+  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, one source may conceptually be the whole repo/subspace or one
-  package/subdirectory. If the user wants one package manual, prefer the
-  package/subdirectory. If the user wants one unified knowledge product across
-  modules, explain that the date source namespace can be used in codegraph
-  NodeRefs when extraction rules derive grouped refs. Current repo extraction
-  still requires choosing a concrete single-module extraction boundary before
-  running extraction; do not run extraction against an ambiguous multi-module
-  source.
+- 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
@@ -51,10 +48,18 @@ Choose and validate what may become draft knowledge.
   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 <source-name> --format json` for module choices.
+- 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.
+- 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`,
@@ -62,6 +67,13 @@ Choose and validate what may become draft knowledge.
 - 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
@@ -83,11 +95,11 @@ 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 | knowledge boundary and local repo path | Register with `context source add repo --local <path>` unless the user explicitly provides a date source name. CLI records git root + optional `subpath`; `sources/repo/YYYYMMDD` becomes an ignored symlink to the chosen repo/subdir view. |
-| Local monorepo package/module | whether the source is the whole repo/subspace or one package/subdir; chosen path | Register the chosen boundary as the repo source. If the user wants one package manual, register that package/subdir. If the user wants a unified subspace manual, register the subspace. Do not use `extractTs.include` as a package selector. |
+| 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 | document boundary, local path, include glob or include-list if needed, and permission to read the source body | Register with `context source add file --local <path>`, declare the matching capture phase, then hand off to material investigation and structure drafting after capture. Do not run capture before the user confirms read permission. |
-| Lark / Feishu document | document URL/token, intended collection, and permission to read remotely | Register with `context source add lark` plus exactly one of `--url`, `--doc-token`, or `--wiki-token`; declare the matching capture phase, then hand off to material investigation and structure drafting after capture. Explain that capture writes a committed snapshot under `sources/lark/YYYYMMDD/`, supports offline verify/fresh clone reproduction, and does not write credentials. Do not fetch through ad hoc scripts. |
+| 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, intended collection, 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. |
 
 When asking for a document mainline collection, do not ask only "which
 collection?". Explain every available option in product language:
@@ -118,34 +130,30 @@ knowledge source. Use the user's language and explain that this is a boundary
 choice:
 
 ```text
-You are choosing what one source means for this knowledge workspace.
-The date source name becomes part of source refs and phase ids. Approved knowledge
-paths are derived later from collection, containment, and slug. NodeRef and
-ViewRef are identity fields, not path strings.
+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/YYYYMMDD/...
-repo:YYYYMMDD#symbol:...
-capture:file:YYYYMMDD
-dist/YYYYMMDD-kb/
+knowledge/codegraph/<module>/...
+repo:YYYYMMDD/<module>#symbol:...
 
 If the source is one document source:
 knowledge/architecture/entity/example.md
-file:YYYYMMDD/getting-started.md#span:...
-align:file:YYYYMMDD:architecture
-dist/YYYYMMDD-kb/
-
-If the source is a parent monorepo/subspace namespace, later multi-module
-outputs can be shaped like:
-knowledge/codegraph/YYYYMMDD/component-web/...
-knowledge/codegraph/YYYYMMDD/component-lynx/...
+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/...
 ```
 
-If the source already points at one package/module root, the source namespace
-is still the date name. An extra module/package segment is only expected when
-the chosen source boundary intentionally covers multiple modules. In the
-current workflow, treat that parent source as a planning/inspection boundary
-first; choose a concrete package/subdirectory source before real extraction.
+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:
@@ -154,17 +162,14 @@ and use the CLI date default:
 I am treating this path as the source boundary:
 <path>
 
-If this path is one package/module, the date source name will be used in
-source refs such as repo:YYYYMMDD#...
+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 is a parent monorepo/subspace that contains multiple modules, the
-date source name becomes the parent source namespace for grouped codegraph NodeRefs
-when extraction derives those refs:
-knowledge/codegraph/YYYYMMDD/<module-name>/...
+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>/...
 
-For the current extraction flow, a multi-module parent source is used for
-inspection/planning first. Before reading code, we still need a concrete
-package/subdirectory boundary.
+Extraction will still run separately for each module.
 ```
 
 Then ask for one of:
@@ -175,9 +180,8 @@ Then ask for one of:
 - 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. Ask for an
-explicit date name only when today's source name already exists or the user
-asks to override it.
+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:
 
@@ -186,27 +190,21 @@ 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:
-name: YYYYMMDD
+batch: YYYYMMDD
+module: component-lib
 path: /repo/packages/component-lib
 
-If you want one manual for the whole subspace, choose the subspace root:
-name: YYYYMMDD
-path: /repo/subspaces/product-ui
-
-The date name is not just a label. It will appear in source refs such as
-repo:YYYYMMDD#... and in phase ids such as extract:YYYYMMDD:codegraph.
-Approved paths are derived from collection, containment, and slug. NodeRef and
-ViewRef are identity fields, not path strings.
+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.
 
-For a unified subspace package shape, the date source name
-lets the output group child modules under that namespace:
-knowledge/codegraph/YYYYMMDD/component-web/...
-knowledge/codegraph/YYYYMMDD/component-lynx/...
+One date can group multiple registered modules while knowledge omits the date:
+knowledge/codegraph/module-a/...
+knowledge/codegraph/module-b/...
 
-Current extraction can inspect a parent source, but it should extract from a
-confirmed single package/subdirectory source. If this path is a parent source,
-I will show the module tree first and ask which package(s) to use before
-reading code.
+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
@@ -221,10 +219,46 @@ For a local repo source, ask for:
 After the user provides the choice, run:
 
 ```bash
-context source add repo --local <repo-or-subdir>
-context source ensure
+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
@@ -235,40 +269,52 @@ cloned source content.
 For local Markdown/MDX document sources, after the user confirms the boundary, run:
 
 ```bash
-context source add file --local <file-or-folder>
+context source add file [YYYYMMDD] --module <module> --local <file-or-folder>
 ```
 
-Use an explicit `<name>` only when the user has approved a non-default date
-source name. Otherwise run `context source add file --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-name>"), processor: mdxJsonDocs() })` in
+`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 a committed snapshot under
-`sources/file/YYYYMMDD/`. After the user confirms read permission, summarize the
+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 [references/capture-source.md](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 the source but do not fetch content
+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 the snapshot is written under `sources/lark/YYYYMMDD/`, that committed
+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-name>") })`, summarize the `src/index.ts`
+`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 [references/capture-source.md](references/capture-source.md) for route
 selection, dependency recovery, output handling, and final reporting, using the
 current capture phase command returned by `context status`.
@@ -278,23 +324,21 @@ current capture phase command returned by `context status`.
 If a registered source may contain multiple packages, run:
 
 ```bash
-context source inspect <source-name> --format json
+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:
 
-- for the current executable flow, register one package/subdirectory as its
-  own source when the user wants a focused package manual;
-- if the user is designing a unified subspace knowledge base, keep the
-  date source namespace as the namespace decision, but do not run extraction
-  until the concrete module extraction boundary is confirmed.
+- 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 a separate source such as:
+as another module in the same date batch:
 
 ```bash
-context source add repo --local <repo>/packages/button
+context source add repo <date> --module button --local <repo>/packages/button
 ```
 
 Do not model a monorepo package choice as `include: ["packages/button/src/**"]`
@@ -309,7 +353,7 @@ the capture summary first:
 - document count;
 - title tree, heading tree, or source span distribution from the CLI output;
 - available reading budget and evidence views;
-- snapshot path under `sources/file|lark/YYYYMMDD/`;
+- 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.
@@ -371,8 +415,8 @@ 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 date
-source with `source("YYYYMMDD")`, add the TypeScript extraction phase, and add
+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:
@@ -385,6 +429,11 @@ source repository unchanged and ask whether its intended knowledge surface is:
 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:
@@ -408,14 +457,13 @@ containment, and slug; NodeRef/ViewRef are identity fields, not path strings:
 knowledge/<collection>/<containment>/<slug>.md
 ```
 
-If date source name, package name, module list, candidate estimate, or path shape is
-not what the user expects, stop and repair the source boundary or explicit date name
+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 a single-module code source, a repeated path like
-`knowledge/codegraph/<date-source-name>/<package-name>/...` is usually a schema
-problem or a wrong source boundary. Stop before extraction if the preview shows
-that shape unexpectedly.
+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,
@@ -431,10 +479,14 @@ matches it, run:
 context run <extract-phase-id>
 ```
 
-Read the structured result before routing. For codegraph, the first run returns
-all code candidates with `next_action.human_gate=true`; later runs return only
+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.
-If `next_action.human_gate=false`, do not open Review and continue with status.
+Do not open Review after each module.
 
 Only when the user explicitly requests a non-interactive CI/CD codegraph sync,
 run:
@@ -443,9 +495,17 @@ run:
 context run <extract-phase-id> --auto-promote --format json
 ```
 
-This applies deterministic codegraph deltas and verifies them. A nonzero exit or
-verification issue is a pipeline failure. Never use `--auto-promote` for prose
-or semantic collections.
+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 an upgraded workspace reports `approved-source-ref-ambiguous` for pre-file-aware
+beta.5 codegraph refs, preserve the existing approval decisions. Rerun the
+declared codegraph extraction phase to produce the current file-aware symbol
+index, then run `context review migrate-codegraph-refs` and `context verify`.
+Tell the user this is evidence metadata migration and does not reopen Review.
 
 If the preview reports modules outside the confirmed source boundary, do not
 run extraction. Ask the user to choose the corrected source boundary.

package/plugin/skills/skill-source-scope/references/capture-source.md

@@ -13,14 +13,27 @@ tools:
 Current capture discipline for document sources. The executable path is source
 registration plus the declared capture phase flow:
 
-- local Markdown/MDX file source: `context source add file --local <path>`
-  followed by `context run capture:file:<source-name> --format json`;
-- Lark/Feishu source: `context source add lark ...` followed by
-  `context run capture:lark:<source-name> --format json`;
+- local Markdown/MDX file source: `context source add file [YYYYMMDD] --module <module> --local <path>`
+  followed by `context run capture:file:YYYYMMDD/<module> --format json`;
+- Lark/Feishu source: `context source add lark [YYYYMMDD] --module <module> ...`
+  followed by `context run capture:lark:YYYYMMDD/<module> --format json`;
 - refresh: rerun the same declared capture phase after status or the user asks
   for recapture.
 
 Use only commands surfaced by the current status output or capture phase.
+For a user-confirmed multi-document batch, `context status --format json`
+returns every uncaptured module in `routing.command_plan`. Run the complete
+list in order; a successful module is omitted from the next status result.
+When the user explicitly asks to capture, ingest, fetch, read, or include exact
+file/Lark paths or URLs, that request is the read permission for those sources;
+do not repeat the question after registration. A mere mention, possible-source
+discussion, or register-only request is not permission, and an explicit refusal
+always wins.
+Register several file/Lark/repo sources with `context source add batch [date]
+--input <yaml|json|->`; do not launch multiple `source add` processes in
+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.
 
 ---
 
@@ -53,8 +66,9 @@ Before choosing a local Markdown capture route, honor the surrounding task conte
 
 - One or more local `.md` / `.mdx` files or a local documentation folder to ingest →
   register one file source with the user-confirmed boundary:
-  `context source add file --local <file-or-folder>`. The CLI returns the date
-  source name (`YYYYMMDD`) to use in project phases. For an explicit
+  `context source add file [YYYYMMDD] --module <module> --local <file-or-folder>`.
+  The CLI returns the `YYYYMMDD/module` identity to use in project phases. More
+  than one file module may share the date. For an explicit
   batch inside a broader folder, preserve the user's include list on source
   registration. Default file capture handles `.md`. If the CLI reports
   document-site files such as `.mdx`, `_meta.json`, sidebars, or docs config,
@@ -66,15 +80,17 @@ Before choosing a local Markdown capture route, honor the surrounding task conte
   `__context_route_metadata.md` as mechanical route evidence; it also extracts
   static MDX component props/children into `__context_mdx_component_text.md`
   when components carry user-facing text. Declare
-  `captureFile({ source: source("<source-name>"), processor: mdxJsonDocs() })`, then
-  run `context run capture:file:<source-name> --format json`. If the selected MDX page
+  `captureFile({ source: source("<date>", "<module>", { type: "file" }), processor: mdxJsonDocs() })`, then
+  run `context run capture:file:<date>/<module> --format json`. If the selected MDX page
   is empty or only mounts runtime-rendered content, tell the user that capture
   found a document-site shell and ask for the rendered-site or data-source
   boundary instead of inventing body text.
 - A Lark/Feishu URL, doc token, or wiki token → register one Lark source:
-  `context source add lark --url <url>` or the matching token flag.
-  Declare `captureLark({ source: source("<source-name>") })`, then run
-  `context run capture:lark:<source-name> --format json`.
+  `context source add lark [YYYYMMDD] --module <module> --url <url>` or the
+  matching token flag. Register every requested document under the same date;
+  do not ask for `YYYYMMDD-2`. Declare
+  `captureLark({ source: source("<date>", "<module>", { type: "lark" }) })`,
+  then run `context run capture:lark:<date>/<module> --format json`.
 - 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.
@@ -99,7 +115,11 @@ registration; do not read file bodies before capture permission is clear.
 Report the CLI output verbatim. If the CLI reports `N sources changed`, suggest the right next step:
 
 - Run `context status --format json` and use its `state`, `routing`, and
-  `next_commands`.
+  `command_plan`; if status returns `needs-capture-phase`, first perform the
+  exact `routing.configuration` edit and rerun status.
+- While status remains `needs-capture`, execute every returned capture command
+  for the already confirmed batch before asking another naming, collection, or
+  read-permission question.
 - If status reports `captured-ready-to-investigate`, suggest the returned
   `context run align:<type>:<source>:<collection> --view read-plan --format json`
   command and hand off to `skill-prose-align`.

package/plugins/VERSION

@@ -1 +1 @@
-0.6.0-beta.5
+0.6.0-beta.7

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "context",
   "description": "Maintain a project-local knowledge workspace through init and next-step agent guidance.",
-  "version": "0.6.0-beta.5",
+  "version": "0.6.0-beta.7",
   "author": {
     "name": "c4a"
   },

package/plugins/claude/skills/skill-continue-workflow/SKILL.md

@@ -24,6 +24,10 @@ Continue an existing Context workspace from its current state.
   workflow; do not treat the host repository root as the workspace.
 - There is no `context continue` CLI command. Start with `context status`.
 - `context status` and CLI diagnostics are the source of truth.
+- Inspect `declarationGraph` and `configurationGaps`. Before structure
+  confirmation they are configuration warnings; after confirmation, a missing
+  compile route is a hard gate. Never substitute a compile phase from another
+  collection.
 - Execute safe mechanical `next:` steps; stop at semantic choices and human
   gates.
 - Delegate source/scope decisions to
@@ -65,6 +69,10 @@ Capture phases are not safe mechanical commands by default. `capture:file:*`
 and `capture:lark:*` read local or remote source bodies and update committed
 snapshots, so they require the source read-permission gate unless the current
 turn already contains explicit user confirmation for that exact source.
+An explicit request to capture, ingest, fetch, read, or include the exact
+file/Lark path or URL is that confirmation; do not ask again after registration.
+Mere mention, source discussion, or a register-only request is not confirmation,
+and an explicit refusal always overrides inferred permission.
 
 ## Human Gates
 
@@ -117,10 +125,20 @@ do not forward a long raw transcript unless requested.
 
 ### Step 2 — Route The State
 
-1. If status says `missing-source` or `needs-capture`,
+1. If status says `missing-source`, `needs-capture-phase`, `needs-capture`,
+   `needs-extract-phase`, or `ready-to-extract`,
    source boundary/name is unclear, source scope is unclear, or an extract
    phase needs first-run scope confirmation, follow
    `${CLAUDE_PLUGIN_ROOT}/skills/skill-source-scope/SKILL.md`.
+   When `routing.configuration` is present, make only that declared project
+   configuration change and rerun status. Otherwise follow
+   `routing.command_plan`: run `immediate` items directly and wait for current-
+   conversation confirmation before `after-human-confirmation` items.
+   For mixed sources, status intentionally returns `ready-to-extract` before
+   `captured-ready-to-investigate` while all document snapshots are captured,
+   document structure is untouched, and code extraction is missing, pending,
+   or stale. Explain that code is processed first, then follow the exact
+   extraction preview/rerun command.
 2. If status says `captured-ready-to-investigate` or `needs-structure`, or the
    user asks to split, merge, classify, relate, or semantically organize
    document evidence before draft pages exist, follow
@@ -129,7 +147,9 @@ do not forward a long raw transcript unless requested.
    to turn confirmed structure into source-bound draft pages, follow
    `${CLAUDE_PLUGIN_ROOT}/skills/skill-prose-compile/SKILL.md`.
 4. If the latest phase result has `next_action.human_gate=false`, follow its
-   command and do not invent a Review gate. If status says
+   command and do not invent a Review gate. This includes
+   `continue_compile_batch` and `continue-codegraph-batch`: finish the whole
+   prepared round first. If status says
    `compile-ready-for-review`, or the latest result has
    `next_action.human_gate=true`, follow
    `${CLAUDE_PLUGIN_ROOT}/skills/skill-review-gate/SKILL.md`.
@@ -173,3 +193,7 @@ usable; inspect generated package structure when package output is involved.
   conclusion and use the CLI view.
 
 </procedures>
+If top-level `state`, `next`, or `routing.command_plan` contradicts
+`draftCandidates`, `pendingReview`, `close.state`, package freshness, or verify
+counts, stop instead of rerunning a completed phase. Report
+`status-route-conflict` and preserve the detailed status output for diagnosis.