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

package/plugins/skills/context-continue/references/internal-procedures/skill-continue-workflow.md

@@ -0,0 +1,172 @@
+---
+name: skill-continue-workflow
+description: >
+  Internal procedure invoked by the public Context continuation entry; not a user slash command.
+  Runs the status-driven Context process, executes safe mechanical next steps,
+  and delegates human gates to source, review, and package procedures.
+tools:
+  - Bash
+---
+
+# skill-continue-workflow
+
+Continue an existing Context workspace from its current state.
+
+## TL;DR
+
+- Use this only inside an initialized Context workspace. If the user is starting
+  a new knowledge workspace or a new batch from a raw project/repo root, do not
+  run `context status` first; use the init workflow and complete setup before
+  returning here.
+- If `context status` reports `workspace-not-found` with a configured
+  `context.workspaceDir`, stop. If the directory exists, enter it and rerun
+  status. If it does not exist, ask whether to initialize it through the init
+  workflow; do not treat the host repository root as the workspace.
+- There is no `context continue` CLI command. Start with `context status`.
+- `context status` and CLI diagnostics are the source of truth.
+- Execute safe mechanical `next:` steps; stop at semantic choices and human
+  gates.
+- Delegate source/scope decisions to
+  `skill-source-scope.md`.
+- Delegate review to `skill-review-gate.md`.
+- Delegate package output choices to
+  `skill-package-output.md`.
+- Delegate document investigation and structure confirmation to
+  `skill-prose-align.md`.
+- Delegate source-bound prose compile requests to
+  `skill-prose-compile.md`.
+- Do not inspect `.tmp`, `unapproved/`, `knowledge/`, `dist/`, or
+  `node_modules/@c4a/context/dist` with ad hoc scripts to decide project state.
+- Only run commands surfaced by the current status route, current phase view,
+  review gate, verify/build gate, or package guidance. Do not invent alternate
+  lifecycle commands from memory.
+
+<reference>
+
+## Safe Mechanical Commands
+
+These can run when already implied by current status and no placeholder/human
+choice remains:
+
+| State / hint | Allowed action |
+|---|---|
+| source already declared | `context source ensure`, `context source list`, `context source get` |
+| declared phase that does not read new source body or require a semantic choice | `context run <phase-id>` |
+| prose align evidence read | `context run align:<type>:<source>:<collection> --view <view>` |
+| prose structure validation | `context run align:<type>:<source>:<collection> --validate --input <structure.yaml>` |
+| prose compile evidence read | `context run compile:<type>:<source>:<collection> --view <view>` |
+| prose compile action validation | `context run compile:<type>:<source>:<collection> --validate --input <compile-actions.yaml>` |
+| copied review payload supplied by user | `context review apply <payload-file>` |
+| close required after review | `context close --format json` |
+| package already declared and close is clean | `context build` |
+| validation requested | `context verify` |
+
+Capture phases are not safe mechanical commands by default. `capture:file:*`
+and `capture:lark:*` read local or remote source bodies and update committed
+snapshots, so they require the source read-permission gate unless the current
+turn already contains explicit user confirmation for that exact source.
+
+## Human Gates
+
+Stop and ask, or wait for user input, for:
+
+- `Human gate:` in CLI output.
+- placeholders such as `<name>`, `<repo-or-subdir>`, `<phase-id>`, `<collection>`.
+- missing source selection.
+- source boundary/name decisions, because they affect `knowledge/` paths and
+  `source_ref` prefixes.
+- source repo operations: clone, checkout, reset, fetch, install, build, test.
+- source scope, package/subdirectory, symbol group, or glob choices.
+- file/Lark capture or refresh, including capture preview, until the user has
+  confirmed which local path or remote document may be read.
+- review approval/rejection decisions.
+- document structure confirmation, section ownership, edge confirmation,
+  rewrite intent, conflict, weak-evidence, or cross-document organization
+  choices unless they are being handled through prose align/compile evidence
+  views and validation.
+- package output type or template choices.
+
+When a human gate has a fixed small option set, use the host's native
+multi-choice tool when available (Claude Code `AskUserQuestion`, Codex's
+available native user-input tool such as `request_user_input` when exposed,
+Cursor Plan Mode `AskQuestion`). If unavailable, fall back to Markdown `A/B/C`
+choices. Each option must include the effect of choosing it.
+
+</reference>
+
+<procedures>
+
+### Step 0 — Confirm Workspace Exists
+
+If the current task is to create a new Context workspace, or the user has not
+identified an initialized Context workspace root for this turn, do not continue
+with this workflow. Initialize through the public Context init entry or
+`context init` first, run the setup command printed by init, then return to this workflow from the
+created workspace.
+
+### Step 1 — Read Status
+
+Run:
+
+```bash
+context status
+```
+
+Use the output as evidence. Explain status and next step in the user's language;
+do not forward a long raw transcript unless requested.
+
+### Step 2 — Route The State
+
+1. If status says `missing-source` or `needs-capture`,
+   source boundary/name is unclear, source scope is unclear, or an extract
+   phase needs first-run scope confirmation, follow
+   `skill-source-scope.md`.
+2. If status says `captured-ready-to-investigate` or `needs-structure`, or the
+   user asks to split, merge, classify, relate, or semantically organize
+   document evidence before draft pages exist, follow
+   `skill-prose-align.md`.
+3. If status says `needs-prose-compile` or `structure-ready`, or the user asks
+   to turn confirmed structure into source-bound draft pages, follow
+   `skill-prose-compile.md`.
+4. If status says `compile-ready-for-review` or review is needed, follow
+   `skill-review-gate.md`.
+5. If status says `compile-close-needed`, run `context close --format json`
+   unless CLI diagnostics require human repair, then return to **Step 1**.
+6. If status says `ready-to-build`, `built`, `needs-package-output`, or approved knowledge exists but
+   package output is not chosen or declared,
+   follow `skill-package-output.md`.
+7. If the next command is safe per [Safe Mechanical Commands](#safe-mechanical-commands),
+   run it and return to **Step 1**.
+8. If the next command crosses a [Human Gate](#human-gates), ask or wait; do not
+   guess.
+
+### Step 3 — Execute Safely
+
+Before editing `src/index.ts` or package templates, read:
+
+```text
+node_modules/@c4a/context/docs/guides/agent-guide.md
+node_modules/@c4a/context/docs/guides/package-outputs.md
+node_modules/@c4a/context/docs/reference/project-api.md
+node_modules/@c4a/context/docs/reference/package-templates.md
+```
+
+Do not write one-off scripts to parse source packages, count extracted symbols,
+or sample candidates. Use `context source inspect` and the extract no-write
+preview command.
+
+### Step 4 — Report
+
+Report only the meaningful state transition: commands run, current status,
+human gate reached, and the precise user decision needed next. Never present
+`context build`, `context verify`, or file counts as proof that a deliverable is
+usable; inspect generated package structure when package output is involved.
+
+### Step 5 — Self-verify Checklist
+
+- [ ] `context status` was run first. If not, return to **Step 1**.
+- [ ] No human gate was crossed. If not, stop and report the protocol error.
+- [ ] No ad hoc file/script probing replaced CLI views. If not, discard that
+  conclusion and use the CLI view.
+
+</procedures>

package/plugins/skills/context-continue/references/internal-procedures/skill-init-workspace.md

@@ -0,0 +1,74 @@
+---
+name: skill-init-workspace
+description: >
+  Internal procedure invoked by the public Context init entry; not a user slash command.
+  Initializes a Context knowledge workspace, executes only safe setup follow-up,
+  then hands off to the next-step workflow until the first human gate.
+tools:
+  - Bash
+---
+
+# skill-init-workspace
+
+Initialize a Context workspace. The CLI creates files; the agent follows safe
+setup hints and stops before source/scope choices.
+
+## TL;DR
+
+- Use `context init`; do not add any extra project-local agent setup.
+- If init prints the standard setup `next:` command, run it instead of only
+  repeating it.
+- After the setup command succeeds, enter the workspace and read `AGENTS.md`
+  before running `context status`.
+- After setup, use `skill-continue-workflow.md`
+  for status-driven continuation.
+- Stop at source registration, extraction scope, review, package output, or any
+  external repo operation that needs user choice.
+- Explain in the user's conversation language. Keep CLI commands, flags, paths,
+  status values, JSONL keys, and copied CLI tokens unchanged.
+
+<procedures>
+
+### Step 1 — Run Init
+
+1. If the user gave no directory, run `context init`.
+2. If the user gave a directory, run `context init <project-dir>`.
+3. If the user supplied a project name option, pass it as `--name <name>`.
+4. Read the CLI feedback block and preserve the project root path.
+
+### Step 2 — Execute Safe Setup
+
+1. If CLI prints `next: cd "<project-root>" && bun install`,
+   execute that command.
+2. If install fails, report the failure and stop.
+3. If setup succeeds, read `<project-root>/AGENTS.md`.
+4. After reading `AGENTS.md`, run `context status` from `<project-root>` and
+   treat that output as the current workspace state.
+
+### Step 3 — Handoff Or Stop
+
+1. If status is ready for a safe mechanical step, continue with
+   `skill-continue-workflow.md`.
+2. If status is `missing-source`, `Human gate:`, or contains placeholders such as
+   `<name>`, `<repo-or-subdir>`, `<phase-id>`, or `<collection>`, ask for the
+   missing human choice and stop. For missing sources, ask for the knowledge
+   source boundary first; do not ask for a raw source name as an isolated
+   parameter.
+3. Do not infer repo source, source boundary, source name, package, or
+   extraction scope from cwd, parent directories, package names, monorepo
+   layout, or git remote.
+
+### Step 4 — Report
+
+Summarize what was initialized, what setup command ran, current status, and the
+human choice needed next. Do not paste a long raw CLI transcript unless the user
+asks for exact output.
+
+### Step 5 — Self-verify Checklist
+
+- [ ] Safe setup was executed when CLI provided the standard setup `next:`. If
+  not, return to **Step 2**.
+- [ ] No repo source or extraction scope was inferred. If not, stop and ask the
+  user to confirm the source boundary and scope.
+
+</procedures>

package/plugins/skills/context-continue/references/internal-procedures/skill-package-output.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/skills/context-continue/references/internal-procedures/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/skills/context-continue/references/internal-procedures/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.