renma User Manual

renma scans agent-facing repository assets and their static declarations, then turns them into deterministic, agent-consumable reports. Use it to keep Skills, Context Assets, Context Lenses, ownership, lifecycle, provenance, security policy, and declared relationships reviewable in Git and CI instead of relying on an LLM to infer repository intent.

What Renma Does And Does Not Do

Renma is deterministic repository governance for Skills, Context Assets, Context Lenses, and related agent-facing documentation. It reads local repository files, builds reviewable evidence, and reports what humans or coding agents should inspect. Its declarations describe repository state; they do not direct a live runtime.

English is the primary language for canonical governance and security wording, and receives Renma's strongest bounded natural-language recognition. Multilingual and non-English repository content remains supported; Renma does not emit a generic warning merely because prose is non-English. Deterministic evidence whose grammar does not depend on prose vocabulary remains active across languages, including URLs and hostnames, command syntax, filesystem paths, executable references, Markdown structure, and hidden Unicode. Renma does not translate security terms or claim general multilingual NLP.

Renma does not call an LLM, conduct an authoring conversation, ask the user questions, retain session state, select, retrieve, or load runtime context, assemble prompts, inject context, execute agents, or collect runtime telemetry.

Run renma guide skill before generation. It prints a deterministic authoring contract that tells the consuming LLM to evaluate the creation gate, inspect applicable user-provided artifacts, repository evidence, and permitted authoritative source content, separate confirmed facts from proposals and unresolved human truth, classify progression separately, and ask only about unresolved Blocking authoring decisions that still require human truth. Clarification is unnecessary when the request and applicable evidence already establish every gate requirement. Renma itself remains non-interactive. The external LLM investigates and proposes, Renma validates the supplied structure and repository evidence it can determine, and a human reviews meaningful decisions. Renma does not independently certify that an authoring conversation occurred or that caller-declared domain facts are true.

Before applying progression, distinguish decisions needed to author the Skill contract from runtime task unknowns the finished Skill should detect, report, request, or handle safely. Runtime task unknowns do not automatically block creation, and “do not guess” does not mean stop on every unknown.

Only after every creation-gate requirement is established, including the smallest justified asset structure, no Blocking authoring decision remains, and the gate is declared passed may platform-native Skill authoring guidance refine trigger descriptions, instructions, workflows, constraints, completion criteria, and ambiguity-resolving examples within the agreed Renma boundaries. It is not the authority for Renma metadata, Context placement, file count, source-of-truth representation, or support files and scripts.

For agent workflows, the consuming LLM records the result in the versioned renma.skill-authoring-handoff.v1 exchange contract only after every creation-gate requirement is established, including the smallest justified asset structure, no Blocking decision remains, and the gate is declared passed. The handoff is caller-declared authoring evidence, not a Renma asset or conversation file:

renma guide skill
  -> external LLM reviews applicable evidence and clarifies only if needed
  -> establish every creation-gate requirement, including the smallest justified asset structure
  -> no declared Blocking authoring decision remains
  -> declare the creation gate passed
  -> external LLM writes renma.skill-authoring-handoff.v1 JSON
  -> renma scaffold skill <agreed-path> --handoff <handoff.json>
  -> external LLM authors within the scaffold
  -> renma scan / catalog / graph / readiness
  -> human review

These arrows show externally observable dependencies, not a prescribed LLM reasoning algorithm. The LLM may combine and revisit activities internally, and clarification remains unnecessary when applicable evidence already establishes the gate requirements.

Renma reads this file locally, validates its version, bounded structure, declared gate state, canonical Skill identity, target agreement, relationship consistency, and resource kinds, then applies the supplied structural values. It does not prove that clarification happened, every blocker was discovered, a designated source is authoritative or was consulted, a human approved every decision, or the declared facts are true. Proposed reversible defaults and Unresolved Deferred items may remain. At Renma's structural validation boundary, a non-empty progression.blocking list prevents scaffolding; an empty list does not independently prove that the authoring creation gate passed.

Install And Build

Renma supports the declared Node.js engine range on Linux, macOS, and Windows. CI keeps the full quality gate on Linux and separately verifies installation, build, path/filesystem behavior, packaged consumer CLI startup, and a representative machine-readable scan on macOS and Windows. Static evidence for POSIX shell, PowerShell, and Windows batch is supported on every host; Renma parses those bounded forms without executing them or requiring the matching interpreter.

From a checkout:

npm install
npm run build

Run the local CLI from the built entry point:

node dist/index.js scan .

When renma is installed as a package, use the renma binary:

renma scan .

For the canonical Skill format, scan validation, and one-way migration workflow, see Agent Skills Compatibility and Migration. Agent Skills results appear inside scan; there is no separate Skill-validation command.

Operational Skills must be specification-valid Agent Skills. All Renma Skill governance and security metadata uses flat, string-valued metadata.renma.* entries. Legacy pre-0.16 top-level Skill metadata is accepted only as migration input for suggest-metadata; non-Skill metadata behavior is unchanged.

Repository Layout

renma is most useful when agent knowledge is stored in predictable places:

