@c4a/context-cli 0.5.29-alpha.2 → 0.5.29-beta.16

package/plugin/skills/skill-align-workflow/references/candidate-resolution.md

@@ -0,0 +1,60 @@
+# Candidate Resolution Rules
+
+Use these rules after reading candidate ledger and aggregate payloads, before `align-structure-decision`.
+
+## Anomaly Signals
+
+`anomaly_signals[]` are mechanical warnings. Do not ignore them and do not treat them as recommendations.
+
+For each anomaly, choose one outcome and record the reasoning in either the next ledger op rationale, the final node summary/audit warning, or `unresolved[]`:
+
+| Outcome | Use When |
+|---|---|
+| `accept` | The anomaly points to a real correction. Apply a concrete op or final structure choice. |
+| `dismiss` | The warning is mechanically true but semantically harmless. Keep the candidate and state why. |
+| `unresolved` | The warning changes structure but the source evidence is insufficient. Add an unresolved question instead of guessing. |
+
+Known anomaly kinds:
+
+| Kind | Meaning | Required Handling |
+|---|---|---|
+| `missing_evidence` | An active candidate has no evidence block. | Add evidence, reject the candidate, or mark the structure unresolved. |
+| `ledger_churn` | A candidate was renamed, merged, superseded, or rejected during discovery. | Confirm the final title/slug/target or mark unresolved if the shape is still ambiguous. |
+| `duplicate_block` | The same evidence block appears more than once on a candidate. | Dedupe the evidence or explain why repeated evidence is harmless. |
+| `general_review_recommended` | The CLI collapsed more than eight anomalies. | Review the affected candidate broadly; do not finalize solely from aggregate ordering. |
+
+## Label Hints
+
+For `merge_into`, `supersede`, and `reject`, include the visible label hint fields:
+
+- `source_label_hint` and `target_label_hint` for `merge_into`
+- `source_label_hint` and `target_label_hint` for `supersede`
+- `candidate_label_hint` for `reject`
+
+These hints are for audit and Agent DX. Copy them from ledger labels/titles when available. Do not invent a label that contradicts the visible candidate.
+
+## `llm_slug_hint` And Refs
+
+Use `llm_slug_hint` as the stable reference inside one `align-structure-decision` payload when final slugs may be normalized by the CLI.
+
+Recommended pattern:
+
+```yaml
+nodes:
+  - llm_slug_hint: local:data-region
+    slug: data-region
+    node_type: entity
+    tags: [term]
+  - llm_slug_hint: local:failover
+    contains_parent_ref: local:data-region
+edges:
+  - edge_type: depends_on
+    from_ref: local:failover
+    to_ref: local:data-region
+sections:
+  - owner: local:data-region
+block_ownership:
+  - owners: [local:data-region]
+```
+
+Refs may point to `llm_slug_hint` or final `slug`; prefer `*_ref` fields when a schema provides them. If the CLI rejects an unknown ref, use the returned `agent_hints[].available_node_refs` and resubmit a corrected `align-structure-decision`.

package/plugin/skills/skill-align-workflow/references/density-profile.md

