Declared Composition

Declared Composition is Renma's deterministic projection of required and optional relationships explicitly authored in a repository.

Renma models explicit composition, not general natural-language inheritance.

A Declared Composition report answers which Skills, Context Lenses and Context Assets belong to one resolved root's declared closure, which declarations include them, and which structural or governance problems need review. It does not prove which Context an agent loaded, selected, or used at runtime.

Expansion Contract

Renma expands only these normalized declaration forms:

Declaration	Target	Membership effect
requires_context	Context Asset	Required unless the route is already optional
optional_context	Context Asset	Makes this route and its descendants optional
requires_lens	Context Lens	Required unless the route is already optional
optional_lens	Context Lens	Makes this route and its descendants optional
requires_skill (Skill source only)	Skill	Required unless the route is already optional
optional_skill (Skill source only)	Skill	Makes this route and its descendants optional
Lens applies_to	Context Asset	Preserves the Lens route's membership

Renma does not expand references, conflicts, covered_by, superseded_by, ownership, lifecycle, policy inheritance, local support, static file references, or extends. Those relationships can still be validated or reported.

extends keeps its existing meaning: an overlay or profile relationship. It belongs only to a typed resolver that defines supported fields, merge and precedence behavior, conflicts, cycles, effective output, and provenance. Declared Composition does not generalize it into natural-language inheritance.

Declaration order is stable for review but has no semantic precedence. Renma does not implement first-wins, last-wins, implicit override, status-based selection, prose merging, or conflict winner selection.

Required And Optional Membership

• A route containing only required edges produces required membership.
• After a route crosses an optional edge, every descendant on that route stays optional, including a Context reached through a required descendant edge.
• A required Lens makes its applies_to Context required; an optional Lens makes it optional.
• When the same resolved asset (ID and source path) has required and optional routes, the asset is listed once as required while both kinds of provenance remain present.
• The root is reported separately and is not duplicated in the required list.
• Optional membership is a repository declaration, not a runtime choice made by Renma.

Assets with different stable IDs are never merged because their titles or contents look similar.

Finite Resolution And Provenance

The resolver operates over the existing catalog and tracks each resolved asset by declared ID and normalized source path in required and optional traversal states. Each state is processed at most once. A later required route upgrades final membership without discarding the optional state or its evidence.

One-off callers use the public resolver wrapper. Repository scans prepare the asset-ID, normalized-path, and dependency-by-source indexes once, then reuse them across roots. Member lists and governance checks visit only the root and reached IDs rather than filtering every catalog asset for every root.

Renma retains predecessor declaration edges rather than eagerly enumerating every root-to-node path. Each edge records source and target IDs, declared target, declaration form, membership, source path, line range, and raw snippet. This preserves multiple parents, duplicate declaration evidence, optional and required routes, and cycle-forming declarations while keeping storage proportional to assets and declarations instead of possible paths.

If required and optional traversal states produce the same resulting membership for one declaration, Renma records that declaration transition once. The transition identity includes source ID and path, declaration form and index, declared target, normalized relationship, and resulting membership. Distinct metadata entries retain distinct declaration indexes and evidence.

Completeness, Cycles, And Conflicts

requiredComplete is false when a required composition declaration is unresolved, originates from an invalid source kind, or resolves to the wrong target kind. Equivalent optional failures make optionalComplete false without changing required completeness. Source-kind validation is independent from target resolution, so an invalid applies_to source with an unresolved target retains both facts.

cycleFree is independent. A complete cycle such as Context A requiring Context B and Context B requiring Context A resolves to a finite closure:

requiredComplete: true
cycleFree: false

Focused reports retain their root-relative required and optional cycles. Scan findings group the same strongly connected component across roots and use the required diagnostic whenever any root reaches it as required, while preserving optional roots in structured details. Cycle asset IDs are a sorted member set, not an inferred path; Markdown lists the actual retained declarations instead. Cycles define no precedence and do not instruct a runtime to load an asset repeatedly.

Conflicts are normalized as stable unordered asset-ID pairs. A conflict where both members are required is stronger than a candidate involving an optional member. Reports retain the conflict declarations and inclusion provenance. Renma never selects a winner from order, lifecycle status, dates, popularity, or model inference.

Composition View

Use the existing graph command with one focus target:

renma graph . --view composition --focus skill.testing.spec-review --format json
renma graph . --view composition --focus skill.testing.spec-review --format markdown
renma graph . --view composition --focus skills/testing/spec-review/SKILL.md --format mermaid

The focus accepts the existing stable-ID and source-path forms. Omitting --focus is an argument error.