• skills/**/SKILL.md and .agents/skills/**/SKILL.md are shorthand for the canonical Agent Skills roots and exact filename. A path crossing a reserved Skill-support directory is support, not an entrypoint; see the precise entrypoint path contract. Repository walking reports historical skill.md and *.skill.md spellings with migration guidance, but they are not operational Skills. Only an explicit suggest-metadata target produces a migration candidate.
• contexts/** for shared context assets.
• configurable prompt or documentation paths for reusable prompts and broader docs.
• renma.config.jsonc is the recommended repository configuration filename; renma.config.json is also supported, while .renma.json is rejected with rename guidance.

Tool helper implementations usually belong under tools/**. They can be referenced from skills and commands, but they are not the same thing as user-facing documentation under docs/**.

Under explicit skill roots, assets, examples, profiles, references, and scripts are reserved for skill-local support directories. These are valid support paths:

• skills/demo/assets/template.md
• skills/demo/examples/happy-path.md
• skills/demo/references/spec.md
• skills/demo/scripts/helper.sh
• skills/demo/profiles/local.md

The same reserved names apply under .agents/skills/**.

These valid support paths are structurally Skill-local. Keep material local when it is specific to one Skill. Promote reusable source-of-truth knowledge to an owned Context Asset, or a helper shared across workflows to tools/**, only when repository evidence supports that change; Renma does not move files automatically.

Renma claims a parent only after repository evidence resolves exactly one Skill entrypoint. When that resolved local support artifact does not declare an owner, ownership, Readiness, graph, Trust Graph, and BOM reporting may use the parent Skill's owner as deterministic effective ownership and mark it as inherited. Missing or ambiguous parents never inherit. See classification evidence for the detailed contract. This does not invent ownership for shared Context Assets or unrelated repository files.

Only files marked Markdown-parser eligible contribute frontmatter metadata, headings, links, code fences, and repeated-context evidence. Text scripts and data assets remain raw text for dedicated static path and inventory analysis; binary assets remain opaque. Security diagnostics do not analyze script or asset contents as executable behavior. The Executable Surface Inventory only recognizes its documented bounded static dependency relationships in eligible text scripts. Security command analysis applies to eligible agent-facing Markdown instructions that reference or invoke them. A separate raw source-integrity check detects conservative hidden-Unicode signals in every already-discovered text artifact without interpreting executable behavior or widening discovery. This includes encoded-looking runs of consecutive Unicode Variation Selectors from the standard, supplementary, and Mongolian Free Variation Selector families while allowing ordinary isolated selectors. The covered families are intentionally conservative rather than an exhaustive Unicode-property policy. The same check allows only the three exact RGI emoji tag sequences for the England, Scotland, and Wales subdivision flags; standalone, malformed, token-embedded, and other encoded-looking tag usage remains suspicious.

Avoid using reserved support directory names as skill names. Paths such as skills/assets/SKILL.md, skills/examples/SKILL.md, skills/references/SKILL.md, skills/scripts/SKILL.md, and skills/profiles/SKILL.md are not treated as skill entrypoints by default. If one of those files is intended to define a Renma skill, rename the directory, for example to skills/example-review/SKILL.md. The same rule applies under .agents/skills/ and at any deeper level: skills/demo/references/vendor/SKILL.md remains Skill-local Reference content owned structurally by skills/demo, not a nested Skill.

Specification-valid Agent Skills declare governance and security values as flat string-valued metadata.renma.* entries. JSON-array strings represent lists; Renma does not treat comma-separated canonical values as lists. These canonical values feed the same catalog, ownership, graph, readiness, BOM, Trust Graph, lifecycle, and reporting behavior as the pre-0.16 fields they replace.

Canonical Skills may also declare exact static continuations with metadata.renma.continues-with, using a JSON-array string of non-empty Skill IDs or repository-relative SKILL.md paths. This field feeds only the prepared Skill Discovery route index and does not enter the existing catalog dependency collection. See the Skill Discovery Graph contract.

Renma does not fall back to top-level pre-0.16 Skill fields. Invalid, hybrid, and pre-0.16 Skills can be scanned and migrated but contribute no operational Skill metadata. Contexts, context lenses, profiles, references, examples, agents, configuration files, and other non-Skill assets continue to use their existing top-level metadata syntax.

Authoritative Metadata Reference

This section is the complete field inventory for frontmatter metadata consumed by Renma. Feature guides explain deeper semantics and edge cases, but this section owns the Skill/non-Skill mapping, value shape, applicability, authoring status, and primary projections.

Metadata model and source selection

Agent Skills owns the portable Skill top-level fields. Renma extensions for a canonical SKILL.md are flat entries inside that portable metadata mapping:

metadata:
  renma.owner: platform-team
  renma.tags: '["review","release"]'
  renma.network-allowed: "false"

Every Agent Skills metadata value is a string. Canonical Renma Skill lists are therefore strings containing JSON arrays, and canonical booleans are quoted strings. A nested metadata.renma mapping and unprefixed keys such as metadata.owner are not canonical Renma Skill metadata.

Contexts, Context Lenses, profiles, references, examples, and other non-Skill assets keep top-level Renma metadata. The normalized catalog accepts those fields only on Markdown-parser-eligible assets classified as Context, Context Lens, Profile, Reference, Example, Script, or Asset. Specialized non-Skill parsers have the narrower applicability stated in the table. Raw Script and Asset bytes cannot declare local security policy, although a uniquely resolved Skill-local Script or Asset can inherit its owning Skill's effective policy.

Operational source selection is fail-closed:

specification-valid canonical Skill
  -> recognized flat metadata.renma.* fields are operational

invalid, hybrid, or pre-0.16 Skill
  -> no operational Skill metadata
  -> recognized legacy fields are input only to suggest-metadata

non-Skill asset
  -> recognized top-level fields are operational for their stated parser

Unknown renma.* keys and other vendors' valid string metadata are preserved but uninterpreted unless a current Renma registry recognizes them. Unknown top-level non-Skill fields may remain in parsed source evidence, but they are outside Renma's operational model unless a current parser is listed below. Repository JSONC/JSON configuration has its own schema and is not frontmatter metadata.

Metadata is governance and static declaration evidence. It does not replace behavior-critical instructions, selection boundaries, permissions, stop conditions, or source-of-truth boundaries in the Skill or asset body. Generic Agent Skills clients may not expose vendor metadata to the model at all.

Portable Agent Skills top-level fields

These are specification-owned fields, not renma.* extensions:

Top-level field	Value format	Agent Skills requirement	Renma behavior
name	Non-empty string; Renma validates 1–64 Unicode code points, lowercase NFKC form, letters/digits/hyphens, no edge or repeated hyphen, and immediate-directory match; repository-wide collisions are detected after trim/NFKC normalization	Required	Runtime-observable Skill identity validation and Discovery presentation; repository-wide uniqueness is optional governance and remains separate from canonical renma.id
description	Non-empty string, at most 1,024 Unicode code points	Required; Renma recommends capability and usage boundaries	Portable Skill discovery text, quality and authoring diagnostics, and Discovery presentation
license	String	Optional	Agent Skills validation; not projected into Renma catalog metadata
compatibility	Non-empty string, at most 500 Unicode code points	Optional	Agent Skills validation; not a Renma lifecycle or dependency declaration
metadata	Mapping from string keys to string values	Optional in Agent Skills; required only when Renma extensions are declared	Container for flat renma.* and other vendor metadata
allowed-tools	String	Optional	Agent Skills validation; Renma does not treat it as a security-policy field

name and description make a Skill portable; they do not make a hybrid or otherwise invalid document operational. Renma authoring warnings do not by themselves invalidate a specification-valid Skill.

Renma operational metadata table

In the Skill column, a key means metadata.<key>. In the non-Skill column, a key is top-level frontmatter. — means Renma has no operational equivalent on that serialization surface. The markers delimit the rows checked against the implementation-owned registries.

Skill key	Non-Skill key	Value format	Applies to	Requirement / authoring status	Primary Renma effects
renma.id	id	Trimmed non-empty text	Skill and cataloged non-Skill assets	Recommended for stable references; Context Lens requires id	Catalog identity, duplicate checks, inspect, graphs, BOM, Trust Graph, diff, and CI reporting
renma.title	—	Trimmed non-empty text	Skill only	Optional	Normalized Skill catalog and inspect presentation; top-level non-Skill title is not an operational equivalent
—	type	Trimmed text; context_lens is the supported Lens discriminator	Non-Skill assets; only Context/Context Lens for Lens validation	Conditional when a file under a Context root must be classified as a Context Lens	Classification evidence, catalog kind, inspect, and Context Lens diagnostics
renma.version	version	Trimmed text; a Context Lens accepts only 1 when present	Skill and cataloged non-Skill assets	Optional	Catalog, Context Lens validation, BOM, semantic diff, and CI reporting
renma.owner	owner	Trimmed non-empty text	Skill and cataloged non-Skill assets	Context Lens requires it; recommended for shared Context; optional elsewhere	Declared/effective ownership, ownership reports, Readiness, BOM, Trust Graph, diff, and CI reporting
renma.writable-by	writable_by	Skill: JSON-array string; non-Skill: YAML list or comma-separated scalar	Skill and cataloged non-Skill assets	Optional unless repository policy requires it	Declared modification principals in catalog JSON, inspection, diff, and CI report; no authorization enforcement or ownership effects
renma.status	status	experimental, stable, suspended, revoked, deprecated, or archived	Skill and cataloged non-Skill assets	Optional lifecycle declaration; suspended and revoked are inactive and require reason/date evidence	Lifecycle/freshness findings, dependency review, Discovery publication eligibility, catalog, Readiness, BOM, Trust Graph, diff, and CI reporting
renma.status-reason	status_reason	Trimmed non-empty text	Skill and cataloged non-Skill assets	Required when status is suspended or revoked; optional for other statuses	Reason for the latest reviewed lifecycle transition in catalog, inspect, Readiness, Discovery/Skill Index, BOM, Trust Graph, semantic diff, and CI reporting
renma.status-changed-at	status_changed_at	Real ISO date YYYY-MM-DD	Skill and cataloged non-Skill assets	Required and blocking when status is suspended or revoked; optional for other statuses	Date of the latest reviewed lifecycle transition in catalog, inspect, Readiness, Discovery/Skill Index, BOM, Trust Graph, semantic diff, and CI reporting
renma.purpose	purpose	Trimmed non-empty text	Skill and cataloged non-Skill assets	Context Lens requires it; optional elsewhere	Catalog/inspect metadata and Context Lens governance diagnostics
renma.last-reviewed-at	last_reviewed_at	Real ISO date YYYY-MM-DD	Skill and cataloged non-Skill assets	Optional; recommended when freshness is governed	Freshness diagnostics, catalog, Readiness, BOM, semantic diff, and CI reporting
renma.review-cycle	review_cycle	P<positive integer>D	Skill and cataloged non-Skill assets	Conditional on cycle-based freshness review; meaningful with last-reviewed-at	Review-due calculation, freshness diagnostics, catalog, Readiness, BOM, diff, and CI reporting
renma.expires-at	expires_at	Real ISO date YYYY-MM-DD	Skill and cataloged non-Skill assets	Optional	Expiration findings, lifecycle/dependency review, catalog, Readiness, BOM, diff, and CI reporting
renma.tags	tags	Skill: JSON-array string; non-Skill: YAML list or comma-separated scalar	Skill and cataloged non-Skill assets	Optional	Catalog, ownership grouping, graph/BOM/Trust Graph asset projections, semantic diff, and CI reporting
—	when_to_use	YAML list or comma-separated scalar	Cataloged non-Skill assets	Recommended for active shared Context	Catalog usage-boundary evidence and Context diagnostics; Skill discovery belongs in portable description
—	when_not_to_use	YAML list or comma-separated scalar	Cataloged non-Skill assets	Recommended for active shared Context	Catalog negative-boundary evidence and Context diagnostics; Skill selection exclusions belong in portable description
renma.requires-context	requires_context	Skill: JSON-array string; non-Skill: YAML list or comma-separated scalar	Skill and cataloged non-Skill assets	Optional; required only when the declared relationship exists	Required catalog dependency, graph/composition/impact, Readiness, BOM, Trust Graph, semantic diff, and CI reporting
renma.optional-context	optional_context	Skill: JSON-array string; non-Skill: YAML list or comma-separated scalar	Skill and cataloged non-Skill assets	Optional	Optional catalog dependency and the same static relationship projections
renma.requires-lens	requires_lens	Skill: JSON-array string; non-Skill: YAML list or comma-separated scalar	Skill and cataloged non-Skill assets	Optional; required only when the declared Lens relationship exists	Required Lens dependency, Lens usage diagnostics, graph/composition/impact, Readiness, BOM, Trust Graph, diff, and CI reporting
renma.optional-lens	optional_lens	Skill: JSON-array string; non-Skill: YAML list or comma-separated scalar	Skill and cataloged non-Skill assets	Optional	Optional Lens dependency and the same static relationship projections
renma.asset-bindings	asset_bindings	Skill: JSON-array string; Context/Lens: native YAML sequence of alias/target/version objects	Independently governed Skills, Contexts and Lenses	Optional	Separate read-only asset-binding API; see asset bindings; does not change scan or composition completeness
—	release_version	Exact non-empty release string	Context Lens only	Required when a Lens participates in a binding	Asset-binding API; Lens version remains the format version
renma.requires-skill	requires_skill	Skill: JSON-array string; non-Skill: YAML list or comma-separated scalar	Skill only; non-Skill declarations are retained as kind-mismatch evidence	Optional	Required Skill composition; catalog, graph/composition/impact, Readiness, BOM, Trust Graph, inspect, diff and CI; no Discovery route or runtime invocation
renma.optional-skill	optional_skill	Skill: JSON-array string; non-Skill: YAML list or comma-separated scalar	Skill only; non-Skill declarations are retained as kind-mismatch evidence	Optional	Optional Skill composition with the same static projections; downstream membership stays optional
renma.conflicts	conflicts	Skill: JSON-array string; non-Skill: YAML list or comma-separated scalar	Skill and cataloged non-Skill assets	Optional	Conflict diagnostics, catalog dependency graph, BOM, Trust Graph, semantic diff, and CI reporting
renma.superseded-by	superseded_by	Skill: JSON-array string; non-Skill: YAML list or comma-separated scalar	Skill and cataloged non-Skill assets	Recommended when an asset is deprecated because a replacement exists; otherwise optional	Lifecycle/supersession diagnostics, reference edges, catalog, BOM, Trust Graph, diff, and CI reporting
renma.continues-with	—	JSON-array string of non-empty Skill IDs or repository-relative SKILL.md paths	Canonical Skill only	Optional	Parsed separately for prepared Skill Discovery, Skill Index, discovery graph, route/cycle diagnostics, Readiness evidence, semantic diff, and CI; never a catalog dependency
—	applies_to	YAML list or comma-separated scalar of Context IDs/paths	Cataloged non-Skill assets via the general parser; supported authoring surface: Context Lens	Context Lens: required and target-validated; recommended authoring scope: Context Lens	Any catalog entry carrying a normalized value: metadata-declared applies_to dependency; Context Lens: requiredness, target resolution to Context Assets, Lens governance, inspect, graph, Readiness, BOM, Trust Graph, diff, and CI projections
—	focus	YAML list or comma-separated scalar	Cataloged non-Skill assets via the general parser; supported authoring surface: Context Lens	Context Lens: optional; recommended authoring scope: Context Lens	General parser normalization and inspect presentation; Context Lens governance and meaningfulness checks; no dependency edge
—	expected_outputs	YAML list or comma-separated scalar	Cataloged non-Skill assets via the general parser; supported authoring surface: Context Lens	Context Lens: optional; recommended authoring scope: Context Lens	General parser normalization and inspect presentation; Context Lens governance and meaningfulness checks; no dependency edge
—	token_budget_override	Positive safe integer greater than the kind's stable compatibility validation baseline	Markdown assets initially classified as Context, Reference, Profile, or Example	Conditional; requires token_budget_rationale and is invalid when content is within that validation baseline	Scan token-budget decision and quality finding details only; a valid declaration below the current repository warning remains accepted but does not lower policy
—	token_budget_rationale	Trimmed non-empty text	Same eligible support-asset kinds as token_budget_override	Required when an override is declared; otherwise non-operational	Scan token-budget decision evidence only
—	token_budget_reviewed_at	Real ISO date YYYY-MM-DD	Same eligible support-asset kinds as token_budget_override	Optional only when an override is declared	Scan token-budget review provenance only; it does not create recurring freshness review
renma.published-entrypoint	—	Exact string "true" only	Canonical Skill only	Optional one-state publication marker	Parsed outside catalog metadata for prepared Skill Discovery, Skill Index, discovery graph, publication diagnostics, Readiness evidence, semantic diff, and CI reporting; no catalog dependency
renma.network-allowed	network_allowed	Skill: exact "true" or "false"; non-Skill: recognized boolean token	Canonical Skill or parser-eligible non-Skill Markdown	Conditional security governance	Effective security-policy resolution, instruction findings, Security Policy Inventory, BOM, Trust Graph, semantic diff, and CI reporting
renma.external-upload-allowed	external_upload_allowed	Skill: exact "true" or "false"; non-Skill: recognized boolean token	Canonical Skill or parser-eligible non-Skill Markdown	Conditional security governance	Effective upload policy, destination/disclosure findings, inventory, BOM, Trust Graph, diff, and CI reporting
renma.secrets-allowed	secrets_allowed	Skill: exact "true" or "false"; non-Skill: recognized boolean token	Canonical Skill or parser-eligible non-Skill Markdown	Conditional security governance	Effective secret-handling policy, findings, inventory, BOM, Trust Graph, diff, and CI reporting
renma.requires-human-approval	requires_human_approval	Skill: exact "true" or "false"; non-Skill: recognized boolean token	Canonical Skill or parser-eligible non-Skill Markdown	Conditional security governance	Effective approval policy, nearby-approval findings, inventory, BOM, Trust Graph, diff, and CI reporting
renma.allowed-data	allowed_data	Skill: JSON-array string; non-Skill: YAML list or comma-separated scalar	Canonical Skill or parser-eligible non-Skill Markdown	Conditional security governance	Effective allowed-data policy, input findings, inventory, BOM, Trust Graph, diff, and CI reporting
renma.forbidden-inputs	forbidden_inputs	Skill: JSON-array string; non-Skill: YAML list or comma-separated scalar	Canonical Skill or parser-eligible non-Skill Markdown	Conditional security governance	Effective forbidden-input policy, findings, inventory, BOM, Trust Graph, diff, and CI reporting
renma.approved-network-destinations	approved_network_destinations	Skill: JSON-array string; non-Skill: YAML list or comma-separated scalar	Canonical Skill or parser-eligible non-Skill Markdown	Conditional when network access is declared or instructed	Effective destination policy, network findings, inventory, BOM, Trust Graph, diff, and CI reporting
renma.approved-upload-destinations	approved_upload_destinations	Skill: JSON-array string; non-Skill: YAML list or comma-separated scalar	Canonical Skill or parser-eligible non-Skill Markdown	Conditional when external upload is declared or instructed	Effective upload-destination policy, findings, inventory, BOM, Trust Graph, diff, and CI reporting
renma.allowed-floating-dependencies	allowed_floating_dependencies	Skill: JSON-array string; non-Skill: YAML list or JSON-array scalar of valid npm:/pypi: selectors	Canonical Skill or parser-eligible non-Skill Markdown	Optional, exceptional asset-local allowance	Suppresses matching npm/PyPI floating-dependency findings only; recorded as local evidence but excluded from inheritance, effective-policy fingerprints/counts, and owning-Skill inheritance
renma.security-profile	security_profile	Trimmed non-empty profile name	Canonical Skill or parser-eligible non-Skill Markdown	Optional reusable-policy selection	Profile-chain resolution and diagnostics, effective policy/inventory, BOM, Trust Graph, semantic diff, and CI reporting
—	scope	Exact context when present; omission defaults to context	Context Lens only	Optional	Context Lens scope validation and summary only

owner identifies the party responsible for maintaining an asset. writable_by records the principals declared as allowed to modify it. Omitting writable_by declares no Renma-specific modification constraint; it does not grant or revoke technical access. Renma reports this repository evidence but does not enforce authorization. Principals are opaque identifiers, without identity resolution or ownership inheritance. This declaration does not create Trust Graph owner edges.

Canonical Skills use the existing JSON-array string encoding:

metadata:
  renma.owner: qa-platform
  renma.writable-by: '["qa-platform","release-engineering"]'

Non-Skill assets use the existing list encoding:

owner: qa-platform
writable_by:
  - qa-platform
  - release-engineering

Non-empty declarations normalize to optional writableBy arrays, preserving order and duplicates while trimming entries and dropping blank entries, like other list metadata. Omitted or empty lists do not emit a writableBy value; neither is an assertion of open access. Repositories may opt into "metadata": { "required": ["writable_by"] } to require an explicit non-empty list using the existing required-metadata diagnostics.

Removed compatibility fields are deliberately outside this operational table. Skill metadata.renma.when-to-use and metadata.renma.when-not-to-use, Context Lens target/targets/output/outputs, and non-Skill canonical_context produce explicit diagnostics and their values are not interpreted. Use portable Skill description, Lens applies_to and expected_outputs, and existing superseded_by plus reviewed Skill Context relationships or placement respectively.

Repository-required metadata policy

Repository configuration may promote the following otherwise-optional catalog fields to explicit per-asset requirements. This policy does not alter portable Agent Skills validity, and an absent metadata.required list preserves current Renma behavior. The table is generated conceptually from the same metadata definition registry used by parsing and is checked against that registry in tests.

Policy field	Skill serialization	Non-Skill serialization	Value kind
version	metadata.renma.version	version	Text
owner	metadata.renma.owner	owner	Text
writable_by	metadata.renma.writable-by	writable_by	List
status	metadata.renma.status	status	Text
status_reason	metadata.renma.status-reason	status_reason	Text
status_changed_at	metadata.renma.status-changed-at	status_changed_at	Text
purpose	metadata.renma.purpose	purpose	Text
last_reviewed_at	metadata.renma.last-reviewed-at	last_reviewed_at	Text
review_cycle	metadata.renma.review-cycle	review_cycle	Text
expires_at	metadata.renma.expires-at	expires_at	Text
tags	metadata.renma.tags	tags	List
when_to_use	—	when_to_use	List
when_not_to_use	—	when_not_to_use	List
requires_context	metadata.renma.requires-context	requires_context	List
optional_context	metadata.renma.optional-context	optional_context	List
requires_lens	metadata.renma.requires-lens	requires_lens	List
optional_lens	metadata.renma.optional-lens	optional_lens	List
conflicts	metadata.renma.conflicts	conflicts	List
superseded_by	metadata.renma.superseded-by	superseded_by	List

Only cataloged, Markdown-parser-eligible Skill, Context, Context Lens, Profile, Reference, Example, Script, and Asset documents are eligible, and only when the selected field has the mapping shown above. Binary files, raw non-Markdown support, configuration files, unknown artifacts, and runtime-only surfaces do not receive impossible frontmatter requirements.

A declaration satisfies policy only when it is unambiguous, structurally and semantically valid, and non-empty after Renma normalization. Empty text, empty lists, malformed YAML, duplicate declarations, and invalid status/date/cycle values fail closed. For Skills, this check is field-local: the required field must use the exact canonical string encoding under a structurally valid portable metadata mapping. An unrelated name/directory, description, allowed-tools, or different metadata-field error remains an independent Agent Skills diagnostic and does not invalidate a correct required field. Pre-0.16 top-level Skill fields and ignored hybrid metadata never satisfy the policy. This exception is limited to required-field validation; invalid Skills still contribute no operational catalog, ownership, security, or other metadata.

The policy is specifically about declared metadata. For example, a uniquely resolved Skill-local support file may retain an inherited effective owner for catalog, ownership coverage, Readiness, and graph calculations. That inherited value does not satisfy metadata.required: ["owner"]; the support file must declare its own valid top-level owner.

Intentionally unsupported policy names include arbitrary custom metadata, security-policy fields, token-budget decision metadata, removed compatibility fields, id, Skill-only title/continues_with, and unrelated non-Skill-only fields. Unknown or unsupported names are configuration errors.

The table intentionally has no top-level non-Skill equivalent for renma.title, continuation, or publication. A scaffolded non-Skill title may remain useful to authors, and suggest-metadata may inspect it, but parseAssetMetadata() does not normalize it. Likewise, allowed-tools is not an alias for Renma security permission.

External-upload governance reporting

external_upload_allowed and requires_human_approval remain independent fields. Security Policy Inventory derives an additive combined count only after the existing effective-policy resolver has applied local declarations, profiles, repository configuration, and owning-Skill inheritance:

External upload	Human approval	Inventory presentation
false	any value	Upload denied
true	true	Upload allowed; approval required
true	false	Upload allowed; approval not required
true	unspecified	Upload allowed; approval requirement unspecified
unspecified	any value	Upload permission unspecified

Both values being true means the effective static policy permits upload and also requires human approval. Denied upload stays denied regardless of approval metadata, and unspecified upload permission is never inferred as allowed from an approval requirement. Approved upload destinations remain separate and do not grant permission.

Renma reports this governance evidence in scan, Readiness, BOM, diff, and CI inventory output. It does not execute an upload, request or record approval, prove approval occurred, or enforce the requirement at runtime; the runtime or agent layer must honor it. The reporting projection does not change effective policy fingerprints, findings, Readiness scoring, or the separate scalar transition rules for upload permission and human approval.

Consolidated value formats and rejection rules

• Text fields become trimmed, non-empty strings where the parser defines text semantics. Empty text is generally treated as absent; a field-specific validator may also report it.
• Every canonical Skill metadata value must first be a YAML string. Canonical list fields contain JSON arrays whose members are strings. [] is valid. Renma trims members and drops empty members for ordinary catalog lists; renma.continues-with instead rejects an empty or whitespace-only member.
• Canonical security booleans accept only the exact strings "true" and "false". The Discovery publication marker is one-state and accepts only exact "true"; "false" means invalid, not unpublished. Omission means unpublished.
• Top-level non-Skill catalog/security lists accept ordinary YAML block or flow sequences and the existing comma-separated scalar form. Values first use YAML 1.2 scalar semantics, so comments are not value text, quotes are removed, and block scalars retain their semantic text. Top-level security booleans are case-insensitive true, yes, allowed, allow, or 1, and false, no, denied, deny, or 0. Prefer YAML true/false for new assets.
• Dates must be real calendar dates in YYYY-MM-DD form. Review cycles support only P<positive integer>D, such as P90D; months, years, zero, signs, fractions, and composite ISO durations are unsupported. The duration must fit within the supported 0000-01-01 through 9999-12-31 range; when last_reviewed_at is present, the resulting review date must also fit that range.
• token_budget_override must be a positive safe YAML integer, exceed the eligible artifact kind's stable compatibility validation baseline, and be needed relative to that baseline. It requires a non-empty rationale. A valid declaration below the current repository warning is retained as a no-op; repository policy is never lowered. token_budget_reviewed_at is optional but valid only alongside an override and does not imply a recurring review cycle.
• Lifecycle status is exactly experimental, stable, suspended, revoked, deprecated, or archived. Experimental and stable are declared active; suspended, revoked, deprecated, and archived are inactive for use. Omitted status retains its existing use-eligible meaning.
• status_reason describes the latest reviewed lifecycle transition, and status_changed_at dates that transition. It is distinct from last_reviewed_at, which records freshness review. Suspended and revoked assets require both a non-blank reason and a real calendar date; other statuses accept both fields without requiring them.
• Suspension preserves inventory and evidence but excludes the asset from active dependency, composition, Skill publication, routing, reachability, coverage, and cycle use. A required direct declaration from an active source to a uniquely resolved suspended asset is an error; an optional declaration is a warning. An isolated suspended asset is not a blocker merely because it is suspended.
• Revocation means trust or authorization for continued use was explicitly withdrawn because of a known problem. It is stronger than suspension and is not an alias for deprecation or archival. Required active dependencies to a uniquely resolved revoked asset emit META-REQUIRED-REVOKED-DEPENDENCY as a built-in High Finding; optional dependencies emit META-OPTIONAL-REVOKED-DEPENDENCY as a built-in Low Finding. Renma does not propagate revoked to dependents or require superseded_by.
• A security profile is a non-empty selected name. The name must resolve in security.profiles; a missing or cyclic chain is diagnosed rather than silently substituted. Profile configuration uses the exact canonical fields documented in the Security Policy Guide, including snake_case governance fields and the retained approvedDomains, approvedUploadDomains, and disallowedCommands names. Historical aliases are rejected with their replacement and are never merged.
• Floating-dependency allowances have an exact lowercase npm: or pypi: prefix followed by one supported package name and a selector classified as bare, dist-tag, range, or wildcard. They do not accept exact versions, variables, direct references, malformed selectors, Homebrew, or Docker. Matching is normalized but exact, not globbed or fuzzy.

Renma does not coerce comma-separated canonical lists, native YAML booleans for canonical metadata, alternate canonical boolean casing, non-string JSON-array members, malformed JSON, impossible dates, or unsupported duration forms. Duplicate top-level Skill fields, duplicate metadata mappings, and duplicate canonical child keys are ambiguous: Renma does not choose the first or last value. Invalid recognized canonical security declarations fail closed and can retain restrictive inherited policy while preventing permissive inheritance; the Security Policy Guide defines the field-specific precedence and diagnostic behavior.

The same ambiguity rule applies to recognized non-Skill operational fields. Malformed YAML supplies no catalog, governance, Context Lens, or security values. Duplicate recognized keys supply no value for the duplicated field, and invalid local security declarations block permissive inheritance. Bounded raw-key detection may establish that malformed frontmatter declared a known security field, but it never recovers or authorizes the raw value.

For example, suspend and later restore a Skill through two reviewed Git/PR changes:

metadata:
  renma.status: suspended
  renma.status-reason: Temporarily disabled while issue QE-1234 is corrected.
  renma.status-changed-at: "2026-08-03"

metadata:
  renma.status: stable
  renma.status-reason: Restored after QE-1234 was corrected and verified.
  renma.status-changed-at: "2026-08-06"

Renma compares the three fields independently in semantic diff and CI evidence. It does not store lifecycle history, schedule automatic expiry, or restore an asset automatically; repository history remains the complete audit trail.

Revocation uses the same canonical fields but records an explicit negative trust decision:

metadata:
  renma.status: revoked
  renma.status-reason: Revoked after the upstream source was found to be compromised.
  renma.status-changed-at: "2026-09-03"

A revoked asset may have no replacement. Renma keeps it as current static repository evidence and does not automatically archive, replace, delete, restore, or propagate its status to dependents.

Consumer and inheritance boundaries

Metadata-declared catalog dependencies come only from required/optional Context and Lens fields, applies_to, conflicts, and supersession references. Renma separately adds static-support dependencies from deterministic Skill-local containment, static references, and Context/Lens direct-link owner provenance; those relationships are not frontmatter declarations. continues-with is a separate Skill Discovery route declaration. published-entrypoint is separate publication intent. Neither creates a catalog dependency or claims runtime selection, loading, or execution.

Ownership inheritance is structural, not metadata merging: a Skill-local support asset with no declared owner inherits only when Renma resolves exactly one parent Skill with a declared owner. Missing or ambiguous parents remain unowned. Shared Context assets never inherit an owner by path. Context/Lens scripts inherit an agreed declared owner from directly linking standalone Contexts/Lenses under the script-parent rules.

Security profile inheritance is a different mechanism. Valid asset-local scalars take precedence over the selected profile chain; a child profile takes precedence over its base. Allowed-data and forbidden-input lists use their documented replacement/fail-closed rules, while approved network/upload destinations accumulate from eligible profile and repository configuration sources. Repository disallowed commands also accumulate. Separately, a uniquely resolved Skill-local Script or Asset inherits its owning Skill's effective policy. Context/Lens direct-link ownership does not inherit or merge security policies; caller policy evidence remains separate. Ordinary Skill-local References, Profiles, and Examples can declare their own top-level policy but do not inherit the Skill's policy by placement. allowed-floating-dependencies is always asset-local and never participates in effective-policy inheritance or fingerprints.

The BOM and Trust Graph project normalized metadata and effective governance; they do not make every declared field part of the same fingerprint. Discovery publication and continuation remain outside catalog/BOM dependency metadata, token-budget decisions remain quality-rule evidence, and compatibility-only fields remain limited to their named diagnostics.

Complete canonical Skill example

Save this as skills/review-public-json/SKILL.md. Its required Context target is the complete Context example in the next section.

---
name: review-public-json
description: Review a proposed public JSON change for compatibility and release risk. Use when a versioned Renma JSON contract may change; do not use for implementing the change or approving a release.
license: MIT
compatibility: Requires repository files and local Renma CLI output; no network access.
metadata:
  renma.id: skill.release.review-public-json
  renma.title: Review Public JSON Compatibility
  renma.version: "1.2.0"
  renma.owner: release-engineering
  renma.status: stable
  renma.last-reviewed-at: "2026-08-01"
  renma.review-cycle: P90D
  renma.expires-at: "2027-08-01"
  renma.tags: '["release","compatibility","json"]'
  renma.requires-context: '["context.release.public-json-compatibility"]'
  renma.optional-context: '[]'
  renma.conflicts: '[]'
  renma.continues-with: '[]'
  renma.allowed-data: '["repo-local-files","skill-bundled-context"]'
  renma.network-allowed: "false"
  renma.external-upload-allowed: "false"
  renma.secrets-allowed: "false"
  renma.requires-human-approval: "true"
  renma.forbidden-inputs: '["credentials","tokens","unsanitized-production-data"]'
---

# Review Public JSON Compatibility

## Required inputs

- The proposed JSON or schema diff.
- The current repository contract and release notes.
- `context.release.public-json-compatibility`.

## Workflow

1. Identify added, removed, renamed, or type-changed public fields.
2. Compare each change with the Context's compatibility criteria.
3. Separate compatible additions from breaking or unresolved changes.
4. Produce a review report with evidence paths, compatibility classification,
   release risk, and required follow-up.
5. Obtain explicit human approval before recommending release of a breaking or
   unresolved contract change.

## Hard constraints

- Do not fetch external sources, upload artifacts, or read secrets. Use the
  repository inputs; if required evidence is absent, report it as unresolved.
- Do not implement the change or approve the release. Return an evidence-backed
  review for the owning team to decide.

## Completion criteria

The report accounts for every public-contract change, cites repository
evidence, identifies unresolved facts, and records whether human approval is
still required.

The body repeats behavior-critical constraints because the security metadata is governance evidence, not an instruction delivery mechanism. The empty continuation array is valid and creates no route.

Complete independent Context example

Save this as contexts/release/public-json-compatibility.md. It is independent of the Skill: the Skill depends on the Context, while the Context retains its own identity, owner, lifecycle, usage boundaries, and source-of-truth scope.

---
id: context.release.public-json-compatibility
version: 1.0.0
owner: release-engineering
status: stable
purpose: Define the reviewed compatibility boundary for versioned public JSON contracts.
last_reviewed_at: 2026-08-01
review_cycle: P90D
expires_at: 2027-08-01
tags:
  - release
  - compatibility
  - json
when_to_use:
  - Reviewing a change to a versioned public JSON document or schema
when_not_to_use:
  - Reviewing internal diagnostic payloads with no published compatibility contract
allowed_data:
  - repo-local-files
network_allowed: false
external_upload_allowed: false
secrets_allowed: false
requires_human_approval: true
forbidden_inputs:
  - credentials
  - tokens
  - unsanitized-production-data
---

# Public JSON Compatibility Context

## Scope

Use this Context to classify changes to a repository-declared, versioned public
JSON contract. Additive optional fields are normally compatible. Removing a
field, renaming it, narrowing its accepted values, or changing its type requires
an explicit compatibility decision and release review.

## Review guidance

1. Compare the proposed and current contract from repository evidence.
2. Record every externally observable change.
3. Treat undocumented consumer assumptions as unresolved, not confirmed.
4. Require human approval before classifying a breaking or unresolved change
   as release-ready.

## Source-of-truth boundary

This Context is the maintained review policy for compatibility classification.
The versioned JSON contract in the target repository remains authoritative for
its actual fields and types, and release owners remain authoritative for
approval. Do not use this Context to invent missing schema details or consumer
requirements.

These two documents have matching IDs, dates, list encodings, policy, and body constraints. They make no network, upload, secret, or external source-of-truth claim and introduce no unresolved Lens or continuation target.

Compatibility classification

• Current canonical fields: specification-valid Skills use the table's metadata.renma.* fields; supported non-Skill assets use the mapped top-level fields. Field omission remains allowed unless the table marks it required or conditional.
• Unsupported legacy fields: Skill renma.when-to-use and renma.when-not-to-use, Context Lens target, targets, output, and outputs, and non-Skill canonical_context produce diagnostics and are not interpreted. Put Skill selection semantics in portable description, use Lens applies_to/expected_outputs, and use the existing superseded_by relationship plus reviewed Skill Context relationships or placement. The top-level non-Skill when_to_use and when_not_to_use fields remain current for shared Context usage boundaries.
• Migration-only: pre-0.16 top-level Skill governance and security fields are accepted only as one-way suggest-metadata input. They never merge with, override, or fall back from canonical metadata.
• Preserved but uninterpreted: unknown canonical renma.* keys and other vendors' valid string metadata remain portable metadata but have no Renma projection. Unknown top-level non-Skill fields remain outside the operational model unless added to a current parser registry.
• Invalid or ambiguous: a specification-invalid, hybrid, or pre-0.16 Skill contributes no operational Skill metadata. Duplicate canonical declarations are not resolved by ordering. Malformed recognized catalog values are absent or diagnosed by their field contract; malformed security, continuation, and publication declarations retain exact evidence and fail closed for their consumer.

Quick Start

For a new repository that wants to record explicit Renma adoption and pin its minimal initial repository policy, run:

renma init .

renma init initializes repository-level Renma configuration. It does not create Skills or Context Assets. An existing repository can use Renma's built-in defaults without running renma init, so initialization is not a prerequisite for scanning or cataloging an existing repository.

For a first pass on an existing repository, run:

renma scan .
renma catalog . --format markdown
renma graph . --format markdown
renma skill-index .
renma readiness . --format markdown

Read these reports together:

• scan shows concrete problems to fix.
• catalog shows what assets and metadata Renma discovered.
• graph shows how skills and contexts are connected.
• readiness summarizes repository-level health and checks.

When creating a Skill, run renma guide skill; let the consuming LLM inspect relevant evidence, clarify unresolved Blocking human truth only when needed, establish the smallest intended asset graph as a creation-gate requirement, and pass the gate only after every requirement is established and no Blocking decision remains; then record a renma.skill-authoring-handoff.v1 exchange artifact, run scaffold skill <path> --handoff <handoff.json> once, create or reuse only justified Context Assets, complete the focused workflow, and validate with renma scan . --fail-on high. For deeper authoring guidance, see the Authoring Guide. For rule details, see the Diagnostics Reference.

Generated Skill and Context starter prose is intentionally incomplete. Renma matches only its own exact generated marker strings and reports each remaining frontmatter description or body line as the High QUAL-RENMA-SCAFFOLD-PLACEHOLDER finding. Untouched and partially edited scaffolds therefore fail renma scan . --fail-on high --strict and fail the Readiness assets.scaffold_completeness check. This is deterministic scaffold residue detection, not a claim that marker-free prose is semantically complete.

LLM-Assisted Skill Maintenance

Use the existing-Skill workflow for ordinary maintenance: scan, inspect relevant evidence, prepare the smallest supported patch, validate, and obtain human review for meaningful semantic changes. A clean scan does not establish domain truth, source authority, or semantic correctness.

Use renma guide skill when intentionally reconsidering Skill or Context boundaries, resource placement, source representation, scripts, or the asset graph. The Authoring Guide owns that contract.

When suggest-metadata reports decisionStatus: "no-change-recommended" with suggestedMode: "no-proposal", do not manufacture a metadata or migration patch. Continue any separately requested Skill-body improvement; stop only when no other intended work remains.

Example instruction for an agent:

Start with `renma scan . --fail-on high`, then inspect the target and only the repository evidence needed for the change. Make only evidence-backed changes. Do not invent owners, references, product rules, or source-of-truth claims. Preserve existing semantics unless a diagnostic or explicit requirement supports a change. Run `renma scan . --fail-on high` after editing, fix relevant diagnostics, rerun it, and summarize both resolved and remaining findings.

For a single classification question, renma inspect <target> --format json may be the initial preflight. Repository-wide work normally starts with scan.

Context Asset Discovery Boundary

contexts/** is the only independent Context Asset root. A context/** path produces migration guidance and remains operationally unknown. Nested directory names never override a recognized root for Markdown assets. Supported executable files under contexts/** and lenses/** are repository scripts, with no implied parent asset or inherited owner/policy. Files under canonical Skill references/, profiles/, examples/, scripts/, and assets/ directories are structurally Skill-local. Renma claims one parent and possible inherited governance only after repository evidence resolves exactly one Skill under skills/** or .agents/skills/**. Supported explicit local metadata remains valid but is not required. See classification evidence for the detailed contract.

An Agent Skills package may also contain other directories. An explicit static reference from SKILL.md or already-inspected support makes a repository-local target such as templates/prompt.md, docs/instructions.txt, or bin/run.py visible as explicit-noncanonical package evidence. That does not make the target canonical support and does not grant inherited ownership or security policy. Renma inspects the exact referenced path without recursively admitting the directory; exclusion, oversize, depth, symlink, and unreadable states remain strict-completeness blockers. Unreferenced noncanonical package content remains outside discovery.

Top-level references/** is not a Context root. tools/** contains shared repository implementation, not Context knowledge, and skills/**/tools/** is not a canonical local support directory. Skill-local executable support belongs under scripts/.

contexts/foo/references/policy.md
  -> independent Context Asset

skills/foo/references/policy.md
  -> Skill-local Reference

references/policy.md
  -> outside the Context root

tools/helper.mjs
  -> repository implementation

skills/foo/tools/helper.mjs
  -> not canonical Skill-local support

Placement as independent Context is a human decision about ownership, lifecycle, reuse, and source of truth. Classification after placement is deterministic. Renma never moves a file based on content. A successful no-proposal result means no edit should be manufactured.

User Story: Create A New Skill With Scaffold

Use this command sequence to create a Skill within the canonical Authoring Guide. Renma establishes the repository contract and generates one starting point; platform-native authoring guidance refines semantics inside that contract after the creation gate passes.

flowchart LR
  Guide["Run renma guide skill"] --> Gate["LLM investigates evidence and evaluates the gate"]
  Gate --> Clarify{"Blocking human truth remains?"}
  Clarify -- Yes --> Ask["Ask the smallest dependency-ready clarification"]
  Ask --> Gate
  Clarify -- No --> Structure["Establish the smallest justified asset structure"]
  Structure --> Ready{"Every gate requirement established and no blockers?"}
  Ready -- No --> Gate
  Ready -- Yes --> Pass["Declare the creation gate passed"]
  Pass --> Handoff["Write renma.skill-authoring-handoff.v1"]
  Handoff --> Scaffold["Run renma scaffold skill --handoff once"]
  Scaffold --> Context["Scaffold or reuse justified Context"]
  Context --> Complete["Complete the focused workflow"]
  Complete --> Validate["Run renma scan . --fail-on high"]
  Validate --> Evidence["Classify findings and inspect evidence"]
  Evidence --> Boundary{"Asset boundary change?"}
  Boundary -- Yes --> Gate
  Boundary -- No --> Fix["Apply uniquely supported repairs and rerun"]
  Fix --> Review["Human review"]

The arrows expose gate dependencies and observable transitions, not a required internal reasoning algorithm. Activities may be combined or revisited, but every gate requirement, including the smallest justified structure, must be established before the gate passes. Decision tables, question themes, and progress-summary formats are optional aids; evidence, authority, ownership, security, completion, asset responsibilities, and the structured handoff remain requirements.

1. Establish the contract. Run renma guide skill, investigate applicable evidence, and resolve Blocking authoring decisions before creating files. Clarification is needed only when evidence and existing authorization do not establish the required truth. Keep authoring decisions separate from runtime task unknowns. The detailed rules live in adaptive clarification, truth sources, and the creation gate.
2. Record the handoff after the gate passes. The external LLM writes renma.skill-authoring-handoff.v1, preserving Confirmed / Proposed / Unresolved understanding separately from Blocking / Reversible default / Deferred progression. It records the Skill contract, justified asset graph, authority, security, and runtime-unknown handling; it contains no finished Markdown or complete implementation plan. Follow the structured handoff contract.
3. Generate once for the agreed path.

renma scaffold skill skills/testing/spec-review/SKILL.md \
  --handoff /tmp/spec-review-handoff.json

The target must match assetGraph.skill.path after safe normalization. --handoff is the single structural authority and cannot be combined with --id, --title, --owner, --tags, or --resources. Direct use with --owner remains supported without a handoff.

4. Complete the starter. Replace placeholder prose and supply required security policy. The Skill uses Agent Skills identity and metadata.renma.*; Context and Context Lens retain their top-level metadata shape. Refine the workflow, constraints, completion criteria, and useful examples without inventing owners, policies, dependencies, domain rules, or authority. Do not run a second independent generator or add unagreed assets. Re-enter the gate if refinement changes asset boundaries.
5. Add independently justified Context and relationships. Context may be justified by independent ownership, lifecycle, maintenance, source-of-truth status, cross-Skill reuse, or another explicit governance need. Source-of-truth status alone suffices; correctness importance alone does not. Cross-Skill reuse is not required.

renma scaffold context contexts/testing/boundary-value-analysis.md --owner qa-platform

An external authoritative URL normally warrants a concise governed Context, not a full copy. Authority designation does not establish its contents. Authoring-time consultation and future runtime access are separate decisions; a URL does not grant network permission and future metadata does not authorize the authoring agent. Follow the truth-source rules for consultation, supplied content, uncertainty, scope, fallback, and aligned security policy.

Add renma.requires-context or renma.optional-context under Skill metadata as JSON-array strings. Choose required versus optional only after Context is independently justified. These are static graph relationships; Renma does not select or load runtime Context.

6. Validate, repair, and review. Run the scan and repository-required checks for the change and stage:

renma scan . --fail-on high

Use catalog, graph, or readiness when they answer a structural or governance question. Classify findings using the Authoring Guide's post-validation decisions: deterministic repair, repository investigation, human decision, or no justified change. Repair only when evidence and Diagnostics v2 constraints uniquely establish the patch. Re-enter the gate for boundary changes; never weaken policy, manufacture metadata, or add suppressions merely to pass.

Verify changed scripts and affected executable behavior with relevant checks. Use external runtime evaluation when the change, unresolved evidence, or repository requirements call for it. Report unavailable required checks and impact. After relevant checks pass, repeat or broaden validation only for further changes, failed checks, or unresolved concerns. Reuse evidence only while its content, environment, and required scope remain applicable. Required CI and release checks still apply.

Complete human review and persist only durable reviewed decisions, not temporary conversation state. Neither a clean scan nor a valid graph proves source authority or runtime accessibility.

7. Optionally generate review evidence.

renma bom . --format markdown
renma bom . --format json

The BOM v3 contract combines declared catalog, graph, diagnostics, Readiness, lifecycle, hash, and security evidence. It does not record actual LLM runtime usage.

User Story: Improve Existing Skills With Diagnostics

Start with repository evidence and treat suggestions as reviewed candidates. LLM assistance is optional; Renma does not rewrite files or accept changes automatically. See the Authoring Guide for semantic review and boundary reconsideration.

flowchart TD
  Scan["Run renma scan . --fail-on high"]
  Scan --> Evidence["Inspect relevant diagnostics and repository evidence"]
  Evidence --> NeedMetadata{"Metadata or migration work needed?"}
  NeedMetadata -- Yes --> Suggest["Run renma suggest-metadata and review the candidate"]
  NeedMetadata -- No --> Prepare["Prepare and review intended changes, if any"]
  Suggest --> Prepare
  Prepare --> Validate["Rerun renma scan . --fail-on high"]
  Validate --> Fix["Fix relevant diagnostics and rerun"]
  Fix --> Review["Human review"]

1. Scan and inspect. Start repository-wide work with:

renma scan . --fail-on high --format json

Findings identify broken references, risky instructions, metadata problems, unclear workflows, and layout issues. Choose additional views for the current question rather than running every view as ceremony:

Question	Command
What assets, metadata, owners, lifecycle states, hashes, tags, and dependencies exist?	renma catalog . --format markdown
What relationships or unresolved references need review?	renma graph . --format markdown
What is one asset's direct neighborhood?	renma graph . --focus skill.testing.spec-review --format markdown
What repository health checks need attention?	renma readiness . --format markdown
What does one target contain?	renma inspect skills/testing/spec-review/SKILL.md --format json
What is the exact source evidence?	renma inspect skills/testing/spec-review/SKILL.md --lines L10-L42

Inspect relevant local resources and referenced Context Assets. Readiness is a static repository signal, not a runtime Context-selection decision.

2. Request a suggestion only when needed. For metadata or migration work:

renma suggest-metadata skills/testing/spec-review/SKILL.md --owner qa-platform --format prompt

For SKILL.md, this supports only the one-way migration from pre-0.16 Renma fields to Agent Skills identity plus flat metadata.renma.* string values, preserving the Markdown body. Unsafe or ambiguous evidence blocks canonical frontmatter output. Review conflicts, confirm intent, correct evidence, and rerun; do not apply a blocked candidate. Follow the compatibility contract and the no-proposal rule. An already canonical Skill needs no ceremonial metadata suggestion.

For an oversized or mixed-purpose file:

renma suggest-semantic-split docs/large-runbook.md

This packages source and guidance for a reviewable split; it does not edit files.

3. Prepare, validate, and review the smallest intended patch. Rerun renma scan . --fail-on high, fix relevant diagnostics, and rerun affected checks plus repository-required validation. Use other reports only for an open evidence question. Summarize changed files, resolved and remaining findings, uncertainty, required human decisions, and verification commands. Obtain human review for meaningful semantic changes; a suggestion or clean scan does not replace it.

The examples/context-repo example combines a Skill, Context Lens, and direct Context relationships. Static navigation requires a consumer with the checkout following relative links; Renma validates those relationships but does not load them.

Configuration

Use --config <path> with commands that scan the repository:

renma scan . --config renma.config.jsonc

JSONC is JSON with line and block comments. Comments let maintainers preserve the human rationale for temporary governance exceptions, and are discarded during parsing rather than exposed to Renma diagnostics or reports. Renma does not execute configuration as JavaScript: .js, .mjs, and .ts configuration files are not supported. Existing .json configuration remains valid. Both conventional config discovery and --config require a non-symlink regular file inside the scanned repository. Renma checks every repository-relative path component without following symlinks; internal, external, and broken config symlinks are caller-correctable errors rather than policy or default fallback.

For example:

{
  "security": {
    // Weakening an effective security boundary requires explicit review.
    "ci_policy": "fail"
  },
  "scan_boundary": {
    // A reviewed revision cannot narrow what CI is able to inspect or retain.
    "ci_policy": "fail"
  },
  "executable_surface": {
    // High-signal executable contract changes require explicit review.
    "ci_policy": "warn"
  },
  "quality": {
    // Repository-specific effective Markdown token-budget policy.
    "ci_policy": "fail",
    "skill_token_warning": 6400,
    "skill_token_high": 8000,
    "context_token_warning": 6400,
    "context_token_high": 8000,
    "reference_token_warning": 7200,
    "reference_token_high": 9000,
    "profile_token_warning": 3200,
    "profile_token_high": 4000,
    "example_token_warning": 4800,
    "example_token_high": 6000
  },
  "metadata": {
    // Promote supported catalog fields to explicit repository requirements.
    "ci_policy": "fail",
    "required": ["owner"]
  },
  "diagnostics": {
    // Elevate selected findings without changing producer definitions.
    "ci_policy": "fail",
    "severity": {
      "META-REQUIRED-SUSPENDED-DEPENDENCY": "critical"
    }
  },
  "agent_skills": {
    // Require an observed Skill name to identify at most one governed Skill.
    "name_uniqueness": "required"
  },
  "skill_discovery": {
    "adopted": true,

    // Keep this warning-only until existing repositories complete migration
    // and maintainers have reviewed the observed warning quality.
    "ci_policy": "warn"
  }
}

The configuration supports the same names used by the implementation, including:

• globs: glob patterns to scan.

• exclude: paths or path prefixes to skip.

• suppressions: rule suppressions that remove matching findings from the active report and failure threshold while retaining them in structured suppressedDiagnostics evidence in scan JSON.

• max_file_size_bytes: largest file renma will read for content analysis. A larger discovered file remains repository existence evidence, so a valid reference is not also reported as missing.

• max_depth: maximum discovery depth.

• concurrency: scan concurrency.

• fail_on: scan exit threshold: low, medium, high, or critical.

• format: default scan output format.

• security: command, network, upload, profile, and revision-review policy. ci_policy supports off, warn, and fail, defaults to fail, and governs effective boolean security-policy relaxations in ci-report.

• scan_boundary: revision-review policy for changes to globs, exclude, max_file_size_bytes, max_depth, and suppressions. ci_policy supports off, warn, and fail and defaults to fail.

• executable_surface: revision-review policy for high-signal changes already present in the canonical executable-surface diff. ci_policy supports off, warn, and fail and defaults to off. renma init does not enable it.

• quality: repository-specific effective policy for the Skill body QUAL-SKILL-TOKEN-BUDGET finding and the Context, Reference, Profile, and Example QUAL-SUPPORT-ASSET-TOKEN-BUDGET finding. The supported keys and Renma defaults are shown below. ci_policy supports off, warn, and fail, defaults to fail, and governs numeric threshold increases and CI-mode weakening in ci-report. fail -> warn, fail -> off, and warn -> off are weakenings. CI uses the stricter base/target mode, so those transitions fail under an effective fail mode and warn under an effective warn mode. off -> warn and warn -> fail are visible, non-blocking tightenings.

  Asset measurement	Warning key and default	High key and default
  Skill Markdown body after frontmatter	skill_token_warning: 6,400	skill_token_high: 8,000
  Context full file	context_token_warning: 6,400	context_token_high: 8,000
  Reference full file	reference_token_warning: 7,200	reference_token_high: 9,000
  Profile full file	profile_token_warning: 3,200	profile_token_high: 4,000
  Example full file	example_token_warning: 4,800	example_token_high: 6,000

  Each omitted key falls back independently to its Renma default. Every value must be a positive safe integer, and each asset kind's warning must be strictly lower than its High threshold. Unknown keys, invalid values, and invalid relationships are caller-correctable configuration errors with exit code 2. At exactly the effective warning threshold there is no finding; above it through the effective High threshold the finding is Medium; above the effective High threshold it is High. These values are not scan-boundary settings. Scripts, assets, metadata-size checks, and other quality rules keep their existing policies. The portable Agent Skills recommendation remains 5,000 Skill body tokens; Renma's repository warning default is 6,400.

• metadata: repository-required declared catalog metadata. Supported keys are required and ci_policy; unknown keys are errors. required defaults to [], must be an array of unique supported string names, and is normalized in registry order. The exact vocabulary and Skill/non-Skill spellings are in Repository-required metadata policy. ci_policy supports off, warn, and fail and defaults to fail. Required-field removal and mode weakening (fail -> warn, fail -> off, or warn -> off) are explicit CI matches. The stricter base/target mode governs the comparison. Requirement additions and mode tightening remain visible but are non-blocking solely as policy transitions. A decrease in findings caused by requirement removal is policy weakening, not verified remediation.

• diagnostics: repository-wide effective severity policy for scan findings, keyed by stable configurable Finding ID. Supported keys are severity and ci_policy; unknown keys, unknown diagnostic IDs, stable IDs that do not identify configurable scan Findings, and values outside low, medium, high, and critical are configuration errors. Raw discovery and configuration diagnostics retain their separate error | warning | info path. severity defaults to {}, so repositories without this section retain producer severities and existing scan behavior. ci_policy supports off, warn, and fail and defaults to fail. Lowering an override, removing an override, or weakening the CI mode is reviewable in ci-report; the stricter base/target mode governs the comparison, so the same change cannot disable its own review. Strengthening remains visible as a non-blocking policy transition, although a newly effective High or Critical finding still uses the ordinary scan and CI finding rules.

• agent_skills: repository-level Agent Skills governance. The supported name_uniqueness value is optional or required and defaults to optional. Duplicate normalized names are always detected and reported with every conflicting path. optional reports a warning and preserves Skill validity; required reports an error and makes every conflicting Skill invalid. This is a governance policy rather than a diagnostics.severity override. Skill name remains distinct from canonical renma.id, and Renma does not perform runtime telemetry.

• skill_discovery: strict repository-wide Skill Discovery configuration. Supported keys are boolean adopted and string ci_policy. The policy supports only off and warn, defaults to off, and warn requires adopted: true. Unknown keys and unsupported values are errors. renma init does not enable adoption or the CI policy.

The compatibility-only top-level layout object and its former tool_namespace and workflow_aliases children were removed before Renma 1.0. They never changed operational findings. An authored layout object is now a caller-correctable configuration error with exit code 2; delete it rather than replacing it with another key.

For scan, --fail-on and --format override the corresponding configuration values. --strict is caller-selected execution policy and is never loaded from repository configuration. Likewise, ci-report --fail-on-status is a CI-integrator exit threshold, not repository policy. Other commands use their documented command-specific format defaults and flags.

High token-budget results use the ordinary severity model. For example, renma scan . --fail-on high gates a Skill or governed content asset above its effective High threshold without --strict; Medium results remain below that exit threshold. diff loads each archived endpoint's effective quality policy independently, and ci-report retains those revision-local semantic findings while separately applying its established CI status model.

Within a canonical Skill entrypoint or one of its classified support documents, helper commands may use scripts/helper.mjs, ./scripts/helper.mjs, or an explicit noncanonical package path such as bin/helper.py; Renma resolves these paths against the owning Skill directory. Noncanonical executable targets stay visible as noncanonical inventory/invocation evidence and do not inherit Skill governance. tools/helper.mjs and ./tools/helper.mjs resolve from the repository root. Explicit repository-root paths such as skills/testing/demo/scripts/helper.mjs, .agents/skills/testing/demo/scripts/helper.mjs, and tools/testing/helper.mjs remain valid. Renma rejects helper candidates whose relative traversal would escape the owning Skill boundary and checks existence against the collected repository snapshot. It validates the declared path but does not execute the command. Non-Skill documents do not receive an inferred Skill-relative base.

Contexts and Lenses use the same individual-file script references and bounded invocation/dependency analyzers. For example, in contexts/deployment/README.md:

[Configuration validator](scripts/validate.py)

Run: `python scripts/validate.py`

Relative command paths resolve from the containing Markdown document; explicit repository-root paths retain their existing meaning. Exact links, quoted paths, and explicit prose path tokens record statically_references evidence. A link alone is not an invocation, and a directory or glob does not select its contents. No context.yaml, new frontmatter field, or directory entrypoint is needed. Supported scripts are discovered even without references. Each reference retains its source asset and target path. Direct Markdown links from inspected standalone Contexts/Lenses supply script owner candidates; commands, prose paths, language imports, and transitive references do not. Agreeing declared owners resolve one effective owner, while conflicting owners remain ambiguous with all candidates retained. Owner resolution does not inherit or combine security policy. Non-Markdown files in scripts/**, including extensionless helpers, are script surfaces just as in Skill support. Elsewhere in Context/Lens roots, the existing supported executable suffixes identify scripts. Markdown files retain their Context/Lens classification. Language analysis remains bounded to supported extensions; discovery alone does not imply full language coverage. Explicitly referenced scripts that cannot be inspected because of exclusions, symlinks, depth/size limits, or unreadability remain inspection-completeness blockers for strict scans, just like referenced Skill support. Skill-local path resolution, containment, and governance inheritance are unchanged. All analysis is static: Renma never runs these scripts or fetches their data.

For Context/Lens script ownership, directly linking standalone Contexts/Lenses supply declared-owner candidates. A README is unnecessary. Agreement resolves the owner; conflicting owners remain ambiguous, and no valid candidate means unowned. All candidates and reference edges are retained. Security policy is separate and is never inherited or merged by this rule. See the complete script ownership rules.

Static support reachability accepts explicit Skill-relative paths under their existing parsing semantics. Filename-shaped basenames are accepted only in Markdown body text, using quoted or unquoted exact-token forms and Markdown link targets. Reachability follows one additional hop through a directly referenced index/reference. Frontmatter metadata does not create basename-only static support reachability; explicit supported paths retain their existing behavior. Free-prose matches against generic filename stems such as run, check, or logo are not evidence, and wrapping command names such as npm, git, or node in inline code does not turn them into support references. Extensionless executables and quoted or linked asset paths with spaces are valid; .. traversal outside the Skill root remains invalid.

Use exclude for files Renma should not scan. Use suppressions for audited exceptions where Renma should scan the file, detect matching findings, omit them from the active finding set and failure decision, and retain them in the structured suppression ledger. A diagnostic is never duplicated into both diagnostics and suppressedDiagnostics. Each retained row identifies the diagnostic, evidence location, matching rule and path pattern, reason, and expiration. A suppression applies only when both id and paths match. Each suppression includes id, paths, required reason, and optional expires; the reason lives in config for auditability.

Diagnostic severity policy and suppression have separate responsibilities:

diagnostic producer     -> built-in severity
diagnostics.severity    -> repository effective severity
suppressions            -> explicit reviewed path-scoped exceptions
fail_on                 -> scan / CI failure threshold
diagnostics.ci_policy   -> governance for weakening severity policy

An active asset with a required dependency on a suspended asset already emits META-REQUIRED-SUSPENDED-DEPENDENCY at built-in High severity. The default fail_on: "high" therefore already blocks. A repository that wants an even stronger threshold can elevate the effective severity from High to Critical:

{
  "fail_on": "critical",
  "diagnostics": {
    "ci_policy": "fail",
    "severity": {
      "META-REQUIRED-SUSPENDED-DEPENDENCY": "critical"
    }
  },
  "suppressions": [
    {
      "id": "META-REQUIRED-SUSPENDED-DEPENDENCY",
      "paths": ["skills/legacy/**"],
      "reason": "Temporary migration exception",
      "expires": "2026-12-31"
    }
  ]
}

The dependency becoming suspended does not make Renma rewrite or suspend its active dependent. Renma detects the unresolved impact, applies the configured effective severity, and lets CI stop for a human or agent decision. Valid review outcomes include suspending the dependent, removing or changing the dependency, migrating to a replacement, or retaining a narrow justified suppression. Renma does not prescribe which remediation is correct.

A required dependency on a revoked asset instead emits the semantically distinct META-REQUIRED-REVOKED-DEPENDENCY, also at built-in High severity. Optional revoked dependencies emit META-OPTIONAL-REVOKED-DEPENDENCY at built-in Low severity. Repositories can configure those Finding IDs independently—for example, elevate only required revocation evidence:

{
  "diagnostics": {
    "severity": {
      "META-REQUIRED-REVOKED-DEPENDENCY": "critical"
    }
  }
}

Only the effective Finding severity changes; the built-in High default remains in structured traceability. Raw-only Discovery diagnostics are not configurable through diagnostics.severity.

Severity-policy diff compares effective values (repository override ?? built-in severity), not whether an override key was added or removed. An override equal to the built-in value is reported as neutral. When one stable ID cannot be resolved to one static built-in Finding severity, Renma reports the policy transition as review_required and lets diagnostics.ci_policy govern it instead of guessing a non-blocking direction.

Use a date in YYYY-MM-DD for temporary workarounds, or "never" when the exception is intentionally permanent. Permanent suppressions should still use narrow path patterns and a clear reason. Suppression path patterns are repository-relative and support exact paths, directory-prefix matches for non-glob patterns, * within one path segment, and ** across directories.

If --config is not provided, Renma checks the repository root for exactly renma.config.jsonc and renma.config.json. Both present is an ambiguity error because Renma does not choose, parse, or merge them. A legacy .renma.json is not a third supported candidate and instead fails with rename guidance. An explicit --config <path> selects a supported .json or .jsonc file even when conventional files coexist; an explicit .renma.json and other extensions are rejected. The explicit path must still identify a non-symlink regular file inside the scanned repository; external configuration is not treated as repository-owned policy authority.

Canonical Agent Skills entrypoints are:

These are qualified discovery shorthand globs; the structural exclusions in the entrypoint path contract still apply after a glob matches:

• skills/**/SKILL.md
• .agents/skills/**/SKILL.md

