@c4a/context-cli 0.6.0-alpha.1 → 0.6.0-beta.1

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

@@ -13,10 +13,10 @@ 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 <name> --local <path>`
-  followed by `context run capture:file:<name> --format json`;
-- Lark/Feishu source: `context source add lark <name> ...` followed by
-  `context run capture:lark:<name> --format json`;
+- 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`;
 - refresh: rerun the same declared capture phase after status or the user asks
   for recapture.
 
@@ -52,19 +52,29 @@ manager or version.
 Before choosing a local Markdown capture route, honor the surrounding task context. Driver documents such as run instructions, handbooks, READMEs, plans, feedback issues, corpus/index/manifests, and batch lists are not Context sources unless the user explicitly asks to ingest them. Capture only ingest targets that are already explicit in the user request; if they are missing, ask one clarification instead of capturing the driver document.
 
 - One or more local `.md` / `.mdx` files or a local documentation folder to ingest →
-  register one file source with the user-confirmed source name and boundary:
-  `context source add file <name> --local <file-or-folder>`. For an explicit
+  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
   batch inside a broader folder, preserve the user's include list on source
-  registration. Default file capture handles `.md`. For MDX documentation sites
-  that use `_meta.json`, declare `mdxJsonDocs()` on `captureFile` in
-  `src/index.ts`; keep `_meta.json` only when it is route metadata for the
-  selected document folder. It is captured as metadata, not body evidence.
-  Declare `captureFile({ source: source("<name>") })`, then run
-  `context run capture:file:<name> --format json`.
+  registration. Default file capture handles `.md`. If the CLI reports
+  document-site files such as `.mdx`, `_meta.json`, sidebars, or docs config,
+  stop and confirm whether the selected boundary is a documentation site before
+  changing capture configuration. For MDX documentation sites that use
+  `_meta.json`, declare `mdxJsonDocs()` on `captureFile` in `src/index.ts`;
+  keep `_meta.json` only when it is route metadata for the selected document
+  folder. The CLI captures it as metadata and generates
+  `__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
+  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 <name> --url <url>` or the matching token flag.
-  Declare `captureLark({ source: source("<name>") })`, then run
-  `context run capture:lark:<name> --format json`.
+  `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`.
 - 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.

package/plugins/VERSION

@@ -1 +1 @@
-0.6.0-alpha.1
+0.6.0-beta.1

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-alpha.1",
+  "version": "0.6.0-beta.1",
   "author": {
     "name": "c4a"
   },

package/plugins/claude/skills/skill-prose-align/SKILL.md

@@ -23,10 +23,14 @@ Turn captured document evidence into confirmed structure.
   and view set returned by the CLI.
 - Write and validate `context.structure.v1` into `unapproved/structure.yaml`.
   Stop for user confirmation before compile.
