renma 0.17.0 → 0.18.1

package/docs/diagnostics.md

@@ -2,6 +2,18 @@
 
 This page documents diagnostics and finding identifiers emitted by the current renma implementation. It does not list planned diagnostics.
 
+Thresholds, units, provenance, and false-positive controls are canonical in the
+[Renma Quality Profile](quality-profile.md). Agent Skills specification
+errors are kept separate from Renma quality advisories.
+
+Agent Skills validation also reports authoring-only `RN-SKILL-*` warnings. In
+0.18.0, `RN-SKILL-DESCRIPTION-MISSING-CAPABILITY` identifies a generic
+description that does not say what the Skill does;
+`RN-SKILL-DESCRIPTION-MISSING-USAGE-BOUNDARY` covers when to use it; and
+`RN-SKILL-DESCRIPTION-OMITS-SELECTION-BOUNDARY` covers an important body
+exclusion missing from discovery metadata. These warnings do not make an
+otherwise specification-valid Skill invalid.
+
 ## Diagnostic Types
 
 renma uses two severity systems:
@@ -160,7 +172,7 @@ These diagnostics are emitted while renma discovers files.
 | Severity  | Message                                                    | Meaning                                             | Fix                                                                         |
 | --------- | ---------------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------- |
 | `error`   | `Could not evaluate glob "<pattern>": <error>`             | A configured discovery glob could not be evaluated. | Fix or remove the glob pattern in config or CLI input.                      |
-| `warning` | `Skipping symbolic link.`                                  | renma found a symlink and skipped it.               | Point config at the real file or directory if the target should be scanned. |
+| `warning` | `Skipping symbolic link; repository discovery never follows symlink targets.` | Renma found a leaf or directory symlink and skipped it without reading or enumerating its target. | Replace it with a regular repository file or directory. A referenced path at or below the symlink also emits `SUPPORT-SYMLINK-PATH`. |
 | `warning` | `Skipping file larger than max_file_size_bytes (<bytes>).` | A file exceeded the configured size limit.          | Raise `max_file_size_bytes`, exclude the file, or split the asset.          |
 | `error`   | `Could not read file: <error>`                             | The file matched discovery but could not be read.   | Fix permissions, remove the bad path, or exclude the file.                  |
 
@@ -168,7 +180,11 @@ These diagnostics are emitted while renma discovers files.
 
 These diagnostics are emitted after files are parsed into catalog entries. For shared-context wording details, see [Context Language Diagnostics](context-language-diagnostics.md).
 
-Owner absence is handled as ownership coverage information. Assets without `owner` are accepted and reported as unowned by `renma ownership`; Renma does not infer owners automatically.
+Owner absence is handled as ownership coverage information. Shared assets
+without `owner` are accepted and reported as unowned by `renma ownership`;
+Renma does not invent an owner. Skill-local support is the exception: it uses
+deterministic effective ownership inherited from its nearest owning Skill and
+reports that provenance separately from declared metadata.
 
 | Severity  | Message                                                                                           | Meaning                                                                                                                        | Fix                                                                                                             |
 | --------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
@@ -179,7 +195,7 @@ Owner absence is handled as ownership coverage information. Assets without `owne
 | `warning` | `Metadata dependency "<to>" from "<from>" does not match a catalog entry.`                        | A metadata dependency points at an asset renma did not discover.                                                               | Correct the reference, add the missing asset, or update include/exclude config.                                 |
 | `warning` | `Metadata dependency "<to>" from "<from>" targets a <status> asset.`                              | A dependency points at a deprecated or archived catalog target.                                                                | Retarget the dependency to a stable replacement or document the migration.                                      |
 | `warning` | `Asset is missing an id.`                                                                         | A cataloged asset has no stable ID.                                                                                            | Add an `id` metadata field.                                                                                     |
-| `warning` | `Asset is missing an owner.`                                                                      | A cataloged asset has no declared owner metadata. Missing owner is allowed and appears as unowned in ownership coverage; it is not converted into a scan finding by default. | If ownership matters for this repository, choose an `owner` through human review or team policy. Do not infer or invent an owner automatically. |
+| `warning` | `Asset is missing an owner.`                                                                      | A shared catalog asset has no declared owner metadata. Missing owner is allowed and appears as unowned in ownership coverage; nearest-Skill support inheritance does not apply to shared assets. | If ownership matters for this repository, choose an `owner` through human review or team policy. Do not invent one. |
 | `warning` | `Shared context asset is missing when_to_use metadata.`                                           | An active, owned shared context asset has no positive usage boundary.                                                          | Add compact `when_to_use` metadata that states when humans or agents should apply the context.                  |
 | `warning` | `Shared context asset is missing when_not_to_use metadata.`                                       | An active, owned shared context asset has no negative usage boundary.                                                          | Add compact `when_not_to_use` metadata so agents do not over-apply the context.                                 |
 | `warning` | `Shared context asset usage-boundary metadata contains placeholder values in <field>.`            | Usage-boundary metadata is present but still says TODO, TBD, unknown, none, or similar.                                        | Replace placeholders with reviewed scope boundaries, or remove the field until it can be completed.             |
@@ -199,6 +215,7 @@ Context Lens governance diagnostics use stable `code` values in JSON output. `er
 | `CONTEXT-LENS-GOVERNANCE-MEANINGLESS`      | `warning`            | A lens has no purpose, target, focus, expected output, or body guidance.                                      | Add compact governance metadata or reviewed interpretation guidance.                                    |
 | `CONTEXT-LENS-MISSING-REQUIRED-FIELD`      | `error`              | A lens is missing `id`, `owner`, `purpose`, or `applies_to`.                                                  | Add the required field in frontmatter.                                                                  |
 | `CONTEXT-LENS-PATH-NORMALIZATION-MISMATCH` | `warning`            | A path target normalizes to a different repository-relative path.                                             | Use the normalized path shown by the diagnostic.                                                        |