The repository walk reports historical skill.md and *.skill.md forms under either Skill root with migration guidance. They are not default scan globs, not operational Skills, and only become migration candidates when passed explicitly to suggest-metadata.

Other default scan glob families are:

• .agents/**/*.md
• AGENTS.md
• README.md
• contexts/**/*.md
• lenses/**/*.md
• contexts/**/scripts/**/*
• lenses/**/scripts/**/*
• contexts/**/*.{mjs,js,cjs,ts,mts,cts,sh,bash,py}
• contexts/**/*.[pP][sS]1
• contexts/**/*.{[bB][aA][tT],[cC][mM][dD]}
• lenses/**/*.{mjs,js,cjs,ts,mts,cts,sh,bash,py}
• lenses/**/*.[pP][sS]1
• lenses/**/*.{[bB][aA][tT],[cC][mM][dD]}
• skills/**/profiles/**/*.md
• skills/**/references/**/*
• skills/**/examples/**/*.md
• skills/**/scripts/**/*
• skills/**/assets/**/*
• .agents/skills/**/profiles/**/*.md
• .agents/skills/**/references/**/*
• .agents/skills/**/examples/**/*.md
• .agents/skills/**/scripts/**/*
• .agents/skills/**/assets/**/*
• tools/**/*

The two Skill roots intentionally use the same support discovery modes. Profiles and examples are Markdown-oriented. References, scripts, and assets may contain arbitrary file types. A discovered non-Markdown Reference remains reference support and is not Markdown-parser eligible merely because the default glob includes it.

