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

package/plugins/codex/skills/continue/references/internal-procedures/skill-prose-align/references/internal-procedures/structure-planning.md

@@ -216,8 +216,10 @@ material to `unresolved[]`.
 
 For pure suggested-split repairs, prefer the CLI repair view before hand-editing:
 `context run align:<type>:<source>:<collection> --repair suggested-splits --input <structure.yaml> --format json`.
-It only rewrites section ids/source_refs inside the same view. It does not
-create child nodes/views or decide semantic regrouping for you.
+It splits non-contiguous Section mirrors. Oversized Views still require the
+Agent to apply the returned child-View and contains-edge suggestions while
+classifying every child Node from evidence. The repair command does not resolve
+orphan ownership, unsupported evidence, or competing semantic groupings.
 
 When the cited source sentence itself is uncertain, preserve that uncertainty on
 the edge with `confidence: possible` or `confidence: hypothesis`. This is only
@@ -251,7 +253,7 @@ There is no parallel candidate-body authoring path. Emit only the
 
 ### Step 6 — Validate And Submit
 
-Before staging, run `context run align:<type>:<source>:<collection> --validate --input - --format json` with the `context.structure.v1` payload. If validate returns blocking diagnostics, repair the exact paths it reports and rerun validate. After validation, show the structure to the user with the structure summary, `structure_report.file_url`, and `structure_report.absolute_path`. If validation returns `confirmation_blockers[]` or `will_block_confirmation`, repair those blockers before asking the user to confirm. If you stage a draft structure first, the stage result is still a human review gate: show the returned report link/summary and ask the user to inspect it before confirming. Only write `lifecycle.state: confirmed` only after explicit confirmation; then run `context run align:<type>:<source>:<collection> --confirm --format json` or pass an explicit file with `--confirm --input <structure.yaml> --format json`.
+Before staging, run `context run align:<type>:<source>:<collection> --validate --input - --format json` with the `context.structure.v1` payload. If validate returns `repair_confirmation_blockers`, follow its repair route and rerun validate without asking for preliminary approval. `--repair suggested-splits` handles non-contiguous source mirror Sections. For oversized Views, apply the returned child-View and contains-edge suggestions while classifying child Nodes from evidence. Resolve other blockers from evidence; ask the user only when evidence supports multiple incompatible semantic choices, and state that this is not final review. Stage only after `confirmation_ready=true`. The stage result opens the final HTML report and is the human review gate: show the structure to the user through `structure_report.file_url`, `structure_report.absolute_path`, and the compact summary before asking for confirmation. Only write `lifecycle.state: confirmed` only after explicit confirmation; then run `context run align:<type>:<source>:<collection> --confirm --format json` or pass an explicit file with `--confirm --input <structure.yaml> --format json`.
 
 After stage succeeds, do not rerun the same write command to confirm success.
 Use `context status --format json` or the returned result for read-only

package/plugins/codex/skills/continue/references/internal-procedures/skill-prose-align.md

@@ -24,16 +24,17 @@ Turn captured document evidence into confirmed structure.
 - Write and validate `context.structure.v1` into `unapproved/structure.yaml`.
   Stop for user confirmation before compile.
 - Before classifying nodes, section plans, edges, support strength, duplicates,
-  conflicts, ownership, or unresolved items, read the current procedure
-  references listed by the CLI as `semantic_reference_files`. These references
-  are the current structure judgment rules, not summaries.
+  conflicts, ownership, or unresolved items, read only the procedure references
+  in the CLI `semantic_rules.required` set. Use each returned `reason` to keep
+  unrelated rules out of the current judgment.
 - Plan source evidence as Sections before promoting any heading to a Node/View.
   Local FAQ, decision, incident, warning, or reference fragments normally stay
   under the owning View unless source evidence proves independent retrieval
   identity.
-- Do not produce or validate a structure payload from this entry file alone. If
-  the relevant `semantic_reference_files` have not been read in the current
-  turn, stop and read them first.
+- Do not produce or validate a structure payload from this entry file alone. A
+  ruleset already present in the active context may be reused only when both its
+  `handle` and `digest` match. If the context was compacted, the digest changed,
+  or the rule content is no longer present, read `semantic_rules.required`.
 - When status reaches `structure-ready` or `needs-prose-compile`, hand off to
   `skill-prose-compile.md`.
 - Compile, review, close, verify, and build remain separate gates.
@@ -54,7 +55,7 @@ Use semantic labels, not SDK function names:
 
 Use these rules in the current phase-runner flow:
 
-- Follow the top-level state, `routing.next_commands`, CLI `next_action`, and
+- Follow the top-level state, `routing.command_plan`, CLI `next_action`, and
   CLI-returned `next_command` values for every write. Treat `allowed_actions[]`
   as permission for read-only insertions; it is not a menu of alternate write
   paths.
