@c4a/context-cli 0.6.18 → 0.7.0

package/providers/context/resources/procedures/code-extraction.md

@@ -27,6 +27,10 @@ selected package's public SDK/README before editing `src/index.ts`; never infer
 its API from bundled output. `moduleTypeEvidence` must identify the inspected
 paths that support the classification. An `unknown` unit or a unit with no
 classification evidence is an incomplete index plan.
+Record exact source-relative Markdown paths read during classification in
+`indexUnits[].documents`. Context inventories module Markdown independently:
+root README or documentation entry files require complete reading, while other
+related Markdown uses the reported Floor and Target coverage.
 
 For every custom extraction preview, Context probes source paths for known
 community structural capabilities: TypeScript symbols, React Router routes, Go
@@ -49,6 +53,15 @@ public-contract plan. Scan mode, repository collections, and custom extraction
 must declare their index units explicitly; an inferred plan is diagnostic only
 and cannot write candidates.
 
+Every index unit must expose one inventory contract. Built-in parsers produce
+it from AST and source traversal; a project adapter returns the same generic
+shape. The inventory separates eligible/analyzed files and non-empty LOC,
+discovered/read Markdown, discovered/analyzed/target/exported symbols, stable
+entries and profile-selected boundaries, plus excluded files and reasons. JSON,
+YAML, lockfiles and assets may be evidence but do not inflate source LOC.
+Evidence-only adapter output is explicitly `unscorable` and cannot pass the
+mechanical quality Gate as a complete module index.
+
 Extractor output shape must match the semantic plan. `extractTs()` projects one
 candidate page per selected symbol and assigns each source to one index unit;
 it is suitable for a deliberately granular public reference. Aggregated module
@@ -64,6 +77,10 @@ separately, together with each index unit's output owner, output profile,
 projected Markdown count, total bytes, largest sampled page, and risk flags.
 For custom phases, also report detected structural probes, covered and uncovered
 probe counts, representative evidence paths, and the affected output profile.
+The preview command returns a bounded summary plus one digest-bound item view.
+Follow its `next_action.command` pages until `preview_items_complete` when the
+Route requires semantic scope, ownership, capability, or scale inspection;
+never recover omitted inventory with host-output slicing.
 Use resolved entry files, exported/internal counts, and symbol-kind counts as
 structural scope evidence only. Resolve TypeScript/JavaScript
 configuration and aliases through the extractor rather than guessing paths
@@ -82,13 +99,17 @@ rerun the batch preview, then process exactly one pending extraction target and
 evaluate again. Do not add a second classification Gate after the page-count
 Gate; a plan revision returns through the same configuration step.
 
-A batch-total page warning and quality risks such as a thin aggregate are
-advisory only. They remain visible for cost and content-shape review but do not
-become a new Gate. Legal scale recovery includes narrowing `include`, excluding
-generated or mirrored directories, enabling `exportedOnly`, moving from a
-symbol catalog to an aggregated `extractCustom()` plan, or registering real
-child sources. Splitting one `extractTs()` source into overlapping units is not
-a valid workaround.
+A batch-total page warning remains advisory. After extraction, independent
+mechanical dimensions enforce source analysis, target-boundary coverage,
+facts/explanation, evidence scope, implementation ratio, and page shape.
+Aggregate custom candidates are rendered only from evidence-scoped `sections`;
+free Markdown, empty optional sections, template instructions, and placeholders
+cannot become reader-facing knowledge. A required Section without evidence is a
+material/capability gap instead of an empty heading. Legal scale recovery
+includes narrowing `include`, excluding generated or mirrored directories,
+enabling `exportedOnly`, moving from a symbol catalog to an aggregated
+`extractCustom()` plan, or registering real child sources. Splitting one
+`extractTs()` source into overlapping units is not a valid workaround.
 
 Current previews are cached below `.tmp/context-runtime/extract/previews/` and
 formal extraction reuses their validated structural result. Cache identity is
@@ -97,11 +118,17 @@ locks, and the preview protocol. Deleting
 `.tmp` only causes a fresh preview. Existing approved knowledge is not
 retroactively rejected solely because it is large.
 
+New workspaces write `knowledge/codeindex/**`. If an old workspace contains
+legacy `knowledge/codegraph/**`, follow the Route-returned
+`context migrate codeindex --format json` action. It rewrites formal collection
+identities and invalidates derived extraction/audit state without requiring
+`.tmp`. Never create a permanent dual-write or move the directory by hand.
+
 Do not open Review while another extraction target in the same batch remains.
 Unchanged approved or rejected symbols do not need another decision; new or
 changed candidates remain subject to the current Review policy.
 