+| `CONTEXT-LENS-TARGET-NOT-CONTEXT`          | `error`              | An `applies_to` target resolves to a cataloged asset whose kind is not `context`.                             | `applies_to` must reference a Context Asset ID or path; Skills, support assets, other Lenses, and repository metadata are not valid Lens targets. |
 | `CONTEXT-LENS-TARGET-NOT-FOUND`            | `error`              | An `applies_to` target does not resolve to a cataloged asset ID or path.                                      | Correct the target, add the missing context asset, or update discovery config.                          |
 | `CONTEXT-LENS-UNPARSEABLE-FRONTMATTER`     | `error`              | A lens frontmatter block starts with `---` but does not close.                                                | Add the closing `---` delimiter or remove malformed frontmatter.                                        |
 | `CONTEXT-LENS-UNSUPPORTED-KIND`            | `warning` or `error` | `type: context_lens` appears under an unsupported artifact kind, or a lens file declares an unsupported type. | Store lens definitions under `lenses/**`, `context/**`, or `contexts/**`, and use `type: context_lens`. |
@@ -265,6 +282,16 @@ Non-Skill assets continue to use `allowed_data`, `network_allowed`,
 inline-list, and block-list behavior is unchanged. Pre-0.16 top-level Skill
 security fields are migration input only.
 
+Script and asset bytes never declare local policy. They participate in the
+security policy inventory even when they have no effective policy. Local
+support inherits policy only from one unambiguous owning Skill; text scripts
+may be scanned under that inherited policy from line 1. Ordinary assets and
+binary files do not contribute instruction text. Orphan scripts receive no
+policy-dependent repository-config evaluation without traceable ownership.
+The inventory distinguishes local metadata, inherited policy, effective policy,
+and no-effective-policy states. Trust Graph policy edges exist only for
+artifacts with effective policy and list every contributing policy source.
+
 Security profiles in `renma.config.json` retain the existing JSON schema.
 Artifact-local explicit denials remain stricter than inherited profile or
 repository allowances, and network approvals remain separate from upload
@@ -278,8 +305,8 @@ examples by asset kind.
 | `LAYOUT-CONTEXT-REFERENCE-NON_CANONICAL`         | Declared dependency uses a non-canonical reference root. | A declared dependency points outside accepted `contexts/**`, `skills/**`, `.agents/skills/**`, or `tools/**` reference paths. | Rewrite the dependency to an accepted repository-relative asset path or ID.                             |
 | `LAYOUT-DISALLOWED-SKILL-ASSET`                  | Compatibility identifier for specific local-policy violations. | Valid Agent Skills support paths do not emit this finding solely because of location. Reusable knowledge is handled by evidence-based maintenance advisories. | Review the specific evidence; keep genuinely local support in place or promote reusable knowledge through human review. |
 | `LAYOUT-HELPER-NON_TOOLS`                        | Helper file is outside supported helper locations.   | A helper script is neither under `tools/**` nor a valid Skill-local `scripts/` directory.                    | Move shared helper code under `tools/**`, or keep a genuinely Skill-specific helper in local `scripts/`. |
-| `LAYOUT-SKILL-EXECUTABLE-COMMAND`                | `SKILL.md` includes executable command detail.       | A skill entrypoint contains shell commands instead of delegating to helpers.                       | Move commands to approved helpers and keep `SKILL.md` as routing guidance.                             |
-| `LAYOUT-SKILL-NOT-THIN`                          | Skill entrypoint is too large or procedural.         | `SKILL.md` contains long procedures, setup, or troubleshooting content.                            | Split detailed material into references, profiles, examples, or tools.                                 |
+| `LAYOUT-SKILL-EXECUTABLE-COMMAND`                | Removed 0.17 compatibility identifier.               | 0.17 treated any command as evidence against a thin router.                                        | No replacement based on command presence; security and helper-path diagnostics remain.                 |
+| `LAYOUT-SKILL-NOT-THIN`                          | Removed 0.17 compatibility identifier.               | 0.17 treated procedures and word counts as evidence against a thin router.                         | Review `QUAL-SKILL-MIXED-RESPONSIBILITY` or progressive-disclosure evidence instead.                    |
 | `MAINT-ASSET-REFERENCES-SUPERSEDED-ASSET`        | Asset references superseded context.                 | Metadata or content points at an asset marked superseded.                                          | Retarget the reference to the stable replacement.                                                      |
 | `MAINT-ASSET-EXPIRED`                            | Asset freshness metadata is expired.                 | `expires_at` is before today's date.                                                               | Review the asset with its owner, then update freshness metadata, status, or references.                |
 | `MAINT-CONTEXT-LENS-APPLIES-TO-INACTIVE-CONTEXT` | Context lens applies to inactive context.            | An active context lens applies to a deprecated or archived context asset.                          | Point `applies_to` at an active replacement, or update the lens lifecycle after review.                |
@@ -291,11 +318,11 @@ examples by asset kind.
 | `MAINT-REPEATED-CODE-BLOCK`                      | Duplicate code block appears across assets.          | Copy-pasted examples or procedures repeat in multiple files.                                       | Extract shared guidance or consolidate the repeated block.                                             |
 | `MAINT-REPEATED-CONTEXT-PATTERN`                 | Repeated context-like wording appears.               | Multiple assets duplicate the same reusable context pattern.                                       | Promote the shared pattern into a context asset and reference it.                                      |
 | `MAINT-REPEATED-HEADING`                         | Same heading repeats across assets.                  | Similar sections are copied through several files.                                                 | Consolidate or reference a shared source of truth.                                                     |
