@c4a/context-cli 0.6.18 → 0.6.19

package/providers/context/resources/procedures/document-optimization.md

@@ -4,40 +4,88 @@ kind: procedure
 mediaType: text/markdown
 ---
 
-# Document revisions
+# Source-constrained editorial revisions
 
-This optional phase improves the presentation of approved file and document
-prose without mutating the approved page. It runs only when
+This optional phase improves the publication value and readability of approved
+file and document prose without mutating the approved page. It runs only when
 `package.json.context.documentOptimization` is true.
 
-Run the Route-selected plan command. Read every returned fragment in the
-current batch and write one decision for each fragment to the returned
-`payload_target`, using the Route input schema. Use `keep` when no safe local
-repair is needed. Use `replace` only for Markdown structure, spacing, obvious
-typographical errors, or link syntax. Preserve meaning, paragraph order,
-technical identifiers, URLs, code, and numbers. Do not summarize, expand,
-reorder, or invent facts.
+Run the Route-selected plan command. Each fragment is one source-backed Context
+Section and includes mechanical readability signals, allowed actions, exact
+line ranges, and source identity. Read every returned Section and write one
+decision for each fragment to the returned `payload_target`:
+
+- `keep` when it is already useful and readable. If the fragment has any
+  mechanical signal, include a concrete `assessment` that explains why every
+  signal is a false positive or why changing the Section would reduce source
+  fidelity. Name every reported signal code in that assessment so the CLI can
+  verify complete coverage; do not use one generic assessment for a batch;
+- `repair` for local typography, Markdown, spacing, or a descriptive link label
+  whose purpose is already stated in the same Section;
+- `reshape` for source-preserving structural changes such as a wide table into
+  a short index plus detail entries, or a long paragraph into stable headings;
+- `omit` only when the plan permits it and the selected reason matches a
+  mechanically identified non-knowledge Section.
+
+An unanswered question set, empty placeholder, decision-free draft, duplicate,
+or obsolete-only Section may be omitted. Questions with answers, limitations
+with impact and action, and deprecations with a replacement remain knowledge.
+Mechanical signals are review leads, not a complete readability verdict. Read
+every fragment even when it has no signal. A mixture of false positives and
+valid repair candidates does not justify keeping the whole batch unchanged.
+Every actionable signal must end in a safe edit, an eligible omission, a
+batched input request, or a Section-specific explanation that the signal is a
+false positive or that the edit would damage source fidelity. Time, token or
+compute cost, workload, batch size, deadline, and desire to finish sooner are
+never valid reasons to keep, skip, defer, or reduce an optimization. Do not
+default a batch to `keep` because it contains many fragments; finish the
+complete current batch with the same quality standard as a single fragment.
+Signals that recommend `request-input` identify ambiguous currency, ownership,
+link purpose, or sensitive values. The plan returns all of them in
+`input_requests`: ask one concise, batched question and wait before applying
+the complete optimization payload. Do not convert a required input into
+`keep` merely to avoid a pause. Preserve the exact destination of a volatile
+URL and safely improve its descriptive label or surrounding layout when the
+same Section already states its purpose; ask only for information that cannot
+be recovered from the approved Section or its source evidence.
+
+In fully managed operation, apply every safe `repair`, `reshape`, and eligible
+`omit` autonomously and continue until the optimization status is current.
+Managed authority removes routine review pauses, not quality work or genuine
+missing-input boundaries. A large repair set is expected work, not a blocker.
+If an `input_requests` batch remains after completing all independently safe
+analysis, ask once for that batch and resume from the returned Route.
+
+Keep all work inside the same source Section. Preserve link destinations,
+images, code, commands, numbers, identifiers, conditions, and source markers
+exactly. Do not introduce facts, infer an answer, or replace a complete
+contract with a summary.
 
 After the complete payload is ready, execute the exact `next_action.command`
-returned by the plan. Context rejects stale, incomplete, duplicate, or
-semantically broad decisions. Unchanged fragments reuse their previous
-decision; changed fragments alone return to this phase.
+returned by the plan. Context rejects stale, incomplete, duplicate,
+cross-Section, protected-value, semantically broad, or unexplained signaled
+`keep` decisions. The assessment is used only to audit the current decision and
+is not stored in approved knowledge, revisions, or package output. Unchanged
+Sections reuse their previous decision; changed Sections alone return to this
+phase.
 
 Only pages with reader-visible changes are stored. A revision is a full
 Markdown sidecar beside its approved page: `knowledge/guides/setup.md` becomes
 `knowledge/guides/setup__revision.md`. Default knowledge discovery excludes the
 reserved suffix. The filename derives the base page; the revision stores only