Where To Go Next

• New to Renma? Start with Authoring Guide.
• Writing security-sensitive skills or context assets? Read Security Policy Guide.
• Fixing scan findings? See Diagnostics Reference.
• Reviewing thresholds? See Renma Quality Profile.
• Trying a minimal clarify-before-act Skill interaction? Use examples/interactive-placeholder.
• Trying richer repository-aware Skill, Context Lens, and Context Asset governance? See examples/context-repo.
• Focusing specifically on Context Lens governance? See examples/context-lens.
• Adding live Skill validation, composition, catalog, and CI evidence to GitHub Actions? See the GitHub Actions example. It updates one CI report comment for same-repository pull requests and keeps uploaded artifacts as the fallback for fork pull requests.

Commands

For a mini-repository with a statically navigable Skill, a Context Lens, shared Context Assets, ownership metadata, and graph relationships, see examples/context-repo. The consumer must have the checkout and follow the Skill and Lens relative links; the fixture is not a portable self-contained Agent Skills package.

renma commands fall into a few groups:

• Repository adoption: init records a minimal explicit repository policy without creating assets.
• Inventory and ownership: catalog lists discovered assets and references, ownership summarizes owned and unowned assets, graph shows relationships between catalog nodes, skill-index shows static Skill Discovery first hops and declared continuations, trust-graph exposes deterministic trust evidence, and bom combines declared repository evidence into a reviewable Repository Context BOM, and experimental execution-contract projects one Skill's portable executable evidence closure.
• Local inspection and authoring: guide prints the deterministic pre-generation Skill authoring contract, inspect reads one file as an outline or exact line slice, scaffold creates starter assets or authoring prompts, suggest-metadata emits safe metadata retrofit guidance for existing assets, and suggest-semantic-split packages source context and helper commands so a human or coding agent can draft a split for mixed-purpose Markdown.
• Review and CI: scan emits deterministic findings, readiness turns repository state into checks and a score, diff compares two refs, and ci-report formats the comparison for pull-request review.

Use renma --version (or renma -v) to print the installed package version.

Exit codes

The Renma CLI exposes one process-level exit-code contract:

Exit code	Meaning
0	The command completed successfully.
1	The command completed and emitted its normal report, but the requested Renma policy or status gate did not pass.
2	The invocation, configuration, requested target, or Git comparison ref is invalid or unavailable and can be corrected by the caller.
3	Renma encountered an unexpected internal failure.

Exit 1 is a completed semantic outcome, not a command-execution error. For example, a ci-report that is generated successfully with status FAIL exits 1. A ci-report that cannot resolve its requested baseline ref exits 2 without generating a report. An unexpected invariant or implementation failure exits 3 with a concise stderr message. Successful reports and completed exit-1 reports remain on stdout; invocation, configuration, input, and internal error messages use stderr. On completed CI reports, stderr also shows the report status, selected --fail-on-status threshold, and resulting exit code. Exit codes are process metadata and do not add fields to Renma's JSON report schemas.

Scan, Catalog, Graph, Trust Graph, Readiness, And BOM

These commands are related, but they answer different repository-review questions.

Command	Main question	Best for	Output shape
scan	What concrete problems were found?	Fixing diagnostics and CI checks	Finding list
catalog	What assets exist?	Reviewing IDs, owners, lifecycle metadata, hashes, tags, and declared dependencies	Asset inventory
graph	How are assets connected?	Inspecting dependencies and references	Asset relationship graph
execution-contract	What executable relationships are statically possible from one Skill?	Binding a future external runtime trace to deterministic static repository evidence	Experimental renma.experimental-execution-contract.v1 JSON
skill-index	Where can static Skill Discovery begin and continue?	Finding published entrypoints, declared continuations, reachability, coverage, and exact review evidence	Compact Markdown or renma.skill-index.v1 JSON
trust-graph	What evidence helps reviewers decide whether assets are safe, owned, current, and usable enough?	Tracing owner, lifecycle, policy, dependency, reference, and diagnostic evidence per asset	Evidence graph
readiness	Is the repository broadly ready for agent-facing use?	Maintainer summary and CI reporting	Repository-level scorecard
bom	What declared repository context manifest should reviewers inspect?	Combining catalog, graph, readiness, diagnostics, lifecycle, hashes, and security posture evidence	Repository Context BOM

catalog is about what assets exist. graph is about how assets relate. readiness is about repository-level health score and checks. trust-graph is about traceability of trust-relevant evidence. bom is the reviewable declared repository manifest that combines asset inventory, dependencies, hashes, lifecycle, diagnostics, readiness, and security posture evidence.

Every public JSON document has a top-level schemaVersion. Consumers must branch on that identifier rather than the package version or incidental field order. See Machine-Readable JSON Compatibility for the complete identifier inventory, 1.x additive/breaking rules, and the exact environment-derived values excluded from portable deterministic comparisons. In the npm type surface, ScanJsonDocument models the serialized scan wire shape with literal schemaVersion: "renma.scan.v2" and format: "json", as emitted by formatJson() and scan --format json. The producerless pre-serialization core scan model remains internal. The serializer explicitly projects supported wire fields, so a new internal scan-result property is not an implicit JSON-contract addition.

Use trust-graph when a reviewer asks: "Why should this asset be considered safe, owned, current, and usable enough for an agent-facing repository?" The command does not decide that an asset is trustworthy. It connects deterministic evidence that humans and downstream tools can review: owner, lifecycle status, dependency and reference relationships, selected security profiles, effective policy fingerprints, and diagnostics.

In short:

• scan lists problems.
• catalog lists what assets exist.
• graph shows structural relationships.
• execution-contract packages one Skill's static possible executable closure.
• skill-index shows static Skill Discovery entrypoints and continuations.
• trust-graph connects trust-relevant evidence.
• readiness summarizes repository health.
• bom combines declared catalog, graph, readiness, diagnostics, lifecycle, hash, and security posture evidence.

Examples:

