@c4a/context-cli 0.6.19 → 0.7.0

package/indexers/bundles/context-code-indexer/references/metrics.md

@@ -0,0 +1,201 @@
+# Profile metric revision guide
+
+Use the current CLI audit as the sole source of actual, recommended, and hard values. This guide explains how to revise a Result; it does not define thresholds or authorize changing a denominator.
+
+## inventory-disposition-coverage
+
+### Meaning
+
+Every identity in the CLI inventory needs an owned, excluded, or unsupported disposition.
+
+### Revise
+
+Return decisions for the reported missing identities, preserving the complete inventory denominator and citing the evidence behind exclusions or unsupported cases.
+
+### Positive example
+
+An internal generated file is retained in the inventory and marked excluded with its generated-source evidence.
+
+### Anti-example
+
+The Result omits files that did not fit the selected template.
+
+## duplicated-fact-target-ratio
+
+### Meaning
+
+The same reader fact should have one canonical target rather than competing copies across Artifacts.
+
+### Revise
+
+Choose the canonical owner, replace other copies with explicit relationships, and keep evidence on the owning fact.
+
+### Positive example
+
+One contract Artifact owns the request semantics while the overview links to it.
+
+### Anti-example
+
+Several pages repeat the same behavior paragraph with different headings.
+
+## narrative-enumeration-ratio
+
+### Meaning
+
+Reader prose should explain capabilities and boundaries instead of restating a deterministic inventory as sentences.
+
+### Revise
+
+Move exhaustive identities into the deterministic catalog, group related items by a reader question, and explain responsibility, differences, and handoffs.
+
+### Positive example
+
+A capability section explains dispatch choices and links to a complete generated route catalog.
+
+### Anti-example
+
+The page turns every discovered symbol into an “observed” bullet.
+
+## normalized-template-repetition-ratio
+
+### Meaning
+
+Repeated sentence frames with only identity substitutions indicate template residue rather than evidence-specific explanation.
+
+### Revise
+
+Merge repeated observations, describe the shared rule once, and record meaningful exceptions with their own evidence.
+
+### Positive example
+
+A family section states the common lifecycle and separately explains the exceptional member.
+
+### Anti-example
+
+Every member receives the same sentence with only its name changed.
+
+## implementation-body-ratio
+
+### Meaning
+
+Reader knowledge should describe stable behavior without copying implementation bodies, generated payloads, or declaration dumps.
+
+### Revise
+
+Replace copied code with an evidence-bound behavioral statement and retain only a small excerpt when it is necessary to explain a contract or failure boundary.
+
+### Positive example
+
+The page explains the validation and rollback sequence and links to the exact implementation locator.
+
+### Anti-example
+
+The page embeds the complete function or generated type file as its main content.
+
+## reference-only-reader-targets
+
+### Meaning
+
+A reader target requires a CLI-authorized declaration, registration, public contract, approved Subject, or Partition Subject identity.
+
+### Revise
+
+Merge aliases and ordinary references into their canonical owner, or remove the target when no authorized identity observation exists.
+
+### Positive example
+
+A re-export alias points to the canonical public target instead of creating another page.
+
+### Anti-example
+
+A frequently imported helper becomes a target solely because it has many references.
+
+## unresolved-ordinal-partitions
+
+### Meaning
+
+Partition identity must come from a stable semantic boundary, not traversal order or a fixed batch label.
+
+### Revise
+
+Regroup members by capability, entrypoint, lifecycle stage, state owner, protocol boundary, or handoff; if none applies, return the protocol outcome for CLI-owned catalog fallback.
+
+### Positive example
+
+Handlers are grouped by the reader-visible protocol capability they implement.
+
+### Anti-example
+
+Files are divided into successive numbered batches to reduce page size.
+
+## discretionary-artifacts-per-logical-unit
+
+### Meaning
+
+Optional Artifacts must answer distinct reader questions allowed by the selected Bundle variant.
+
+### Revise
+
+Remove unsupported optional Artifacts, merge overlapping ones, or select another CLI-eligible variant when canonical facts justify it.
+
+### Positive example
+
+An examples Artifact is retained because it explains a distinct usage scenario with independent evidence.
+
+### Anti-example
+
+The Result creates extra pages to spread the same prose across a larger Bundle.
+
+## example-candidate-decision-coverage
+
+### Meaning
+
+Every CLI-discovered example candidate needs one explicit terminal or merge decision.
+
+### Revise
+
+Decide each reported candidate as linked, merged, documentation-only, excluded with reason, or blocked by a material request.
+
+### Positive example
+
+A duplicate scenario is merged into a canonical example through its full example identity.
+
+### Anti-example
+
+Unclear examples disappear from the Result without a disposition.
+
+## example-representative-coverage
+
+### Meaning
+
+Eligible scenarios need retained representatives that explain setup, key calls, parameters, and expected behavior.
+
+### Revise
+
+Promote or merge evidence-backed examples for the reported uncovered scenarios and close each required facet explicitly.
+
+### Positive example
+
+A canonical example covers the scenario and records evidence-backed not-applicable facets.
+
+### Anti-example
+
+A path is listed as an example without explaining how or why it is used.
+
+## example-public-target-linkage
+
+### Meaning
+
+Eligible examples should resolve to the exact public target they demonstrate whenever that target exists.
+
+### Revise
+
+Resolve aliases, repair the terminal decision chain, and bind the representative to the CLI-supplied public target identity.
+
+### Positive example
+
+A scenario variant merges into a representative whose terminal decision links the canonical public target.
+
+### Anti-example
+
+An example is linked to a similarly named internal helper or only to a directory.