-- Before classifying nodes, section plans, edges, weak evidence, duplicates,
+- 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.
+- 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.
@@ -195,15 +199,23 @@ Validate:
 context run align:<type>:<source>:<collection> --validate --input <structure.yaml> --format json
 ```
 
-Validation returns `structure_summary` and writes a temporary
-`structure_report.path` under `.tmp/context-runtime/reports/`. Use those
-artifacts as the primary confirmation material; do not ask the user to confirm a
-structure they cannot inspect. If the user needs a focused view, run:
+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.
+If the user needs a focused view, run:
 
 ```bash
 context run align:<type>:<source>:<collection> --view structure-summary --input <structure.yaml> --format json
 ```
 
+The CLI response may include a large full `structure_summary` for debugging and
+report rendering. For user confirmation, prioritize the first-screen fields:
+`review_notice`, `structure_report`, and `structure_summary_compact`. A valid
+user-facing confirmation prompt must include the report `file_url`, the absolute
+path fallback, and a compact summary of collections/views/unresolved/diagnostics.
+Do not ask the user to confirm from counts alone.
+
 Repair diagnostics by routing them to the right decision:
 
 - source ref or snapshot mismatch -> reread evidence views or refresh capture;
@@ -228,13 +240,15 @@ After validation, and again after a draft structure is staged, show the user:
 - expected compile order;
 - downstream impact: these choices freeze paths, section ownership, and
   relationships for this compile round.
-- the `structure_report.path` generated by validate or `--view
-  structure-summary`.
+- the `structure_report.file_url` generated by validate or `--view
+  structure-summary`;
+- the `structure_report.absolute_path` fallback in case the host cannot click
+  file URLs.
 
 If the CLI stage result includes `next_action.human_gate: true`, treat it as a
 hard stop for structure review. Do not ask for a blind "confirm structure"
-reply. Surface the report path and enough structured summary for the user to
-inspect what will be confirmed.
+reply. Surface the report `file_url`, absolute path, and enough structured
+summary for the user to inspect what will be confirmed.
 
 Use the host's multi-choice question tool when available. If unavailable, use a
 short Markdown fallback. Good options are:

package/plugins/claude/skills/skill-prose-align/references/internal-procedures/structure-planning/references/gates.md

@@ -22,12 +22,10 @@ Answer in this order and stop at the first match:
 1. **Action?** A large executable event / process with both:
    - scale: can support `planned_sections` with at least two distinct Section kinds, or contains at least one child Action;
    - process evidence: explicit steps, phases, trigger -> handling -> result, role collaboration, or repeatable plan. Parallel lists such as "three API modes" are not process evidence.
-   Single-section exceptions are allowed only when the collection route and
-   source evidence give the record its own lifecycle or tracking identity:
-   product `user-story`, test `scenario`, or incident `action-item` /
-   incident record. These still need source-backed acceptance, lifecycle,
-   scenario, or tracking evidence; otherwise keep the material as a Section
-   under the owning Node.
+   Single-section user-story / scenario / incident records may be meaningful to
+   a human reader, but the CLI does not infer that exception from source prose.
+   If the structure cannot express at least two distinct Section kinds or a
+   child Action, keep the material as a Section under the owning Node.
 2. **Entity?** A concrete independent subject with retrieval value: deployable code, product/application/system, library/module/CLI/symbol, or an atomic term/pattern.
 3. **Domain?** A container/scope that groups at least one child Node.
 4. Otherwise do not create a Node; leave the material for compile as a Section under the owning Node.
@@ -75,6 +73,36 @@ scope/process suffixes.
 
 For no-write placeholder summaries, describe only the preserved page identity and unresolved navigation clues. Do not say the Node "provides navigation/links/relations to X" unless those targets are resolved graph children or rendered links; say the source contains deferred navigation clues instead.
 
+## Section Promotion Gate
+
+Classify local evidence as a Section before creating a child Node/View. A
+heading, table row, FAQ label, or short sub-topic does not by itself establish a
+standalone page.
+
+Promote a Section to a child View only when at least one condition is supported
+by source evidence:
+
+1. The title is a concrete product/code object/system/module/library, not just a
+   local heading.
+2. The item is an atomic term or pattern that answers standalone lookup
+   questions outside the parent page.
+3. The item clears the Action Gate or Domain Gate.
+4. The source gives it independent article identity: owner/date, lifecycle,
+   timeline, tracking record, or cross-cutting support scope.
+
+Hard repairs:
+
+| Pattern | Repair |
+|---|---|
+| One local Q&A under a product/system page | `faq` Section under the owning View |
+| One-off conclusion or trade-off note | `decision` Section under the owning View |
+| Warning/failure note without incident identity | `warning` or `incident` Section under the owning View |
+| Reference/link bucket with no body | `unresolved[]` or omit, not an Entity page |
+| Many same-source, single-section child Entities under one parent | Merge them into parent Sections unless each child has standalone lookup identity |
+
+The CLI treats section-like child Views as invalid unless the payload provides
+source-backed independent identity through the surrounding structure.
+
 ## Entity Tag Rules
 
 Use `tags` to state what the Entity is. Legal combinations:
@@ -88,6 +116,11 @@ Use `tags` to state what the Entity is. Legal combinations:
 
 `term` is mutually exclusive with A/B tags. React is `[lib]`, not `[lib, term]`; if a separate term entry is useful, create another Entity tagged `[term]` and let the structure plan express the relation as a typed edge or unresolved relation with `source_refs[]`.
 
+Do not inherit scope tags mechanically. If a parent Entity is tagged `system` or
+`application`, a child Entity should repeat that tag only when it is itself an
+independent system/application. Local aspects under that parent should either
+use their own shape tag or remain Sections.
+
 ## Action Gate
 
 Use `node_type: action` only after the Node Type Order says action. Fill the
@@ -105,7 +138,7 @@ bar is:
 | `is_repeatable_or_planned` | The work is repeatable, scheduled, policy-like, or intentionally planned. | May be inferred; record the source. |
 | `queries_answerable_with_refs` | The Node can answer how/when/who/what-to-do questions from cited spans. | May be inferred; record the source. |
 
-Do not emit an Action for a single sentence, a one-off conclusion, a short operation, or a parallel enumeration. Those become Sections under the owning Entity or Domain. The only single-Section Action exceptions are source-backed `user-story`, `scenario`, and incident/action-item records with lifecycle, acceptance, or tracking identity.
+Do not emit an Action for a single sentence, a one-off conclusion, a short operation, or a parallel enumeration. Those become Sections under the owning Entity or Domain. The CLI does not infer single-Section Action exceptions from source prose; represent the material with enough structure or keep it as a Section.
 
 Action anti-examples:
 
@@ -209,7 +242,7 @@ Each source must include `rationale` when inferred and at least one of `source_r
 ## Final Reflection
 
 - Entity cannot pick a legal tag, or depends on its upstream title to make sense -> write it as a Section under the upstream Node or change type before submit.