@@ -200,9 +201,12 @@ context run align:<type>:<source>:<collection> --validate --input <structure.yam
 ```
 
 Validation returns `structure_summary` and writes a temporary HTML report under
-`.tmp/context-runtime/reports/`. Use `structure_report.file_url` as the primary
-user-facing link, and include `structure_report.absolute_path` as a copyable
-fallback. Do not ask the user to confirm a structure they cannot click or open.
+`.tmp/context-runtime/reports/`. A validation report with
+`confirmation_ready=false` is an Agent repair artifact, not a user review gate:
+do not ask the user to approve it. The staged report produced after
+`confirmation_ready=true` is the final review surface; use its
+`structure_report.file_url` as the primary user-facing link and include
+`structure_report.absolute_path` as a copyable fallback.
 If the user needs a focused view, run:
 
 ```bash
@@ -225,14 +229,21 @@ Repair diagnostics by routing them to the right decision:
   structure or keep the relation unresolved;
 - stale structure -> regenerate from the current snapshot hash.
 
-When validation returns a new `next_action.command`, follow that exact command.
-When it returns blocking diagnostics without a write command, repair and
-validate again. Do not stage a structure just because the YAML shape looks
-valid.
+When validation returns `repair_confirmation_blockers`, follow its exact repair
+route without stopping for human confirmation. `--repair suggested-splits`
+mechanically splits non-contiguous source mirror Sections; write its
+`repaired_payload` to a scratch YAML file and validate again. For oversized
+Views, use the returned child-View and contains-edge suggestions, but classify
+each child Node from evidence instead of mechanically inheriting the parent
+type. Repair other diagnostics from evidence and validate again. Ask the user only when evidence
+supports multiple incompatible semantic choices, and label that question as a
+structure-design choice rather than final review. Do not stage until
+`confirmation_ready=true`.
 
 ### Step 4 — Review Structure Before Confirmation
 
-After validation, and again after a draft structure is staged, show the user:
+After validation reports `confirmation_ready=true`, stage the draft. The stage
+command opens the final report. Then show the user:
 
 - node list and planned paths;
 - section ownership;
@@ -250,6 +261,12 @@ hard stop for structure review. Do not ask for a blind "confirm structure"
 reply. Surface the report `file_url`, absolute path, and enough structured
 summary for the user to inspect what will be confirmed.
 
+Do not turn `confirmation_blockers` into a preliminary approval round. A
+validator-required page split, continuous-source split, ref repair, or
+structure-spine connection is work to resolve before staging. If a genuinely
+ambiguous semantic choice needs the user, ask only that choice and then resume
+repair; it does not replace the final report-based confirmation.
+
 Use the host's multi-choice question tool when available. If unavailable, use a
 short Markdown fallback. Good options are:
 

package/plugins/codex/skills/continue/references/internal-procedures/skill-prose-compile.md

@@ -38,12 +38,13 @@ Compile confirmed document structure into reviewable draft knowledge.
   faithful mirrored continuous span, split the section or return to prose align
   for a confirmed structure change.
 - Before choosing section kind, summary, skip/update, weak-evidence handling, or
-  structure repair, read the current procedure references listed by the CLI as
-  `semantic_reference_files`. These are the migrated compile judgment rules, not
-  summaries.
-- Do not produce or validate compile actions from this entry file alone. If the
-  relevant `semantic_reference_files` have not been read in the current turn,
-  stop and read them first.
+  structure repair, read only the procedure references in the CLI
+  `semantic_rules.required` set. The CLI selects core and conditional rules for
+  the current node and explains each selection with `reason`.
+- Do not produce or validate compile actions from this entry file alone. A
+  ruleset already present in the active context may be reused only when both its
+  `handle` and `digest` match. If the context was compacted, the digest changed,
+  or the rule content is no longer present, read `semantic_rules.required`.
 
 <reference>
 
@@ -60,7 +61,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 +76,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
@@ -159,9 +163,10 @@ context run compile:<type>:<source>:<collection> --view node-context --source <v
 context run compile:<type>:<source>:<collection> --view schema --format json
 ```
 
-Read the compile references listed by `semantic_reference_files` before
+Read only the compile references listed by `semantic_rules.required` before
 classifying section kind, summary, support, skip/update, weak evidence, or
-structure repair.
+structure repair. Do not load the full rule inventory unless the CLI explicitly
+returns it as required.
 
 Do not treat those references as optional background. They are the current
 compile drafting, judgment, and semantic-repair procedures.
@@ -226,13 +231,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.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.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 +270,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/codex/skills/continue/references/internal-procedures/skill-review-gate.md

@@ -2,7 +2,7 @@
 name: skill-review-gate
 description: >
   Internal procedure invoked by the public Context continuation entry; not a user slash 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.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/codex/skills/continue/references/internal-procedures/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`.