package/indexers/bundles/context-code-indexer/templates/adapter-integration.md

@@ -0,0 +1,119 @@
+---
+id: context.code-indexer.template.adapter-integration
+kind: procedure
+media-type: text/markdown
+---
+
+# Adapter, bridge, and integration template
+
+Use for `adapter-integration`: 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.
+
+Use the exact profile and Artifact policy variant supplied by the workset. For
+an inbound operation surface, combine this template with the selected gateway
+or protocol evidence without creating a second operation registry.
+
+## 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.
+
+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-integration`; 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-generated-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.

package/indexers/bundles/context-code-indexer/templates/api-service.md

@@ -0,0 +1,118 @@
+---
+id: context.code-indexer.template.api-service
+kind: procedure
+media-type: text/markdown
+---
+
+# API service and gateway template
+
+Use after classifying an inbound HTTP, RPC, GraphQL, message-request, or similar
+surface as `api-service`. A module that only calls a remote API is a protocol
+consumer, not automatically an API service. Gateways that translate to another
+protocol normally also selects `adapter-integration`.
+
+Use the exact profile and Artifact policy variant supplied by the workset. If
+the reader goal is primarily the transformation between inbound and outbound
+boundaries, use the selected adapter-integration profile and retain one
+canonical operation registry.
+
+## Evidence pass
+
+Locate and connect:
+
+- process/server entry and service startup;
+- route, method, resolver, or service registration;
+- middleware, authentication, authorization, validation, and request context;
+- handler dispatch and the first stable domain/downstream boundary;
+- authoritative IDL, OpenAPI, schema, service definition, or registration;
+- response/error mapping, retry, timeout, and compatibility behavior;
+- configuration, local run, test, deployment, and release entrypoints;
+- generated models or clients and their actual source of truth.
+
+Prefer explicit registrations over handler filenames. Sample enough operations
+from each registration family to verify that the proposed aggregation is real.
+
+## Questions the knowledge must answer
+
+1. What protocol does the module provide, and where is it registered?
+2. Which operations are stable and who handles each one?
+3. What authentication, validation, middleware, or request context applies?
+4. Where does each operation hand off to domain logic or a downstream system?
+5. How are successful responses and failures translated?
+6. Which schema is authoritative, and which files are generated projections?
+7. How is the service run, configured, observed, and released?
+
+## Suggested knowledge units
+
+- **Service boundary**: responsibility, startup, supported protocols,
+  middleware order, downstream systems, and ownership.
+- **Operation registry**: use the canonical operation record from
+  `protocol-boundary.md`, adding handler and middleware detail from this
+  template rather than creating a second registry.
+- **Dispatch and dependency map**: route/service registration to handler to
+  domain/RPC/repository boundary, grouped by coherent operation family.
+- **Error and compatibility contract**: only when status/error mapping,
+  versioning, fallback, or compatibility is stable and source-backed.
+- **Runtime and delivery guide**: configuration, startup, diagnostics,
+  deployment, and release entrypoints owned by this service.
+
+Do not create a page per generated request/response model, constant, converter,
+pack/unpack helper, or handler-local function.
+
+## Chapter blueprints
+
+A service-boundary page may use:
+
+```markdown
+# <Service> boundary
+## Responsibility and consumers
+## Startup and protocol registration
+## Middleware and request lifecycle
+## Operation families
+## Domain and downstream dependencies
+## Error, timeout, and compatibility behavior
+## Configuration, observability, and release
+## Exclusions and authoritative schemas
+```
+
+A focused execution-path page may use:
+
+```markdown
+# <Operation> execution path
+## Inbound contract
+## Middleware and validation
+## Handler orchestration
+## Domain/downstream handoff
+## Response and error mapping
+## Source-backed edges
+```
+
+## Granularity and relationships
+
+Aggregate operations that share registration, middleware, handler family, and
+downstream ownership. Split when operation families have different contracts,
+owners, or execution paths—not merely because they are separate methods.
+
+Record a route-to-handler or handler-to-downstream edge only when the route
+table, registration, call site, or parser evidence is unambiguous. Generated
+types can locate fields but do not prove runtime behavior.
+
+## Template composition examples
+
+- A gateway that receives HTTP and calls RPC reads `adapter-integration.md` and
+  `protocol-boundary.md` in addition to this template.
+- An RPC service containing stable domain orchestration also reads
+  `domain-service.md`.
+- An event-triggered endpoint may require `event-flow.md`; background consumers
+  use `background-runtime.md`.
+
+## Revise or stop when
+
+- no registration or authoritative operation identity is available;
+- the plan lists handlers without connecting them to provided operations;
+- the only contract source is generated code with an unknown upstream schema;
+- security or error behavior would be guessed from names;
+- scan mode would expand models and helpers into hundreds of pages.
+
+Return a `request-material` disposition tied to a blocking material-question
+proposal when required protocol semantics remain unavailable before preview.

package/indexers/bundles/context-code-indexer/templates/background-runtime.md

@@ -0,0 +1,109 @@
+---
+id: context.code-indexer.template.background-runtime
+kind: procedure
+media-type: text/markdown
+---
+
+# Background runtime template
+
+Use for `background-runtime`: queue or stream consumers, scheduled jobs,
+pipelines, functions, controllers, watchers, and long-running agents activated
+by a trigger instead of an interactive request.
+
+Use the exact profile and Artifact policy variant supplied by the workset.
+
+## Evidence pass
+
+Locate:
+
+- process/runtime bootstrap and worker/job registration;
+- trigger identity: topic, queue, schedule, hook, file, controller event, or
+  platform invocation;
+- payload/schema locator and producer when available;
+- handler dispatch, concurrency, partitioning, ordering, and state changes;
+- downstream services, persistence, emitted events, and side effects;
+- retry, timeout, checkpoint, idempotency, dead-letter, and recovery behavior;
+- configuration, scaling, health, observability, deployment, and ownership;
+- replay/test fixtures and generated payload types that are not authoritative.
+
+Distinguish code defaults from runtime configuration. Do not describe delivery
+guarantees unless registration, framework configuration, or maintained
+documentation proves them.
+
+## Questions the knowledge must answer
+
+1. What activates the runtime and where is that trigger registered?
+2. What input contract is consumed, and who produces it?
+3. How does work move from dispatch through orchestration and side effects?
+4. What are the concurrency, ordering, retry, and idempotency boundaries?
+5. How does the runtime checkpoint, recover, or surface failed work?
+6. How is it configured, operated, observed, scaled, and deployed?
+
+## Suggested knowledge units
+
+- **Runtime map**: bootstrap, trigger families, handler registry, dependencies,
+  state boundaries, and operating model.
+- **Trigger/workflow registry**: stable trigger identity, input contract,
+  handler, downstream effects, retry/idempotency, and source locator.
+- **Processing flow**: focused end-to-end path for a high-value workflow family.
+- **Recovery and operations guide**: checkpointing, failed work, observability,
+  configuration, local execution, deployment, and safe replay where evidenced.
+- **Producer-consumer chain**: only when both registered modules and the event
+  identity are source-backed.
+
+## Chapter blueprints
+
+```markdown
+# <Background runtime> map
+## Responsibility and activation model
+## Bootstrap and trigger registration
+## Workflow or handler families
+## State and downstream side effects
+## Concurrency, ordering, retry, and idempotency
+## Failure recovery and observability
+## Configuration, scaling, and deployment
+## Contract sources and exclusions
+```
+
+For a trigger family:
+
+```markdown
+## <Trigger or workflow>
+- Trigger identity and registration:
+- Input contract and producer:
+- Dispatch and handler:
+- State changes and downstream effects:
+- Retry/idempotency/checkpoint behavior:
+- Failure destination and operator action:
+- Source evidence:
+```
+
+## Granularity and relationships
+
+Prefer one record per stable trigger or coherent workflow family. Do not create
+one page per handler helper, event field, retry branch, or generated payload
+type. Split a page when triggers have different contracts, ownership, delivery,
+or recovery semantics.
+
+Every retained page must name concrete trigger, handler, state, side-effect,
+and recovery identities with source locators. A runtime page that only lists
+directories or says a worker “processes events” is too thin.
+
+Connect producers and consumers only through a concrete topic/trigger/schema
+identity. A shared type name or import is insufficient.
+
+## Template composition examples
+
+- A consumer that invokes a domain boundary reads `domain-service.md`.
+- A scheduler that calls external APIs selects `adapter-integration` and reads
+  `protocol-boundary.md`.
+- A controller exposing administrative commands may combine this template with
+  `cli-tool.md` or `api-service.md`, but should still produce one runtime map.
+
+## Revise or stop when
+
+- no trigger registry or executable worker entry can be found;
+- delivery, ordering, retry, or idempotency would be guessed;
+- the producer or authoritative payload contract is required but unavailable;
+- the plan expands generated event structures or helpers one symbol per page;
+- runtime configuration cannot be distinguished from test setup.

package/indexers/bundles/context-code-indexer/templates/cli-tool.md

@@ -0,0 +1,129 @@
+---
+id: context.code-indexer.template.cli-tool
+kind: procedure
+media-type: text/markdown
+---
+
+# CLI and developer tool template
+
+Use for `cli-tool`: command-line applications, developer tools, administrative
+executables, generators, and command-driven plugin hosts. A build script used
+only internally does not need a CLI knowledge unit unless it is a supported
+operator or contributor surface.
+
+Use the exact profile and Artifact policy variant supplied by the workset.
+
+## Evidence pass
+
+Locate:
+
+- executable/bin entry, runtime requirement, and command parser;
+- root and nested command registration;
+- positional arguments, flags, defaults, mutually exclusive options, and input
+  schemas;
+- configuration files, environment variables, profiles, credential sources,
+  and precedence;
+- interactive prompts versus non-interactive/automation behavior;
+- filesystem, repository, network, platform, and plugin side effects;
+- output formats, stdout/stderr behavior, exit codes, polling, and recovery;
+- local development, packaging, installation, compatibility, and release;
+- deprecated commands, aliases, parser helpers, and formatters to exclude.
+
+Inspect actual command registration and representative execution paths. Help
+text is useful evidence but may not describe hidden preconditions or effects.
+
+## Questions the knowledge must answer
+
+1. How is the CLI installed or invoked, and what runtime does it require?
+2. What stable command families exist and what user outcomes do they produce?
+3. What inputs, configuration, credentials, and precedence rules apply?
+4. Which commands mutate files, repositories, remote services, or user state?
+5. What output and exit behavior supports automation and diagnosis?
+6. Which plugin or extension points change the command surface?
+7. How does a user recover from common source-backed failure states?
+
+## Suggested knowledge units
+
+- **Command map**: invocation model, command families, configuration,
+  credentials, side effects, output formats, and extension points.
+- **Task workflow**: an end-to-end supported user goal spanning several
+  commands, with preconditions, state transitions, and recovery.
+- **Command-family reference**: coherent subcommands with inputs, outputs,
+  side effects, and examples.
+- **Configuration and credentials**: when precedence or environment behavior is
+  complex and stable enough for a dedicated page.
+- **Plugin/extension contract**: use the single complete blueprint in
+  `plugin-extension.md`; the command map only links commands and configuration
+  to that contract.
+- **Development and release guide**: only source-backed contributor workflows
+  owned by this module.
+
+## Chapter blueprints
+
+```markdown
+# <CLI> command map
+## Purpose, installation, and invocation
+## Command families
+## Configuration and precedence
+## Credentials and external dependencies
+## Filesystem/repository/remote side effects
+## Output formats and exit semantics
+## Plugins, compatibility, and release
+## Diagnostics, recovery, and exclusions
+```
+
+For a command family:
+
+```markdown
+# <Command family>
+## User outcomes and preconditions
+## Commands and arguments
+## Configuration and credential requirements
+## Execution and side effects
+## Output and exit behavior
+## Failure recovery
+## Source-backed examples
+```
+
+A workflow page may use:
+
+```markdown
+# <User task>
+## Starting state
+## Command sequence
+## State and artifact changes
+## Remote operations
+## Success checks
+## Recovery and rollback boundaries
+```
+
+## Granularity and relationships
+
+Prefer command families and user tasks over one page per parser node, flag,
+prompt, formatter, or implementation function. Split only when commands have
+different state ownership, external systems, or safety/recovery contracts.
+
+Every retained page must name real commands, task outcomes, state changes, or
+extension identities with source locators. A list of command directories or
+parser nodes is not a command map.
+
+Connect commands to configuration, package/file outputs, plugin providers, and
+platform operations only when source registrations or call sites prove them.
+
+## Template composition examples
+
+- A CLI with installable providers also reads `adapter-integration.md` and
+  `plugin-extension.md`.
+- A CLI that primarily wraps a remote protocol selects `adapter-integration` and
+  reads `protocol-boundary.md`.
+- A monorepo release tool may combine this template with
+  `monorepo-container.md` and the `development-and-delivery.md` composer
+  contract without duplicating its command registry.
+
+## Revise or stop when
+
+- no stable command registry or executable entry is found;
+- examples require inventing flags or commands not present in source;
+- side effects or credential behavior are unclear but material to safe use;
+- every option/parser helper is becoming an independent page;
+- deprecated or hidden implementation commands are presented as supported.