-For TypeScript sources, Context also carries extractor-reported AST relations
+For TypeScript, JavaScript, TSX, and JSX sources, Context also carries extractor-reported AST relations
 between selected symbols. A relation is projected only when both endpoints
 resolve uniquely inside the selected module; external, unselected, and
 ambiguous endpoints are counted as omissions instead of guessed. The extract
@@ -119,7 +146,7 @@ source-backed extraction that found no approved edges from an older or
 otherwise unknown relationship mode. Never infer missing edges from symbol
 co-occurrence, filenames, or package size.
 
-When the built-in TypeScript extractor cannot represent the code source, use a
+When the built-in ECMAScript-family extractor cannot represent the code source, use a
 declared `extractCustom` phase. The project-owned callback returns candidate
 semantics plus structured source evidence; Context owns canonical refs,
 fingerprints, candidate storage, Review snapshots, freshness, and rerun cleanup.
@@ -148,10 +175,11 @@ empty or guessed graph.
 
 After every complete code-extraction batch, the Route produces one batch-level
 code-index audit. Mechanical signals cover content depth, evidence scope,
-declared-source coverage, and structured handoffs. They are review evidence,
-not an automatic numeric rejection: the Agent must inspect the affected pages
-and submit one `accept`, `revise`, or `request-input` decision for all index
-units together.
+declared-source coverage, and structured handoffs. A dimension outside its
+absolute bounds is a mechanical rejection and cannot be accepted. Advisory or
+elevated signals inside those bounds remain review evidence: the Agent must
+inspect the affected pages and submit one `accept`, `revise`, or
+`request-input` decision for all index units together.
 
 Do not split this into one confirmation per module. In fully managed operation,
 real issues select `revise` and the Route returns through project configuration,

package/providers/context/resources/procedures/code-index-audit.md

@@ -10,17 +10,78 @@ This Route is a required semantic review of the complete proposed code index.
 The CLI reports mechanical signals; the Agent reads the affected candidate
 content and evidence, compares registered sources with the user-confirmed
 scope, and decides whether the index is fit for its declared output profiles.
+Reader metrics exclude Context lifecycle comments and evidence annotations.
+Improve the source-backed knowledge itself; do not change Markdown syntax,
+sentence count, or pagination solely to influence a mechanical counter.
+The complete inventory is evidence, not the default reader-facing output. Do
+not create one sentence, bullet, table row, or page for every discovered file
+or symbol merely to satisfy coverage or density. Group related identities by a
+reader-visible capability, entrypoint, protocol boundary, lifecycle stage, or
+handoff, then explain the group's responsibility, stable inputs and outputs,
+state or failure boundary when applicable, next handoff, and exact supporting
+sources. A granular catalog is appropriate only for a declared public API,
+protocol, or command reference.
 
-The report is not a numeric rejection. A signal may be a false positive, but
-it may not be ignored. Every elevated signal must receive an assessment tied
-to inspected content. Submit one `context.code-index-audit-decision.v1`
-payload for the complete batch.
+When the report shows low density, add source-backed explanation or a complete
+relationship chain. Never add repeated `Observed ...` rows. When symbol
+coverage is low, use a verified evidence-backed group or a profile-appropriate
+catalog instead of copying the inventory into prose. Normalized template
+repetitions do not count as semantic facts, and enumeration-heavy output has a
+profile-specific ceiling.
+
+Identity groups and chain candidates are mechanical contracts, not optional
+notes. A group counts only when its members belong to the target inventory, its
+source files belong to the eligible inventory, and its reader-facing page cites
+those files. Every chain candidate must be documented, merged into a documented
+candidate, excluded with a concrete reason, or routed to missing-material input.
+For each discovered external boundary family, retain a representative
+source-backed chain or an explicit material gap.
+When the boundary inventory contains adjacent families such as operation and
+handler, handler and downstream, command and effect, event and processor, or a
+cross-source handoff, the adapter must return the corresponding candidate
+family. Returning an empty candidate list does not bypass chain review.
+
+The report contains no aggregate score. Every dimension is computed
+independently with its observed value, floor, recommended target, ceiling,
+mechanical score, uncovered identities, and legal repair actions. A dimension
+outside its absolute bounds cannot be accepted or offset by another strong
+dimension. Every elevated signal must receive an assessment tied to inspected
+content. Submit one `context.code-index-audit-decision.v1` payload for the
+complete batch.
+
+Read the complete digest-bound inventory before deciding. The Route-selected
+audit resource returns one budget-safe inspection command. Execute it and then
+each returned `next_action.command` until `audit_items_complete`; do not use
+host output truncation or shell slicing as pagination. The item stream separates
+eligible and analyzed files/LOC, read documents, target and exported symbols,
+stable entries, protocol boundaries, exclusions, and parser gaps. For each
+failed or below-target dimension, use the returned uncovered identities,
+affected pages, recommended template resources, and action vocabulary. Do not
+replace those facts with an inferred file list.
+
+For custom adapters, file and symbol identity arrays are complete denominators,
+not samples: their lengths must match the declared counts, analyzed identities
+must belong to eligible identities, and exported identities must belong to the
+target-symbol set. For a single-source unit, the CLI independently enumerates
+the represented language families plus Markdown/MDX after declared exclusions;
+an adapter cannot make its ratio pass by reporting only hand-picked evidence
+files. Conventional sibling page entries, Go route-register calls, and exported
+operations from a declared Go handler source of truth are also independently
+enumerated; include every discovered identity in the target-symbol and boundary
+denominators even when one aggregate page explains them. Section evidence may
+contain multiple files and may overlap
+another Section when one fact crosses a boundary. It must not be reduced to one
+arbitrary primary file, and every Section must not repeat the complete page
+evidence set merely to satisfy coverage. Distinct structured relationships must
+cite the concrete evidence for their own handoff instead of repeating one whole
+page evidence set across every destination.
 
 ## Decisions
 