-the base digest that cannot be derived. Unchanged fragments inside a revision
-are inferred. A page with no changes stores one derived negative cache key
-below `.tmp/context-runtime/document-optimization/`; replacement prose and
-fragment metadata are never duplicated there.
+the base digest that cannot be derived. Unchanged Sections inside a full
+revision are inferred. A page with no changes stores one derived negative cache
+key below `.tmp/context-runtime/document-optimization/`; replacement prose and
+Section metadata are never duplicated there. An omitted Section keeps its
+lifecycle marker in the revision so its source identity remains auditable, but
+its reader-visible body and all revision audit state are absent from `dist/`.
 
 For a later user-requested correction, use `context revise "<title or approved
 path>" --format json`. The resulting `route.document-revision.requested` owns
 target selection, revision editing, and validation; it also works when broad
 document optimization was not previously enabled. The compatibility entry
 `context optimize-docs revise` accepts the same selectors. Validation rejects
-lifecycle metadata changes, stale page baselines, unsafe token changes, broad
-rewrites, and invalid Markdown structure. A source change makes the revision a
-blocking conflict instead of silently applying it. Do not create fragment JSON
-files or another revision namespace.
+lifecycle metadata changes, stale page baselines, protected-value changes,
+cross-Section rewrites, unsupported omissions, and invalid Markdown structure.
+A source change makes the revision a blocking conflict instead of silently
+applying it. Do not create fragment JSON files or another revision namespace.

package/providers/context/resources/procedures/document-revision.md

@@ -8,7 +8,10 @@ mediaType: text/markdown
 
 Use this procedure only for a correction explicitly requested by the user after
 an approved knowledge page already exists. The request selects one page; it
-does not authorize a broad rewrite or a change to source facts.
+does not authorize a free rewrite or a change to source facts. It may repair or
+reshape reader-visible content within one existing Context Section, and may
+omit a complete Section only when the current source supports a documented
+non-knowledge reason.
 
 1. Run the Route command `context optimize-docs revise-current --format json`.
 2. Read the complete approved page and its sibling `__revision.md` page named
@@ -16,12 +19,14 @@ does not authorize a broad rewrite or a change to source facts.
    could change a fact rather than formatting or wording.
 3. Edit only the returned revision page. Preserve its frontmatter identity,
    `context_revision` baseline, Context section boundaries, evidence markers,
-   links, code, numbers, and unsupported details. Make the smallest change that
-   satisfies the user's request. Never edit the approved base page for this
-   operation.
+   link destinations, images, code, numbers, identifiers, and supported facts.
+   A wide table may become an index plus detail entries, and a source-backed
+   list may be reorganized, but facts cannot move across Section boundaries.
+   Never edit the approved base page for this operation.
 4. Run `context optimize-docs validate --format json`. If validation reports a
-   stale baseline, unsafe replacement, or missing evidence, stop and report the
-   exact finding instead of weakening the correction.
+   stale baseline, protected-value change, unsupported omission, broad rewrite,
+   or missing evidence, stop and report the exact finding instead of weakening
+   the correction.
 5. Continue from the returned `context status --format json` Route. A valid
    correction makes the package stale, so the normal build Route will offer
    compilation without requiring a second correction decision.

package/providers/context/resources/procedures/knowledge-review.md

@@ -24,7 +24,9 @@ Without explicit session-managed authority:
 
 - open the report returned by the route;
 - let the user approve or reject candidates;
-- apply the exact returned decision payload.
+- apply the exact returned decision payload; and
+- retain the exact report reference and reviewed scope in this conversation for
+  the final completion summary.
 
 The ordinary Route also carries a revision-bound force-approval resolution
 Action as an escape path. Do not advertise it when first presenting Review.
@@ -38,3 +40,4 @@ conversation. It does not bypass source permission, validation, close, or
 verify.
 
 After apply, re-evaluate. Do not infer that close or package output is current.
+Do not persist a duplicate review-report ledger in the workspace.

package/providers/context/resources/procedures/source-boundary.md

@@ -10,14 +10,26 @@ A source boundary is a user decision about which repositories, modules, or
 documents may become approved knowledge. It affects extraction scope,
 provenance, output paths, and freshness checks.
 