renma scan . --format json
renma catalog . --format json
renma graph . --format json
renma execution-contract . --entrypoint skill.release-prep --format json
renma skill-index .
renma skill-index . --format json
renma trust-graph . --format markdown
renma trust-graph . --format json
renma readiness . --format markdown
renma bom . --format json
renma bom . --format markdown

init

Initializes repository-level Renma configuration at root, which defaults to .:

renma init
renma init .
renma init path/to/repository

When no conventional configuration file exists, init creates a concise renma.config.jsonc containing the initial fail_on and format policy plus one comment demonstrating where to preserve the rationale for a temporary policy exception. The command never overwrites, parses, normalizes, migrates, or validates an existing renma.config.jsonc or renma.config.json. If both supported files exist, init reports the ambiguity and changes neither. If .renma.json exists without that supported ambiguity, init exits with rename guidance and does not create another configuration file.

Use init when a repository wants to record explicit Renma adoption. Existing repositories can continue directly to scan because Renma operates with built-in defaults when no configuration file exists. The command does not create Skills, Context Assets, Context Lenses, example assets, or asset directories, and it does not run any repository analysis command.

renma scaffold creates one explicitly requested Skill, Context Asset, or Context Lens after its responsibility and asset boundary have been decided. It does not initialize repository configuration. Init the repository. Scaffold an asset.

scan

Scans a target path and prints findings.

renma scan .
renma scan . --format json
renma scan . --fail-on high
renma scan . --fail-on high --strict

Without --strict, scan retains its finding-threshold contract: active findings at or above --fail-on fail the command. Strict scan supplements that threshold and also fails for an Agent Skill that is specification-invalid or invalid under a required Renma Agent Skills governance policy, any Renma error diagnostic, a blocking inspectionCoverage issue, or applicable YAML frontmatter-comment security analysis that is not-analyzable because the parser-owned extractor could not complete that analysis safely. It does not make warnings, active suppressions, or other unsupported or non-analyzable security-analysis states generally fatal. A below-threshold finding remains below threshold in strict mode. The narrow security-analysis failure is exposed as strict_scan.incomplete_security_analysis; repository inspection failures remain strict_scan.incomplete_inspection.

Every scan includes renma.inspection-coverage.v1 JSON evidence. It counts expected first-class agent-facing paths plus statically proven Skill-support targets, paths actually represented in the inspection evidence appropriate to their surface, and blocking issues. Canonical Skill entrypoints and other deterministically classified first-class agent-facing assets are blocking when they are symlinks, unreadable, oversized, depth-limited, or otherwise present but unavailable to semantic inspection. A Skill-support target is expected only when one unambiguous owning Skill reaches it through references emitted by parsed sources. Each transitive edge therefore requires its own parsed source; Renma does not guess children hidden behind an unparsed parent. Blocking issues distinguish exact expected artifacts from subtree traversal boundaries and retain the owning Skill, reference source, source line, reachability depth, and required inspection kind for statically expected support. A symlinked, unreadable, or depth-limited directory under skills, .agents/skills, contexts, context, lenses, or .agents is a subtree issue when the configured globs can select first-class descendants there; the evidence names the affected boundary without guessing a hidden descendant path. Relevance is decided conservatively from the glob's literal prefix before its first magic segment: a provably disjoint prefix is ignored, while character classes, extglobs, braces, and other magic remain potentially overlapping. Exact non-glob paths use precise descendant and classification checks. Explicit scan-boundary exclusion is not a single-revision coverage failure for an otherwise inferred first-class path, but explicitly excluding a statically expected support target is blocking because the Skill still directs the agent to consume it. Unreferenced support and ordinary unsupported repository subtrees such as tools/vendor-cache do not turn strict scan into a requirement to parse every file. Opaque assets and executable scripts retain their own resource or executable-surface inspection semantics rather than being forced through plain-text semantic analysis. Renma never follows a blocked subtree or repository symlink.

Every scan also includes renma.security-analysis-coverage.v1 target-state JSON evidence. This is separate from repository inspection coverage: it records which existing security-analysis layers actually ran for each artifact Renma already discovered and scanned. The current layers are raw hidden Unicode, semantic instructions for Markdown and proven reachable plain-text Skill support, canonical Skill description, and eligible Skill or non-Skill YAML frontmatter comments. Renma does not walk additional files or infer runtime agent reachability to build this evidence.

Each layer reports analyzed, not-applicable, unsupported, blocked, or not-analyzable. unsupported makes current format limitations explicit. A discovered UTF-8 references/runtime.txt receives semantic instruction analysis only when existing static-support evidence proves it reachable from exactly one owning Skill; an otherwise identical unreferenced file remains unsupported. Plain text cannot declare Renma policy, and JSON, YAML, TOML, source code, executable support, and binary assets remain outside this path. A malformed, duplicate, or non-string canonical Skill description is not-analyzable, never analyzed. YAML comment coverage includes a separate surface count, so a valid Skill with zero comments still reports the comment analysis capability as analyzed with a count of zero. Coverage entries exist only for scanned artifacts. Statically expected support paths that could not be read, selected, or traversed remain exact blocking evidence in inspectionCoverage; Renma does not invent an artifact row merely to duplicate that evidence.

Human-readable output states whether inspection was complete, so zero findings with blocking coverage issues is not described as a complete result. The JSON output includes normalized diagnostics, suppressedDiagnostics, reviewBundles, trustGraph, executableSurfaceInventory, inspection coverage, security-analysis coverage, and summary data that other tools can consume.

These three facts are intentionally independent: a repository path may be successfully inspected, one or more security-analysis layers may still be unsupported for its format, and the supported layers may produce zero findings. inspectionCoverage says whether expected repository evidence could be inspected; securityAnalysisCoverage records supported security layers and their parser-owned execution states. Security-analysis coverage does not say that an artifact is safe, secure, fully analyzed, or safe for an LLM, and it does not change normal scan finding thresholds or CI policy. Most unsupported or not-analyzable layer states are informational coverage evidence. Strict mode additionally fails only when the applicable YAML frontmatter-comment layer reports yamlFrontmatterComments: "not-analyzable", because that is a security surface Renma expected to inspect but could not safely parse.

Output includes normalized scan and discovery diagnostics, the effective exit threshold, and evidence paths or snippets. Diagnostics may include typed repair constraints, structured verification steps, and concise LLM hints; reviewBundles groups related diagnostics for code review.

