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

package/plugins/claude/skills/skill-package-output/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: skill-package-output
+description: >
+  Internal procedure invoked by the public Context continuation entry; not a user slash command.
+  Explains package output choices, prefers kb packages, declares selected
+  package builders, builds, and inspects generated package structure.
+tools:
+  - Bash
+---
+
+# skill-package-output
+
+Choose and build a package output from approved knowledge.
+
+## TL;DR
+
+- Package output is a human choice. Do not add package builders just because an
+  example exists.
+- Recommend an agent knowledge-base package first for agent consumption.
+- Present an LLM text bundle as an alternative for a single text/RAG import
+  bundle.
+- Do not use `kbPackage()` or `llmsPackage()` as user-facing option labels.
+  Mention those API names only after the user chooses an output shape.
+- Do not offer `both` as a shortcut. Add one output, build, inspect, then ask
+  before adding another.
+- Build happens after review and deterministic close. If status says
+  `compile-close-needed`, run `context close --format json` before build.
+- Package templates may customize navigation and query guidance, but coverage,
+  gap, scope, or known-limit claims must cite approved knowledge,
+  `knowledge/structure.yaml`, or `context-build-inventory.json`.
+- Generated package structure, not `context build` alone, proves usability.
+
+<reference>
+
+## Output Shapes
+
+Recommended first output:
+
+```text
+dist/<name>-kb/
+├── AGENTS.md
+├── skills/
+│   └── knowledge-query/
+│       └── SKILL.md
+└── wikis/
+    ├── index.md
+    ├── <group>/
+    │   ├── index.md
+    │   └── ...
+    └── ...
+```
+
+Alternative:
+
+```text
+dist/<name>-llms/
+└── llms.txt
+```
+
+</reference>
+
+<procedures>
+
+### Step 1 — Read Package Docs
+
+Before editing package declarations or templates, read:
+
+```text
+node_modules/@c4a/context/docs/guides/package-outputs.md
+node_modules/@c4a/context/docs/reference/package-templates.md
+```
+
+### Step 2 — Explain The Choice
+
+Explain in the user's conversation language:
+
+- an agent knowledge-base package creates copied approved knowledge pages and
+  reusable query guidance under `dist/<name>-kb/`;
+- the default `knowledge-query` skill teaches agents how to query and cite those
+  copied approved knowledge pages;
+- the kb template must keep `wikis/index.md` as the OKF bundle entry page;
+- the default `wikis/index.md` is intentionally shallow: it describes the
+  bundle and links to next-level directories;
+- `context build` maps internal production collections into OKF roots and
+  generates child directory indexes such as `<okf-root>/<group>/index.md`, so
+  users can browse from OKF root -> group -> page; `wikis/index.md` is the
+  required default OKF root entry, while selected `guides/`, `rules/`, or
+  `feats/` roots get their own indexes too;
+- an LLM text bundle creates one text/RAG import bundle under
+  `dist/<name>-llms/`;
+- the user can customize `src/package-templates/kb/` before build;
+- template variables and examples are documented in
+  `node_modules/@c4a/context/docs/reference/template-variables.md`;
+- build writes a package inventory such as `context-build-inventory.json`, which
+  templates may cite when describing package coverage. Its edge section reports
+  the structural edge contract and the evidence status from `context verify`;
+- the user can skip package output for now and keep only `knowledge/`.
+
+Ask which single output to create first using the host's native multi-choice
+tool when available. Use semantic option labels:
+
+- Agent knowledge-base package: for agents to query and cite approved knowledge pages.
+- LLM text bundle: for one text/RAG import bundle.
+- Skip package output for now: keep approved Markdown only.
+
+### Step 3 — Declare The Selected Package
+
+After the user chooses, read the template variable guide if the template needs
+navigation changes:
+
+```text
+node_modules/@c4a/context/docs/reference/template-variables.md
+```
+
+Then edit `src/index.ts` and package templates according to the SDK docs. For
+kb output, prefer a clear package name such as `<source-name>-kb`.
+
+### Step 4 — Build And Inspect
+
+If status says close is required, run:
+
+```bash
+context close --format json
+```
+
+Do not build from unclosed approved knowledge.
+
+Run:
+
+```bash
+context build
+```
+
+Inspect the generated `dist/<name>-kb/` or `dist/<name>-llms/` structure against
+[Output Shapes](#output-shapes). For kb packages, inspect every selected
+OKF root that appears in `context-build-inventory.json`, not only
+`wikis/`.
+If templates are placeholders or knowledge pages are thin, say that plainly and
+stop for user direction.
+
+If build reports that a template path collides with copied knowledge, do not
+retry blindly. Explain that template files and selected knowledge cannot render
+to the same path, then rename the template file or ask whether to exclude that
+knowledge path.
+
+If build reports a template-boundary diagnostic, repair the template by
+referencing approved knowledge, `knowledge/structure.yaml`, or
+`context-build-inventory.json` for coverage/gap/scope/known-limit statements.
+Do not patch `dist/` as the durable fix; edit the template under
+`src/package-templates/`.
+
+### Step 5 — Self-verify Checklist
+
+- [ ] User selected the package output. If not, return to **Step 2**.
+- [ ] Only one output was added first. If not, ask before continuing with more.
+- [ ] A kb package template contains `wikis/index.md` and at least one
+  `SKILL.md`.
+- [ ] For kb output, the generated OKF root indexes link to next-level
+  directories, and child directory indexes exist when selected knowledge has
+  subdirectories.
+- [ ] Template paths do not collide with copied knowledge paths.
+- [ ] Template coverage/gap/scope/known-limit claims cite approved knowledge,
+  `knowledge/structure.yaml`, or build inventory.
+- [ ] Generated structure was inspected after build. If not, return to
+  **Step 4**.
+
+</procedures>

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

@@ -0,0 +1,296 @@
+---
+name: skill-prose-align
+description: >
+  Internal procedure invoked by the public Context continuation entry; not a user slash command.
+  Uses Context document evidence views to propose, validate, and confirm
+  `unapproved/structure.yaml` without reading raw snapshots directly.
+tools:
+  - Bash
+---
+
+# skill-prose-align
+
+Turn captured document evidence into confirmed structure.
+
+## TL;DR
+
+- Use this after document capture, or when the user asks to split, merge,
+  reorganize, classify, or relate document evidence.
+- The first product output is a structure draft, not final page body.
+- Read source material only through CLI evidence views: `read-plan`,
+  `source-index`, `span-detail`, `span-text`, `schema`, and
+  `structure-summary`. Additional views are diagnostic surfaces; use the route
+  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,
+  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.
+- 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.
+- When status reaches `structure-ready` or `needs-prose-compile`, hand off to
+  `${CLAUDE_PLUGIN_ROOT}/skills/skill-prose-compile/SKILL.md`.
+- Compile, review, close, verify, and build remain separate gates.
+
+<reference>
+
+## User-Facing Gates
+
+Use semantic labels, not SDK function names:
+
+| Gate | Say this | Do not say this first |
+|---|---|---|
+| Material investigation | "I will read the evidence index and source spans through Context, then propose a structure draft." | `alignProse`, `source-index`, `context.structure.v1` |
+| Structure confirmation | "Confirming this structure freezes page paths, section ownership, and relationships for this compile round." | `unapproved/structure.yaml` as a raw parameter |
+| Compile handoff | "The structure is confirmed; I will switch to source-bound compile for draft pages." | Continuing to edit structure in compile |
+
+## Runtime Discipline
+
+Use these rules in the current phase-runner flow:
+
+- Follow the top-level state, `routing.next_commands`, 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.
+- Use `views[].command` / `next_command` for evidence reads, prioritizing the
+  CLI-designated expected view when present.
+- Treat `agent_hints[]` as temporary diagnostics. If an agent hint conflicts
+  with a top-level `next_action` or status route, follow the top-level route.
+- Do not use direct file tools, shell scripts, `jq`, `sed`, `cat`, `head`,
+  `tail`, Python, or Node.js to inspect `sources/`, `unapproved/`,
+  `knowledge/`, `dist/`, or CLI-managed `.tmp` as a substitute for Context
+  views.
+- Write digest/hash flags are stale guards. Use the value returned by the CLI;
+  do not parse stdout fragments or host tool-result files to reconstruct one.
+- Delegated execution is only valid when the user explicitly authorizes it in
+  this conversation. Do not infer it from "continue", "继续", or general trust.
+- Run one write at a time. Do not parallelize align stage, compile stage, review
+  apply, close, or build writes.
+- If a payload is too large for a heredoc, stage it under
+  `.tmp/agent-payloads/<run-id>/...` in the workspace root and redirect stdin
+  from that file. Never reuse fixed `/tmp/c4a-*` names, and never place agent
+  scratch payloads under CLI-managed `.tmp/context-cli/`, `sources/`,
+  `unapproved/`, `knowledge/`, `dist/`, or package output directories.
+- If a validation or view response includes `reason_code`, `path`, `missing[]`,
+  `diagnostics`, `repair_hints`, or `agent_hints`, treat those fields as the
+  repair contract. Do not recover by replaying a stale manual route, editing
+  rendered files, or guessing schema aliases.
+
+## Evidence Views
+
+Recommended read order:
+
+```bash
+context run align:<type>:<source>:<collection> --view read-plan --format json
+context run align:<type>:<source>:<collection> --view source-index --compact --format json
+context run align:<type>:<source>:<collection> --view span-detail --span <source-ref> --format json
+context run align:<type>:<source>:<collection> --view span-text --span <source-ref> --format json
+context run align:<type>:<source>:<collection> --view schema --format json
+context run align:<type>:<source>:<collection> --view structure-summary --input <structure.yaml> --format json
+```
+
+Use CLI-returned `next_command` values for pagination. Do not reconstruct
+documents with ad hoc `cat`, `grep`, or scripts against `sources/` or `.tmp`.
+
+## Structure Contract
+
+The structure draft uses `schema_version: context.structure.v1` and lives at
+`unapproved/structure.yaml` after staging. It contains:
+
+- lifecycle state such as validated/confirmed and frozen snapshot metadata;
+- concept `nodes[]` with stable `node_ref`, `node_type`, title/summary, and
+  ownership;
+- materialized `views[]` with `view_ref`, collection, path, section plans, and
+  evidence refs;
+- typed edges using the closed set defined by the CLI;
+- unresolved items when evidence is weak, conflicting, or the target node is
+  missing.
+
+Confirmed structure is a human gate. Validation passing is not the same as
+confirmation. Do not write `lifecycle.state: confirmed`, `confirmed_by`,
+`confirmed_at`, or `structure_digest` until the user has explicitly confirmed
+the structure proposal in the conversation.
+
+## Procedure References
+
+These are current structure planning rules. They define the source-bound
+semantic gates for Node planning, section ownership, and relationship handling.
+
+| Decision | Reference |
+|---|---|
+| Structure planning, Node ownership, density, candidate resolution | [references/internal-procedures/structure-planning.md](references/internal-procedures/structure-planning.md) |
+| Node type, title, tags, fake entity, action/domain gates, edge gates | [references/internal-procedures/structure-planning/references/gates.md](references/internal-procedures/structure-planning/references/gates.md) |
+| Source density and coarse reading judgment | [references/internal-procedures/structure-planning/references/density-profile.md](references/internal-procedures/structure-planning/references/density-profile.md) |
+| Candidate anomalies, stable ids, paths, duplicates, and conflicts | [references/internal-procedures/structure-planning/references/candidate-resolution.md](references/internal-procedures/structure-planning/references/candidate-resolution.md) |
+
+</reference>
+
+<procedures>
+
+### Step 1 — Open Material Investigation
+
+Run:
+
+```bash
+context run align:<type>:<source>:<collection> --view read-plan --format json
+```
+
+Use the returned views, budgets, snapshot hash, and next actions. If the CLI
+reports a missing or stale snapshot, route back to source capture/refresh. Do
+not read the snapshot file yourself.
+
+### Step 2 — Read Evidence Through The Index
+
+Read a compact index before requesting exact spans:
+
+```bash
+context run align:<type>:<source>:<collection> --view source-index --compact --format json
+```
+
+For exact evidence, copy CLI-returned source refs or next commands:
+
+```bash
+context run align:<type>:<source>:<collection> --view span-detail --span <source-ref> --format json
+context run align:<type>:<source>:<collection> --view span-text --span <source-ref> --format json
+```
+
+Keep a short note of what evidence supports each proposed node, section, and
+edge. If the evidence is weak or conflicting, keep it as unresolved instead of
+turning it into a fact.
+
+Before drafting structure, read:
+
+- [references/internal-procedures/structure-planning.md](references/internal-procedures/structure-planning.md)
+- [references/internal-procedures/structure-planning/references/gates.md](references/internal-procedures/structure-planning/references/gates.md)
+- [references/internal-procedures/structure-planning/references/density-profile.md](references/internal-procedures/structure-planning/references/density-profile.md)
+- [references/internal-procedures/structure-planning/references/candidate-resolution.md](references/internal-procedures/structure-planning/references/candidate-resolution.md)
+
+Do not treat this as optional background. These files contain the current
+semantic gates for source-bound structure planning. A structure payload drafted
+without the applicable references is incomplete, even if the CLI schema accepts
+its shape.
+
+### Step 3 — Draft And Validate Structure
+
+Request the schema:
+
+```bash
+context run align:<type>:<source>:<collection> --view schema --format json
+```
+
+Create a `context.structure.v1` YAML file. The draft may include a one-page-per
+source shape, but that is represented as ordinary nodes and sections; it does
+not bypass structure confirmation.
+
+For small payloads, use stdin/heredoc. For larger payloads, write a scratch file
+under `.tmp/agent-payloads/<run-id>/` and pass it through `--input`. Scratch
+files are disposable agent working files; they are never phase state and
+must not be read back as a substitute for CLI views.
+
+Validate:
+
+```bash
+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:
+
+```bash
+context run align:<type>:<source>:<collection> --view structure-summary --input <structure.yaml> --format json
+```
+
+Repair diagnostics by routing them to the right decision:
+
+- source ref or snapshot mismatch -> reread evidence views or refresh capture;
+- unsupported node/section/edge -> remove it or mark unresolved;
+- duplicate/conflict -> ask the user which structure should win;
+- illegal edge type, missing target node, or edge without source refs -> fix the
+  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.
+
+### Step 4 — Review Structure Before Confirmation
+
+After validation, and again after a draft structure is staged, show the user:
+
+- node list and planned paths;
+- section ownership;
+- typed edges and unresolved relation candidates;
+- 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`.
+
+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.
+
+Use the host's multi-choice question tool when available. If unavailable, use a
+short Markdown fallback. Good options are:
+
+- Confirm this structure and continue to compile.
+- Revise the structure with additional guidance.
+- Go back to source scope or capture because the evidence set is wrong.
+
+Only after confirmation, run the CLI confirmation command, normally:
+
+```bash
+context run align:<type>:<source>:<collection> --confirm --format json
+```
+
+If confirming a structure file other than `unapproved/structure.yaml`, pass it
+with `--input <structure.yaml>`. A draft stage in `unapproved/structure.yaml` is
+not confirmation. Do not edit `unapproved/structure.yaml` after confirmation to
+change meaning; return to this gate instead.
+
+### Step 5 — Handoff To Compile
+
+After the user confirms the structure and the CLI reports `structure-ready` or
+`needs-prose-compile`, stop this procedure and follow:
+
+```text
+${CLAUDE_PLUGIN_ROOT}/skills/skill-prose-compile/SKILL.md
+```
+
+Do not keep editing structure while compiling. If compile diagnostics show the
+planned structure is wrong, return to this align gate and ask the user to
+confirm the corrected structure.
+
+### Step 6 — Self-verify Checklist
+
+- [ ] Evidence came only from Context evidence views.
+- [ ] `context.structure.v1` was validated before user confirmation.
+- [ ] User confirmed the structure before compile.
+- [ ] Compile was delegated to `skill-prose-compile`; this procedure did not
+  write draft page body.
+- [ ] Relationships are expressed as structure edges or unresolved items.
+- [ ] No direct edits were made to `sources/`, `.tmp`, `unapproved/`,
+  `knowledge/`, review HTML, or `dist/`.
+
+### Final Report
+
+Report in the user's language. Include only:
+
+- evidence views actually read;
+- proposed and confirmed node count, section count, edge count, and unresolved
+  count;
+- user confirmation outcome;
+- validation warnings that still matter for compile;
+- next route reported by status or the align phase.
+
+Do not report payload digests, snapshot hashes, source-ref hashes, absolute
+paths, or scratch file paths unless the CLI explicitly asks the user to repair
+one.
+
+</procedures>

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

@@ -0,0 +1,91 @@
+# Candidate Resolution Rules
+
+Use these rules after reading the current align evidence views and before
+authoring `context.structure.v1`. They define how current anomaly diagnostics
+map to supported structure outcomes.
+
+## Anomaly Signals
+
+Anomaly diagnostics are mechanical warnings. Do not ignore them and do not treat
+them as recommendations.
+
+For each anomaly, choose one current outcome and record the reasoning in the
+structure payload or user-facing explanation:
+
+| Outcome | Use When |
+|---|---|
+| Accept the correction | The anomaly points to a real structure fix. Apply a concrete node, section, edge, or ownership correction supported by source refs. |
+| Dismiss with rationale | The warning is mechanically true but semantically harmless. Keep the structure and state why in the confirmation summary. |
+| Keep unresolved | The warning changes structure but source evidence is insufficient. Add an `unresolved[]` item instead of guessing. |
+
+Known anomaly kinds:
+
+| Kind | Meaning | Required handling |
+|---|---|---|
+| Missing evidence | A proposed node, section, or edge has no source-backed evidence. | Add source refs, remove it, or keep the issue unresolved. |
+| Structure churn | A node was renamed, split, merged, replaced, or rejected during investigation. | Confirm the final id/title/target with the user or keep the ambiguity unresolved. |
+| Duplicate evidence | The same source ref appears more than once for the same semantic role. | Deduplicate it or explain why the repeated ref supports different roles. |
+| Broad review needed | The CLI collapsed many anomalies or reports aggregate risk. | Review the affected structure broadly; do not finalize solely from ordering. |
+
+## Stable References
+
+Use stable `node_ref`, `view_ref`, and `section_ref` values from the current
+`context.structure.v1` payload for in-payload references. A NodeRef should be
+safe, lower-case, and path-shaped, such as `entity/rspack` or
+`domain/build-tooling`. `slug` and `path` are derived fields in the current
+flow; do not invent alternate reference aliases.
+
+When an edge or section points at knowledge:
+
+- use the schema ref that matches the target layer:
+  `node_ref` for a conceptual Node, `view_ref` for a collection view, and
+  `section_ref` for a planned section;
+- ensure the target NodeRef, ViewRef, or SectionRef exists in the current
+  structure or approved knowledge;
+- keep relation hints unresolved when the target does not exist;
+- follow CLI diagnostics if a ref is unknown or stale.
+
+Do not create alternate alias fields or non-schema candidate ledger fields.
+They are not part of the current structure contract.
+
+## Visible Labels And Audit Rationale
+
+Humans need to understand merge, reject, rename, and replacement choices
+without decoding temporary ids. Keep that discipline in the current structure
+flow through current fields:
+
+- use `title` and `summary` to name the final node in user-facing language;
+- explain renamed/split/merged candidates in the confirmation summary, not by
+  adding non-schema label fields;
+- when a relation or rename cannot be settled from evidence, put the visible
+  title/target clue in `unresolved[]`;
+- when asking the user, phrase the choice with business labels ("Rspack build
+  tool page" vs "Webpack page"), not with source refs or internal section ids.
+
+NodeRef is the stable conceptual identity. ViewRef is the collection-specific
+view identity and is the durable approved-page identity. SectionRef is the
+stable planned-section identity under a ViewRef. Package paths are derived from
+the approved ViewRef plus containment/slug; do not treat paths as an alternate
+identity contract. Visible labels help humans review the choice, but they do
+not authorize a different NodeRef, ViewRef, edge, or section ownership without
+source-backed evidence and user confirmation.
+
+## Duplicate And Conflict Handling
+
+- Exact duplicate structure -> keep one node/section/edge and explain the
+  duplicate in the confirmation summary.
+- Same topic but different evidence boundary -> keep separate sections only
+  when each section has a distinct source-backed role.
+- Conflicting facts -> ask the user or keep an `unresolved[]` item. Do not
+  pick a winner from title order or source order.
+- Replacement or rename -> ask the user when it changes NodeRef, ViewRef,
+  containment, slug, or the derived approved path. These are durable user-facing
+  identities, not disposable labels.
+
+## Self-verify
+
+- [ ] Every accepted node, section, and edge has source-backed support.
+- [ ] Every unresolved relation or conflict is explicit in `unresolved[]`.
+- [ ] No non-schema candidate ledger fields or alias fields appear in the payload.
+- [ ] NodeRef, ViewRef, and SectionRef values, not temporary labels or paths,
+  are used for current references.

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

@@ -0,0 +1,30 @@
+# Evidence Density Selection
+
+Use density as a private reading and section-planning strategy. It is not a
+separate payload, not a quality score, and not a workflow stage. Persist only
+current `context.structure.v1` fields such as `nodes[]`, `sections[]`,
+`source_refs[]`, `edges[]`, and `unresolved[]`.
+
+Apply this reference when a captured source is long, dense, fragmented, or hard
+to split into stable planned sections. Use the current CLI evidence views
+(`read-plan`, `source-index`, `span-detail`, `span-text`) to inspect material;
+do not invent a separate coarse-read artifact.
+
+| Profile | Use When | Agent Behavior |
+|---|---|---|
+| `macro` | A long source has many headings, sections, or broad topic shifts. | Create section proposals around major headings and preserve document-level anchors so later passes do not flatten scope. |
+| `meso` | Default for normal product, design, or operational documents with several related sections. | Produce section proposals for meaningful local units and preserve evidence anchors. |
+| `micro` | The source is fragmented, note-like, or dense with short independent claims. | Keep section proposals narrow and avoid bundling unrelated blocks into one candidate. |
+| `single_pass` | The source is short enough that one read can safely discover all relevant structure. | Keep anchors minimal and avoid over-segmentation, but still validate the resulting structure. |
+
+Treat Markdown heading changes as section-planning hints, not hard boundaries.
+Sibling sub-headings under a shared parent can remain in one planned section
+when they form one coherent semantic topic for that parent. Headings with no
+shared parent should usually split unless you intentionally want one section to
+span them. When a dense source has many headings, split by heading first, then
+merge adjacent or sibling groups only when the merged section is still one
+coherent fact group.
+
+Do not let density alone choose `node_type`, `tags`, `section.kind`, or body
+content. Action/domain gates are decided from source evidence and the current
+schema, not from density metadata.