JSON contains the root, required and optional assets, complete provenance edges, unresolved declarations, source- and target-kind mismatches, cycles, conflicts, freshness and lifecycle findings, and completeness flags. Markdown is a compact review report. Mermaid uses labeled solid required edges and labeled dotted optional edges; it depicts repository composition, not runtime execution.

Scan Findings

Composition analysis supplies these stable scan identifiers:

• META-DEPENDENCY-SOURCE-KIND-MISMATCH
• META-DEPENDENCY-TARGET-KIND-MISMATCH
• META-DUPLICATE-DECLARED-DEPENDENCY
• COMPOSITION-REQUIRED-CYCLE
• COMPOSITION-OPTIONAL-CYCLE
• COMPOSITION-DECLARED-CONFLICT
• COMPOSITION-OPTIONAL-CONFLICT

Existing MAINT-ASSET-EXPIRED and MAINT-ASSET-REVIEW-OVERDUE freshness governance now also applies to Context Lenses. Findings remain deterministic repository evidence and do not perform runtime selection, loading, prompt assembly, execution, crawling, or automatic rewriting.

Declared Skill Dependencies

Declared Skill dependency ≠ Discovery continuation ≠ runtime invocation. A Skill can statically require another Skill as part of its workflow, or declare that another Skill may participate. Neither form selects, loads, invokes, or completes the target. Discovery's continues_with declarations and projected continuation routes remain separate and are never inferred in either direction. Prose, links, paths mentioned in prose, directory names, and telemetry do not create dependencies. Renma does not rewrite declarations.

Canonical Agent Skills use flat string-valued metadata keys (not a nested metadata.renma mapping):

metadata:
  renma.requires-skill: '["skill.security-review"]'
  renma.optional-skill: '["skill.changelog-authoring"]'

The authoritative serialization reference is the metadata table. Normalized relationship names are requires_skill and optional_skill; top-level Skill fields are migration input only, following existing Context/Lens compatibility behavior. These portable extensions are optional. This change adds no completeness policy and does not add them to repository-required metadata policy fields.

If A requires B and B requires Context C, A includes B and C as required. If A optionally depends on B, B and its required Contexts, Lenses, and Skills remain optional. Multiple required/optional routes retain all provenance; required membership wins in the final asset list. Skill cycles use the same finite state traversal and cycle model, including required-cycle precedence when the same component also has optional routes.

Both source and target must be Skills. Wrong kinds and exact duplicate values retain existing diagnostics and declaration ranges. Missing targets remain unresolved. Ambiguous Skill targets are not selected: unresolved issues include resolutionReason: "ambiguous" and sorted candidatePaths; missing Skill targets include resolutionReason: "missing". Ambiguous references do not create reverse impact, resolved graph/BOM targets, or Trust Graph edges.

Cross-owner composition is valid and preserves ownership and writable_by evidence. Suspended/revoked targets retain the existing required-error and optional-warning lifecycle diagnostics; required dependencies from usable roots make required composition incomplete. Deprecated/archived targets retain lifecycle findings and optional inactive-dependency warnings without acquiring suspended/revoked completeness semantics.

A uniquely resolved Skill path retains that file throughout traversal, membership, cycle detection, freshness, and lifecycle checks, even when another Skill has the same declared ID. Declarations from the other file are not traversed. Public IDs remain unchanged; existing source paths and declaration evidence identify files.

Exact release annotations

Asset bindings annotate existing relationships with an alias and exact release version. Skills use metadata.renma.asset-bindings as a JSON-array string; Contexts and Lenses use native top-level asset_bindings. Lens release_version is distinct from its existing format version. [label](renma-asset:alias) provides an explicit local binding reference. The dedicated builder API reports declaration validity and local version satisfaction separately; existing composition, scan and Discovery behavior remain unchanged. Acquisition, packaging and rewriting are external.

Release bindings and snapshot completeness

Asset bindings annotate existing provenance edges, unresolved declarations and kind mismatches. Asset releaseVersion identifies the inspected release, while each binding's version is the requested release. Target resolution and release satisfaction are separate.

requiredComplete retains its existing unresolved-target, kind-mismatch and required unavailable-asset checks. optionalComplete retains its existing unresolved-target and kind-mismatch checks. Neither includes release satisfaction; cycles and conflicts retain their independent fields. Optional bindingSatisfaction reports required and optional satisfaction separately.

Traversal follows local snapshot assets even when a binding is unsatisfied. Following B 2.0.0 does not establish the dependencies of requested B 1.0.0. External builders supply and inspect selected releases; Renma does not acquire sources, resolve Git revisions, write lockfiles, bundle assets or generate plugins.