executableSurfaceInventory uses schema renma.executable-surface-inventory.v1. An executable surface is an already-discovered repository-local Skill, Context, or Lens script or tools/** helper that falls within Renma's existing bounded helper evidence. Rows report normalized path, scope, content classification and hash, conservative interpreter hints, static references and invocations, Skill-local reachability, and bounded security-policy correlation. Invocation rows retain launcher, target, source line, exact resolution state, and invocation-context governance evidence. Current rows also include bounded static executable dependency evidence and a per-surface direct, transitive, or unreached projection.

These layers have separate responsibilities: the executable surface inventory describes executable behavior Renma can statically observe in one revision; the executable surface diff describes what changed between two revisions; and executable_surface.ci_policy selects which high-signal diff transitions affect ci-report status. Evidence generation does not depend on enabling the policy.

Executable TypeScript surface extensions are .ts, .mts, and .cts, in addition to the established JavaScript, Python, shell, PowerShell .ps1, and Windows batch .bat / .cmd extensions. .tsx and .jsx are not executable surfaces in this release, and .psm1 module dependency analysis is not supported even where an existing Skill-local script classification makes such a file visible. This is static repository evidence and does not claim that every runtime configuration can execute every recognized extension.

Dependency analysis is deliberately limited to five private built-ins:

• js-ts analyzes text .js, .mjs, .ts, .mts, and .cts surfaces. It recognizes static string-literal ESM imports and export ... from declarations, including multiline, semicolonless, and import-attribute forms. Targets must start with ./ or ../ and explicitly end in .js, .mjs, .cjs, .ts, .mts, .cts, .py, .sh, or .bash.
• python analyzes text .py surfaces. It recognizes only explicit relative from imports. A module produces exact .py and /__init__.py candidates; from . import helper, parser produces separate candidate sets. Multiple parsed candidates are ambiguous.
• shell analyzes text .sh and .bash surfaces. At the beginning of one physical command line, after whitespace, it recognizes only ./helper.sh, bash ./helper.sh, sh ./helper.sh, source ./helper.sh, and . ./helper.sh, plus the corresponding single- or double-quoted relative path and repository-safe ../ form. The target must end in .sh or .bash. bash or sh must be followed immediately by the path; launcher options and wrappers are not interpreted. Execution forms emit static-execution; source and dot-source forms emit static-source.
• powershell analyzes text .ps1 surfaces. It recognizes an explicit relative .ps1 path at the start of a physical line, the & call operator, dot-sourcing, and exact pwsh -File or powershell -File forms; .exe launcher spellings are accepted under the same grammar. Single- and double-quoted relative literals qualify. Launcher names, -File, .ps1, and the sole supported $PSScriptRoot anchor are matched case-insensitively. The anchor is accepted only when followed by a static literal suffix with no other expansion. Execution emits static-execution; dot-sourcing emits static-source.
• batch analyzes text .bat and .cmd surfaces. It recognizes a direct explicit ./ or ../ batch path, immediate call, and exact cmd /c or cmd.exe /c forms. Double-quoted paths and the sole %~dp0 script-directory anchor with a static literal suffix qualify. CMD grammar tokens, the anchor modifier spelling, and .bat / .cmd extensions are matched case-insensitively. All recognized forms emit static-execution; transfer-versus-return behavior is not modeled.

The JS/TS collector ignores .cjs sources, .jsx, .tsx, dynamic import(), CommonJS require, packages, node: built-ins, absolute paths, template specifiers, query/fragment suffixes, extensionless imports, TypeScript declaration-level type-only syntax, and named import or re-export clauses made entirely of inline type Binding or type Binding as Alias specifiers. Mixed type/runtime clauses, default imports, namespace imports, and bindings literally named type remain runtime evidence. import = require, compiler substitution, directory indexes, aliases, package exports, project references, and import maps are also excluded. The Python collector ignores .pyi, .pyc, absolute imports, dynamic import helpers, package metadata, virtual environments, PYTHONPATH, runtime sys.path changes, and implicit containing-package edges. The shell collector ignores variables, parameter or command substitution, backticks, aliases, environment-assignment or wrapper prefixes, launcher options, globs, tilde expansion, concatenated quoted words, absolute paths, URLs, bare/PATH-resolved commands, unsupported target extensions, and commands that do not begin the physical line. Conservative lexical state also excludes recognized heredoc bodies, multiline single- or double-quoted literal regions, and physical lines continued from a preceding line. An unsupported or dynamic heredoc delimiter stops shell dependency collection for the remaining source rather than risking a false topology edge. A bounded arithmetic state recognizes obvious $(( ... )) and (( ... )) regions. Shift operators inside them are data for dependency purposes and do not enter heredoc state, so collection resumes for later supported commands. Bash <<< here-string operators are advanced over as complete non-heredoc tokens. Their operands do not create dependency evidence, and a later supported physical line remains eligible for collection. The PowerShell collector ignores variables other than its sole $PSScriptRoot anchor (matched case-insensitively), subexpressions, interpolation, wildcards, Invoke-Expression, Get-Command, aliases, bare command names, module loading, and runtime command discovery. It suppresses line comments, nested block comments, single- and double-quoted here-strings, multiline quoted data, and a physical line continued from a preceding backtick. An unsupported or unterminated lexical region can suppress recognition for the remaining source; an encountered PowerShell data statement is deliberately opaque from that point because Renma does not implement its restricted-language brace semantics. .psm1, .psd1, and Import-Module resolution are explicitly deferred. The batch collector ignores arbitrary %VAR% and !VAR! expansion, labels, bare command names, delayed expansion, generated command lines, arbitrary cmd options, and general command-block semantics. It excludes REM and :: comment lines and suppresses a physical line continued from a preceding ^. Windows separators are normalized to / before shared repository resolution; filesystem case is not normalized or emulated. A relative .. form that would escape the repository is retained only as unsafe resolution evidence and never becomes a graph edge. No collector executes code or implements a complete parser.

Dependency targets resolve only to surfaces already in the inventory. not-inventory means the exact parsed repository file exists but is outside that surface boundary. Other states are resolved, missing, unsafe, ambiguous, noncanonical, excluded, deep, oversize, unsupported, symlink, and unreadable. Python preserves every candidate and sets normalizedTarget only when selection is deterministic.

Every recognized syntactic declaration remains an auditable dependency row and contributes to totalDependencies, including identical declarations on the same source line. Public rows retain line numbers and occurrence ordinals; the private source offset used to distinguish declarations is not emitted. Graph topology instead contains one edge per unique source path and normalized target for resolved and noncanonical rows. Analyzer, relation, line, raw specifier, and occurrence ordinal do not distinguish graph edges. Incoming/outgoing counts, adjacency, reachability, and semantic diff graph signatures share this unique edge set.

Directly invoked surfaces have minimum dependency depth 0; a reachable imported surface is transitive at its minimum breadth-first depth; otherwise it is unreached. Cycles terminate, direct wins over transitive, and imports from unreached sources do not seed reachability. invokedSurfaces remains the direct count, so uninvokedSurfaces may include both transitive and unreached surfaces. “Uninvoked” does not mean unused, and transitive evidence is not runtime proof.

Surface policy evidence and invocation-context policy evidence have different meanings. Surface evidence belongs to or is inherited by the executable surface itself. Invocation-context evidence records prepared policy rows associated with the instruction artifact and its structurally resolved owning Skill. Calling-Skill policy is never assigned to a shared repository tool. Invocation-context policy is not propagated, merged, intersected, or checked for conflicts across executable dependency edges.

Invocation governance retains source-artifact and owning-skill relationships separately, including useful negative evidence. Renma does not merge their policy fields, select a precedence winner, or expose complete effective-policy values. “With effective policy evidence” means only that at least one recorded relationship already has effective policy evidence. Multiple distinct fingerprints describe visible policy variants; they are not a conflict, safety result, or compliance verdict.

Default scan text is action-oriented. A healthy inventory renders one compact line with total surfaces, direct/transitive static reachability, resolved invocation coverage, and invocation-context policy-evidence coverage; a surface-only inventory reports that no invocations were recognized and reports zero transitive reachability. Scan JSON and BOM JSON/Markdown retain the complete inventory.

Scan text expands to Executable Surface Review only for missing, unsafe, unscoped, non-canonical, or unavailable invocations; non-canonical surfaces; unreachable Skill-local surfaces; invocations without effective context-policy evidence; invocations with multiple effective fingerprints; or dependency rows that are not resolved. Expanded output includes a bounded Review dependencies: section with source line, analyzer, relation, target candidates, and exact resolution. It does not print complete source files. Output is bounded and includes only relevant surface, invocation, and dependency evidence. Repository-tool surface-policy absence, unreferenced tools, and uninvoked tools do not trigger review by themselves. Dependency unreached state also does not trigger review by itself. The review is informational and uses neutral evidence terminology.

Canonical scopes are skill-local for a script under the resolved owning Skill's scripts/**, and repository-tool for a helper under repository-root tools/**; Context/Lens scripts use repository-script. Other discovered scripts remain visible as noncanonical; the inventory does not silently discard them. Skill-local reachability uses the same static reference graph and minimum depth as existing support diagnostics. Context/Lens scripts use repository-script scope. Their parentResolution describes the number of directly linking Context/Lens source assets: no sources is missing, one is resolved, and multiple sources is ambiguous, even if their declared owners agree. One source supplies parentAssetCandidatePath and owningAsset; multiple sources supply parentAssetCandidates. For one source, reachableFromOwningAsset is true and owningAssetReferenceDepth is 1 because the link is direct. No README or structural parent directory is required. These fields are separate from ownership agreement and invocation/dependency reachability. Repository tools have no invented parent or parent reachability state.

The inventory recognizes the existing node, bash, sh, python, and python3 helper grammar plus exact Windows launcher forms: pwsh -File, powershell -File, cmd /c, and their .exe spellings. PowerShell launchers accept only .ps1; CMD launchers accept only .bat or .cmd. Windows launcher names, the bounded -File and /c switches, and these extensions are matched case-insensitively. This is not a generic option parser: pwsh -Command, cmd /k, dynamic targets, and arbitrary interpreter expressions remain unresolved. Captured path spelling remains exact; backslashes are normalized before the existing repository-root and Skill-relative scripts/** rules. Interpreter hints come from recognized launchers, a bounded first-line shebang for text files, then a supported extension fallback. Hints are descriptive evidence, not an execution decision.

Direct helper commands remain recognized on fenced-code lines. Renma also recognizes this exact bounded inline form:

Run `node tools/check.mjs`.
Run: `python scripts/check.py`.
- Run `bash scripts/check.sh` before proceeding.

The complete command must occupy one inlineCode node on one source line. Its direct mdast parent must be a paragraph, and the visible paragraph text before the code span must normalize to exactly case-sensitive Run or Run:. Top-level, ordered-list, unordered-list, and nested-list paragraphs qualify, including a soft source wrap between the cue and code span. Harmless formatting of the cue with emphasis or strong may qualify when it contains only allowed textual cue content and its visible text remains exactly Run. Markdown line breaks are whitespace and HTML comments may be ignored. Links, images, inline code, non-comment HTML, reference-like nodes, and unsupported descendants cannot contribute cue text; in particular, a link label or image alt value of Run is not an imperative cue. The command span itself must still be a direct paragraph child.

Headings, blockquotes, linked commands, emphasized or strongly formatted command spans, frontmatter, HTML-comment examples, multiline code spans, and ordinary inline code are excluded structurally. Blockquotes are intentionally excluded because quoted material may be an example or copied external instruction. Lowercase or case-insensitive cues, other English verbs, multilingual cues, broad prose classification, and shell prompt stripping are not supported. For example, Then run, Do not run, Try, Run this:, and bare `node tools/check.mjs` remain outside the grammar.

Only the span immediately following the exact cue can qualify. In Run `node tools/check.mjs`; pass `--local` when requested., the command is one invocation and the option span is not another. In Run `/status` and `node tools/smoke.mjs`., the second span is not recognized because its preceding visible paragraph text is no longer exactly the cue. Chained commands, alternatives, and secondary spans are deliberately deferred.

Inline and fenced commands use the same helper parser, path resolver, invocation governance, and executable-dependency reachability. A path already visible as a static reference on the same source path and line remains one reference rather than being counted again when it becomes an invocation. Inline syntax adds no origin field or separate public schema: scan JSON and BOM use the established invocation rows. Recognition is deterministic, reporting-only, and does not execute the command or imply general natural-language understanding.

Invocation resolution distinguishes resolved, missing, unsafe, unscoped, noncanonical, excluded, deep, oversize, unsupported, symlink, and unreadable. Unavailable targets never become invented surface rows. Path safety and scope are resolved first, then exact repository availability; canonical surface scope is considered only for parsed targets, so a non-canonical path never hides missing or unavailable evidence. A parsed Skill-local target is resolved only with exactly one owning Skill.

Shebang evidence requires #! at offset zero of the original first line. Indented or byte-order-mark-prefixed text is not a shebang; recognized invocation launchers and supported file extensions remain independent interpreter hints. Renma does not follow symlinks, inspect executable permission bits, execute/import/compile/sandbox files, or classify ordinary external commands.

catalog

Builds a deterministic catalog of discovered assets.

renma catalog . --format json
renma catalog . --format markdown

Use the catalog to review asset IDs, owners, status, dependencies, and metadata-derived references.

Output includes catalog assets, dependency edges, owners, lifecycle status, tags, and diagnostics.

bom

Prints a declared Repository Context BOM.

renma bom .
renma bom . --format json
renma bom . --format markdown
renma bom . --format json --omit-generated-at

Use the BOM when reviewers or CI consumers need one repository evidence manifest that combines existing Renma evidence. Renma currently emits only v3; v2 was the first supported long-term BOM contract and v3 updates its embedded Readiness checks. V3 includes normalized declared/effective ownership plus static support relationships. See the Repository Context BOM contract.

The BOM is not a record of actual LLM runtime usage. Renma does not collect telemetry, assemble prompts, choose task-specific context, inject context into agents, import consumed-context evidence, or claim what an LLM actually consumed.

JSON is the source of truth for automation. Markdown is a compact pull-request review view.

Renma derives each BOM from one in-memory repository snapshot: configuration, discovered artifacts, parsed documents, catalog, graph evidence, diagnostics, readiness, and security summaries all come from the same collected state.

BOM v3 additively includes the complete executableSurfaceInventory projection—schema, summary, surface, invocation, and dependency rows—so consumers can audit and diff the same evidence emitted by scan. No standalone executable BOM command is needed. Current output includes invocation governance and per-surface invocation aggregates, dependency rows, and per-surface dependency summaries unconditionally. The published BOM v3 schema carries forward those optional field boundaries from v2; each new object is strict when present. The nested executable-surface inventory remains v1.

By default, generatedAt records when the BOM was produced. Add --omit-generated-at when CI or review automation needs to avoid clock-based diffs. With the same checkout path, config path, repository contents, Renma version, and UTC evaluation date, repeated --omit-generated-at runs should produce byte-identical JSON. The option does not remove metadata freshness dates, suppress freshness diagnostics, normalize absolute root or configPath, hide file moves, or guarantee portable byte-for-byte output across runners.

execution-contract

This experimental command generates one portable static-evidence contract for an exact Skill ID or repository-relative SKILL.md path:

renma execution-contract . \
  --entrypoint skill.release-prep \
  --format json

renma execution-contract . \
  --entrypoint skills/release-prep/SKILL.md \
  --source-revision <git-sha> \
  --format json

The schema identity is renma.experimental-execution-contract.v1 with stability: "experimental"; this first shape has no long-term compatibility promise. Every canonical invokes relationship has expectation: "possible". Direct and transitive repository-script relationships reuse the executable graph's canonical edge semantics, while line-level duplicates remain in each relationship's evidence. contains remains separate structural placement and is never traversed as invocation. Neither relationship implies ownership, exclusive belonging, required execution, runtime use, or authorization. A suspended or revoked Skill retains its declared lifecycle evidence, but generating its contract does not permit execution.

The command calls repository collection once and derives every section from the same in-memory snapshot. It does not call the public BOM or graph commands, embed an absolute checkout root, or add generatedAt. Repeated output is byte-identical for the same repository contents, configuration, Renma version, evaluation date, entrypoint, and supplied revision value.

The artifact exposes three complementary identities:

Identity	Produced by	What it binds
sourceRevision	Caller, optional and unverified	A supplied revision provenance value
evidenceDigest	Renma, always present	The selected execution-contract evidence projection
External SHA-256	Caller, optional	Exact serialized JSON bytes, including sourceRevision when supplied

evidenceDigest uses SHA-256 with scope selected_execution_contract_evidence_v1. Renma calculates it from a versioned, domain-separated canonical payload containing the subject identity and content hash, projected executable surfaces and hashes/fingerprints, canonical and structural relationships, exact auditable relationship and unresolved evidence rows, bounded coverage/observation facts, and relevant diagnostics. Duplicate evidence remains digest-relevant even when topology is deduplicated.

The embedded payload excludes sourceRevision, itself, absolute checkout-root identity, timestamps, and output formatting. It is independent of checkout location and caller revision labels, but changes with selected content or auditable evidence. Unrelated files outside the selected projection do not change it. Exact source-authored evidence is retained, including unsafe absolute targets recognized from repository content. The digest works for dirty working trees, non-Git directories, extracted archives, and other VCS checkouts without inspecting Git state. It is not a repository hash, repository snapshot hash, Git-tree hash, or complete filesystem hash.

An external SHA-256 over execution-contract.json remains a separate exact- artifact identity. It covers the serialized formatting, optional sourceRevision, and embedded digest. That external hash is performed by the caller; Renma calculates the embedded selected-evidence digest.

unresolvedEvidence preserves relevant recognized evidence that did not become topology, including resolution classifications, raw targets or specifiers, paths, lines, launchers/analyzers, candidates, and occurrence ordinals. Zero unresolved rows means only that no unresolved recognized static evidence was observed. The bounded analyzers do not prove absence of dynamic, unsupported, or runtime-only behavior, and this phase performs no drift or runtime comparison.

--source-revision is recorded verbatim with providedBy: "caller" and verifiedByRenma: false. It complements the Renma evidence digest and is not a more authoritative version of that identity. Renma does not invoke Git or claim that the value matches the analyzed files. For historical evidence, the caller creates a detached worktree and supplies the same commit:

revision=<git-sha>
worktree=$(mktemp -d)

git -C /path/to/repository worktree add --detach "$worktree/repository" "$revision"

renma execution-contract "$worktree/repository" \
  --entrypoint skill.release-prep \
  --source-revision "$revision" \
  --format json \
  > execution-contract.json

sha256sum execution-contract.json

Git/worktree creation and exact-artifact hashing are caller operations, not Renma operations. Observation schemas, runtime-log import, conformance verification, and allowed/required/forbidden, ordering, call-count, approval, and execution-policy semantics remain deferred. See the dedicated Experimental Execution Contract document.

skill-index

Prints the canonical static Skill Index from one shared repository snapshot and its already prepared Discovery index:

renma skill-index
renma skill-index .
renma skill-index . --format markdown
renma skill-index . --format json
renma skill-index . --json
renma skill-index . --focus skill.release-prep --format markdown
renma skill-index . --focus skills/release-prep/SKILL.md --format json

Markdown is the default compact human/agent view. JSON uses schemaVersion: "renma.skill-index.v1" and preserves the existing complete Discovery Skill and route structures, adoption, repository-scoped coverage, publication and reachability facts, structural-root, standalone, and unrouted IDs, and separate repository and Discovery diagnostic arrays. Repository diagnostics stay repository-wide in a focused report. Route-cycle warnings appear naturally in the existing Discovery diagnostic array and affected Skill or route linkedDiagnostics; the v1 schema and top-level shape do not change.

Focus accepts only an exact effective Skill ID or exact repository-relative SKILL.md source path. It retains the selected Skill and its direct incoming and outgoing declarations without transitive traversal. It does not accept titles, tags, aliases, basenames, suffixes, case-insensitive or fuzzy matches, or task text. Selecting focus does not make a Skill reachable:

coverage is repository-scoped

summary and visible ID arrays are projection-scoped

The command writes only to stdout and creates no .renma/ directory, config, metadata, or generated index. It does not interpret a user request, recommend or rank Skills, load Context, assemble prompts, infer undeclared routes, call an LLM, invoke a child Skill, or execute a workflow. Warnings still produce exit 0; an error in either diagnostic collection produces exit 1; invalid CLI, config, focus, or report construction produces exit 2.

Open the referenced source SKILL.md, apply its description and routing conditions, and follow only a declared continuation supported by those source conditions. Renma reports possible declared paths; it does not choose them.

graph

Prints the relationship graph between assets.

renma graph . --view summary
renma graph . --view workflow --format markdown
renma graph . --view full --format mermaid
renma graph . --view layered --format mermaid
renma graph . --view discovery --format markdown
renma graph . --view composition --focus skill.testing.spec-review --format json
renma graph . --view impact --focus context.shared-api --format markdown
renma graph . --view executable --focus skill.release-prep --format markdown
renma graph . --view executable --focus tools/check-changelog.sh --format markdown

Views are:

• summary: compact graph overview.
• workflow: workflow-oriented relationships.
• full: all known graph edges.
• layered: Mermaid-focused graph grouped by asset kind so skill-to-lens-to-context paths are easier to read. lens is accepted as an alias.
• composition: the focused root's complete explicit required and optional Context/Lens closure. This view requires --focus.
• impact: the focused asset's complete reverse explicit required and optional Context/Lens closure, including declared dependent Skills. This view requires --focus.
• dependencies: transitive explicit composition plus static support references from a focused asset. Requires --focus.
• asset-impact: reverse traversal of the same composition and support edges from a focused asset. Requires --focus.
• discovery: exact declared Skill-to-Skill continuations, route eligibility/usability, declaration evidence, diagnostics, structural roots, and standalone Skills. Focus is optional and exact.
• executable: normalized Skill/Context/Lens-to-script and script-to-script invocation relationships, individual Context/Lens script references, and independent deterministic Skill-local structural containment. Focus accepts a Skill, Context, or Lens ID/path or an executable path.

Layered Mermaid output groups skills, context lenses, contexts, support assets, and unresolved targets into separate subgraphs. JSON and Markdown keep the same node and edge detail while reporting the selected view.

See Static Asset Dependencies for exact Context and cross-distribution support references, traversal boundaries, and examples. These views provide static review evidence without changing declared composition, ownership, policy, or runtime behavior.

Inspect executable relationships

Use the executable view to answer either direction of the same canonical relationship:

# Scripts invoked by a Skill
renma graph . --view executable --focus skill.release-prep --format markdown

# Skills using a repository script
renma graph . --view executable --focus tools/check-changelog.sh --format markdown

# Scripts referenced or invoked by a Context
renma graph . --view executable --focus contexts/deployment/README.md --format markdown

invokes edges come from normalized executable invocation evidence and the same canonical deduplicated script dependency topology used by inventory counts, adjacency, reachability, fingerprints, and diff signatures where applicable. Repeated declaration locations remain in the invocation and script dependency evidence tables while producing one graph edge. A script invoked by multiple Skills is labeled as shared, and focusing that script renders the canonical relationship in reverse as used by.

Context/Lens consumers retain their asset identity and source path. Exact file references appear as statically_references, whose reverse label is referenced by. These edges do not seed invocation reachability or add scripts to a Skill's experimental execution contract. Merely requiring a Context or Lens also does not imply an invocation of its scripts.

contains is separate structural evidence: Renma emits it only for a script inside the canonical scripts/** boundary of one uniquely resolved Skill. The reverse human label is belongs to; it means structural placement only. Invocation does not imply ownership, containment does not imply exclusive use, and a shared or repository-root script may be invoked without being contained. Observed absolute external executable targets are labeled separately and never receive containment. Ordinary external-command discovery remains outside the bounded helper grammar.

JSON preserves detailed evidence rows under executable; Markdown presents the relationship neighborhood and evidence tables; Mermaid distinguishes Skill, Context, Lens, repository-script, and external-executable nodes and uses separate edge labels. If no canonical relationship is available, the view explains the normalization boundary and directs the reader to scan --format json → executableSurfaceInventory for unresolved evidence.

Composition and Impact follow declared Context/Lens relationships in opposite directions. Composition reports the focus asset's transitive dependencies; Impact reports its transitive dependents. Both preserve required/optional membership and declaration evidence. Complete composition may still contain cycles; declaration order does not choose precedence or conflict winners. See Declared Composition and Declared Impact for relationship, resolution, and completeness rules.

Discovery reports explicit Skill continuations and publication, including unusable declarations without treating them as authoritative graph edges. Structural roots and published entrypoints are different facts. Repository-wide adoption controls whether reachability is descriptive or authoritative; focus preserves that global meaning. See the Discovery graph contract and route-cycle review guidance.

The graph forms answer distinct questions:

Form	Question
full without focus	What is in the whole catalog graph?
full with focus	What is the direct incoming and outgoing neighborhood?
composition with focus	What is in the transitive outgoing composition closure?
dependencies with focus	What composition and referenced support files are reachable from this asset?
asset-impact with focus	What assets transitively depend on this asset through composition or support references?
impact with focus	What is in the transitive incoming composition closure?
discovery without focus	Which eligible Skills are reachable from explicit published entrypoints through usable declared continuations, and is that evidence descriptive or authoritative?
discovery with focus	What global reachability state and direct incoming/outgoing declarations touch this exact Skill while repository adoption and coverage stay repository-scoped?

Focusing The Graph

The graph command can be focused on one asset with --focus <asset-id-or-path>.

Use this when you want to inspect the local neighborhood around one context asset, skill, or other catalog entry instead of reading the entire repository graph. A focused graph is useful for answering questions such as:

• What does this asset depend on?
• What other assets reference this asset?
• Is this asset connected to the expected parts of the context repository?
• Is this asset isolated or unexpectedly central?

Examples:

renma graph . --focus context.testing.boundary-value-analysis
renma graph . --focus contexts/testing/boundary-value-analysis.md --view full
renma graph . --focus skill.testing.spec-review --view composition --format markdown
renma graph . --focus context.shared-api --view impact --format markdown
renma graph . --focus skill.review-request --view discovery --format markdown

--focus accepts one value. The value must match either a catalog asset ID, a repository-relative source path such as contexts/testing/boundary-value-analysis.md, or an absolute source path. It does not match projected summary view node IDs such as contexts/testing/*.

Discovery focus is narrower: it accepts one exact Skill ID or repository-relative Skill source path and shows only direct incoming and outgoing declared continuation routes. A duplicate Skill ID makes ID focus ambiguous, so use one exact SKILL.md path. Discovery focus performs no fuzzy matching or automatic transitive traversal.

For summary, workflow, full, and layered views, --focus keeps the matched asset, its directly connected incoming and outgoing graph edges, and the assets at the other ends of those edges. The composition view instead uses the focus as the root of its transitive outgoing declared closure. The impact view uses the focus as the target of its transitive incoming declared closure. If the focus value does not match an asset ID or source path, the command exits with usage code 2 and reports that graph --focus did not match any asset id or source path.

For non-transitive projections, --focus runs before view grouping. For example, --view summary --focus <asset> selects the focused neighborhood and then groups that smaller graph. Composition and impact have no depth option because each resolves a finite explicit closure; repeated --focus flags are not a multi-focus API.

Note: this graph focus argument is a CLI option. It is not a metadata field on an asset.

Output includes graph nodes, relationship edges, declaration form and evidence, unresolved targets, and diagnostics. Composition JSON adds the complete composition-specific report; impact JSON adds the complete impact-specific report; discovery JSON adds visible Skill identities, all declarations, resolution and usability, evidence, structural roots, standalone IDs, and route diagnostics. Mermaid output renders the selected repository graph as a diagram definition, never runtime execution flow. Declared Impact is change-review scope evidence, not actual runtime usage or guaranteed breakage.

trust-graph

Prints deterministic Trust Graph evidence derived from catalog, graph, scan, and security policy data.

renma trust-graph . --format markdown
renma trust-graph . --format json
renma scan . --format json

Use this when a reviewer or downstream tool needs one stable evidence layer that links assets to owners, lifecycle status, declared dependencies, selected security profiles, effective policy fingerprints, and diagnostics.

Trust Graph is repository evidence. It does not compute a trust score, select or inject runtime context, assemble prompts, call an LLM, collect telemetry, or enforce policy at runtime.

Renma supports only Trust Graph v2, the first supported long-term contract. It includes normalized ownership and static owns_local_resource, statically_references, inherits_owner, and inherits_policy evidence. JSON is the source of truth; Markdown is for human review. scan --format json includes the same v2 contract under trustGraph.

Consumers must branch on schemaVersion, not on the Renma package version. Changes within v2 must remain additive and backward-compatible; an incompatible change requires a new schema version.

Reviewers can use Trust Graph to find assets without owners, find assets without lifecycle status, inspect assets sharing the same effective policy fingerprint, and connect diagnostics back to asset evidence. trust-graph exits 0 when the report is generated successfully; use scan --fail-on when CI should fail on findings.

metadata-keys

Print all metadata keys understood by the installed Renma version, without reading repository files or configuration:

renma metadata-keys
renma metadata-keys --format text
renma metadata-keys --format json
renma metadata-keys --json

The default is text. JSON returns three arrays: skill (flat keys under SKILL.md's metadata mapping), nonSkill (top-level keys for other assets), and agentSkillTopLevel (portable Agent Skills frontmatter fields). Keys follow the central metadata definitions in deterministic order. The list includes optional catalog, security, publication, auxiliary, and asset-binding keys; applicability varies by asset kind. It excludes arbitrary unknown/vendor extensions. Consult the metadata tables above for value formats and requirements. This command accepts no target path or repository configuration options.

inspect

Inspects one file as an outline or exact line slice.

renma inspect skills/testing/spec-review/SKILL.md
renma inspect contexts/testing/boundary-value-analysis.md --format json
renma inspect skills/testing/spec-review/SKILL.md --lines L10-L42

Use this when editing one skill or context file and you want a deterministic outline without reading the whole repository catalog. Without --lines, output includes file size, line count, frontmatter range, headings, code fences, links, asset relationships, and a concise Context Lens governance summary when repository context can be inferred. It also always includes classification with kind, scope, matchedRule, reasonCode, root or parent evidence, and concise competing rules. A Skill-local path exposes parentAssetCandidatePath; parentAssetPath appears only when parentResolution is resolved, while missing and ambiguous remain explicit fail-closed states. governance is separate and reports ownership, policy, and metadata provenance only from repository evidence. Unknown files and repository tools still receive classification. Use --lines <range> for an exact source slice; ranges can look like L10-L42 or 10-42. --lines output itself is unchanged.

JSON also includes repositoryBoundary. Resolved results record the root, repository-relative path, and resolution source. Unresolved results retain a stable reason code and candidateRoots; structural ambiguity uses repository-boundary-ambiguous instead of selecting a broad ancestor.

For a file target, Renma resolves a repository root from an explicit caller root, the nearest safe .git file/directory or Renma config marker, or an unambiguous structural boundary, in that order. Current-working-directory containment alone does not establish a repository. This keeps nested repositories and absolute targets outside the current directory deterministic without scanning an unrelated parent tree.

readiness

Prints a deterministic readiness report.

renma readiness .
renma readiness . --format markdown
renma readiness . --format json

Readiness combines catalog diagnostics, Context Lens governance diagnostics, ownership metadata, graph resolution, required and optional context references, asset status, selected scan findings, and a compact projection of the prepared Skill Discovery index.

JSON uses renma.readiness.v2. Compared with v1, v2 removes the producerless layout.disallowed_skill_assets check and adds skills.support_integrity, which fails when explicitly referenced Skill support is missing or cannot be inspected. The check uses authoritative static-support inspectionCoverage evidence for excluded, symlinked, unreadable, oversized, depth-limited, and unsupported targets, plus missing-reference evidence where inspection coverage intentionally has no missing-path issue. It ignores unrelated repository coverage blockers and unreferenced Skill-local files. Suppressing an ordinary support Finding does not convert authoritative support-inspection incompleteness into a pass. Consumers that key or allowlist checks must migrate to the new ID and meaning.

Readiness answers whether the repository currently passes Renma's readiness gates. The authoritative JSON level remains ready, needs_attention, or not_ready: a score of at least 90 with no failing check is ready, 70-89 with no failing check is needs_attention, and a score below 70 or any failing check is not_ready. renma readiness exits 0 only for ready; both other levels exit 1.

skills.support_integrity has no separate numeric score penalty. Its failing status still makes the overall level not_ready; this avoids inheriting the unrelated layout penalty from the removed location-policy check.

Markdown adds a presentation-only Status so actionable evidence does not look contradictory beside a ready level:

• Ready: level is ready, with no warning check, warning diagnostic, or finding.
• Ready with advisories: level is still ready, with at least one warning check, warning diagnostic, or finding. An info diagnostic alone is not an advisory.
• Needs attention: level is needs_attention.
• Not ready: level is not_ready.

Ready with advisories is not a fourth machine state and still exits 0. Warning-check and finding counts are shown separately because the underlying evidence can overlap. Findings on a ready report appear as non-blocking findings: they remain actionable, but they do not make the repository Not Ready unless an existing readiness score or check rule says so. Finding severity and Readiness blocking status are separate dimensions.

Output includes a readiness score and level, workflow checks, Context Lens counts, diagnostics, scan findings, graph or ownership summary data, and summary.skillDiscovery. The Skill Discovery summary reports the existing adoption state and counts for effective published entrypoints, route-eligible Skills, reachable and not-reached Skills, unrouted Skills, usable and unusable routes, unresolved routes, and maximal cyclic components. It does not embed the complete Skill or route graph.

The focused checks are discovery.publication, discovery.route_validity, discovery.coverage, discovery.unrouted_skills, and discovery.cycle_review. Coverage gaps are authoritative only when skill_discovery.adopted: true; partial and not-adopted coverage is descriptive and does not reduce the score. Cycles remain warning-level review evidence and do not by themselves make a repository not ready. These checks add no scoring weight, and Discovery diagnostics are referenced rather than duplicated or penalized again.

Markdown includes compact Context Lens and Skill Discovery sections. Run renma skill-index for the complete static Discovery report or renma graph --view discovery for topology and source evidence.

Security posture, Context Lens, and Skill Discovery summaries remain static repository evidence in this report. Readiness does not accept task text, select or execute a Skill, choose runtime context, assemble prompts, inject context, or describe what an LLM actually used.

diff

Compares deterministic repository evidence for two git refs.

renma diff . --base origin/main
renma diff . --from main
renma diff . --from main --to HEAD
renma diff . --from main --to HEAD --format markdown

Use this to review changes in Renma evidence between branches or commits. This is not a generic source-code diff.

Exactly one baseline is required: --from <ref> or its ergonomic alias --base <ref>. Renma does not guess a baseline, and supplying both options is an exit-2 usage error even when their values match. --to <ref> defaults to the concrete Git ref HEAD; it does not mean the uncommitted working tree. Explicit --to still selects another target ref. Renma compares the requested refs directly and does not substitute a merge base. Invalid baseline or target refs exit 2, with no generated comparison report.

Output includes readiness deltas, changed assets, graph edge changes, check changes, added or removed findings, and an additive renma.skill-discovery-diff.v1 section. It also includes an executableSurface section with count deltas, added/removed/changed surface paths, concise change reasons, semantic invocation-resolution changes, and line-insensitive invocation-governance changes. It reports line-insensitive added/removed executable dependencies, dependency resolution changes, new dependency evidence for review, newly transitive surfaces, lost static invocation reachability, and meaningful minimum-depth changes. Dependency edge count changes use dependency-graph; reachability/depth changes use invocation-reachability. Import-only changes are not classified as invocations, invocation-governance, or security-policy. Caller-only aggregate changes use invocation-governance; security-policy remains reserved for changes to the surface's own policy evidence. These governance changes are informational: no combined policy, conflict classification, or enforcement decision is derived. Generated diff JSON also lists newly added invocations that already carry multiple effective fingerprints, separately from path/resolution problems and from governance changes to invocations present at both endpoints. The Discovery section reports exact adoption and coverage transitions, count deltas, published entrypoint changes, newly reachable/not-reached and newly/resolved unrouted Skill identities, route additions/removals/state changes, and added/resolved cyclic components.

Asset comparison also uses the canonical catalog content hash. Newly generated JSON includes endpoint contentHash, a contentChanged boolean on changed asset rows, and summary.contentChangedAssets; changedFields remains limited to governance metadata such as path, kind, ownership, and lifecycle. A content-only edit is therefore a changed asset even when changedFields is empty. Markdown reports the content-change count and, for bounded changed-asset details, the before/after hashes. This remains semantic identity evidence, not a generic source-hunk renderer.

Asset endpoints in diff and CI-report JSON retain optional writableBy arrays. changedFields includes writableBy only when the normalized declaration changes. Comparison uses array contents in order, retaining duplicates: equal independently created arrays are unchanged, while reordering or changing duplicate counts is a declaration change. Existing metadata normalization trims entries and drops empty entries; diff does not sort or deduplicate principals.

Both Markdown reports show Writable by (declared) once for an unchanged declaration on a changed asset, or previous → new principals for declaration changes. A missing endpoint declaration is labeled Not declared. Added assets show their declaration; removed assets retain their previous declaration. When both endpoints omit it, no line appears. CI Markdown bounds principal lists using the existing item cap; JSON retains the full evidence.

owner remains maintenance responsibility; writable_by records declared modification principals. Omission means no Renma-specific modification constraint is declared, not “everyone allowed” or “access denied.” Principals are opaque identifiers, with no identity resolution or authorization enforcement. Each asset uses only its own declaration, without inheritance through parent Skills, references, or dependencies. Declaration changes introduce no CI warning or failure policy; existing required-metadata diagnostics still apply. Dependency impact and asset selection are unchanged.

Legacy or partially comparable snapshots do not assert that content stayed unchanged. contentChanged is omitted for an asset unless both endpoint hashes are present, and the aggregate content-change count is omitted unless every shared asset is comparable. Comparable changed rows may still retain their individual hash evidence in a partially comparable report.

Skills are identified by repository-relative path and ID. Routes are grouped by normalized source Skill path and normalized declared target, so declaration reordering, YAML array position, and source-line movement do not create false changes. Duplicate declarations change one declarationCount; resolution, candidate, target, lifecycle, usability, and reason changes under the same identity remain a changed route instead of removal plus addition. Cycle identity uses the sorted maximal component member IDs.

The renma.scan-boundary-diff.v1 section separately records canonical endpoint boundaries and every exact weakening or tightening fact. Its endpoint evidence uses renma.scan-boundary.v1 and contains config path (or null for defaults), sorted exact glob and exclusion declarations, maximum file size and depth, and active suppression declarations. Exact string identity is intentional because runtime discovery passes those declarations directly to path.matchesGlob and the exclusion predicate; evidence does not erase leading ./, trailing /, or backslash differences. Suppression paths remain separately normalized according to their runtime matcher. Suppressed finding ledgers remain available under the finding diff. The other semantic sections report facts only and do not affect the direct diff command exit code. Markdown caps detailed lists and directs readers to JSON for omitted entries.

ci-report

Formats a diff result for CI or pull-request review.

renma ci-report . --base origin/main
renma ci-report . --from main
renma ci-report . --from main --to HEAD --format markdown
renma ci-report . --from main --to HEAD --format json
renma ci-report . --from main --to HEAD --fail-on-status warn

ci-report uses exactly the same ref contract as diff: one mandatory --from or --base baseline, a --to default of the Git ref HEAD, a from/base conflict error, and exit 2 for an invalid requested ref.

The report summarizes readiness deltas, graph-resolution changes, added and removed findings, inspection-coverage regressions, and policy-relevant status. By default (--fail-on-status fail), PASS and WARN exit 0 and FAIL exits 1. With --fail-on-status warn, PASS exits 0 while WARN and FAIL exit 1. The threshold never changes the semantic report status and is never read from repository configuration. Usage, command, configuration, target, or ref errors exit 2; unexpected Renma failures exit 3. See Exit codes for the authoritative process contract.

Markdown includes a Status Reasons section derived from the same matched conditions used to compute status. It identifies findings with IDs and locations, unresolved required edges, readiness and coverage regressions, metric deltas, and active policy matches. Policy details retain their specific changes and match IDs; disabled policies may show informational matches but do not contribute a status reason. JSON retains its existing fields: full evidence is in diff and each policy evaluation, with no new status or exit fields. The CLI writes a separate completion line to stderr explaining whether report status meets the selected threshold and the resulting exit code. Stdout remains the complete JSON or Markdown report, including when the exit code is 1.

A worse readiness level, a previously passing readiness check becoming failing/error, a new blocking readiness check, or a newly introduced blocking inspection-coverage issue makes the report at least WARN; an independently failing condition remains FAIL. Existing baseline coverage issues are not revision regressions. Coverage diff containment is subtree-aware: a baseline exact path that was parsed and then falls below a target blocked subtree is reported as a meaningful regression, and a newly blocked agent-facing subtree is reviewable even when no exact baseline asset path is known. Target-state rejection of an already-existing issue is the responsibility of scan --strict.

Output includes a CI status (PASS, WARN, or FAIL), a summary, readiness changes, graph changes, review-focused finding changes, and Skill Discovery topology changes. An informational Executable Surface Changes section reports surface deltas, added/removed/changed paths, new unresolved, unsafe, non-canonical, or unavailable invocation evidence, Skill-local reachability changes, surface policy-evidence coverage, invocation-context policy-evidence deltas, newly observed invocations without effective policy evidence, gained or lost evidence, total before/after multiple-fingerprint counts, newly added multi-fingerprint invocations, and governance changes involving multiple effective fingerprints. It also reports dependency totals, resolved counts, analyzer counts, new dependency evidence for review, dependency resolution changes, newly transitive surfaces, and surfaces that lost static invocation reachability. The bounded dependency and governance lists use neutral evidence terminology, omit complete fingerprints, and do not enter newProblematicInvocations. The detailed evidence does not by itself affect the CI verdict; the separate executable-surface CI evaluator consumes only its documented high-signal item-level transitions. Newly generated JSON includes the complete renma.skill-discovery-diff.v1 value once at top-level skillDiscovery plus one renma.skill-discovery-ci-policy.v1 evaluation at top-level skillDiscoveryPolicy. It also includes one renma.security-policy-ci-policy.v1 evaluation at top-level securityPolicy; the nested diff.security.policyTransitions array is the canonical per-asset scalar/list transition evidence consumed by that evaluation. New reports also include renma.scan-boundary-ci-policy.v1 at top-level scanBoundaryPolicy. Reports also include renma.executable-surface-ci-policy.v1 at top-level executableSurfacePolicy, with archived from, to, and stricter effective modes, outcome, match count, and complete structured matches. The scan-boundary evaluation's effectiveBoundary is renma.ci-evidence-boundary.v1: target repository paths are evaluated against both archived endpoint coverage predicates and the inspected-path union is retained. sourceBoundaries (ordered base then target) and inspectedPaths are authoritative; flattened glob, exclusion, and limit fields are a deterministic envelope for review rather than a new merged-glob language. Repository semantic configuration, including effective security policy and Skill Discovery semantics, remains revision-local. Only evidence coverage is fail-closed against target-only narrowing. The existing nested diff remains Discovery-policy-free. Diff endpoints also expose the readiness ownership numerator, eligible-asset denominator, and coverage percentage while retaining the existing summary.ownershipCoverageDelta field.

Token-threshold changes appear in nested diff.qualityPolicy as renma.quality-policy-diff.v1, with asset kind, warning/High threshold type, old/new values, default/configured provenance, and weakening/tightening direction. Top-level qualityPolicy is renma.quality-policy-ci-policy.v1; it records archived from, to, and stricter effective modes plus outcome and complete weakening matches. modeTransition records configured endpoints and unchanged, weakening, or tightening direction; numericThresholdChanges independently counts numeric weakenings and tightenings. Increasing either threshold is weakening; decreasing one is tightening, and simultaneous changes retain both directions. A CI-mode weakening emits the stable quality_policy_ci.ci_policy_relaxed match. In effective fail mode any weakening makes the report FAIL; effective warn makes it at least WARN; when both endpoints use off, numeric threshold weakenings remain visible but do not change CI status. Mode tightening is visible but non-blocking. Markdown renders the Quality Policy section whenever the modes differ, numeric thresholds differ, or the evaluator has a match, so a mode-only relaxation never receives a no-regression review note. A finding that disappears alongside threshold weakening is not treated as verified remediation. This evaluator is separate from scan-boundary policy.

Markdown is a bounded, progressively disclosed review artifact. Its always visible portion shows status, range, readiness, ownership coverage, non-zero summary deltas, the content-changed asset count when available, and review notes so WARN and FAIL reasons remain immediately visible in a pull request. When detailed evidence changes without affecting those net deltas, compact non-zero change groups also call out affected assets, graph edges, checks, Skill Discovery, executable surfaces and governance, findings, or security-policy metrics. A true no-change report omits this overview instead of printing a zero-filled inventory.

Readiness details, semantic changes, executable-surface evidence, security metrics, and unchanged inventory are grouped under a collapsed Full report details disclosure.

The detailed Markdown shows before/after ownership counts and percentages, added and changed asset metadata with canonical declared and effective ownership, added and removed graph edges with resolution state, readiness check status/severity and summary changes, and concrete security policy inventory deltas. Each detail collection uses the shared presentation limit and directs reviewers to JSON when more items exist. JSON remains the complete, unbounded machine-readable report and is unaffected by Markdown disclosure.

A content-only asset edit is neutral by itself: it does not change CI status or the command exit code. It remains visibly reviewable as a changed asset, while an independently added high/critical finding or governed policy regression can make the same edit FAIL.

When an asset's normalized effective security boundary changes, the Security Changes section under Full report details adds only the non-empty policy details. Scalar network, external-upload, secret-handling, and human-approval fields render as before -> after. Approved network destinations, approved upload destinations, allowed-data values, forbidden inputs, and disallowed commands render as separate added and removed values. Removed forbidden inputs and removed disallowed commands remain visible. If network or upload access becomes enabled, Markdown also shows the resulting effective destination scope, even when the destination list itself did not change. That scope uses the shared presentation limit and reports omitted values; an empty scope says none declared and is not described as unrestricted. JSON retains the complete post-change destination lists.

For complete machine-readable evidence, use:

• diff.security.policyChanges: normalized before/after policy and field-level provenance.
• diff.security.sharedPolicyChanges: shared-source changes and every affected asset.
• diff.security.policyTransitions: matched-asset scalar/list transitions consumed by CI.

CI evaluates per-asset transitions, so opposite changes on different assets cannot cancel through aggregate counts. Direct diff Markdown shows a bounded Security policy relaxations list before Aggregate security metrics; CI-report keeps the policy outcome and transitions above collapsed details.

The Security-aware semantic diff contract defines direct/inherited/mixed/unresolved provenance, restrictive states, list-change directions, stable match IDs, and complete JSON versus bounded Markdown evidence. These are static policy-review facts; they neither prove runtime activity nor change scan --fail-on or Readiness scoring.

Configure this review policy independently from Skill Discovery:

{
  "security": {
    "ci_policy": "fail"
  }
}

The default is fail. CI reads both archived revisions and selects the stricter mode under off < warn < fail; a simultaneous fail -> off change therefore cannot bypass the gate. A match under fail makes CI-report FAIL and exit 1; under warn it promotes PASS to WARN; under off it has no status effect, while transition evidence and matches remain visible. No security outcome downgrades an existing failure.

Renma permits declared security policies to evolve, but weakening a security boundary is a reviewable security event. A reduction in scan findings caused by policy relaxation is not considered verified remediation. CI-report suppresses the generic Scan findings decreased. praise and explicitly says the decrease is not verified remediation when both occur. Removing or correcting the contradictory instruction without relaxing policy remains valid remediation.

Scan-boundary weakening is governed independently:

{
  "scan_boundary": {
    "ci_policy": "fail"
  }
}

The default is fail, and CI selects the stricter archived mode under off < warn < fail. Removing an include glob, adding an exclusion, reducing a size/depth limit, adding or expanding a suppression, or extending its lifetime is weakening. Opposite changes are tightening. A pattern replacement may retain both facts rather than pretending its net effect is known. Stable match IDs use the scan_boundary_ci.* namespace and identify exact patterns, limits, or suppression scopes rather than aggregate counts. The IDs are scan_boundary_ci.glob_removed, scan_boundary_ci.exclusion_added, scan_boundary_ci.max_depth_reduced, scan_boundary_ci.max_file_size_reduced, scan_boundary_ci.suppression_added, and scan_boundary_ci.suppression_lifetime_extended.

CI enforcement scans the target through the union of the base and target path coverage predicates. This both preserves base-trusted coverage and admits new target coverage without heuristic glob-language subset reasoning. A suppression affects that enforcement view only for an exact rule ID and normalized path scope active on both revisions at the evaluation date. Its trusted expiration is the stricter endpoint lifetime (never is positive infinity), so tightening does not reactivate an unchanged finding and weakening cannot extend base trust. Reason-only edits do not invalidate enforcement equivalence, and path scopes are intersected without broadening. Target-only additions, path expansion, or lifetime extension remain evidence but cannot hide a finding. When a finding count falls alongside boundary weakening, CI does not call the reduction verified remediation. Markdown renders repository-controlled suppression reasons as single-line inline code, and terminal text exposes line breaks and control characters visibly instead of interpreting them.

Executable-surface CI review is configured independently:

{
  "executable_surface": {
    "ci_policy": "warn"
  }
}

The default is off for backward compatibility: executable inventory and diff evidence continue to be generated, but matching changes remain informational. warn makes a matching change contribute WARN; fail makes it contribute FAIL. CI reads the actual configuration archived at both endpoints and uses the stricter mode under off < warn < fail, so a target revision cannot bypass an existing gate with fail -> warn, fail -> off, or warn -> off.

The initial policy consumes item-level evidence already present in the canonical ExecutableSurfaceDiff. Its stable matches are:

• executable_surface_ci.surface_added from addedSurfacePaths.
• executable_surface_ci.problematic_invocation_added from newProblematicInvocations.
• executable_surface_ci.problematic_dependency_added from newProblematicDependencies.
• executable_surface_ci.invocation_policy_evidence_missing from newInvocationsWithoutEffectivePolicyEvidence.
• executable_surface_ci.invocation_policy_evidence_lost from invocationsLostEffectivePolicyEvidence.
• executable_surface_ci.invocation_policy_ambiguous from newly added multi-fingerprint invocations and existing invocations whose target-side fingerprint count changes from at most one to more than one.
• executable_surface_ci.skill_local_reachability_lost from newlyUnreachableSkillLocalPaths.
• executable_surface_ci.static_invocation_reachability_lost from surfacesLostStaticInvocationReachability.
• executable_surface_ci.transitive_reachability_added from newlyTransitivelyReachableSurfacePaths.

One invocation may retain multiple independent policy reasons, so matchCount counts reasons rather than unique source lines. Matches are deterministically ordered and retain exact path, source line, target, occurrence, resolution, and governance transition evidence appropriate to their kind. Markdown presents a bounded ## Executable Surface CI Policy projection; JSON retains all matches without duplicating them into the canonical executable diff.

Ordinary content-only edits to an existing executable, surface removal, resolved dependency addition, resolved invocation addition with complete and unambiguous policy evidence, interpreter-only changes, line-only movement, reference-count-only changes, resolved problematic evidence, policy-evidence improvements, ambiguity resolution, and reachability improvements do not match by themselves. If one of those changes also causes an explicitly matched transition, that transition remains reviewable.

For ci-report, the evaluator consumes the same enforcement-view report.diff.executableSurface collected under the union of base and target scan-boundary coverage. It never performs a target-local rescan, so adding a tool while removing its target glob cannot hide that surface from this policy. The scan-boundary policy may independently match the narrowing. Direct renma diff remains observation-only and gains no status or exit policy.

This is static evidence. Renma does not execute scripts, prove runtime reachability, infer that a file is malicious, replace SAST, or perform general language-level semantic or data-flow analysis. “Transitively reachable” means reachable in the bounded static dependency graph, not observed execution.

Asset details in diff and CI-report JSON use canonical declaredOwner and effectiveOwner values. CI-report Markdown always renders both values so declared, inherited, and unowned states remain explicit.

Markdown also includes a bounded ## Skill Discovery Changes section after the general governance details. It summarizes configured and effective policy, policy outcome, adoption, coverage, published entrypoints, reachability, unrouted Skills, routes, cyclic components, and bounded policy matches. Use JSON for every identity when a Markdown section reports omitted entries.

The policy is disabled by default. To opt in:

{
  "skill_discovery": {
    "adopted": true,
    "ci_policy": "warn"
  }
}

CI reads ci_policy from both archived refs and uses the stricter mode under off < warn; both off -> warn and warn -> off therefore evaluate as warn. The fixed conditions are adoption weakening, target adoption being incomplete, newly not-reached Skills under authoritative target coverage, existing routes becoming unusable under authoritative target coverage, and added unusable routes under authoritative target coverage. Stable IDs and the full exact condition contract are listed in the Skill Discovery contract.

Cycles and self-loops, removed entrypoints, newly unrouted Skills, removed routes, declaration-count-only changes, newly reachable or resolved not-reached Skills, routes becoming usable, adoption becoming authoritative, and count-only deltas do not match. Policy matches add one review note and may upgrade existing PASS to WARN; they never create FAIL. A WARN report exits 0 with the default --fail-on-status fail, and 1 with --fail-on-status warn. Any existing non-Discovery FAIL remains dominant and exits 1 under either threshold. Ownership, asset, edge, readiness-check, and security inventory details are observability evidence and do not independently alter PASS, WARN, or FAIL. Readiness scoring and direct renma diff remain policy-free, and Discovery CI policy continues to control only its existing configured review behavior.

Serialized reports that predate the Discovery fields continue to format without a synthetic Discovery section. A report that contains skillDiscovery but no skillDiscoveryPolicy retains its observation-only Discovery section without an invented policy result. Earlier serialized reports without securityPolicy or diff.security.policyTransitions, or without executableSurfacePolicy, also continue to format, while newly built reports always emit the current policy fields.

Repository Context BOM artifacts describe declared repository state, not prompt assembly, context injection, agent execution, actual LLM runtime usage, or telemetry. Use renma bom . --format json when CI needs a machine-readable manifest and renma bom . --format markdown for review comments or artifacts. For v2 compatibility and reproducibility details, see the Repository Context BOM contract.

ownership

Reports asset ownership.

renma ownership .
renma ownership . --include-owned
renma ownership . --owner qa-platform
renma ownership . --format json

Use this to find unowned assets, review what each owner is responsible for, and filter the report to assets owned by a specific owner.

Output includes total asset count, owned asset count, ownership coverage, owner groups, and assets without an effective owner. --owner <owner> keeps the repository-level totals for context and adds filtered matched assets for that owner. Filtered JSON reports omit unownedAssetList so the repository-level unownedAssets count is not confused with owner-filtered asset details. --include-owned also includes the backward-compatible flat owned asset list.

Markdown preserves every script owner candidate, including all agreeing sources, conflicting declared owners, and undeclared sources. Candidate evidence includes source asset IDs, source paths, and direct Markdown link locations and snippets. An owner conflict has no effective owner and is labeled separately from an undeclared owner. Rendering does not select one parent or alter JSON or graphs.

Ownership policy

Renma treats owner as governance metadata. Declaring an owner is recommended because it makes context assets easier to review, maintain, and share across teams.

Owner metadata is not globally required. Assets without an owner are accepted and reported as unowned unless the repository explicitly configures metadata.required: ["owner"].

Renma resolves inherited ownership only from the documented explicit Skill-parent or Context/Lens direct-link evidence. It does not invent an owner when that evidence is missing or conflicting. Choose an undeclared owner or resolve an owner conflict through human review or team policy.

guide

Prints the deterministic authoring contract for a supported topic. skill is the only supported topic:

renma guide skill
renma guide skill --format prompt
renma guide skill --format json
renma guide skill --json

Prompt is the default. It is a compact execution projection of the core contract; JSON is the complete deterministic structured reference. Both derive from the same guidance data and include the installed Renma version. The command writes only to stdout, needs no repository, and performs no filesystem or network operations. Missing or unknown topics and unsupported arguments exit 2; use renma guide --help for the supported contract.

The JSON projection uses schemaVersion: "renma.skill-authoring-guide.v2". Consumers must branch on schemaVersion and must not apply v1 assumptions about ordered phases, mandatory clarification, fixed question batches, or the last phase containing human-review guidance. V2 owns human review explicitly in interaction.humanReviewRules; it does not reinterpret or emit v1 as the new contract.

The default prompt includes the smallest sufficient authoring contract. It tells the consuming LLM—not Renma—to inspect applicable truth sources, distinguish Confirmed, Proposed, and Unresolved decisions, classify Blocking, Reversible default, and Deferred progression separately, evaluate and pass the creation gate, ask only when unresolved Blocking human truth remains, classify findings conservatively, and re-enter the gate when asset boundaries may change. It also distinguishes authoring decisions from runtime task unknowns and gives unresolved items an action: Ask now, Queue as blocker, Proceed with reversible default, Defer, or Report as finding. Questions should respect prerequisite dependencies; their count and batching are adaptive, and Renma requires no decision graph, frontier, or round-based algorithm. These working classifications are not repository metadata or stored conversation state. A short request is enough to begin; no --interactive option or upfront plan document is required.

Both projections describe the small renma.skill-authoring-handoff.v1 contract. JSON includes a structured handoff section with its purpose, trust boundary, construction rules, and a template; the default prompt includes the handoff boundary and directs consumers to JSON for the template and complete reference. The consuming LLM creates a filled handoff only after no declared Blocking authoring decision remains. guide never fills or writes one itself.

The complete reference is domain-neutral and structurally separate from its optional illustrations. Renma does not classify a request by matching it to a built-in example or ask the LLM to choose the closest one. The consuming LLM applies the core contract to current evidence. It may ignore illustrations or combine individual decision patterns, but must not copy their workflows, structures, questions, completion criteria, security policies, unresolved items, or domain assumptions as templates. Optional illustrations do not change the core authoring contract.

The default prompt omits illustrations to reduce anchoring. JSON retains their useful optional structures and source-specific review details. Both projections derive from the same structured guidance source; they are intentionally not required to render every field identically.

The prompt does include the compact conditional rule that, when the finished Skill may recursively follow references discovered inside an external source, the consumer must consult and apply externalTraversalRules from the complete JSON reference before passing the creation gate. Detailed traversal mechanics remain in JSON.

Use it before generation, or when intentionally redesigning asset boundaries, to identify the smallest non-redundant asset graph, source-of-truth Context, focused Skill workflow, justified support files, metadata discipline, conciseness rules, and verification loop. It does not conduct the conversation, retain state, call an LLM, accept a natural-language task, design a Skill, create files, fetch URLs, select runtime Context, infer governance or domain facts, or claim that scan creates Context Assets.

scaffold

Creates one explicitly requested Skill, Context Asset, or Context Lens after its responsibility and asset boundary have been decided and, for Skill authoring, after renma guide skill establishes the intended graph. A Skill is a focused workflow entrypoint, Context is independently maintained knowledge, and a Context Lens is purpose-specific interpretation of one or more declared Context Assets. scaffold does not initialize repository-level configuration.

renma scaffold skill skills/testing/spec-review/SKILL.md --owner qa-platform
renma scaffold skill skills/testing/spec-review/SKILL.md --handoff /tmp/spec-review-handoff.json
renma scaffold context contexts/testing/boundary-value-analysis.md --owner qa-platform
renma scaffold context_lens lenses/testing/spec-review-boundary-values.md --owner qa-platform
renma scaffold skill skills/testing/spec-review/SKILL.md --owner qa-platform --format prompt
renma scaffold skill skills/testing/spec-review/SKILL.md --owner qa-platform --id skill.testing.spec-review --title "Spec review" --tags testing,review --resources references,scripts,assets

scaffold --format file writes a starter file, --format prompt emits an authoring prompt, and --format json emits structured scaffold data. The generated content is intentionally minimal; fill in metadata, dependencies, and verification steps before depending on it in automation.

--id, --title, and comma-separated or repeated --tags set scaffold metadata. For a Skill scaffold, --resources creates only the selected empty references, scripts, or assets directories; it never creates placeholder files or accepts other resource directory names.

--handoff <path> is an additive Skill-only workflow. The exchange file may be outside the repository and is read without network access. Before any filesystem side effect, Renma reads and parses it, requires schemaVersion: "renma.skill-authoring-handoff.v1" and topic: "skill", checks that progression.blocking is empty, confirms safe target-path agreement, validates canonical skills/**/SKILL.md or .agents/skills/**/SKILL.md identity and Agent Skills naming, rejects blank IDs, titles, and owners or owner: "unowned", and validates unique non-overlapping Context and Lens relationships, planned supporting-asset consistency, Context justifications, and the supported references, scripts, and assets resource kinds.

