@c4a/context-cli 0.6.11 → 0.6.16

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

@@ -10,13 +10,33 @@ Code extraction operates on user-confirmed repository modules and source
 patterns. A source registration identifies the repository or module; the
 extraction declaration defines the code scope inside it.
 
-Before declaring a phase, run the extraction-scope Gate's inspection Action for
-every confirmed module. Read all reported `manifests`, including mixed-module
-signals, then use the route-selected Code Extractor Selection manual to choose
-`extractTs`, an optional structural package inside `extractCustom`, or a
-project-owned adapter. Read the selected package's public SDK/README before
-editing `src/index.ts`; never infer its API from bundled output. Do not silently
-substitute the TypeScript extractor for Go, Rust, or another unsupported source.
+Before declaring a phase, run the Route-selected batch inspection once for all
+confirmed modules. Read their manifests, module documentation, stable entries,
+and dependency/protocol locators. First record an evidence-backed classification
+for every module without reading an archetype template. A module has one primary
+`moduleType`, may declare additional `moduleTypes`, and may combine relevant
+`facets`. Only after classification, read every matching file from the Route's
+recommended `resources/semantic/code-index/templates/` directory and merge them
+into one deduplicated plan per user-visible module or aggregate.
+
+The target is a stable module map, public contract, protocol boundary, or
+runtime map—not a page for every function, variable, constant, or internal type.
+Use the Code Extractor Selection manual to choose `extractTs`, an optional
+structural package inside `extractCustom`, or a project-owned adapter. Read the
+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.
+
+For every custom extraction preview, Context probes source paths for known
+community structural capabilities: TypeScript symbols, React Router routes, Go
+symbols, Rush workspace structure, and source-owned protocol schemas. Every
+probe applicable to an index unit's output profile must be represented by the
+candidate evidence for that unit. A project adapter may aggregate and explain
+those facts in one high-value page, but it cannot replace a matched structural
+probe with a static template or a manually listed filename. Missing probe
+coverage is a `material-required` capability gap and uses the same
+non-delegatable capability Gate in ordinary and fully managed conversations.
 
 `include` filters files inside a selected source; it is not a package/module
 selector. Use source declarations to select repository modules. Use configured
@@ -24,14 +44,58 @@ entry patterns when entry-led traversal is meaningful, or scan mode when the
 selected module intentionally has no package entry. Do not require source-code
 rewrites merely to create an extraction entry.
 
-Use a dry-run when the current route requests scope inspection. Report
+Exports-only single-package TypeScript extraction has a compatible stable
+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.
+
+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
+maps, registries, protocol indexes, cross-module flows, or multiple units over
+one source require `extractCustom()` with explicit candidate ownership. For a
+monorepo, register independently visible children as separate sources before
+giving them separate `extractTs()` units.
+
+The Route runs one cache-writing batch preview after classification, template
+selection, and configuration, but before any candidate write. Report
 discovered files, AST-analyzed files, skipped files, symbols, and relations
-separately. Use resolved entry files, exported/internal counts, and symbol-kind
-counts as structural scope evidence only. Resolve TypeScript/JavaScript
+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.
+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
-from imports. Explain the scope without treating filenames or symbol kinds as
-semantic knowledge. After confirmation, process exactly one pending extraction
-target and evaluate again.
+from imports.
+
+Template examples never determine the expected page count. Scale policy is
+applied only to the measured batch preview and is fixed per index unit: at most
+100 pages continues normally,
+101–300 pages continues with a warning, and more than 300 pages stops at the
+non-delegatable extraction-scale Gate. Fully managed authority cannot bypass
+that Gate. Ambiguous output ownership and `material-required` capability gaps
+also stop before candidate writes. Ambiguous ownership returns to project
+configuration without creating another human Gate. Revise all affected units
+together, re-check whether their classification or selected templates changed,
+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.
+
+Current previews are cached below `.tmp/context-runtime/extract/previews/` and
+formal extraction reuses their validated structural result. Cache identity is
+bound to source scope, phase/adapter declarations, project `src/`, dependency
+locks, and the preview protocol. Deleting
+`.tmp` only causes a fresh preview. Existing approved knowledge is not
+retroactively rejected solely because it is large.
 
 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
