# Renma Quality Profile

The User Manual's
[authoritative metadata table](user-manual.md#renma-operational-metadata-table)
owns the complete field inventory. This document owns the deterministic quality
thresholds and the deeper token-budget decision policy.

`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`. Quality
defaults remain fixed except for the explicitly documented Skill body and
content-asset thresholds. Repositories may override those values through the
corresponding `quality.*_token_warning` and `quality.*_token_high` keys. Numeric
increases and weakening `quality.ci_policy` (`fail` to `warn`/`off`, or `warn`
to `off`) are governed using the stricter mode from the compared revisions.
Mode tightening remains visible but does not block solely because of that
transition. `quality.ci_policy` supports `off`, `warn`, and `fail`, and defaults
to `fail`. The
[User Manual configuration section](user-manual.md#configuration) is the
authoritative configuration contract. The internal shape is versioned so
effective policy remains centralized rather than 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 stable compatibility validation baseline:
Context 4,000, Reference 5,000, Profile 2,000, or Example 2,500. These values
validate declarations independently from current repository warning defaults. 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.

When a Skill body threshold is exceeded, the finding exposes `measured`,
`warningThreshold`, `highThreshold`, `triggeredThreshold`, `effectiveSeverity`,
`overBy`, the deterministic rounded `overPercent`, `policySource`, and the
source of each threshold. Content-asset findings expose the declared override,
whether it affects the effective warning, its compatibility validation
baseline, and the corresponding repository and effective warning/High
thresholds. This keeps Renma defaults,
repository-specific effective policy, the measurement scope, and the triggered
comparison visible together.

For a support asset, a valid `token_budget_override` raises the effective
warning floor only when it is greater than the repository warning threshold:
`effectiveWarning = max(repositoryWarning, override)`. The effective High
threshold is `max(repositoryHigh, effectiveWarning)`, so neither configuration
nor an override can make High lower than the approved warning floor. Existing
`defaultLimit` and `effectiveLimit` detail fields remain available for
compatibility; they identify the Renma kind default and effective warning
threshold. Invalid metadata never raises either effective threshold, and a
valid override suppresses no finding above its effective thresholds. A valid
override below the repository warning remains compatible but is a no-op.

Markdown findings can also include up to three largest heading-based review
candidates. Renma selects H2 sections beneath a single H1 title when available;
otherwise it uses the shallowest useful heading depth. A section runs until the
next heading at the same or a shallower depth, so nested headings remain part of
their parent. Candidates are ordered by descending estimated size and then
source line. They help locate concentrated content; they are not automatic
split instructions or semantic classifications. Keep core routing, ordered
workflow, constraints, and completion criteria in `SKILL.md`; use
`references/`, `scripts/`, `assets/`, or independently owned `contexts/`
according to semantic responsibility. Any support-asset split or override
change still requires an explicit human decision. When no useful heading
structure exists, the finding calls for manual semantic review.

## 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 | portable recommendation only; Renma's default Medium finding begins above its separate 6,400 warning | 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 |
| `skillTokenWarning` | 6,400 | `estimated_tokens`; Markdown body above | medium | Renma repository governance; separate from the portable 5,000 Agent Skills recommendation | Progressive-disclosure review; focused workflows may validly exceed it | `QUAL-SKILL-TOKEN-BUDGET` | 0.32.0 | `quality.skill_token_warning` |
| `skillTokenHigh` | 8,000 | `estimated_tokens`; Markdown body above | high | Renma repository governance | High maintainability evidence, not proof that a split is required | `QUAL-SKILL-TOKEN-BUDGET` | 0.32.0 | `quality.skill_token_high` |
| `contentTokenWarning.context` | 6,400 | `estimated_tokens`; full file above effective warning | medium | 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.32.0 | `quality.context_token_warning` plus metadata decision |
| `contentTokenHigh.context` | 8,000 | `estimated_tokens`; full file above effective High | high | Renma | High maintainability evidence does not prove a split is required | same | 0.32.0 | `quality.context_token_high` plus metadata decision |
| `contentTokenWarning.reference` | 7,200 | `estimated_tokens`; full file above effective warning | medium | Renma | Detailed local references may legitimately be long | same | 0.32.0 | `quality.reference_token_warning` plus metadata decision |
| `contentTokenHigh.reference` | 9,000 | `estimated_tokens`; full file above effective High | high | Renma | Same false-positive risk at larger scale | same | 0.32.0 | `quality.reference_token_high` plus metadata decision |
| `contentTokenWarning.profile` | 3,200 | `estimated_tokens`; full file above effective warning | medium | Renma | Profiles should remain reviewable overlays | same | 0.32.0 | `quality.profile_token_warning` plus metadata decision |
| `contentTokenHigh.profile` | 4,000 | `estimated_tokens`; full file above effective High | high | Renma | Long focused overlays can still be valid | same | 0.32.0 | `quality.profile_token_high` plus metadata decision |
| `contentTokenWarning.example` | 4,800 | `estimated_tokens`; full file above effective warning | medium | Renma | Complete examples may legitimately be long | same | 0.32.0 | `quality.example_token_warning` plus metadata decision |
| `contentTokenHigh.example` | 6,000 | `estimated_tokens`; full file above effective High | high | Renma | Complete end-to-end examples may legitimately be long | same | 0.32.0 | `quality.example_token_high` plus metadata decision |
| `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 |

Routing clarity is deterministic evidence, not a description-length check. An
explicit selection phrase may appear in the effective Agent Skill description,
an Agent's description metadata, or the Markdown body. Common authoring forms
include `Use when`, `When to use`, `Use this Skill ...`, `Routing`, and explicit
trigger language. A description that only summarizes output does not satisfy
`QUAL-MISSING-ROUTING-CLARITY`. In ordinary prose, the phrase must be a positive
selection or role statement; negative-only guidance and incidental routing,
trigger, or mixin nouns do not count. Exact routing-oriented headings remain
strong structural evidence.

Verification guidance is detected only in parsed Markdown headings and body
text; unrelated frontmatter does not count. Renma recognizes common bounded
forms such as `Verification`, `Validation`, `verify`, `validate`, `testing`, and
`expected output` or `expected result`. This advisory detects the presence of
static success-checking guidance; it does not judge whether a command is correct
or the checks are exhaustive. A test-related noun such as `test fixture` is not
verification guidance, and an instruction not to test, verify, or validate does
not count as a positive check. Exact verification-oriented headings remain
sufficient structural evidence.

## 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, unresolved required graph closure, and exact
Renma-owned scaffold residue remain blocking even when the numeric score would
otherwise pass. Deprecated or archived assets have no existence penalty.

Readiness answers whether a repository passes these gates; it does not require
the report to contain zero findings. A `ready` report may still have actionable,
non-blocking findings, warning checks, or warning diagnostics. Markdown labels
that case `Ready with advisories` and labels a clean `ready` report `Ready`.
These are presentation labels only: the JSON level remains `ready`,
`needs_attention`, or `not_ready`, and advisory presence or count adds no score,
check, workflow percentage, CI, or exit-code effect. Finding severity and
Readiness blocking semantics remain separate dimensions.

The 0.23.0 Skill Discovery checks are visibility-first and have no separate
score weight. Partial or not-adopted coverage never subtracts points, and a
cycle warning alone never creates a hard failure. Authoritative coverage and
declared-route problems reuse existing prepared diagnostics as compact check
evidence; those diagnostics are not copied into Readiness diagnostics, so the
new checks cannot subtract a second time for the same condition. Existing
Readiness penalties and thresholds below are unchanged.

`skills.support_integrity` is a non-scoring hard gate over explicitly
referenced static Skill-support inspection. A failure makes the Readiness level
`not_ready` without subtracting the legacy layout penalty that applied to the
removed location-policy check.

| 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.scaffoldResiduePenalty` | 20 | points; one or more exact Renma-owned Skill or Context scaffold markers remain | subtract once and fail check | Renma | Generated starter prose is not authored content; exact-marker matching keeps the boundary deterministic and narrow | `assets.scaffold_completeness` / `QUAL-RENMA-SCAFFOLD-PLACEHOLDER` | 0.32.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. The two-line fast path does not cross a
Markdown heading or frontmatter boundary, so a guard in an unrelated peer
section cannot authorize a later action. Binary snippets are never exposed.
Scan operational limits retain their existing public config fields. Only the
explicit Skill and governed content warning/High thresholds in the table are
repository-configurable; other quality and Readiness thresholds are internal.