-- `accept`: the requested scope is represented and every real content-depth,
-  evidence-scope, and relationship issue is resolved. An acceptable or
-  non-applicable signal needs a concrete reason.
+- `accept`: the requested scope is represented, every dimension is within its
+  absolute bounds, and every real content-depth, evidence-scope, template, and
+  relationship issue is resolved. A below-target dimension remains visible
+  and needs a concrete reason in ordinary operation.
 - `revise`: one or more real problems remain. Identify the affected units and
   describe changes to scope, aggregation, sections, evidence, or structured
   handoffs. The Route returns to `src/index.ts`, Preview, extraction, and a new
@@ -31,13 +92,22 @@ payload for the complete batch.
 
 ## Fully managed operation
 
-Fully managed authority does not auto-accept this audit. When a signal is a
-real problem, choose `revise` and continue the revision loop without asking the
-user. Repeat until the proposed index matches the requested scope and its
-module maps, contracts, and handoffs contain useful source-backed explanation.
-Pause only for unavailable material, source access, tool failure, or a
-concrete no-progress blocker.
+Fully managed authority does not bypass the audit. When an absolute dimension
+fails, choose a returned repair action and continue through configuration,
+Preview, extraction, and audit without asking the user. Aim for the recommended
+target instead of stopping immediately at the floor. The retry ledger is bound
+to unit, source revision, profile, and problem fingerprint; superficial wording
+changes do not reset it. After three unsuccessful revisions of the same
+problem, Context combines all affected modules into one human-guidance Gate.
+Pause earlier only for unavailable material, source access, or missing parser
+capability.
 
 After each decision, briefly tell the user which decision was selected, the
 affected units, and the next Graph path. Do not stop a managed run merely to
 announce a successful automatic revision.
+
+The current `context.code-index-audit-report.v2` is computed from proposed or
+approved knowledge. Only its decision receipt and compact retry metrics stay
+under `.tmp/context-runtime/code-index-audit/`. Package output records only the
+selected report digest and decision; page metrics, exclusions, template
+fingerprints, and repair history are never published.

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

@@ -47,3 +47,12 @@ asset links. If a selected local
 boundary is a documentation site rather than plain Markdown, use the
 Context-provided processor/configuration diagnostic; do not invent rendered
 text or scan outside the confirmed boundary.
+
+For Lark reads, Context prefers the authenticated user identity. If that
+identity is unavailable because its credential is missing, expired, or cannot
+be refreshed, Context may retry the same registered source with the bot
+identity. It does not switch identity after a permission or missing-scope
+response. Once selected, the same identity is used for the document body and
+all embedded resources. If `docs +fetch` lacks the required `--doc-format`
+capability, follow the returned `lark-cli update` recovery and rerun the same
+Route command; do not replace the capture with a hand-written export.

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