@@ -45,6 +109,10 @@ receipt reports `relationships.detected`, `emitted`, and omission counts.
 Review materializes those source-backed relations with the approved symbol,
 and deterministic close refreshes the typed edge projection.
 
+Project-owned custom edges use `source-backed-explicit` rather than claiming
+AST derivation. They remain subject to the same evidence, endpoint, Review, and
+close projection checks.
+
 Zero edges remain a valid result. Read `close.relationshipCoverage` or the
 package inventory's `structure.relationship_coverage` to distinguish a current
 source-backed extraction that found no approved edges from an older or
@@ -56,6 +124,11 @@ 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.
 Do not use a generic `customPhase` callback to write lifecycle files directly.
+Large custom adapters may return candidates as an `AsyncIterable`; Context
+retains at most the proof boundary for an over-limit unit instead of collecting
+thousands of full Markdown candidates. A project-owned `inspect` adapter may
+report generic module/protocol findings and capability gaps without putting
+framework-specific rules in the community CLI.
 
 Prefer a reusable structural library over a project-local parser when one
 matches the confirmed source: `@c4a/extract-go` for Go facts,

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

@@ -0,0 +1,43 @@
+---
+id: procedure.document-optimization
+kind: procedure
+mediaType: text/markdown
+---
+
+# Document revisions
+
+This optional phase improves the presentation 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.
+
+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.
+
+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.
+
+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.

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

@@ -0,0 +1,31 @@
+---
+id: procedure.document-revision
+kind: procedure
+mediaType: text/markdown
+---
+
+# Conversational document correction
+
+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.
+
+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
+   by the returned plan. Check the cited source when the requested correction
+   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.
+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.
+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.
+
+If the entry returned more than one target candidate, select a candidate only
+when the user's wording or current conversation identifies it uniquely;
+otherwise ask the user which approved page to correct. Do not guess.

package/providers/context/resources/procedures/package-output.md

@@ -36,37 +36,13 @@ maintain the complete final Skill directory name in the template, such as
 Package output is incremental: a built package is current only for the approved
 knowledge and template digests recorded by its receipt.
 
-When declaring a new KB package, make resource delivery an explicit author
-choice. Offer Git raw when the workspace is in Git or the author supplies a
-raw `urlPrefix`; it keeps package payloads small and uses either the derived
-commit-pinned URL or that explicit prefix. Context does not check whether those
-files are committed, pushed, or remotely readable; that remains the package
-author's responsibility. If neither Git nor an explicit prefix is available,
-offer bundled resources or explicit omission; omission keeps unresolved links
-and must be described as such.
-
-Before falling back to bundled delivery for a non-GitHub remote, inspect the
-confirmed repository web URL or a known raw-file URL. When the Git service uses
-the GitHub-compatible same-host shape
-`https://<host>/<namespace>/<repository>/raw/<ref>/<path>`, prefer an explicit
-`urlPrefix` such as
-`https://git.example.com/team/knowledge/raw/{commit}`. Include the
-repository-relative workspace directory in that prefix when the Context
-workspace is nested below the repository root; Context appends the
-project-relative `knowledge/assets/...` path. Lack of built-in automatic
-derivation alone is not a reason to bundle. Prefer `{commit}` for immutable
-links; use a literal published ref only when the author intentionally wants it.
-If the service's raw convention or repository identity cannot be established,
-do not guess or probe an invented endpoint: ask the author for `urlPrefix`, or
-offer bundled delivery.
-
-Large image optimization applies only to bundled delivery. Without an `assets`
-declaration, existing workspaces continue to copy selected resources
-byte-for-byte. If build or status reports
-`package.assets.optimization-recommended`, explain that the current package is
-valid but contains more than 20 MiB of eligible PNG/JPEG resources. Do not
-install a dependency or edit project configuration automatically. If the user
-chooses to optimize the package, use the exact reported setup command and add
-the reported `kbPackage().assets.optimize` value. The processor is installed in the
-Context workspace, not bundled into Context itself. Optimization changes only
-`dist/`; source snapshots and approved resources remain unchanged.
+KB packages bundle referenced resources by default. Images are copied to
+`others/assets/`; when necessary, Context compresses supported images so each
+output image is at most 1 MiB and their combined package size is at most 40
+MiB. This changes only `dist/`, never captured or approved source resources.
+
+Configure `assets.delivery="git-raw"` only when the author explicitly wants
+external links and accepts responsibility for publishing and access. Use a
+confirmed immutable HTTPS prefix where possible; do not infer or probe an
+unknown host convention. Explicit omission keeps unresolved links and must be
+described as such.

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