-| `MAINT-REPEATED-LINK`                            | Same link repeats across assets.                     | Repeated references suggest duplicated guidance.                                                   | Centralize the reference or keep only necessary local links.                                           |
+| `MAINT-REPEATED-LINK`                            | Removed from default maintenance findings in 0.18.0. | Repeated links to one official source are normal.                                                   | No action based on link equality alone.                                                                |
 | `MAINT-REPEATED-SECTION`                         | Similar section text repeats.                        | A section has been copied into multiple assets.                                                    | Extract common material or reduce duplication.                                                         |
 | `MAINT-SKILL-CONTEXT-REFERENCE-NOT-DECLARED`     | Skill mentions context without metadata.             | Body text references `contexts/...` but `requires_context` omits it.                               | Add the context to `requires_context` or remove the stale mention.                                     |
 | `MAINT-SKILL-REFERENCES-SUPERSEDED-ASSET`        | Skill refers to superseded context.                  | Skill content names a superseded context asset.                                                    | Update the skill to the stable replacement context asset.                                              |
-| `MAINT-SKILL-REUSABLE-CONTEXT-CANDIDATE`         | Skill contains reusable context.                     | `SKILL.md` includes broadly reusable setup, troubleshooting, or risk guidance.                     | Move reusable content to shared context and reference it.                                              |
+| `MAINT-SKILL-REUSABLE-CONTEXT-CANDIDATE`         | Disabled compatibility identifier.                   | 0.17 used broad workflow signals for reusable Context candidates.                                  | Review `QUAL-SKILL-MIXED-RESPONSIBILITY`; keep core workflow and Skill-specific detail local.           |
 | `MAINT-SUPPORT-ASSET-SHARED-CONTEXT-CANDIDATE`   | Support asset looks reusable.                        | A reference, profile, or example contains content useful beyond one skill.                         | Promote it to shared context when reuse is intended.                                                   |
 | `META-CATALOG-DIAGNOSTIC`                        | Catalog diagnostic was promoted to a scan finding.   | Catalog validation emitted a lower-level diagnostic.                                               | Fix the original catalog diagnostic shown in the finding evidence.                                     |
 | `META-CONTEXT-MISSING-WHEN-TO-USE`               | Shared context usage boundary is missing.            | An active, owned shared context asset lacks `when_to_use`.                                         | Add compact positive scope guidance.                                                                   |
@@ -317,16 +344,24 @@ examples by asset kind.
 | `QUAL-MISSING-REQUIRED-INPUTS`                   | Required inputs are unclear.                         | The asset does not state what information is needed.                                               | Add an explicit required-inputs section.                                                               |
 | `QUAL-MISSING-ROUTING-CLARITY`                   | Routing guidance is unclear.                         | A skill does not clearly say when to use it.                                                       | Clarify triggers, audience, and handoffs.                                                              |
 | `QUAL-MISSING-VERIFICATION`                      | Verification guidance is missing.                    | The asset lacks checks for validating the result.                                                  | Add verification steps or expected evidence.                                                           |
-| `QUAL-SHORT-DESCRIPTION`                         | Description is too short.                            | Metadata description is present but not informative.                                               | Expand it enough to explain purpose and scope.                                                         |
-| `QUAL-SKILL-TOKEN-BUDGET`                        | Skill content is too large.                          | A skill exceeds the configured token budget.                                                       | Split support content out of the skill entrypoint.                                                     |
-| `QUAL-SUPPORT-ASSET-TOKEN-BUDGET`                | Support asset is too large.                          | A reference, profile, or example exceeds its token budget.                                         | Split the asset or shorten nonessential material.                                                      |
+| `QUAL-SHORT-DESCRIPTION`                         | Disabled compatibility identifier.                   | 0.17 applied an independent 150-character minimum.                                                  | Use Agent Skills validity and selection-boundary diagnostics; short clear descriptions are accepted.  |
+| `QUAL-SKILL-MIXED-RESPONSIBILITY`                | Skill may mix workflow and reusable knowledge.       | A sufficiently large Skill has multiple distinct reusable-knowledge signals.                       | Promote only independently owned shared knowledge; keep Skill-local workflow and detail local.         |
+| `QUAL-SKILL-PROGRESSIVE-DISCLOSURE`              | Progressive disclosure needs review.                 | Reserved 0.18 focused-workflow contract identifier.                                                | Keep read conditions and core workflow in `SKILL.md`; place details by semantic responsibility.        |
+| `QUAL-SKILL-TOKEN-BUDGET`                        | Skill body exceeds an advisory estimate.             | Markdown body exceeds 2,000 or 5,000 estimated tokens.                                             | Review progressive disclosure without splitting or moving content by size alone.                       |
+| `QUAL-INVALID-TOKEN-BUDGET-OVERRIDE`             | Support-asset decision metadata is invalid.           | The decision is malformed, unsafe to represent exactly, ambiguous, incomplete, orphaned, duplicated, or unnecessary while the asset remains within its default. | Correct or remove the declaration. Ask about a meaningful split first; use an override only after the user confirms the asset should remain intentionally long. |
+| `QUAL-SUPPORT-ASSET-TOKEN-BUDGET`                | Support asset exceeds its effective advisory estimate. | A context, reference, profile, or example exceeds its default or valid declared override.          | Ask whether a semantic split preserves coherence and execution order. Split only with user agreement; otherwise record an explicit rationale, never an override added merely to pass diagnostics. |
 | `QUAL-USER-LOCAL-PATHS`                          | User-local path appears in content.                  | Guidance includes machine-specific paths such as home directories.                                 | Replace local paths with repository-relative or configurable paths.                                    |
 | `SEC-DESTRUCTIVE-COMMAND`                        | Destructive command appears.                         | Content includes risky commands such as forced deletion or reset.                                  | Remove it, gate it with explicit safety guidance, or use a safer command.                              |
 | `SEC-ENV-COPY`                                   | Environment copying is suggested.                    | Content copies broad environment or secret-bearing files.                                          | Narrow the copied data and document secret handling.                                                   |
 | `SEC-LITERAL-SECRET`                             | Literal secret-like value appears.                   | Content includes token, password, key, or credential patterns.                                     | Remove the secret and replace it with a placeholder.                                                   |
 | `SEC-PRIVATE-KEY`                                | Private key material appears.                        | Content includes a private key block.                                                              | Remove the key and rotate it if it was real.                                                           |
 | `SEC-REMOTE-DEFAULT`                             | Remote command default is unsafe.                    | Guidance defaults to network commands, prod hosts, or insecure flags.                              | Use safe examples and require explicit approval for risky remotes.                                     |