All handoff failures are caller errors (exit 2) and create no target or resource directory. A non-empty blocker list is not a policy-report failure and therefore never exits 1. The positional target remains the explicit side-effect boundary. Do not combine --handoff with --id, --title, --owner, --tags, or --resources; no precedence or merge is attempted.

For a valid handoff, scaffold applies the supplied id, title, owner, tags, resources, requiresContext, optionalContext, requiresLens, and optionalLens values directly. File mode writes the deterministic placeholder Skill plus only declared local resource directories. Planned supporting Context and Lens assets are recorded but never created by that invocation. Prompt mode includes the supplied decision sets, Skill contract, asset graph, source authorities, security decisions, and runtime-unknown handling for the authoring LLM. JSON mode adds the structured handoff projection to the normal bundle. Temporary Confirmed / Proposed / Unresolved and Blocking / Reversible default / Deferred state is not written into SKILL.md, and Renma does not synthesize polished prose from the supplied contract.

The published Skill Authoring Handoff v1 JSON Schema bounds the exchange shape. Cross-field checks remain deterministic TypeScript validation. Schema or structural success is not proof that the conversation occurred, the blocker set is complete, a source was actually authoritative or consulted, human review occurred, or domain declarations are true.

For a Context Lens, replace every placeholder purpose, applies_to, focus, and expected_outputs value with repository-grounded content. Every applies_to target must resolve to a real Context Asset. Do not use a Lens as generic persona storage, a prompt template, or a runtime routing rule, and do not create one when there is no Context Asset to interpret. See the Context Lens guide for the canonical decision model.