@@ -4,40 +4,107 @@ 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. `high` signals cannot be kept unchanged. Name every remaining
+  `review` 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.
+Signals marked `high` are deterministic presentation obligations. A repair or
+reshape is rescanned against the effective replacement and cannot complete
+while one of those signals remains. Signals marked `review` require semantic
+inspection and may be kept only with the signal-specific assessment below.
+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.
+
+If the same current-batch quality problem fails three consecutive apply
+attempts, stop the automatic revision loop and follow
+`route.document-optimization.guidance-required`. Present one aggregated report
+for all affected Sections and ask for content-organization, source-fidelity, or
+missing-material direction. Do not restart Sections that already pass. A
+successful complete-batch apply clears the temporary retry record; retry
+history is never knowledge or package content.
+
+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. It also rescans every repair and reshape against the same
+mechanical analyzer before writing the revision; submitting a decision is not
+proof that the effective Markdown is clean. A repair or reshape that retains a
+review-confidence signal must include a Section-specific assessment naming
+that signal. The apply result reports each signal as `resolved` or `justified`
+with its source and post-revision range. The assessment and rescan detail are
+used only to audit the current decision and are 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/resources/semantic/code-index/templates/adapter.md

@@ -89,6 +89,15 @@ helper separately.
 Add structured edges only for concrete registration and call paths. Keep a
 narrative locator when dynamic dispatch prevents an unambiguous edge.
 
+Return `identityGroups` when several target identities share one explained
+adapter responsibility. Return every source-backed adjacency in
+`chainCandidates`, then provide one `chainCandidateDecisions` record for each
+candidate. A documented decision names the reader-facing view and emits its
+structured edge; an equivalent candidate merges into that canonical candidate;
+false positives and missing external material use `exclude` or `request-input`
+with a concrete reason. Read `contracts-and-chains.md` for the complete generic
+contract.
+
 ## Template composition examples
 
 - An HTTP endpoint backed by an RPC client is `api-service` + `adapter`; combine

package/providers/context/resources/semantic/code-index/templates/contracts-and-chains.md

@@ -0,0 +1,81 @@
+---
+id: semantic.code-index.template.contracts-and-chains
+kind: procedure
+media-type: text/markdown
+---
+
+# Contracts, identity groups, and execution chains
+
+Use this resource after module classification when a code index must connect
+stable identities without turning the inventory into reader-facing prose. It
+applies to application, service, library, runtime, command, adapter, and
+cross-source units.
+
+## Separate inspection facts from reader content
+
+The adapter inventory is complete machine evidence. A reader page should group
+members only when they share a source-backed responsibility, boundary, or
+lifecycle. Do not create one sentence, bullet, row, or page per discovered
+identity.
+
+An `identityGroups` record must provide:
+
+- a stable group `id`;
+- the exact target `members` from the same index-unit inventory;
+- one reader-facing `viewRef` that explains their common responsibility;
+- `sourceFiles` from the eligible-file inventory that prove membership.
+
+The referenced page must cite every declared source file. A group does not pass
+coverage merely because its members exist in frontmatter or evidence.
+
+## Discover chain candidates
+
+Emit a candidate only when code structure or an authoritative declaration
+supports both adjacent endpoints. Supported families are:
+
+- `entry-operation`;
+- `operation-handler`;
+- `handler-downstream`;
+- `event-processing`;
+- `command-effect`;
+- `export-implementation`;
+- `cross-source-handoff`.
+
+Each candidate records a stable `id`, `from`, `to`, confidence, and the exact
+eligible `sourceFiles` that support the adjacency. Imports, filenames, symbol
+co-occurrence, or similar names alone are ambiguous evidence; mark such a
+candidate ambiguous or request material instead of asserting a runtime chain.
+
+## Decide every candidate
+
+Every discovered candidate receives exactly one decision:
+
+- `document`: add a source-backed structured edge and name its reader-facing
+  `viewRef`;
+- `merge`: point `canonicalChainId` at an equivalent candidate whose decision
+  is `document`;
+- `exclude`: explain why the static match is not a stable runtime relation;
+- `request-input`: explain which external protocol, runtime registration, or
+  authoritative material is missing.
+
+Decision coverage is 100%. Excluding all candidates does not close an external
+boundary family: at least one representative chain must be documented, merged
+into a documented chain, or explicitly require material.
+
+## Reader-facing chain blueprint
+
+```markdown
+## <Reader goal or boundary>
+
+<Explain the starting trigger and the stable outcome.>
+
+1. **Entry or trigger** — <identity and responsibility>.
+2. **Operation or handler** — <validation, transformation, or state change>.
+3. **External handoff or effect** — <contract, ownership, and next boundary>.
+
+Failure and retry boundary: <only source-backed behavior>.
+Evidence: <section-scoped locators for each adjacent handoff>.
+```
+
+Remove stages that do not apply. Do not leave empty template headings, repeat a
+module inventory, or infer missing runtime behavior.