-- Action only supports one Section -> write it as a Section instead of an Action, unless it is a source-backed `user-story`, `scenario`, or incident/action-item record with lifecycle, acceptance, or tracking identity. The discriminator is scale or record identity, not the presence of "step" words.
+- Action only supports one Section -> write it as a Section instead of an Action, or add source-backed structure that reaches at least two distinct Section kinds / one child Action. The CLI does not use source prose keywords to grant an exception.
 - Action "steps" are parallel options/configs -> route to Entity `comparison` / `spec` / `description`.
 - Domain has no children -> delete it or merge it into a larger Domain.
 
@@ -225,11 +258,12 @@ checks as deterministic diagnostics:
 | `tags.term_conflict` | An Entity uses `term` together with concrete runtime/product tags such as `lib`, `service`, `application`, or `system`. | Split the term from the concrete object, or remove the conflicting tag before staging. |
 | `node.description_dominates` | A non-Action Node has at least half of its planned Sections as `description`. | Re-run kind precision. Keep it only when source evidence is genuinely narrative; otherwise split into `example`, `spec`, `comparison`, `faq`, `incident`, `decision`, `warning`, or `principle`. |
 | `node.thin_concrete_entity` | A concrete Entity has one Section and no child Nodes. | Keep it only when it has stable standalone retrieval value; otherwise merge it into the owning Node. |
+| `node.children_should_be_sections` | One parent contains many same-source, single-section child Entities with no stable shape tag. | Merge those children into parent Sections unless the user confirms each child has standalone lookup value. |
 | `node.term_expanded_beyond_definition` | A `term` Entity has grown past a compact definition or owns children. | Move rules, procedures, designs, and examples to the owning Node; keep the term entry narrow. |
-| `node.action_too_thin` | An Action has fewer than two distinct planned Section kinds and no child Action. | Downgrade it to a Section under the owning Node unless evidence supports a repeatable process or a source-backed `user-story`, `scenario`, or incident/action-item record with lifecycle, acceptance, or tracking identity. |
+| `node.action_too_thin` | An Action has fewer than two distinct planned Section kinds and no child Action. | Downgrade it to a Section under the owning Node, add a distinct Section kind, or add a child Action; the CLI does not infer a single-section exception from source text. |
 | `node.domain_without_children` | A Domain has no source-backed `contains` child edge. | Add supported children, keep an explicitly confirmed no-write placeholder, or reclassify the Node. |
+| `tags.child_inherits_system` | A child Entity repeats its parent `system` / `application` scope tag. | Retag by the child’s own shape/scope, or keep the child as a Section if it is only a local aspect. |
 | `edge.confidence_invalid` | An edge declares a confidence value outside the current schema. | Use only `possible` or `hypothesis`, or omit the field for source-certain relations. |
-| `edge.confidence_required` | The cited relation sentence contains source-level uncertainty such as "可能", "疑似", "may", or "might". | Preserve source-authored uncertainty with `confidence: possible` / `confidence: hypothesis`, or move the relation to `unresolved[]`. |
 
 Warnings are not automatic blockers, but they are not suggestions to ignore.
 Resolve them or include the user-confirmed rationale when confirming structure.

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

@@ -151,6 +151,24 @@ the shared evidence.
 
 Source titles and headings are ordinary evidence, not structural authority. Choose titles and summaries that fit the final Node type and the CLI-provided generation policy.
 
+Plan source material as Sections first. A source heading only becomes a child
+Node/View when the cited evidence names a concrete independent subject, an
+atomic term, a gated Action, or a child-bearing Domain. A `contains` edge only
+states hierarchy; it does not prove that a thin child page has standalone
+retrieval value.
+
+Avoid same-source fragmentation. If one parent would contain many single-section
+child Entities from the same source document, keep them as Sections unless each
+child has an independent product/code object, atomic term, Action, or Domain
+identity. Also avoid copying the parent `system` / `application` scope tag onto
+local child aspects; tag a child by what it independently is.
+
+Do not promote local support fragments into child pages. FAQ, decision, and
+incident snippets under an owning topic stay as `faq`, `decision`, or
+`incident` Sections unless the source proves an independent article, lifecycle,
+timeline, owner/date, or cross-cutting retrieval scope. The CLI will reject
+section-like child views before confirmation.
+
 For `node.title` and `node.summary`, follow the workspace/source language
 surfaced by the current view or the user's instruction. In Chinese workspaces,
 translate descriptive scaffold words such as architecture, strategy, lifecycle,