-Do not infer this boundary from the current directory, monorepo layout, package
-names, or Git remotes. Explain the decision in the user's language, obtain the
-specific paths or documents, then use the Context source schema and conditional
-registration command selected by the route. The command uses `--input -`; after
-the current conversation contains the required confirmation, send one YAML or
-JSON payload matching the selected schema to its standard input. Do not run the
-command before confirmation and do not replace it with a command remembered
-from another route.
+Do not infer this boundary by using the current directory, monorepo layout,
+package names, or Git remotes to select additional sources. Once the user has named a concrete local module
+or path, resolving its unique local directory and reading that checkout's Git
+root, `origin`, and current commit are mechanical identity resolution, not a
+new source-boundary decision. Paths in the registration payload are resolved
+from the Context project root; after initializing a child `context/` directory,
+recompute sibling paths from that root instead of reusing the caller's relative
+path. As a final CLI safeguard, an omitted `local` may resolve only to one Git
+directory named by the confirmed module at the project root or its parent; zero
+or multiple matches do not authorize a guess.
+
+Explain the decision in the user's language, obtain the specific paths or
+documents, then use the Context source schema and conditional registration
+command selected by the route. If the current user request already names the
+exact modules or documents, that decision is already present; do not ask for
+their remote URLs when a confirmed local Git checkout can supply them. The
+command names a file below `.tmp/agent-payloads/`; after the current
+conversation contains the required confirmation, write one JSON payload
+matching the selected schema to that exact path. Do not run the command before confirmation and do not replace
+it with a command remembered from another route.
 
 Context source identity has two parts:
 

package/providers/context/resources/semantic/align/structure-planning.md

@@ -141,7 +141,7 @@ Use collection routing first:
   `product`;
 - architecture, service/module/system design, runtime dependency, code-adjacent
   prose -> `architecture`; if an existing code projection already owns the
-  object, reuse its NodeRef/ViewRef instead of creating a `codegraph` prose
+  object, reuse its NodeRef/ViewRef instead of creating a `codeindex` prose
   view;
 - SOP, runbook, operation drill, workflow, or how-to procedure -> `sop`;
 - FAQ, question/answer, support notes -> `faq` only when the evidence is an
@@ -158,7 +158,7 @@ Use collection routing first:
   Sections under the owning view;
 - test plan, validation scenario, acceptance case -> `test`;
 
-Do not route prose align views to `codegraph` or `feats`: `codegraph` is
+Do not route prose align views to `codeindex` or `feats`: `codeindex` is
 produced by code extraction / AST projection, and `feats` is reserved for the
 dedicated feature workflow. For section-vs-collection overlap, keep a local
 `faq`, `decision`, or `incident` as a Section kind under the owning view unless
@@ -314,7 +314,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. The CLI applies deterministic boundary repairs internally and returns only remaining blockers. For oversized Views, apply the returned child-View and contains-edge suggestions while classifying child Nodes from evidence. Resolve other blockers from evidence; ask the user only when evidence supports multiple incompatible semantic choices. Stage only after validation state is `ready`. The stage result opens the final HTML report for the Route-selected structure-confirmation gate. Execute the revision-bound confirmation command returned by `workflow.current`; managed session authority may resolve that gate without another question.
+Before staging, write the `context.structure.v1` payload to the Route-selected `.tmp/agent-payloads/` path and run the returned `context run align:<type>:<source>:<collection> --validate --input <payload-file> --format json` command. The CLI applies deterministic boundary repairs internally and returns only remaining blockers. For oversized Views, apply the returned child-View and contains-edge suggestions while classifying child Nodes from evidence. Resolve other blockers from evidence; ask the user only when evidence supports multiple incompatible semantic choices. Stage only after validation state is `ready`. The stage result opens the final HTML report for the Route-selected structure-confirmation gate. Execute the revision-bound confirmation command returned by `workflow.current`; managed session authority may resolve that gate without another question.
 
 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
@@ -331,7 +331,7 @@ editing CLI-managed files.
 - [ ] Evidence was read through returned `next_action.command`, `next_command`, or current CLI schema/view commands only. If not, return to **Step 2**.
 - [ ] Node classification used the semantic gates in `structure-planning/references/gates.md`. If not, return to **Step 4**.
 - [ ] URL/reference ownership followed CLI diagnostics, not static prompt rules. If not, return to **Step 5**.
-- [ ] The requested align payload passed `context run align:<type>:<source>:<collection> --validate --input - --format json` before stage. If not, return to **Step 6**.
+- [ ] The requested align payload passed the exact Route-selected `--validate --input <payload-file>` command before stage. If not, return to **Step 6**.
 - [ ] No `sources/`, `knowledge/`, `dist/`, `.tmp`, host tool-results, or CLI-managed files were read or written with generic tools. If violated, restart from **Step 1**.
 
 </procedures>

package/providers/context/resources/semantic/code-index/classification.md

@@ -52,6 +52,7 @@ Each module must have:
 - every additional applicable type in `moduleTypes`;
 - relevant behavior and boundary `facets`;
 - concrete inspected paths in `moduleTypeEvidence`;
+- exact source-relative Markdown paths already read in `documents`;
 - an explicit gap when available source cannot support a reliable claim.
 
 Choose the primary type from the boundary through which a reader most often