@@ -0,0 +1,267 @@
+---
+id: semantic.code-index.classification
+kind: procedure
+media-type: text/markdown
+---
+
+# Classify code modules before choosing a template
+
+This procedure is the first semantic step for code extraction. Start from the
+Route-selected batch inspection. Do not open an archetype template and then fit
+the module to it. First classify every confirmed module from inspected evidence,
+then read only the matching templates.
+
+Classification determines which reader questions the index must answer. It
+does not grant access to undeclared sources, prove a relationship, or override
+the measured extraction preview.
+
+## 1. Use one batch evidence pass
+
+Use the inspection result for every confirmed module before opening more files.
+It already reports manifests, maintained documentation, entry candidates,
+protocol locators, lifecycle signals, and generic structural capabilities.
+Open source files only for unresolved facts, and follow stable registration or
+executable wiring rather than scanning the whole tree.
+
+Confirm, where applicable:
+
+- the module manifest or workspace registration;
+- its README or nearest maintained operating documentation;
+- build, executable, application, service, or library entrypoints;
+- route, command, service, event, job, plugin, or export registries;
+- authoritative protocol/schema locations and concrete consumer call sites;
+- generated, mirrored, vendored, legacy, test, fixture, and mock boundaries;
+- development, configuration, deployment, and release entrypoints owned by the
+  module.
+
+A language, framework dependency, exported symbol, or folder name does not by
+itself prove a module type.
+
+## 2. Record classification before reading templates
+
+Produce one batch table first:
+
+| module | primary type | additional types | facets | evidence paths | gaps |
+| --- | --- | --- | --- | --- | --- |
+| `customer-portal` | `web-application` | — | `page-routing`, `protocol-consumer` | `package.json`, `src/routes.ts` | upstream schema is external |
+| `edge-gateway` | `api-service` | `adapter` | `protocol-provider`, `protocol-consumer` | `cmd/server.go`, `api/openapi.yaml` | — |
+
+Each module must have:
+
+- one primary `moduleType` for concise reports;
+- every additional applicable type in `moduleTypes`;
+- relevant behavior and boundary `facets`;
+- concrete inspected paths in `moduleTypeEvidence`;
+- an explicit gap when available source cannot support a reliable claim.
+
+Choose the primary type from the boundary through which a reader most often
+enters the module. A gateway is normally `api-service`, a plugin-hosting command
+application is normally `cli-tool`, and a generated client is normally
+`sdk-library`; their translation or provenance roles remain additional types.
+
+Supported types are:
+
+- `web-application`: browser, native mobile, desktop, embedded, or cross-platform
+  interactive applications with routes, pages, screens, or host integration;
+- `api-service`: an HTTP, RPC, GraphQL, message-request, or similar inbound
+  protocol surface with dispatch to handlers;
+- `service`: a stable domain/use-case or reusable service boundary whose public
+  operations coordinate implementation or persistence;
+- `background-runtime`: workers, consumers, schedulers, pipelines, functions,
+  or long-running processes driven by triggers rather than interactive calls;
+- `sdk-library`: a reusable package with a deliberately supported consumer API;
+- `cli-tool`: an executable tool organized around commands, flags,
+  configuration, outputs, and exit behavior;
+- `adapter`: a bridge that translates protocols, identities, models, lifecycle,
+  or host capabilities between boundaries;
+- `monorepo-container`: a workspace whose stable value is its child-module,
+  ownership, dependency, build, or release topology;
+- `derived-source`: generated, mirrored, vendored, or legacy source whose
+  authority lives elsewhere;
+- `contract-source`: an authoritative IDL, API description, schema, or contract
+  registry used by providers, consumers, generators, or validators;
+- `unknown`: the source is insufficient to classify without guessing.
+
+`unknown` cannot be combined with a known type. A hybrid module may combine
+several known types. Independent infrastructure definitions, migration sets,
+or data-model projects that do not fit a supported type remain `unknown` and
+use a project-owned inspection/extraction adapter; do not force them into an
+unrelated application type.
+
+## 3. Add composable facets
+
+Facets identify behavior that may cross the primary type:
+
+- `page-routing`: concrete route, page, screen, or navigation registration;
+- `public-api`: a deliberately supported programmatic consumer surface;
+- `protocol-provider` / `protocol-consumer`: inbound or outbound operation
+  boundaries with authoritative locators;
+- `event-producer` / `event-consumer`: asynchronous trigger and delivery flow;
+- `persistence`: repository, datastore, cache, or durable-state boundary;
+- `plugin-extension`: discovery, activation, contribution, or host extension;
+- `configuration-runtime`: configuration or runtime selection that changes
+  observable behavior;
+- `build-release`: module-owned build, packaging, deployment, or release entry;
+- `cross-module-chain`: an evidenced flow joins two or more registered modules;
+- `generated-contract`: generated code represents or locates an upstream
+  schema but is not automatically authoritative.
+
+Require a registration, call site, schema locator, or runtime entry. A matching
+dependency alone is not evidence.
+
+## 4. Read matching templates
+
+After the batch table is complete, read every applicable type template and only
+the applicable facet template:
+
+| Type or facet | Template path |
+| --- | --- |
+| `web-application` | `resources/semantic/code-index/templates/web-application.md` |
+| `api-service` | `resources/semantic/code-index/templates/api-service.md` |
+| `service` | `resources/semantic/code-index/templates/domain-service.md` |
+| `background-runtime` | `resources/semantic/code-index/templates/background-runtime.md` |
+| `sdk-library` | `resources/semantic/code-index/templates/sdk-library.md` |
+| `cli-tool` | `resources/semantic/code-index/templates/cli-tool.md` |
+| `adapter` | `resources/semantic/code-index/templates/adapter.md` |
+| `monorepo-container` | `resources/semantic/code-index/templates/monorepo-container.md` |
+| `derived-source` | `resources/semantic/code-index/templates/derived-source.md` |
+| `contract-source` | `resources/semantic/code-index/templates/contract-source.md` |
+| `protocol-provider`, `protocol-consumer`, `generated-contract` | `resources/semantic/code-index/templates/protocol-boundary.md` |
+| `event-producer`, `event-consumer` | `resources/semantic/code-index/templates/event-flow.md` |
+| `persistence` | `resources/semantic/code-index/templates/persistence-boundary.md` |
+| `plugin-extension` | `resources/semantic/code-index/templates/plugin-extension.md` |
+| `cross-module-chain` | `resources/semantic/code-index/templates/cross-module-chain.md` |
+
+`page-routing` and `public-api` refine their matching application or library
+template. `configuration-runtime` and `build-release` add chapter expectations
+to the selected type template. They do not require duplicate pages.
+
+Templates are question sets and chapter blueprints. Omit unsupported sections,
+merge overlapping output, and retain concrete identifiers and source locators
+for every kept claim.
+
+## 5. Match the plan to the extractor
+
+Extractor shape is part of the plan, not an implementation detail:
+
+- `extractTs()` projects each selected symbol to its own candidate page. It is
+  suitable for a deliberately granular public reference, but it does not
+  produce an aggregated module map, registry, protocol index, or chain page.
+- `extractTs()` assigns ownership by source. A source can belong to only one
+  index unit in a phase. Splitting one source into several units or adding an
+  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.
+- 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.
+
+Do not wait for an expensive preview to discover that the chosen extractor
+cannot produce the planned page shape.
+
+## 6. Produce one deduplicated plan
+
+Create one `CodeIndexUnitPlan` per user-visible module or independently useful
+custom cross-module flow. A minimal plan has this shape:
+
+```ts
+{
+  module: "customer-portal",
+  moduleType: "web-application",
+  moduleTypes: ["web-application"],
+  facets: ["page-routing", "protocol-consumer"],
+  moduleTypeEvidence: ["package.json", "src/routes.ts"],
+  outputOwner: "customer-portal",
+  outputProfile: "application-map",
+  inputSources: ["repo:customer-portal"],
+  entries: ["src/bootstrap.ts", "src/routes.ts"],
+  protocols: ["api/openapi.yaml"],
+  excludes: ["dist/**", "**/*.test.ts"],
+  lifecycle: "source",
+  pageKinds: ["application-map", "route-registry", "protocol-boundary"],
+  capability: "complete"
+}
+```
+
+`outputProfile` is a closed value and selects structural coverage expectations:
+
+| Profile | Intended output |
+| --- | --- |
+| `module-map` | stable module responsibility and entry map |
+| `application-map` | application entry, route, state, and boundary map |
+| `protocol-index` | provider/consumer operations anchored to contracts |
+| `service-boundary` | service operations, orchestration, and dependencies |
+| `runtime-map` | triggers, processing, state, effects, and recovery |
+| `public-api-reference` | deliberately supported consumer API |
+| `command-map` | commands, options, effects, outputs, and recovery |
+| `adapter-contract` | inbound-to-outbound translation contract |
+| `module-registry` | workspace child modules, ownership, and topology |
+| `cross-module-flow` | evidenced handoffs across registered modules |
+| `provenance-only` | source identity, derivation, consumers, and authority |
+
+The preview also requires these evidence-scoped section kinds:
+
+| Profile | Required section coverage |
+| --- | --- |
+| `module-map` | `responsibility`, `entrypoint` |
+| `application-map` | `entrypoint`, `operation`, `handoff` |
+| `protocol-index` | `contract`, `operation`, `handoff` |
+| `service-boundary` | `operation`, `handoff` |
+| `runtime-map` | `entrypoint`, `operation`, `failure-recovery` |
+| `public-api-reference` | `contract` |
+| `adapter-contract` | `contract`, `handoff` |
+| `command-map` | `entrypoint`, `operation`, `failure-recovery` |
+| `module-registry` | `responsibility`, `source-authority` |
+| `cross-module-flow` | `operation`, `handoff`, plus at least one structured edge |
+| `provenance-only` | `source-authority` |
+
+The `build-release`, `persistence`, `configuration-runtime`, and
+`generated-contract` facets additionally require `delivery`, `state-boundary`,
+`state-boundary`, and `source-authority` respectively. A heading without an
+evidence-scoped section does not satisfy coverage.
+
+The profile affects structural probes and advisory risks. `pageKinds` remains
+free-form so projects can name useful page families, but use stable kebab-case
+tokens consistently within a project. Type templates provide recommended
+tokens.
+
+For a multi-module round, finish all classifications first, read the union of
+matching templates once, and revise affected plans together. Do not create a
+copy of the same operation or plugin record for each selected template.
+
+## 7. Capability gaps and preview
+
+Use `capability: "material-required"` when an unsupported parser, missing
+project adapter, absent evidence, or unresolved source boundary prevents the
+promised output. This typed capability is valid in ordinary and fully managed
+flows and stops both at the same Route Gate.
+
+Missing authority does not always block all output. For generated or mirrored
+source whose upstream schema cannot be located, a `provenance-only` unit may
+still record source identity, known derivation facts, and evidenced consumers.
+Keep field semantics and compatibility claims material-required. Stop the
+whole unit only when those semantics are the confirmed knowledge goal.
+
+Run the Route-selected batch preview after every plan is evidence-backed. Its
+projected Markdown count is authoritative per index unit:
+
+- up to 100 pages: continue;
+- 101–300 pages: report an advisory and continue;
+- more than 300 pages: block and revise, including in fully managed mode.
+
+A large batch also reports a batch-total advisory even when each unit remains
+within its limit. Advisory risks describe quality or cost; they do not become a
+new human Gate. `scale-limit-exceeded`, `ownership-ambiguous`, and
+`material-required` capability gaps remain blocking.
+
+Legal recovery includes narrowing `include`, excluding generated or mirrored
+areas, using `exportedOnly`, changing a symbol catalog into an aggregated
+`extractCustom()` output, or registering real child sources. Splitting one
+`extractTs()` source into overlapping units is not a valid workaround. Group all
+affected modules into one plan revision instead of creating one Gate per
+module.