@@ -188,6 +206,19 @@ structure gate. Current compile writes approved knowledge by mirroring source
 spans; it does not use rewritten multi-ref sections to compress unrelated
 evidence.
 
+Validate will surface source mirror blockers before confirmation. Treat
+`section.source_mirror_split_required`,
+`section.source_mirror_repair_required`, and
+`section.source_mirror_source_refs_missing` as structure problems, not compile
+drafting problems. Use the returned `repair.suggested_splits[]` when present;
+otherwise repair source refs from CLI evidence views or move unsupported
+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.
+
 When the cited source sentence itself is uncertain, preserve that uncertainty on
 the edge with `confidence: possible` or `confidence: hypothesis`. This is only
 for source-authored uncertainty such as "可能", "疑似", "may", or "might". If
@@ -220,7 +251,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 and `structure_report.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/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 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`.
 
 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/claude/skills/skill-prose-compile/SKILL.md

@@ -21,9 +21,12 @@ Compile confirmed document structure into reviewable draft knowledge.
 - The input is already confirmed `context.structure.v1`; do not redesign node
   ownership, page paths, or relationships here. Return to prose align if those
   are wrong.
-- Read compile context through CLI views only: `read-plan`, `node-context`, and
-  `schema`. Use align evidence views only when the compile view or validation
-  output gives a specific source ref that needs exact text.
+- Read compile context through CLI views only: `blockers`, `read-plan`,
+  `node-context`, and `schema`. Start with `blockers` for large or recently
+  repaired structures; if it returns section blockers, return to prose align
+  instead of drafting compile actions. Use align evidence views only when the
+  compile view or validation output gives a specific source ref that needs exact
+  text.
 - Emit `context.compile-actions.v1`; the CLI mirrors source spans, derives
   `content_mode`, writes review candidates, and enforces source-bound evidence.
 - The `summary` field in each action is the Agent-authored behavior half only:
@@ -88,14 +91,17 @@ Use semantic labels, not SDK function names:
 Recommended read order:
 
 ```bash
+context run compile:<type>:<source>:<collection> --view blockers --format json
 context run compile:<type>:<source>:<collection> --view read-plan --format json
 context run compile:<type>:<source>:<collection> --view node-context --source <view-ref> --format json
 context run compile:<type>:<source>:<collection> --view schema --format json
 ```
 
 Use CLI-returned `available_view_refs`, `planned_sections`, `local_sources`, and
-`next_action.command`. Do not reconstruct the structure by opening
-`unapproved/structure.yaml` or `knowledge/structure.yaml` directly.
+`next_action.command`. If `blockers.section_blockers[]` is non-empty, repair the
+structure through align first; do not inspect every node or hand-split compile
+actions. Do not reconstruct the structure by opening `unapproved/structure.yaml`
+or `knowledge/structure.yaml` directly.
 
 ## Procedure References
 
@@ -134,12 +140,15 @@ relationship reference blocks.
 Run:
 
 ```bash
+context run compile:<type>:<source>:<collection> --view blockers --format json
 context run compile:<type>:<source>:<collection> --view read-plan --format json
 ```
 
-Use the returned node list, source overview, and next action. If the CLI says
-the structure is missing, unconfirmed, stale, frozen against the wrong
-snapshot, or invalid, return to prose align or source capture as indicated.
+Use the returned blockers, node list, source overview, and next action. If the
+blockers view reports section blockers, return to prose align and repair the
+confirmed structure before compile. If the CLI says the structure is missing,
+unconfirmed, stale, frozen against the wrong snapshot, or invalid, return to
+prose align or source capture as indicated.
 
 ### Step 2 — Inspect One Node
 

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

@@ -20,8 +20,8 @@ Run the human review gate. The user decides approval or rejection.
 - `<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`.
-- If browser opening fails or the host cannot make a path clickable, provide the
-  `file://` URL.
+- 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.
 - Do not parse `unapproved/entities.jsonl`, `.tmp`, or HTML internals with
   scripts to synthesize decisions.
@@ -40,9 +40,9 @@ For the internal collection reported by status, run:
 context review html <collection> --open
 ```
 
-Tell the user where the page opened. If needed, provide a clickable
-`file://.../<collection>.html` URL or the exact path printed by the CLI. Do
-not assume a fixed review filename; review scope is collection or `--all`.
+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`.
 Do not substitute OKF package roots (`wikis`, `guides`, `rules`) for this
 argument; review scope is the internal collection namespace.