-| `SUPPORT-MISSING-REACHABILITY-GUIDANCE`          | Support docs are not discoverable.                   | A skill has local profiles, references, or examples without routing guidance.                      | Add guidance that explains when to load each support asset.                                            |
+| `SUPPORT-MISSING-REACHABILITY-GUIDANCE`          | Local resources are not discoverable.                | A Skill has local references, scripts, assets, profiles, or examples without routing guidance.     | State when each resource should be read, executed, or used.                                            |
+| `SUPPORT-DEEP-REFERENCE-CHAIN`                   | Local resource is behind more than two hops.         | A resource is reachable only through a deep static chain.                                          | Reference it directly or through one directly referenced index.                                       |
+| `SUPPORT-MISSING-PATH`                           | Referenced local resource does not exist.            | `SKILL.md` names a path under a standard local resource directory that is absent.                  | Create the intended resource or correct the Skill-root-relative path.                                  |
+| `SUPPORT-SYMLINK-PATH`                           | A symbolic-link resource is intentionally unusable.  | Discovery encountered a symlink, or Skill guidance references a path at or below one.              | Replace it with a regular repository file or directory; Renma never follows symlink targets.           |
+| `SUPPORT-UNREACHABLE-ASSET`                      | Local asset is unreachable.                          | A Skill-local asset has no direct or transitive static reference.                                  | Add an explicit use condition and path from the Skill or its direct index.                             |
+| `SUPPORT-UNREACHABLE-SCRIPT`                     | Local script is unreachable.                         | A Skill-local script has no direct or transitive static reference.                                 | Add an explicit execution condition and path from the Skill or its direct index.                       |
 | `SUPPORT-UNREACHABLE-EXAMPLE`                    | Example is unreachable.                              | A skill-local example is not referenced by the skill.                                              | Link it from the skill or move/remove it.                                                              |
 | `SUPPORT-UNREACHABLE-PROFILE`                    | Profile is unreachable.                              | A skill-local profile is not referenced by the skill.                                              | Link it from the skill or move/remove it.                                                              |
 | `SUPPORT-UNREACHABLE-REFERENCE`                  | Reference is unreachable.                            | A skill-local reference is not referenced by the skill.                                            | Link it from the skill or move/remove it.                                                              |

package/docs/metadata-budget.md

@@ -4,11 +4,43 @@ Renma intentionally keeps asset frontmatter small. Frontmatter should work as a
 
 Use frontmatter for concise fields such as `id`, `owner`, `status`, `tags`, `when_to_use`, `when_not_to_use`, and declared context relationships. Put detailed guidance, examples, procedures, policy rationale, and long routing prose in the markdown body or in referenced context assets.
 
+Contexts, references, profiles, and examples also support these top-level
+human-decision fields:
+
+```yaml
+token_budget_override: 6000
+token_budget_rationale: "This is a single ordered workflow and splitting it would break execution order."
+token_budget_reviewed_at: "2026-07-12"
+```
+
+`token_budget_override` must be a positive safe integer greater than the asset
+kind's default content limit, and `token_budget_rationale` must be a non-empty
+string. `token_budget_reviewed_at` is optional and must be a real `YYYY-MM-DD`
+date when present. Invalid metadata does not replace the default limit.
+The three fields form one decision bundle: rationale and review-date fields are
+invalid without an override. Duplicate fields, relevant YAML errors, and an
+override declared while the full file remains within its default limit also
+produce `QUAL-INVALID-TOKEN-BUDGET-OVERRIDE`. Renma selects no value from an
+ambiguous or invalid bundle, and catalog output omits all three normalized
+fields.
+
+These fields record a declared human decision; Renma never inserts them. When
+the default is exceeded, first ask whether the asset can be split along
+meaningful semantic boundaries without harming coherence or execution order.
+Split only after the user agrees. Use an override only when the user confirms
+the asset should remain intentionally long, and never recommend one merely to
+make diagnostics pass.
+
+Renma records and validates this declaration; it cannot prove that a human
+actually reviewed the asset. `token_budget_reviewed_at` is declared provenance,
+not independently verified evidence.
+
 Current metadata budget diagnostics:
 
 | Finding | Meaning | Typical fix |
 | --- | --- | --- |
 | `META-FRONTMATTER-TOO-LARGE` | Frontmatter has grown beyond the compact index budget. | Move long prose, examples, procedures, or rationale into the body or referenced context assets. |
 | `META-LIST-ITEM-TOO-LONG` | A block-list metadata item is too long to serve as concise routing/index metadata. | Keep the list item short and move detailed conditions into body sections. |
+| `QUAL-INVALID-TOKEN-BUDGET-OVERRIDE` | Support-asset token-budget decision metadata is invalid or ambiguous. | Correct or remove it after an explicit user decision; invalid metadata leaves the default content limit active. |
 
 These diagnostics are intentionally advisory. They should help reduce LLM-facing catalog noise and token usage without deleting substantive knowledge.

package/docs/quality-profile.md