@@ -152,11 +153,12 @@ Extractor shape is part of the plan, not an implementation detail:
   overlapping cross-source unit causes `ownership-ambiguous`.
 - Use `extractCustom()` for aggregate pages or multiple units over one source.
   Every candidate must declare its owning `module`, and its evidence must cover
-  the Route-reported structural probes. Use evidence-scoped `sections` rather
-  than one undifferentiated `markdown` body: each section declares a coverage
-  kind and the exact source evidence supporting that part of the page. Resolve
-  source roots from the extractor context's `sources[].absolutePath`; never
-  embed a machine-specific checkout path.
+  the Route-reported structural probes. The custom-candidate contract has no
+  page-level Markdown fallback: every candidate must provide at least one
+  evidence-scoped `section`, and each section declares a coverage kind and the
+  exact source evidence supporting that part of the page. Resolve source roots
+  from the extractor context's `sources[].absolutePath`; never embed a
+  machine-specific checkout path.
 - Register independently visible monorepo children as separate sources before
   giving them separate `extractTs()` units. An `include` pattern filters files;
   it does not create a source boundary.
@@ -176,6 +178,7 @@ custom cross-module flow. A minimal plan has this shape:
   moduleTypes: ["web-application"],
   facets: ["page-routing", "protocol-consumer"],
   moduleTypeEvidence: ["package.json", "src/routes.ts"],
+  documents: ["README.md", "docs/architecture.md"],
   outputOwner: "customer-portal",
   outputProfile: "application-map",
   inputSources: ["repo:customer-portal"],

package/providers/context/schemas/document-optimization-decisions.schema.json

@@ -1,12 +1,12 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "context.document-optimization-decisions.v1",
-  "title": "Context document optimization decisions",
+  "$id": "context.document-optimization-decisions.v2",
+  "title": "Context source-constrained editorial revision decisions",
   "type": "object",
   "additionalProperties": false,
   "required": ["schema", "decisions"],
   "properties": {
-    "schema": { "const": "context.document-optimization-decisions.v1" },
+    "schema": { "const": "context.document-optimization-decisions.v2" },
     "decisions": {
       "type": "array",
       "items": {
@@ -18,14 +18,37 @@
           "input_digest": { "type": "string", "minLength": 1 },
           "context_digest": { "type": "string", "minLength": 1 },
           "policy_digest": { "type": "string", "minLength": 1 },
-          "action": { "enum": ["keep", "replace"] },
+          "action": {
+            "enum": ["keep", "repair", "reshape", "omit"],
+            "description": "Keep the Section, repair local presentation, reshape it within the same source boundary, or omit a mechanically eligible non-knowledge Section."
+          },
           "replacement": { "type": "string" },
-          "reason": { "type": "string" }
+          "assessment": {
+            "type": "string",
+            "minLength": 12,
+            "description": "Required when keeping a Section that has mechanical signals. Explain why the signals are false positives or why changing the Section would reduce source fidelity. This value is decision-only and is not published."
+          },
+          "reason": {
+            "enum": [
+              "unanswered-question",
+              "empty-or-placeholder",
+              "draft-without-decision",
+              "duplicate-content",
+              "obsolete-without-replacement",
+              "volatile-reference",
+              "sensitive-value-candidate",
+              "conversion-artifact"
+            ]
+          }
         },
         "allOf": [
           {
-            "if": { "properties": { "action": { "const": "replace" } } },
+            "if": { "properties": { "action": { "enum": ["repair", "reshape"] } } },
             "then": { "required": ["replacement"] }
+          },
+          {
+            "if": { "properties": { "action": { "const": "omit" } } },
+            "then": { "required": ["reason"] }
           }
         ]
       }

package/providers/context/schemas/source-batch-input.schema.json

@@ -44,13 +44,28 @@
           "$ref": "#/$defs/module"
         },
         "local": {
-          "$ref": "#/$defs/nonEmptyString"
+          "allOf": [
+            {
+              "$ref": "#/$defs/nonEmptyString"
+            }
+          ],
+          "description": "Local repository or module path resolved from the Context project root. A valid Git checkout supplies origin and current commit when remote/ref are omitted."
         },
         "remote": {
-          "$ref": "#/$defs/nonEmptyString"
+          "allOf": [
+            {
+              "$ref": "#/$defs/nonEmptyString"
+            }
+          ],
+          "description": "Repository remote URL. Optional when local resolves to a Git checkout with origin configured."
         },
         "ref": {
-          "$ref": "#/$defs/nonEmptyString"
+          "allOf": [
+            {
+              "$ref": "#/$defs/nonEmptyString"
+            }
+          ],
+          "description": "Pinned commit. Optional when local resolves to a Git checkout with a current commit."
         }
       }
     },