For a Skill, establish Renma boundaries first and use platform-native Skill authoring guidance only to refine semantics within them. File mode directs authors back to renma guide skill, Context decisions, scan, catalog and graph evidence, rerun, and human review. Prompt mode includes the same responsibility boundary and validation loop. Context and Context Lens output does not receive Skill-specific guidance. JSON retains the existing bundle shape.

After completing a Skill, run renma scan . --fail-on high, fix relevant diagnostics, rerun the scan, and complete human review. Do not use a second independent generator against the same target file.

suggest-metadata

Suggests a safe metadata retrofit workflow for an existing asset.

renma scan .
renma ownership .
renma suggest-metadata skills/testing/spec-review/SKILL.md --format prompt
renma suggest-metadata skills/testing/spec-review/SKILL.md --owner qa-platform --format json

Use this after scan detects metadata issues or ownership shows unowned assets. The command does not rewrite files. It emits a deterministic prompt or JSON payload that a human or coding agent can use to prepare a reviewed patch.

For Skill targets, metadata suggestion remains narrower than semantic authoring. Apply only intended metadata or migration changes; run renma scan . --fail-on high; fix relevant diagnostics; and rerun the scan. Use platform-native Skill authoring guidance separately when the requested work calls for semantic review. Context Asset output does not receive this Skill-specific metadata guidance. JSON adds classification, decisionStatus, structured decision evidence, and safe nextActions to the existing suggestion fields. Each action has kind and invocation; execute invocation.command with the exact invocation.args array. invocation.display is for people and must not be parsed as the machine contract, including on paths with spaces, quotes, or Windows separators.

When no repository root resolves, decisionStatus is blocked and Renma does not emit an executable scan . action. Establish the repository root with an explicit root or repository marker before verification; the caller's current directory is not assumed to contain the target.

For Skill targets using the legacy pre-0.16 Renma Skill format, metadata migration is one-way: recognized governance and security frontmatter becomes Agent Skills identity plus supported metadata.renma.*. Historical when_to_use and when_not_to_use may inform recovery of portable description text but are never emitted as Renma routing metadata. Separately, explicit skill.md and *.skill.md targets report any required entrypoint rename or move, even when their frontmatter already uses Agent Skills fields. For a canonical Agent Skill, --owner may instead propose an owner metadata retrofit; it never causes reverse migration. Skill migration sourcePath and targetPath values are repository-relative, including when the user invokes Renma from the parent of a nested repository. The normative behavior is documented in Agent Skills Compatibility and Migration.

Pre-0.16 security fields migrate with strict serialization: booleans become the exact strings "true" or "false", and lists become JSON-array strings of strings. Unsafe or ambiguous values block canonical frontmatter generation. For an already canonical Skill, suggest-metadata proposes neither migration nor an unnecessary rewrite unless an explicit supported retrofit is requested.

When migration is blocked, do not apply a candidate. Review the conflict or invalid evidence, confirm the Skill's intent with platform-native Skill authoring guidance, correct the source evidence, rerun suggest-metadata, then validate intended corrections with renma scan . --fail-on high.

Owner metadata remains recommended but not required. Without --owner, Renma does not invent an owner. With --owner <owner>, the command may include that owner because it was explicitly provided. If an existing asset already declares an owner, suggest-metadata preserves it; a different --owner value is treated as conflicting evidence and blocks a candidate. Renma does not infer owners from Git history, file paths, prose, or authors. If the explicit owner equals the existing canonical metadata.renma.owner, the result is suggestedMode: "no-proposal" with decisionStatus: "no-change-recommended"; no candidate metadata, canonical frontmatter, or patch instruction is emitted.

Ordinary Skill-local support returns suggestedMode: "no-proposal" and decisionStatus: "no-change-recommended" when it can inherit governance from one resolved parent Skill. Its candidateMetadata is empty. A missing or ambiguous parent returns decisionStatus: "blocked", leaves governance unowned or unresolved, and provides a scan/layout action instead of claiming inheritance. Existing explicit local owner or policy metadata is preserved under skill-local-existing-metadata-preserved; an explicit --owner can still request a supported intentional override after the parent resolves. Prompt and JSON output both distinguish the observed path fact, deterministic interpretation, recommendation, and remaining human decision. Repository tools and unknown paths never receive fabricated Context metadata candidates.

decisionStatus is authoritative: blocked never authorizes a patch, no-change-recommended stops without a patch, human-confirmation-required identifies what must be confirmed before applying only the candidate fields, and deterministic permits the reviewed candidate. Consumers should include a conservative default for unknown future suggestedMode values rather than assuming every non-no-proposal value is applicable.

suggest-semantic-split

Suggests a semantic split for large or mixed-purpose assets.

renma suggest-semantic-split docs/large-runbook.md
renma suggest-semantic-split docs/large-runbook.md --format json
renma suggest-semantic-split docs/large-runbook.md --max-source-bytes 32768
renma suggest-semantic-split docs/large-runbook.md --max-context-bytes 32768

Use this as an editing aid when an asset has grown beyond one clear responsibility.

Output is a prompt by default. With --format json, output includes source context, sibling-file context, helper commands, and a structured review bundle. The command does not apply a split itself; it gives a human or coding agent enough context to draft a proposal.

Output Formats

Use --format <format> to select output and --json as a shortcut where the command help lists that shortcut. scaffold supports JSON only through --format json. Avoid combining --json and --format: skill-index rejects --json with a non-JSON --format; the other commands that accept --json let it select JSON.

Command	Formats
metadata-keys	text, json
scan	text, json
bom	json, markdown
catalog	json, markdown
ownership	json, markdown
readiness	json, markdown
diff	json, markdown
ci-report	json, markdown
graph	json, markdown, mermaid
execution-contract	json
skill-index	json, markdown
trust-graph	json, markdown
inspect	text, json
guide	prompt, json
scaffold	file, prompt, json
suggest-metadata	prompt, json
suggest-semantic-split	prompt, json

Prefer JSON in automation and markdown for human review in pull requests. Use Mermaid when you want to render a graph diagram.

CI Workflow

Package-consumer CI

In an ordinary repository, install and commit Renma once as an exact development dependency:

npm install --save-dev --save-exact renma@0.44.0

Renma release preparation verifies this complete maintained command and the matching setup comment in the GitHub Actions example against the exact target version, including --save-dev and --save-exact. For the workflow, it also requires the exact npm ci step and every maintained npx --no-install renma invocation. Both files are part of the intended release-finalization set; a missing, stale, duplicate, floating, or malformed installation command blocks release preparation.

Commit both package.json and package-lock.json. CI then restores the locked dependency with npm ci and invokes its installed binary without allowing npx to download a missing package:

npm ci
npx --no-install renma scan . --fail-on high --strict
npx --no-install renma readiness . --format json > renma-readiness.json
npx --no-install renma ci-report . --base origin/main --format markdown --fail-on-status warn

The public GitHub Actions example uses this package-consumer model, checks out full Git history for ci-report, checks out the pull request's immutable github.event.pull_request.head.sha, and compares github.event.pull_request.base.sha directly with that head SHA rather than deriving refs from local branch names, and keeps the job that executes repository code read-only while a separate same-repository job owns pull-request comment permission.

Renma source-checkout development

When developing Renma itself from a source checkout, install its locked development dependencies, build dist, and invoke that checkout directly:

npm ci
npm run build
node dist/index.js scan . --fail-on high --strict
node dist/index.js readiness . --format json > renma-readiness.json
node dist/index.js ci-report . --base origin/main --format markdown --fail-on-status warn

These gates are complementary: strict scan validates the current target state, while the WARN threshold rejects meaningful review-time regressions. Security policy governance and scan-boundary governance remain independent contributors to the CI-report status.

renma readiness exits 1 when blocking diagnostics make the repository not ready, including Context Lens governance errors such as duplicate lens IDs, missing required fields, or unresolved applies_to targets.

Interpreting Results

renma reports three related but different kinds of output:

• Diagnostics: problems reading files, parsing metadata, or resolving catalog data. See Diagnostics Reference.
• Scan findings: rule results from scan, such as layout, security, maintenance, quality, profile, and support issues. Each scan finding has a finding identifier, such as SEC-LITERAL-SECRET, that labels the kind of issue independently from the file path, asset ID, or human-readable message.
• Readiness checks: workflow-level pass, warning, or error states derived from catalog, graph, ownership, and finding data.

Treat errors as blockers for deterministic automation. Treat warnings as review items that can become blockers when they affect agent reliability.