@@ -0,0 +1,135 @@
+# Renma Quality Profile
+
+`renma-quality` is Renma's internal quality-profile family. Reports identify
+the active profile as `renma-quality@<Renma package version>`, derived from
+`package.json` at build time. The source is `src/quality-profile.ts`. The current
+implementation does not expose quality overrides in `renma.config.json`; fixed
+defaults preserve comparable repository reports. The internal shape is
+versioned so later releases can add declared overrides without scattering
+constants across rules.
+
+`estimated_tokens` means Renma's deterministic, model-neutral estimate. Latin
+words, identifiers, URLs, and paths are lexical units; consecutive CJK text is
+grouped in two-code-point units; other punctuation is grouped in units of up to
+three code points. It is not an exact token count for any model. Skill budgets
+measure Markdown after frontmatter. Content-asset budgets measure the full file.
+
+Contexts, references, profiles, and examples may record a declared human
+decision and effective limit with top-level `token_budget_override` and
+`token_budget_rationale` metadata. The override must be a positive safe integer
+greater than the asset kind's unchanged default. Optional
+`token_budget_reviewed_at` must be a real `YYYY-MM-DD` date. Renma does not add
+these fields automatically. When an asset exceeds its default, an agent should
+first ask whether it can be split along meaningful boundaries without harming
+coherence or execution order, and split only after the user agrees. An override
+is appropriate only when the user confirms the long-form asset is intentionally
+coherent or ordered; it is not a general ignore mechanism. Renma validates the
+declaration but cannot prove that human review occurred.
+
+## Agent Skills requirements and recommendations
+
+| Field | Value | Unit and trigger | Severity | Source | Rationale and false-positive risk | Diagnostic | Reviewed | Configurable later |
+| --- | ---: | --- | --- | --- | --- | --- | --- | --- |
+| `agentSkills.nameMaxChars` | 64 | characters; above is invalid | error | Agent Skills specification | Portable identity limit | `AS-SKILL-INVALID-NAME` | 0.18.0 | no |
+| `agentSkills.descriptionMinChars` | 1 | characters; below is invalid | error | Agent Skills specification | Required discovery metadata | `AS-SKILL-MISSING-DESCRIPTION` / `AS-SKILL-INVALID-DESCRIPTION` | 0.18.0 | no |
+| `agentSkills.descriptionMaxChars` | 1,024 | characters; above is invalid | error | Agent Skills specification | Portable hard limit | `AS-SKILL-DESCRIPTION-TOO-LONG` | 0.18.0 | no |
+| `agentSkills.compatibilityMaxChars` | 500 | characters; above is invalid | error | Agent Skills specification | Keeps optional environment requirements concise | `AS-SKILL-COMPATIBILITY-TOO-LONG` | 0.18.0 | no |
+| `agentSkills.skillBodyRecommendedMaxTokens` | 5,000 | recommended body tokens | medium Renma advisory above | Agent Skills recommendation | Large focused workflows can still be valid | `QUAL-SKILL-TOKEN-BUDGET` | 0.18.0 | no |
+| `agentSkills.skillRecommendedMaxLines` | 500 | recommended `SKILL.md` lines | documented review evidence | Agent Skills recommendation | Line count alone does not prove mixed responsibility | none | 0.18.0 | no |
+| `agentSkills.recommendedReferenceDepth` | 1 | resource hop from `SKILL.md`; Renma accepts one additional index hop | low beyond two static hops | Agent Skills recommendation plus Renma reachability policy | An index may be useful; deep chains are easy to miss | `SUPPORT-DEEP-REFERENCE-CHAIN` | 0.18.0 | possibly |
+
+The Agent Skills body has no prescribed format. Step-by-step instructions,
+examples, edge cases, short commands, and the optional `scripts/`, `references/`,
+and `assets/` directories are valid. See the official
+[specification](https://agentskills.io/specification) and
+[description guidance](https://agentskills.io/skill-creation/optimizing-descriptions).
+
+## Renma workflow and content advisories
+
+| Field | Value | Unit and trigger | Severity | Source | Rationale and false-positive risk | Diagnostic | Reviewed | Configurable later |
+| --- | ---: | --- | --- | --- | --- | --- | --- | --- |
+| `descriptionMinChars` | 0 | characters; disabled | none | Renma | Length does not establish selection clarity | `QUAL-SHORT-DESCRIPTION` removed from default behavior | 0.18.0 | possibly |
+| `skillTokenWarn` | 2,000 | `estimated_tokens`; body above | low | Renma | Early progressive-disclosure review; focused workflows may exceed it | `QUAL-SKILL-TOKEN-BUDGET` | 0.18.0 | possibly |
+| `skillTokenStrongWarn` | 5,000 | `estimated_tokens`; body above | medium | Agent Skills recommendation with Renma severity | Stronger review, not a required split | `QUAL-SKILL-TOKEN-BUDGET` | 0.18.0 | possibly |
+| `contentTokenWarn.context` | 4,000 | `estimated_tokens`; full file above effective limit | low | Renma | Prefer an agreed semantic split when coherence survives; intentionally coherent or ordered assets may record a declared decision | `QUAL-SUPPORT-ASSET-TOKEN-BUDGET` | 0.18.1 | metadata only after human decision |
+| `contentTokenWarn.reference` | 5,000 | same | low | Renma | Detailed local references may legitimately be long | same | 0.18.1 | same |
+| `contentTokenWarn.profile` | 2,000 | same | low | Renma | Profiles should remain reviewable overlays | same | 0.18.1 | same |
+| `contentTokenWarn.example` | 2,500 | same | low | Renma | Complete examples may legitimately be long | same | 0.18.1 | same |
+| `lowHeadingDensityMinTokens` | 400 | body `estimated_tokens`, with fewer than 2 headings | low | Renma | Long prose can still be intentionally linear | `QUAL-LOW-HEADING-DENSITY` | 0.18.0 | possibly |
+| `lowHeadingDensityMinHeadings` | 2 | headings | low | Renma | Navigation heuristic only | same | 0.18.0 | possibly |
+
+## Metadata advisories
+
+| Field | Value | Unit and trigger | Severity | Source | Rationale and false-positive risk | Diagnostic | Reviewed | Configurable later |
+| --- | ---: | --- | --- | --- | --- | --- | --- | --- |
+| `frontmatterMaxLines` | 48 | lines; above | low | Renma | Metadata should be a compact index | `META-FRONTMATTER-TOO-LARGE` | 0.18.0 | possibly |
+| `frontmatterMaxChars` | 4,096 | characters; above | low | Renma | Separate from Agent Skills validity | same | 0.18.0 | possibly |
+| `metadataListItemMaxChars` | 256 | characters per JSON-array or YAML-list element; above | low | Renma | Tags and prose routing should be compact; IDs, URLs, and paths are exempt where practical | `META-LIST-ITEM-TOO-LONG` | 0.18.0 | possibly |
+
+## Reuse candidate advisories
+
+| Detector | Eligibility and evidence | Severity | Source | Rationale and false-positive risk | Diagnostic | Reviewed | Configurable later |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `reusableContextCandidate` | 60 lines **or** 800 body `estimated_tokens`; 4 distinct reusable signals; at least one reusable-knowledge signal | low | Renma | Verification, Examples, Edge Cases, Risks, Do not, Always, Never, and procedure headings do not qualify by themselves | `QUAL-SKILL-MIXED-RESPONSIBILITY` | 0.18.0 | possibly |
+| `sharedSupportCandidate` | 80 lines **or** 1,200 full-file `estimated_tokens`; 3 reusable headings; 4 reusable phrases | low | Renma | Promotion still requires cross-Skill use, duplication, independent lifecycle, or source-of-truth evidence | `MAINT-SUPPORT-ASSET-SHARED-CONTEXT-CANDIDATE` | 0.18.0 | possibly |
+
+## Repeated-context evidence
+
+| Field | Default | Trigger | Severity | Source | False-positive control | Diagnostic | Reviewed | Configurable later |
+| --- | ---: | --- | --- | --- | --- | --- | --- | --- |
+| `repeatedContext.exactSectionMinTokens` | 40 | normalized section estimated tokens at or above | medium | Renma | combined with character and file floors | `MAINT-REPEATED-SECTION` | 0.18.0 | possibly |
+| `repeatedContext.exactSectionMinChars` | 240 | normalized section characters at or above | medium | Renma | combined with token and file floors | same | 0.18.0 | possibly |
+| `repeatedContext.exactSectionMinFiles` | 2 | files containing the exact section | medium | Renma | requires maintained duplication | same | 0.18.0 | possibly |
+| `repeatedContext.exactCodeMinChars` | 80 | normalized fenced-code characters at or above | medium | Renma | combined with token and file floors | `MAINT-REPEATED-CODE-BLOCK` | 0.18.0 | possibly |
+| `repeatedContext.exactCodeMinTokens` | 10 | normalized fenced-code estimated tokens at or above | medium | Renma | combined with character and file floors | same | 0.18.0 | possibly |
+| `repeatedContext.exactCodeMinFiles` | 2 | files containing the exact block | medium | Renma | requires maintained duplication | same | 0.18.0 | possibly |
+| `repeatedContext.headingMinChars` | 24 | normalized heading characters at or above | low | Renma | excludes short generic headings | `MAINT-REPEATED-HEADING` | 0.18.0 | possibly |
+| `repeatedContext.headingMinTokens` | 3 | normalized heading estimated tokens at or above | low | Renma | excludes terse boilerplate | same | 0.18.0 | possibly |
+| `repeatedContext.headingMinFiles` | 3 | files containing the same heading | low | Renma | heading equality is review evidence only | same | 0.18.0 | possibly |
+| `repeatedContext.tokenShingleTokens` | 40 | estimated tokens in one normalized sequence | medium | Renma | common boilerplate excluded; near duplicates collapsed | `MAINT-REPEATED-CONTEXT-PATTERN` | 0.18.0 | possibly |
+| `repeatedContext.tokenShingleMinFiles` | 3 | files containing the sequence | medium | Renma | requires broader repeated evidence | same | 0.18.0 | possibly |
+| `repeatedContext.tokenShingleNearbyLineWindow` | 8 | source lines | n/a | Renma | collapses overlapping nearby matches from the same repeated passage | same | 0.18.0 | possibly |
+| `repeatedContext.tokenShingleMinUniqueTokens` | 12 | unique estimated-token units | medium | Renma | excludes repetitive boilerplate sequences | same | 0.18.0 | possibly |
+| `repeatedContext.tokenShingleMinUsefulTokens` | 14 | non-boilerplate estimated-token units | medium | Renma | requires meaningful lexical evidence | same | 0.18.0 | possibly |
+| `repeatedContext.tokenShingleMinChars` | 140 | normalized characters | medium | Renma | excludes compact coincidental matches | same | 0.18.0 | possibly |
+| `repeatedContext.findingCap` | 10 | findings per repeated-context category | n/a | Renma | presentation only; prevents category domination | all repeated-context IDs | 0.18.0 | possibly |
+| repeated links | disabled | same target repeated | none | Renma | links to the same official source are normal | `MAINT-REPEATED-LINK` removed from default findings | 0.18.0 | possibly |
+
+## Readiness policy
+
+Readiness starts at 100. Specification failures, high or critical security
+findings, diagnostic errors, and unresolved required graph closure remain
+blocking even when the numeric score would otherwise pass. Deprecated or
+archived assets have no existence penalty.
+
+| Field | Default | Unit and trigger | Effect | Source | Rationale and false-positive risk | Related check or diagnostic | Reviewed | Configurable later |
+| --- | ---: | --- | --- | --- | --- | --- | --- | --- |
+| `readiness.blockingDiagnosticPenalty` | 40 | points; one or more diagnostic errors | subtract once and fail check | Renma | Structural errors require correction; diagnostic aggregation avoids multiplying one root cause | `diagnostics.errors` | 0.18.0 | possibly |
+| `readiness.unresolvedRequiredGraphPenalty` | 30 | points; one or more unresolved required edges | subtract once and fail check | Renma | Required context closure is operationally necessary; optional edges are excluded | `graph.unresolved_edges` | 0.18.0 | possibly |
+| `readiness.ownershipMaximumPenalty` | 20 | points; proportional to unowned assets | subtract 0-20 | Renma | Ownership supports review, but small or imported repositories may intentionally omit it | `ownership.coverage` | 0.18.0 | possibly |
+| `readiness.emptyInventoryPenalty` | 10 | points; no cataloged assets | subtract once | Renma | Usually signals a wrong root or incomplete repository; an intentionally empty repository can be valid | `assets.minimum_inventory` | 0.18.0 | possibly |
+| `readiness.workflowClarityPenalty` | 10 | points; workflow clarity warning | subtract once | Renma | Missing routing clarity impairs use; prose phrasing may evade static recognition | `workflow.clarity` and related `RN-SKILL-*` diagnostics | 0.18.0 | possibly |
+| `readiness.workflowOptionalContextPenalty` | 5 | points; unusable optional context | subtract once | Renma | Optional context should resolve but does not block the core workflow | `workflow.optional_context` | 0.18.0 | possibly |
+| `readiness.workflowRequiredInputsPenalty` | 5 | points; required inputs are unclear | subtract once | Renma | Review signal only because some Skills require no external inputs | `workflow.required_inputs` | 0.18.0 | possibly |
+| `readiness.workflowCompletionCriteriaPenalty` | 10 | points; completion criteria are unclear | subtract once | Renma | Review signal only because completion language varies by workflow | `workflow.completion_criteria` | 0.18.0 | possibly |
+| `readiness.layoutWarningPenalty` | 5 | points per warning layout/path check | subtract per check | Renma | Keeps resolvable path and layout debt visible without making one advisory blocking | `layout.*` / `paths.helper_commands` | 0.18.0 | possibly |
+| `readiness.layoutFailurePenalty` | 15 | points per failing layout/path check | subtract per check and fail | Renma | Strict layout failures can make repository evidence unusable | `layout.*` / `paths.helper_commands` | 0.18.0 | possibly |
+| `readiness.readyMinimumScore` | 90 | score; at or above with no failing check | `ready` | Renma | Maintains a high bar without making subjective advisories blocking | Readiness `level` | 0.18.0 | possibly |
+| `readiness.needsAttentionMinimumScore` | 70 | score; below | `not_ready`; 70-89 is `needs_attention` | Renma | Separates accumulated review debt from isolated advisories | Readiness `level` | 0.18.0 | possibly |
+
+## Security proximity, scan operations, and presentation
+
+| Field | Default | Unit and trigger | Effect | Source | Rationale and false-positive risk | Related check or diagnostic | Reviewed | Configurable later |
+| --- | ---: | --- | --- | --- | --- | --- | --- | --- |
+| `security.precedingLineFastPath` | 2 | preceding source lines | supplements structural guard association | Renma | Preserves nearby-guard detection while headings, paragraphs, and list structure reduce formatting false positives | applicable `SEC-*` command diagnostics | 0.18.0 | no |
+| `scan.defaultMaxFileSizeBytes` | 524,288 | bytes per discovered file | bound reading and hashing work | Renma operational default | Protects scans from unexpectedly large files; larger legitimate files may require existing scan configuration | discovery diagnostic | 0.18.0 | already configurable |
+| `scan.defaultMaxDepth` | 16 | directory levels | bound discovery depth | Renma operational default | Prevents runaway traversal; unusually deep repositories may need existing scan configuration | discovery diagnostic | 0.18.0 | already configurable |
+| `scan.defaultConcurrency` | 16 | concurrent file operations | bound scan concurrency | Renma operational default | Balances throughput and file-descriptor pressure | none | 0.18.0 | already configurable |
+| `presentation.markdownReadinessFindingCap` | 50 | findings in Readiness Markdown | truncate presentation only | Renma | Keeps human reports readable without changing JSON evidence or score | Readiness Markdown | 0.18.0 | possibly |
+| `presentation.topSummaryItemCap` | 10 | items in compact summaries | truncate presentation only | Renma | Avoids unbounded summaries; reviewers can use full reports | report summaries | 0.18.0 | possibly |
+
+Structural guard proximity includes the same constraint or safety section, the
+same list item, a directly associated paragraph, or a parent Human Approval,
+Safety, or Constraints heading. Binary snippets are never exposed. Scan
+operational limits retain their existing public config fields; none of the
+quality or Readiness thresholds above are currently configurable.

package/docs/repository-context-bom.md

@@ -1,6 +1,6 @@
 # Repository Context BOM
 
-`renma bom` emits the Repository Context BOM: a declared repository manifest for review and CI consumers. It is generated from Renma's local repository evidence and keeps `schemaVersion` at `renma.repository-context-bom.v1`.
+`renma bom` emits a declared repository manifest for review and CI consumers. Renma 0.18.0 supports only the v2 BOM and Trust Graph schemas. It does not provide a v1 compatibility mode. V2 is the first supported long-term contract; earlier v1 output was an experimental pre-contract surface removed before broader adoption.
 
 The BOM is not a runtime usage report. It does not describe what an LLM actually consumed, assemble prompts, choose task-specific context, inject context into agents, execute agents, call an LLM, import consumed-context evidence, or collect telemetry.
 
@@ -12,7 +12,7 @@ flowchart TD
   Diagnostics["Diagnostics and Readiness"]
   Governance["Lifecycle and ownership evidence"]
   Security["Security posture and policy inventory"]
-  Bom["Repository Context BOM v1"]
+  Bom["Repository Context BOM v2"]
   Json["Authoritative JSON"]
   Markdown["Markdown review projection"]
   Revision["Git, CI, or PR context supplies revision identity"]
@@ -56,6 +56,10 @@ JSON is the authoritative BOM output. Markdown is a compact review projection fo
 
 Array ordering is deterministic and part of Renma's output contract. Asset `sourcePath` values remain repository-relative. `root` and `configPath` remain absolute paths from the current environment.
 
+Assets use `ownership.declaredOwner`, `ownership.effectiveOwner`,
+`ownership.source`, and optional `ownership.inheritedFrom`. Readiness uses the
+effective owner.
+
 ## Reproducibility
 
 `--omit-generated-at` means only:
@@ -77,24 +81,79 @@ Supported guarantee:
 
 > 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.
 
-Freshness evaluation uses the UTC calendar date. Metadata dates remain part of the snapshot and must not be removed as timestamp noise. A real file move is a meaningful BOM change because `sourcePath` is repository evidence. Portable byte-for-byte output across different runners is not a v1 guarantee.
+Freshness evaluation uses the UTC calendar date. Metadata dates remain part of the snapshot and must not be removed as timestamp noise. A real file move is a meaningful BOM change because `sourcePath` is repository evidence. Portable byte-for-byte output across different runners is not a v2 guarantee.
 
 ## Schema Evolution
 
 `schemaVersion` represents the consumer-facing BOM schema. `generator.version` represents the Renma implementation version and is not the schema version.
 
-Within BOM v1, changes should be backward-compatible and additive:
+V2 is the first supported long-term contract for normalized ownership,
+first-class support assets, and static support relationships. Consumers must
+inspect `schemaVersion` independently from `generator.version`. A future
+incompatible contract may intentionally introduce v3.
+
+Within a schema, changes should be backward-compatible and additive:
 
 - existing fields must not be removed, renamed, or given incompatible types or meanings;
 - new optional fields may be added when a real consumer requires them;
 - enum additions are consumer-visible changes and must be documented;
-- a future breaking contract requires a new schema version rather than silently changing v1 semantics.
+- a future breaking contract requires a new schema version rather than silently changing existing semantics.
+
+Treat `owns_local_resource`, `statically_references`, `inherits_owner`, and
+`inherits_policy` as static repository evidence, not runtime behavior. Branch
+on `schemaVersion`; `generator.version` is provenance only.
+
+The published [BOM v2 JSON Schema](schemas/repository-context-bom-v2.schema.json)
+is the machine-readable contract. `generatedAt` is required when `outputMode`
+is `default` and forbidden when `outputMode` is `omit_generated_at`.
+`configPath` remains optional and is absent when no configuration file was
+loaded. Every other top-level field is required. Optional lifecycle, version,
+status, target-resolution, and inherited-ownership fields appear only when
+their evidence exists. Owner values are explicitly nullable; missing optional
+fields are omitted rather than serialized as `null`.
+
+Arrays are deterministically ordered by their identity/path keys, and count
+fields are non-negative integers. Count maps contain every declared enum
+member, including zero counts. Policy source ordering is `local`,
+`security_profile`, `repository_config`, `owning_skill`. Static support
+relationships use `owns_local_resource`, `statically_references`,
+`inherits_owner`, and `inherits_policy`.
+
+The Readiness summary is a closed contract for asset, ownership, graph,
+diagnostic, workflow, Context Lens, security posture, and security policy
+inventory evidence. Coverage and readiness percentages are constrained to
+`0..100`. Security posture top-finding entries require an ID, non-negative
+count, and maximum severity. Security policy `assetKinds` is a complete count
+map containing every generated artifact kind, including zero values.
+
+Representative top-level JSON (nested objects are shortened for readability;
+the schema defines every nested field):
+
+```json
+{
+  "schemaVersion": "renma.repository-context-bom.v2",
+  "outputMode": "omit_generated_at",
+  "generator": { "name": "renma", "version": "0.18.0" },
+  "root": "/checkout/repository",
+  "scope": { "type": "declared_repository_manifest", "runtimeUsage": false, "telemetryCollected": false },
+  "summary": { "scannedFileCount": 0, "assetCount": 0, "dependencyCount": 0, "resolvedDependencyCount": 0, "unresolvedDependencyCount": 0, "ownedAssetCount": 0, "unownedAssetCount": 0, "readinessScore": 100, "readinessLevel": "ready", "diagnosticCounts": { "error": 0, "warning": 0, "info": 0 } },
+  "assets": [],
+  "dependencies": [],
+  "readiness": { "score": 100, "level": "ready", "checks": [], "summary": {} },
+  "securityPosture": { "totalSecurityFindings": 0, "riskClasses": { "violation": 0, "suspicious": 0, "advisory": 0, "unclassified": 0 }, "severities": { "critical": 0, "high": 0, "medium": 0, "low": 0 }, "highOrCritical": 0, "topFindingIds": [] },
+  "securityPolicyInventory": {},
+  "diagnostics": []
+}
+```
+
+Generated representative reports are validated against the published schema in
+the contract test suite.
 
 `--omit-generated-at` does not make the report a generic canonical JSON format or a portable artifact.
 
 ## Source Provenance
 
-BOM v1 provenance is deliberately repository-local:
+BOM v2 provenance is deliberately repository-local:
 
 - repository-relative source paths;
 - per-asset content hashes;
@@ -102,11 +161,11 @@ BOM v1 provenance is deliberately repository-local:
 - current absolute `root` and `configPath` information when available;
 - lifecycle, dependency, diagnostic, readiness, security posture, and security policy inventory evidence.
 
-Renma does not automatically invoke Git or add Git commit, branch, tag, or dirty-state fields in BOM v1. Git revision identity is expected to come from the surrounding Git, CI, artifact, or pull-request context. Native Git provenance fields and a BOM digest may be considered later if external artifact storage or cross-run consumers require them.
+Renma does not automatically invoke Git or add Git commit, branch, tag, or dirty-state fields. Git revision identity is expected to come from the surrounding Git, CI, artifact, or pull-request context. Native Git provenance fields and a BOM digest may be considered later if external artifact storage or cross-run consumers require them.
 
 ## Consumed-Context Evidence
 
-BOM v1 describes declared repository state. Future consumed-context evidence must not redefine or mutate that meaning.
+The BOM v2 schema describes declared repository state. Future consumed-context evidence must not redefine or mutate that meaning.
 
 Runtime evidence should be a separate artifact or explicitly separate attachment. A future evidence record should relate back to a BOM using stable values such as a BOM digest or snapshot identity, asset ID, asset content hash, producer identity and version, and observation timestamp.