renma 0.17.0 → 0.18.0

package/docs/quality-profile.md

@@ -0,0 +1,123 @@
+# 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 reviewed 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.
+
+## 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 | low | Renma | Review coherent scope; size alone is insufficient | `QUAL-SUPPORT-ASSET-TOKEN-BUDGET` | 0.18.0 | possibly |
+| `contentTokenWarn.reference` | 5,000 | same | low | Renma | Detailed local references may legitimately be long | same | 0.18.0 | possibly |
+| `contentTokenWarn.profile` | 2,000 | same | low | Renma | Profiles should remain reviewable overlays | same | 0.18.0 | possibly |
+| `contentTokenWarn.example` | 2,500 | same | low | Renma | Complete examples may legitimately be long | same | 0.18.0 | possibly |
+| `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.