package/providers/context/resources/semantic/code-index/templates/adapter.md

@@ -0,0 +1,109 @@
+---
+id: semantic.code-index.template.adapter
+kind: procedure
+media-type: text/markdown
+---
+
+# Adapter, bridge, and integration template
+
+Use for `adapter`: BFFs, protocol bridges, host integrations, plugin adapters,
+compatibility layers, gateways, and translators whose stable responsibility is
+to connect two boundaries. An ordinary internal helper that converts one object
+is not automatically an adapter module.
+
+Recommended `outputProfile`: `adapter-contract`. For an inbound gateway whose
+reader goal is the provided operation surface, use `protocol-index` instead.
+
+## Evidence pass
+
+Locate both sides of the boundary and the code that joins them:
+
+- inbound operation, event, command, host hook, or extension registration;
+- outbound operation, client, plugin contribution, or runtime capability;
+- authoritative input and output contract locations;
+- identity, field, enum, version, and lifecycle mappings;
+- authentication, authorization, credential, and context propagation;
+- validation, normalization, batching, caching, fallback, and compatibility;
+- timeout, retry, partial failure, and error/status translation;
+- configuration, feature selection, ownership, and release entrypoints;
+- generated DTOs/clients and converter helpers that should remain evidence.
+
+Sample representative paths from each mapping family. Do not claim a mapping
+from matching field names alone.
+
+## Questions the knowledge must answer
+
+1. Which two boundaries does the adapter connect, and who owns each one?
+2. What triggers the mapping and where is it registered?
+3. Which fields, identities, versions, or lifecycle states are transformed?
+4. Which values pass through unchanged, default, or intentionally disappear?
+5. How are credentials, context, errors, retries, and fallbacks translated?
+6. Which contracts are authoritative and which artifacts are generated?
+7. What compatibility obligation makes the adapter stable knowledge?
+
+## Suggested knowledge units
+
+- **Adapter contract**: responsibility, inbound/outbound boundaries,
+  registration, ownership, and authoritative contracts.
+- **Operation mapping registry**: use the canonical operation record from
+  `protocol-boundary.md` and add only adapter-specific transformation fields.
+- **Data or identity mapping**: only stable, non-trivial mappings that readers
+  must understand; summarize generated field copies.
+- **Lifecycle and failure translation**: when activation, cancellation,
+  retries, partial failure, or compatibility behavior is material.
+- **Cross-module execution path**: when both connected modules are registered
+  sources and the chain is source-backed.
+
+## Chapter blueprints
+
+```markdown
+# <Adapter> contract
+## Responsibility and connected boundaries
+## Activation or registration
+## Inbound contracts
+## Outbound contracts
+## Data, identity, and lifecycle mapping
+## Authentication and context propagation
+## Error, retry, fallback, and compatibility behavior
+## Configuration, ownership, and release
+## Evidence and exclusions
+```
+
+For adapter-specific detail attached to a canonical operation record:
+
+```markdown
+## Adapter transformation
+- Mapper/handler entry:
+- Field/identity/default transformations:
+- Context and credential propagation:
+- Error and fallback mapping:
+```
+
+## Granularity and relationships
+
+Group mappings that share the same boundary pair and transformation policy.
+Split when protocol authority, ownership, lifecycle, or failure semantics
+differ. Do not publish every DTO, converter, generated client, or transport
+helper separately.
+
+Add structured edges only for concrete registration and call paths. Keep a
+narrative locator when dynamic dispatch prevents an unambiguous edge.
+
+## Template composition examples
+
+- An HTTP endpoint backed by an RPC client is `api-service` + `adapter`; combine
+  one operation registry with one mapping contract rather than duplicating the
+  route facts.
+- A host plugin bridge reads `plugin-extension.md` and may also be `sdk-library`
+  when consumers import
+  a supported extension API.
+- A compatibility wrapper over generated clients also reads
+  `derived-source.md` and identifies the authoritative schemas.
+
+## Revise or stop when
+
+- either side of the adapter cannot be identified;
+- mappings are inferred only from same-named types or fields;
+- credential, identity, or error behavior would be guessed;
+- generated DTOs are replacing authoritative contracts in the plan;
+- the adapter page would merely say that one module “calls” another.