@@ -0,0 +1,23 @@
+# Coarse Read Density Selection
+
+Use `density_profile` in `align-coarse-read` to describe how much structure the document needs before candidate discovery. This is a reading strategy, not a quality score.
+
+| 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 neutral content signals for each anchor. |
+| `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. | Still emit the `align-coarse-read` artifact, but keep anchors minimal and avoid over-segmentation. |
+
+## Content Signals
+
+`content_signals` are neutral shape signals used later by action/domain gates. They must not directly claim `node_type`, tags, or recommendations.
+
+| Signal | Meaning |
+|---|---|
+| `temporal_density` | The text has timelines, phases, schedules, version changes, or ordered time references. |
+| `actor_density` | The text names roles, users, teams, systems, services, or operators that perform work. |
+| `step_density` | The text contains ordered steps, procedures, phases, checklists, or how-to flow. |
+| `directive_density` | The text contains imperatives, policies, constraints, must/should language, or runbook-like instructions. |
+
+Use only `high`, `med`, or `low` based on the local section text. The canonical middle value is `med`; do not write `medium`. High `step_density` plus explicit actors and outcomes is useful evidence for an Action Gate, but it is not enough by itself to emit an `action` Node.

package/plugin/skills/skill-align-workflow/references/gates.md

@@ -0,0 +1,95 @@
+# Candidate Validation Gates
+
+Use these gates before producing `align-structure-decision`. The CLI may reject malformed gates or downgrade weak `domain` / `action` proposals to `entity`.
+
+## Action Gate
+
+Use `node_type: action` only when the candidate is a user story, runbook, how-to, roadmap, or other planned procedure. Fill both `action_probe` and `action_gate`.
+
+`action_probe` and `action_gate` use the same five booleans:
+
+| Field | Meaning | Evidence rule |
+|---|---|---|
+| `has_steps_or_phases` | The source contains explicit steps, phases, ordered work, or a procedural sequence. | Hard requirement. Must be directly supported by block evidence. |
+| `has_actor_or_role` | A user, system, operator, service, or role performs the work. | May be inferred, but inference must be recorded. |
+| `has_outcome_or_goal` | The action has a target result, acceptance condition, or operational goal. | May be inferred, but inference must be recorded. |
+| `is_repeatable_or_planned` | The work is repeatable, scheduled, policy-like, or intentionally planned. | May be inferred, but inference must be recorded. |
+| `queries_answerable_with_refs` | The resulting Node can answer how/when/who/what-to-do questions from cited blocks. | May be inferred, but inference must be recorded. |
+
+`has_steps_or_phases: false` means do not emit an action Node. If the subject has a stable named definition that people can reference, use `entity` with tag `term`. Routing schemes, durable rules, and data-shape descriptions belong inside the matching domain/entity/action Sections (`spec`, `principle`, `decision`, `comparison`, `warning`, and related mounted kinds).
+
+## Term Entity Boundary
+
+Use `entity` + `tags: [term]` only for a stable named definition. The core content should fit a 1-3 sentence glossary entry answering "what is X?" without if/else branches, steps, trade-offs, or "we choose" reasoning.
+
+Decision tree:
+
+1. If the subject is a procedure, ordered work, runbook, how-to, or repeated planned operation, use an `action` Node.
+2. If the subject is a concrete product, service, system, app, library, module, CLI, or code symbol, use the matching concrete `entity` tag.
+3. If the content is a rule, risk, design choice, comparison, data shape, durable behavior, or operational detail, do not create a Node for it; place it as a Section under the owning Node.
+4. If the subject is a stable named definition that can be written as a short glossary entry and referenced across documents, use `entity` + `tags: [term]`.
+5. If explaining the subject requires alternatives, steps, condition branches, trade-offs, or "we choose" reasoning, it is not `term`; route it to an owning Section or an `action` Node.
+
+Term boundary TTL: re-run this decision tree before every candidate-ops batch and again immediately before `align-structure-decision`. If you have processed more than one batch or about ten candidates since the last check, treat the previous check as expired.
+
+Good `term` examples:
+
+- `Data Region`: a named deployment or compliance scope used across documents.
+- `IDC` / `Region`: named scope terms with stable definitions.
+- `request-id`: a named identifier with a stable meaning.
+- `target-region`: a named cookie, header, or routing key.
+- `Dynamic Site Acceleration`: a named traffic acceleration category.
+
+Not `term`:
+
+- cookie-plus-IP routing: a conditional routing scheme; put it in the owning service/system as `spec`.
+- shared load-balancer rollout: a design choice with constraints; use `spec`, `principle`, or `decision` under the owning entity.
+- six-dimensional resilience matrix: a structured comparison/framework; use a domain/entity `comparison` or `spec` Section.
+- CDN scheduling strategy: service behavior and design choices; model the CDN or traffic service as `service` and place the strategy in Sections.
+
+## Inference Sources
+
+`action_gate.inference_sources` is required and must be a structured object with four keys:
+
+```yaml
+inference_sources:
+  actor:
+    source_type: explicit-block
+    evidence_blocks: [b0001]
+    rationale: "The block names the operator role."
+  outcome_or_goal:
+    source_type: inferred-from-block
+    evidence_blocks: [b0001]
+    rationale: "The block describes recovery as the expected result."
+  repeatability_or_plan:
+    source_type: heading-and-block
+    evidence_blocks: [b0001]
+    rationale: "The runbook heading and ordered list indicate planned reuse."
+  answerability:
+    source_type: explicit-block
+    evidence_blocks: [b0001]
+    rationale: "The steps answer how the operation is performed."
+```
+
+Allowed `source_type` values:
+
+| Value | Use when |
+|---|---|
+| `explicit-block` | The evidence block directly states the signal. |
+| `heading-and-block` | The heading plus block text together support the signal. |
+| `ref-node` | An existing or same-decision Node reference supplies the signal. Include `ref_nodes`. |
+| `inferred-from-block` | The signal is inferred from block content. Keep the rationale short and concrete. |
+
+Each source must include `rationale` and at least one of `evidence_blocks[]` or `ref_nodes[]`. Do not write free-text-only inference explanations.
+
+## Domain Gate
+
+Use `node_type: domain` only for a scope that groups multiple child Nodes. Fill:
+
+| Field | Meaning |
+|---|---|
+| `scope_blocks[]` | Blocks that describe the scope boundary or grouping. |
+| `child_refs[]` | Candidate ids, local refs, or final slugs for children in the scope. |
+| `grouping_reason` | Why these children belong together under this domain. |
+
+If a domain has no resolvable child refs, no clear grouping reason, or only one same-file child without a broader scope, emit an `entity` instead. Weak domain gates are downgraded by finalize and recorded in `audit_warnings`.

package/plugin/skills/skill-compile-close/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: skill-compile-close
+description: >
+  Packaged skill invoked by `/context:compile`; not a user slash command. Runs after every draft
+  iteration. Triggers `context compile --close`, which in one invocation
+  refreshes locator-only evidence, canonicalizes source refs, compacts and verifies the final workspace,
+  rebuilds the knowledge index, appends a changelog
+  entry, rebuilds section fingerprints + incremental cache, and
+  archives compile scratch files. Agent intervention is
+  limited to interpreting the CLI's output and routing any verify
+  error back to its upstream command (`/context:compile` for Section
+  issues, `/context:align` for structural issues, `/context:drop`
+  for dropped-source references). The skill never hand-edits rendered knowledge.
+  Activates once all draft actions are applied and before user-visible
+  success is declared.
+tools:
+  - Bash
+---
+
+# skill-compile-close — global verify + index + changelog
+
+Close a compile run. The CLI does the work; the skill reads the
+CLI's output and routes any failure back to the correct upstream
+command. It does not hand-edit rendered knowledge.
+
+## TL;DR — Non-negotiables
+
+- CLI-driven. `context compile --close` performs deterministic close writes first (locator refresh, source_ref canonicalization, compact, index/changelog), verifies the final workspace, then rebuilds section fingerprints + incremental cache and archives compile scratch files. Use the command's stdout + exit code; that's the close's full output.
+- **Agent NEVER edits rendered knowledge from the close stage.** The CLI is the sole writer for articles, the index, and the changelog. If verify reports an error here, route it back, not around:
+  - Content / Section issues (`invalid-section-mount`, `body-ad-hoc-heading`, `dangling-source-alias`) → user re-runs `/context:compile` (draft loop fixes its own Section actions; the close stage does not patch)
+  - Structural issues (`contains-cycle`, `edge-dangling-node`, `duplicate-slug`, `invalid-node-type`, `domain-same-file-child`) → user runs `/context:align` to revise the plan
+  - Source issues (`dropped-source-reference`) → user runs `/context:drop <id>` to complete the drop
+- Exit 0 → summarise node/section totals, verify, `recompiled`, `locator_updates`, `rebuilt`, fingerprint rebuild count, and archive status / archived file count when printed; then stop.
+- Exit 2 → report the full issue list verbatim + point at the right re-entry command above. Do not hand-open the affected rendered article.
+- If exit 2 includes `coverage-high-signal-unresolved`, follow the CLI hint. Read the node-scoped payload with `context workflow show --payload coverage-candidates --scope <node-run-scope> --view coverage` or inspect `context schema coverage-disposition`; do not guess workspace-scope payload paths.
+- Never re-run `context compile --draft` from close to paper over verify failures. Draft failures belong in the draft loop.
+- Do not use Python, Node.js, shell scripts, `ls`, `find`, `rg`, `cat`, or similar ad-hoc commands to inspect `WORKSPACE_DIR`, `.context`, knowledge files, or `/tmp` workflow artifacts.
+- Derivable files self-heal: missing `_index.md` or `changelog.md` is rebuilt inside `compile --close` before the append, locator-only source moves are refreshed, non-canonical but hash-valid `source_ref` locators are canonicalized, and high-signal coverage candidates already backed by active Sections are marked covered. No pre-check needed.
+- LLM-assisted repair (`--fix-with-llm`) is not available in the current release.
+- Output language: summary prose matches the user's language; CLI output, issue codes, file paths stay as printed.
+- Successful close archives CLI scratch artifacts through the output lifecycle and rebuilds the user-level incremental cache. Current align state is internal CLI state, not a file protocol. The CLI owns this lifecycle — the agent must not move, delete, or archive workspace output files by hand.
+- Semantic decisions are applied and recorded before close. Compile-close does not judge or rewrite semantic decisions; it only verifies the already-applied workspace and rebuilds derived indexes.
+
+<reference>
+
+## Stages inside `context compile --close`
+
+Close is one in-process command with one exit code:
+
+1. **Coverage guard with self-heal** — drops stale candidates and treats high-signal candidates already backed by active Sections as covered.
+2. **Locator refresh** — if evidence moved but block hashes are unchanged, updates only section locators.
+3. **Source ref canonicalization** — if a Section `source_ref` resolves to the same raw evidence block but has a stale anchor/range rendering, rewrites it to the canonical locator.
+4. **Workspace compact** — re-renders every knowledge article canonically (Section order, frontmatter field order, `## Contains` list ordering, heading depth).
+5. **Rebuild knowledge index** — regenerates the index from the current workspace state; previous content overwritten.
+6. **Append changelog** — appends one compile list item to the changelog; existing entries preserved.
+7. **Workspace verify** — runs the full rule set against the final close output. Any error flips exit to 2 and close rolls back its writes.
+8. **Rebuild incremental cache** — rebuilds section fingerprints and cache indexes from workspace truth sources.
+9. **Archive scratch files** — moves CLI-owned context/draft/prepare/review scratch payloads into the output archive lifecycle.
+
+## Outcome routing
+
+| Outcome | Agent action |
+|---|---|
+| Exit 0, 0 issues | Summarise those counts in the user's language: Nodes touched; Sections added / updated / superseded / deprecated / skipped; `recompiled`; `locator_updates`; `rebuilt`; verify green. Stop. |
+| Exit 0, warnings only | Summarise + list warnings verbatim. Point at `/context:status` or `context cache status` when the warning is incremental-cache-related. Stop. |
+| Exit 2, Section / content issue | Surface the full issue list; point the user at re-running `/context:compile` (the draft loop owns Section writes). Do NOT Edit the affected rendered article. |
+| Exit 2, structural issue (cycle, duplicate slug, `invalid-node-type`, `domain-same-file-child`) | Surface the full issue list; point the user at `/context:align` to revise structure. Do not re-run compile. |
+| Exit 2, `dropped-source-reference` | Surface the source-id; point the user at `/context:drop <id>` to complete the drop cleanup. |
+| Exit 2, `coverage-high-signal-unresolved` | Read the node-scoped coverage payload named in the CLI hint. If the candidate is intentionally covered by sibling Nodes or should not be written for this Node, submit `action: skip` with a reason; for skip only, `source_refs` may be omitted to dispose the whole candidate. |
+
+The close stage never edits rendered knowledge on the agent side. Every verify error routes back to the correct upstream command (compile / align / drop), never sideways into a hand Edit. Use the CLI issue code and hint printed by `context compile --close` for the error→command mapping.
+
+## Changelog entry shape
+
+`context compile --close` appends one markdown list item per run to
+the changelog with aggregate counts — not a multi-line
+block:
+
+```
+- [compile] nodes=N sections=M recompiled=R locator_updates=L @ <ISO timestamp>
+```
+
+`[drop]` lines from `/context:drop` follow the same single-line list-
+item convention (see the drop skill for the exact shape).
+
+</reference>
+
+<procedures>
+
+### Step 1 — Invoke close
+
+Run `context compile --close`. The caller (typically `/context:compile`) may have already invoked it; check for existing output before re-running.
+
+### Step 2 — Interpret
+
+Use stdout + stderr. The exit code selects the path via [Outcome routing](#outcome-routing).
+
+### Step 3 — Route errors to the correct upstream command
+
+For each error in the CLI's report, classify via [Outcome routing](#outcome-routing) and name the re-entry command in your report. Do NOT hand-edit rendered knowledge — that violates the CLI-sole-writer principle and masks the real upstream fix. Specifically:
+
+- Section / content issue → user re-runs `/context:compile` (draft loop produces new Section actions; the CLI re-writes).
+- Structural issue → user runs `/context:align` (revise the plan; re-compile afterwards).
+- `dropped-source-reference` → user runs `/context:drop <id>` to finish drop cleanup.
+
+One pass. If the CLI reports multiple errors, list them all and let the user choose the order; do not loop the close stage itself.
+
+### Step 4 — Report
+
+Summarise in the user's language:
+
+- Nodes touched and counts per op (add / update / supersede / deprecate / skip / locator-only).
+- Knowledge index rebuilt / updated; changelog appended at `<timestamp>`.
+- Incremental close counts printed by the CLI: `recompiled`, `locator_updates`, `canonical_source_ref_updates`, `rebuilt`, and section fingerprint rebuild count.
+- Verify result: green / `<n>` warnings / `<n>` errors (issue codes verbatim).
+
+Stop. Do not auto-invoke follow-on commands.
+
+### Step 5 — Self-verify
+
+- [ ] `context compile --close` ran exactly once per close call — if not, **Step 1**.
+- [ ] If exit 2, every error is surfaced to the user with a re-entry command (compile / align / drop); no silent ignores — **Step 3**.
+- [ ] No agent-hand edits to rendered knowledge — if any, revert; the close stage is read-only for knowledge content.
+- [ ] No Read / Glob / Grep / Write was used against `WORKSPACE_DIR`; CLI-owned output archival is allowed.
+- [ ] No ad-hoc script or shell file traversal was used against `WORKSPACE_DIR`, `.context`, or `/tmp` workflow artifacts.
+
+</procedures>