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

package/plugins/cursor/skills/skill-prose-compile/SKILL.md

@@ -60,7 +60,7 @@ Use semantic labels, not SDK function names:
 
 ## Runtime Discipline
 
-- Follow `context status`, `routing.next_commands`, compile view
+- Follow `context status`, `routing.command_plan`, compile view
   `next_action`, and validation diagnostics. Treat CLI commands as the source
   of truth.
 - Use only the returned `next_action.command` for the next required write.
@@ -75,6 +75,9 @@ Use semantic labels, not SDK function names:
   views.
 - Run one write at a time. Do not parallelize compile stage, review apply,
   close, or build writes.
+- One write still means one View, not one human Review. Stage every View in the
+  same confirmed structure sequentially, follow `continue_compile_batch`, and
+  open Review only after the CLI reports that the whole batch is prepared.
 - Compile does not get a second, looser rule set. If a rule conflicts with the
   current CLI schema or diagnostics, follow the CLI and repair the payload.
 - Write digest/hash flags are stale guards. Use values returned by the CLI; do
@@ -226,13 +229,21 @@ Stage only after validation has no errors:
 context run compile:<type>:<source>:<collection> --stage --input <compile-actions.yaml> --format json
 ```
 
-After staging, return to `context status`. If status reaches
-`compile-ready-for-review`, delegate review to
-`../skill-review-gate/SKILL.md`.
+After staging, follow `next_action` exactly:
+
+- `continue_compile_batch` with `human_gate=false`: move to the returned next
+  View and repeat **Step 2–4**. Do not open Review yet.
+- `review_candidates` with `human_gate=true`: every planned View in this
+  confirmed structure is prepared; return to `context status`, then delegate
+  one collection-level Review to
+  `../skill-review-gate/SKILL.md`.
+
+The CLI blocks Review and close while confirmed Views remain unprepared. Do not
+turn sequential View writes into sequential user approvals.
 
 ### Step 5 — Close Handoff
 
-After review apply, return to `context status`. If status says
+After the single batch review apply, return to `context status`. If status says
 `compile-close-needed`, run deterministic close:
 
 ```bash
@@ -257,6 +268,7 @@ Then route to package output when status reaches `ready-to-build`.
   verbatim text.
 - [ ] No direct edits were made to `sources/`, `.tmp`, `unapproved/`,
   `knowledge/`, review HTML, or `dist/`.
+- [ ] Every planned View was staged before opening the one batch Review.
 
 ### Final Report
 

package/plugins/cursor/skills/skill-review-gate/SKILL.md

@@ -2,7 +2,7 @@
 name: skill-review-gate
 description: >
   Internal procedure invoked by the public Context continuation entry; not a user command.
-  Opens the review UI, waits for user decisions, applies copied JSONL payloads,
+  Opens the review UI, waits for user decisions, applies copied review decision Payloads,
   and prevents agent-authored approval/rejection decisions unless the user
   explicitly requests the scoped quick-decision path.
 tools:
@@ -19,13 +19,16 @@ Run the human review gate. The user decides approval or rejection.
 - Enter this skill only when the preceding command returns
   `next_action.human_gate=true`. A no-delta codegraph run returns false and does
   not need Review.
-- Use `context review html <collection> --open` for visual review.
+- For prose, enter only after every View in the confirmed compile batch is
+  prepared. For codegraph, enter only after all pending extract phases in the
+  confirmed module round are complete. The CLI blocks partial-batch Review.
+- Use `context review html <collection> --open --format json` for visual review.
 - `<collection>` is an internal production collection such as `architecture`,
   `sop`, `decision`, or `standards`; it is not an OKF package root such as
   `wikis`, `guides`, or `rules`.
 - Always surface the CLI-printed `file_url`. If browser opening fails or the
   host cannot make a path clickable, also provide `absolute_path`.
-- Apply only the JSONL payload copied by the user from the review UI.
+- Apply only the review decision Payload copied by the user from the review UI.
 - Do not parse `unapproved/entities.jsonl`, `.tmp`, or HTML internals with
   scripts to synthesize decisions.
 - If the user explicitly asks for quick or automated approval/rejection, use
@@ -34,7 +37,11 @@ Run the human review gate. The user decides approval or rejection.
   these commands still enforce the current scoped candidate-id gate.
 - `context run <extract-phase-id> --auto-promote` is a separate, explicit
   codegraph-only CI/CD policy. It may apply code add/update/remove deltas and
-  verify them without this gate; it never applies to semantic knowledge.
+  refresh deterministic close, and verify them without this gate; it never
+  applies to semantic knowledge. Package build remains an explicit later step.
+- `approved-source-ref-ambiguous` on beta.5 approved codegraph pages is an
+  evidence migration, not a new review decision. Rerun the declared codegraph
+  extraction, then run `context review migrate-codegraph-refs` and verify.
 
 <procedures>
 
@@ -43,12 +50,14 @@ Run the human review gate. The user decides approval or rejection.
 For the internal collection reported by status, run:
 
 ```bash
-context review html <collection> --open
+context review html <collection> --open --format json
 ```
 
-Tell the user where the page opened and include the CLI-printed `file_url` as a
-clickable link plus `absolute_path` as a copyable fallback. Do not assume a
-fixed review filename; review scope is collection or `--all`.
+Inspect the returned `opened` field. When it is `true`, tell the user the page
+was opened. When it is `false`, do not claim it opened; report `open_error` and
+provide `file_url` as the primary clickable link plus `absolute_path` as a
+copyable fallback. Do not drop `--open`, and do not assume a fixed review
+filename; review scope is collection or `--all`.
 Do not substitute OKF package roots (`wikis`, `guides`, `rules`) for this
 argument; review scope is the internal collection namespace.
 
@@ -60,7 +69,8 @@ must not choose these states.
 ### Step 2 — Wait For Payload
 
 Ask the user to review candidates in the HTML page, open Payload, copy the
-compact JSONL payload, and paste it into the agent chat. The payload records the
+compact review decision Payload, and paste it into the agent chat. Uniform
+decisions produce one JSON line; exceptions add JSONL lines. The Payload records the
 user's decisions, usually as a default decision plus exceptions, so it should
 not be expanded into pretty JSON unless the user asks.
 
@@ -68,7 +78,7 @@ The user should not need to create a payload file manually. Do not continue
 until the user supplies that payload.
 
 If the user instead explicitly asks the agent to use the quick approval or
-rejection path, do not synthesize JSONL. Run the scoped quick command with the
+  rejection path, do not synthesize a decision Payload. Run the scoped quick command with the
 candidate id shown by review/list/status and either `--collection <collection>`
 or `--all`.
 
@@ -91,6 +101,19 @@ commands to store this payload.
 Run `context status` after apply. If it reports package output choice, return to
 `../skill-continue-workflow/SKILL.md`.
 
+If status instead reports `approved-source-ref-ambiguous` for a pre-file-aware
+codegraph ref, explain that the user's decisions remain approved. Rerun its
+declared extraction phase to refresh the symbol index, then run:
+
+```bash
+context review migrate-codegraph-refs
+context verify
+```
+
+Do not reopen Review, synthesize another payload, delete approved pages, or
+filter conflicting symbols. If the ref is already file-aware, report a
+duplicate extract-index defect rather than running the metadata migration.
+
 ### Step 5 — Self-verify Checklist
 
 - [ ] Every decision came from the user's copied payload. If not, stop and

package/plugins/cursor/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.