# Diagnostics Reference 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. These warnings do not make an otherwise specification-valid Skill invalid. The canonical identifier table is in [Agent Skills Diagnostic Identifiers](agent-skills-compatibility.md#agent-skills-diagnostic-identifiers). `QUAL-RENMA-SCAFFOLD-PLACEHOLDER` is intentionally not a general prose-quality heuristic. It matches only canonical Renma-generated Skill and Context starter strings, after bounded whitespace/YAML resolution, and retains the exact source line. Marker-free content may still be incomplete and requires human review. ## Diagnostic Types renma uses two severity systems: - Discovery, metadata, catalog, and readiness diagnostics use `info`, `warning`, and `error`. - Scan findings use rule severities such as `low`, `medium`, `high`, and `critical`. In JSON output, diagnostics usually appear as structured objects with a `severity`, a `message`, and, when available, a `path`. Repository configuration can set an effective scan-finding severity by stable configurable Finding ID through `diagnostics.severity`. IDs that exist only as raw discovery/configuration diagnostics are rejected because this policy does not affect their `error | warning | info` path. Producer definitions remain unchanged. When an override applies, scan JSON retains the effective value as `details.findingSeverity` and adds `details.defaultSeverity` plus `details.severitySource: "repository_configuration"`. The v2 `error | warning | info` transport severity continues to be derived from the effective finding severity by the existing normalization. `fail_on` evaluates the effective severity. Suppressions are applied afterward, so a path-scoped suppression still removes an overridden finding from the active set while the suppressed evidence retains both effective and default severity. See the [configuration contract](user-manual.md#configuration). `META-REQUIRED-SUSPENDED-DEPENDENCY` retains its established built-in scan Finding severity of High (and DiagnosticV2 transport severity of `error`). With the default `fail_on: "high"`, an active asset that requires a suspended target already blocks. Repository policy can still strengthen it to Critical or lower it explicitly; Renma never propagates suspension or rewrites the dependent. `META-REQUIRED-REVOKED-DEPENDENCY` is separately configurable and also has built-in High severity; `META-OPTIONAL-REVOKED-DEPENDENCY` has built-in Low severity. This preserves the stronger meaning of explicit trust withdrawal without aliasing suspension. Renma never propagates revocation or rewrites the dependent. ## Diagnostic and Rule Evolution during 1.x Diagnostic behavior is a compatibility surface distinct from wire compatibility. A JSON document may remain schema-compatible while a new or more severe finding changes the result of a command such as `renma scan . --fail-on high`. Consumers that require exactly stable CI outcomes should pin an exact Renma version. Diagnostic IDs are machine-consumed identifiers. After 1.0, the same stable ID continues to represent the same conceptual problem class. Detection precision, evidence, and remediation may improve, but an ID must not silently acquire an unrelated meaning. Patch releases may: - reduce false positives; - improve evidence, source ranges, deduplication, or remediation wording; - fix deterministic classification to match the already documented rule meaning; and - fix a false negative only when doing so restores behavior clearly promised by the existing diagnostic contract without materially broadening the rule. Patch releases should not introduce a new default-blocking High or Critical diagnostic, increase an existing diagnostic's severity, materially broaden a rule into a new behavior category, or remove or rename a stable diagnostic ID. Minor releases may add diagnostic IDs, bounded detection coverage, new advisory, quality, or security findings, open-enum values where the contract already permits them, and backward-compatible scanner capabilities. A material addition that can newly fail common CI configurations must be called out in the Changelog with upgrade guidance as an intentional compatibility change, not a silent behavior change. For a new High or Critical rule, prefer where practical an advisory and documented introduction, followed by operational experience, before later default-blocking behavior. A severe vulnerability may require immediate blocking, in which case the release must document the behavioral CI impact explicitly. A major release is required to remove or rename a stable diagnostic ID, reuse an existing ID for materially different semantics, change a closed compatibility contract, or change an established diagnostic meaning in a way consumers cannot reasonably treat as an additive extension. Increasing severity can change CI outcomes and is not an ordinary patch-level wording change. Reducing severity to correct an established false positive may be a patch. This policy does not promise that every new finding is non-breaking: wire compatibility and behavioral CI compatibility are separate concerns. ## LLM-Actionable Diagnostics V2 `renma scan --json` uses the `renma.scan.v2` contract. Its canonical `diagnostics` array is the normalized view for LLM-assisted repair, code review tools, and humans who want explicit repair guardrails. The pre-1.0 `findings`, legacy `diagnostics`, and transitional `diagnosticsV2` wire fields were removed instead of preserving three overlapping representations. Each v2 diagnostic includes: - `version`: currently `2`. - `code`: stable diagnostic or finding code. - `severity`: `error`, `warning`, or `info`. Scan finding severities are mapped into this simpler diagnostic scale, while the original `findingSeverity` remains in `details`. - `message`: concise human-readable issue summary. - `repairPolicy`: currently `preserve_semantics` when repairs must preserve the intended behavior rather than merely satisfying the scanner. - `location`: repository path, line range, and snippet when available. - `repairConstraints`: typed guardrails for what must be preserved, what must not change, allowed repair shapes, human decisions, and risks. - `verificationSteps`: concrete follow-up checks. When a command is known, Renma uses real project commands such as `renma scan`, `renma catalog`, `renma readiness`, `renma graph`, or `npm test`. - `llmHint`: short practical guidance for an LLM or coding agent. It is not a source of truth; the diagnostic evidence and repair constraints remain authoritative. - `details`: compatibility metadata plus stable structured facts when known, such as asset IDs, lens IDs, source paths, targets, duplicate paths, reference kinds, and target lifecycle status. Structured facts in `details` are the authoritative inputs for review tooling. `llmHint` is guidance only; changing hint wording should not change bundle grouping, affected files, affected assets, or repair decisions. Typed repair guidance is authoritative before Diagnostics v2 is constructed. Finding and diagnostic producers author `RepairConstraint[]` and `VerificationStep[]` values directly, including constraint kinds, commands, and expected outcomes. Renma does not derive those semantics from phrases such as "Do not", "Preserve", or "Run renma". Findings expose only the typed `repairConstraints` and `verificationSteps` fields; Diagnostics v2 consumes those values directly. ## Classification Evidence `inspect`, `suggest-metadata`, and relevant scan finding or diagnostic `details` include additive `classification` evidence. Classification answers what path rule matched; governance separately answers whether owner, policy, or metadata is declared, inherited, missing, or not required. A file's kind never implies that it has an owner. `inspect` additionally exposes `repositoryBoundary`, preserving resolution source and repository-relative path when resolved or stable unresolved/ambiguous reason evidence and candidate roots when no safe boundary can be selected. For marker-free directory-segment inference, only `.agents`, `skills`, `contexts`, `lenses`, and `tools` can positively establish a structural boundary. Recognized root filenames are handled separately: `AGENTS.md` may establish its containing directory as the structural root when no stronger repository marker is available, while `renma.config.jsonc` and `renma.config.json` normally establish the boundary through repository-marker detection. The support-like names `profiles`, `references`, `examples`, `scripts`, and `assets` are guards only: they can block a later boundary-like segment or contribute ambiguity evidence, but never establish a repository root by themselves. The `skills/**/SKILL.md` and `.agents/skills/**/SKILL.md` notation is qualified shorthand: a path that crosses one of those reserved support segments is not a Skill entrypoint. Renma reports the stable `LAYOUT-SKILL-ENTRYPOINT-UNDER-RESERVED-SUPPORT-DIR` guidance diagnostic for a Skill-looking basename there without turning the support path into an entrypoint or requiring a semantics-preserving repair. See the canonical [entrypoint path contract](agent-skills-compatibility.md#entrypoint-paths). The repository walk emits `LAYOUT-HISTORICAL-SKILL-ENTRYPOINT` for `skill.md`/`*.skill.md` under a Skill root and `LAYOUT-LEGACY-CONTEXT-ROOT` for files under `context/**`. These diagnostics carry migration guidance only: the files remain `unknown`, do not enter operational catalogs or inheritance, and are not made operational by a custom glob. > Classification describes how Renma interpreted repository structure. It does > not by itself prove ownership, policy, lifecycle, source-of-truth status, or > human intent. > Governance evidence describes what is actually declared or inherited. > Decision evidence describes whether Renma recommends a change, blocks one, > requires confirmation, or recommends no change. ### How to Read Classification Evidence These fields answer different questions and must not be substituted for one another: | Field | What it indicates | What it does not indicate | | --- | --- | --- | | `kind` | The semantic parsing or inventory role Renma assigned to the file. | Governance scope, ownership, policy, lifecycle, validity, or human intent. | | `scope` | The structural governance boundary implied by the path. | That governance metadata exists, is valid, or may be inherited. | | `matchedRule` | The primary stable structural rule that classified the normalized repository-relative path. | That the resulting asset is owned, current, authoritative, or safe to change. | | `reasonCode` | A more specific deterministic reason for the rule result. | Governance or a repair decision by itself. | | `parentResolution` | How repository evidence resolved the parent implied by a Skill-local path. | The parent's owner or policy values. It is normally absent outside Skill-local classification. | | `governance` | Declared or inherited ownership, policy, and metadata provenance supported by repository evidence. | Human intent beyond the declarations Renma found. | | `decisionStatus` | The application gate for a command that can recommend a change. It is decision evidence, not classification evidence. | A different structural classification or permission to ignore blocked evidence. | `kind` is one of `skill`, `agent`, `context`, `context_lens`, `profile`, `reference`, `example`, `script`, `asset`, `config`, or `unknown`. It selects a semantic parsing or inventory role. It is not equivalent to `scope`: for example, a `reference` can be `skill-local`, while a repository tool currently has `kind: "unknown"` and `scope: "repository-support"`. Metadata can refine a file under a Context root from `context` to `context_lens` without changing the structural rule that matched. Optional classification fields add evidence without changing those core meanings: | Field | Meaning | Do not infer | | --- | --- | --- | | `reason` | Human-readable explanation of the current result. | A stable machine branch; wording may improve without a contract change. | | `recognizedRoot` | The repository-relative asset root or boundary recognized by the matched rule, such as `skills`, `.agents/skills`, or `contexts`. | The absolute filesystem repository root; use `repositoryBoundary` for that evidence. | | `parentAssetCandidatePath` | The parent Skill path implied by structure before repository resolution. | That the file exists or supplies governance. | | `parentAssetPath` | The one parent Skill source path selected by a `resolved` result. | That the parent declares an owner or policy. | | `parentAssetCandidates` | All plausible parent Skill paths retained by an `ambiguous` result. | That the first candidate is preferred or safe to select. | | `supportDirectory` | The support-like directory involved in classification, such as `references` or `scripts`. | That the directory is valid Skill-local support without the matching rule and parent evidence. | | `ignoredNestedSegments` | Nested support-like names that did not override a higher-priority recognized root. | That Renma ignored the file's content or omitted it from inventory. | | `competingRules` | Stable negative evidence explaining why a nearby alternative rule did not match. | An additional positive classification or permission to choose that rule. | #### Scope | `scope` | Meaning | Do not infer | | --- | --- | --- | | `independent` | The path establishes a recognized first-class asset or agent boundary rather than Skill-local or repository-support placement. | That owner, policy, lifecycle, or source-of-truth metadata exists or is valid. | | `skill-local` | The path is under a recognized canonical Skill support directory. | That a parent Skill exists or that inheritance is valid. Check `parentResolution` and `governance`. | | `repository-support` | The path is recognized as repository implementation or configuration support. | That it is an independently governed Context Asset. | | `unknown` | The path rule does not establish a known governance scope. | That the file is irrelevant, safe, unowned, or outside the repository. | #### Matched Rules `matchedRule` is the primary stable structural classification. Rules are applied in the precedence shown after this table, so a higher-priority match prevents a later, more generic interpretation. | `matchedRule` | Repository evidence matched | Indicates | Must not be inferred | | --- | --- | --- | --- | | `skill-entrypoint` | An exact `SKILL.md` under `skills/**` or `.agents/skills/**` that does not cross a reserved Skill-support segment. | The file is classified as a canonical Skill entrypoint with independent scope. | That Agent Skills frontmatter is valid or governance is complete. | | `skill-local-support` | A path inside `references/`, `profiles/`, `examples/`, `scripts/`, or `assets/` beneath a recognized Skill path shape. | The file has a structurally implied Skill parent candidate and Skill-local scope. | That the parent exists or inheritance is valid. Require `parentResolution: "resolved"` and governance evidence. | | `context-root` | A file under `contexts/**`. | The file is an independent Context Asset by structure; metadata may refine its `kind` to `context_lens`. | That owner, lifecycle, policy, or source-of-truth metadata is complete or valid. | | `lens-root` | A file under `lenses/**`. | The file is an independent Context Lens by structure. | That Lens targets, governance, or policy declarations are valid. | | `agent-root` | `AGENTS.md` or a file under `.agents/**` after higher-priority Skill entrypoint rules. | The file is repository agent guidance with independent scope. | That it is an Agent Skill, that its instructions are valid, or that governance is complete. | | `repository-tool` | A file under top-level `tools/**`. | The file is repository implementation with repository-support scope. | That it is an independently governed Context Asset. | | `config-file` | A filename matching `renma.config.jsonc` or `renma.config.json` after higher-priority rules. | The file is recognized as Renma configuration support. | That its contents are valid, effective for a particular target, or proof of asset governance. | | `generic-reference` | A nested `references/` directory outside recognized independent and Skill-local asset boundaries. | The file receives the `reference` parsing or inventory role, but its scope remains unknown. | That it belongs to a Skill, may inherit governance, or is an independent Context Asset. | | `generic-example` | A nested `examples/` directory outside recognized independent and Skill-local asset boundaries. | The file receives the `example` parsing or inventory role, but its scope remains unknown. | That it belongs to a Skill, may inherit governance, or is independently governed. | | `generic-profile` | A nested `profiles/` directory outside recognized independent and Skill-local asset boundaries. | The file receives the `profile` parsing or inventory role, but its scope remains unknown. | That it is selected by a Skill, may inherit governance, or defines effective policy. | | `unknown` | No supported positive structural rule matched, or the path uses an unsupported reserved layout. | Renma has no more specific structural classification for the path. | That the file is irrelevant, harmless, unowned, safe to edit, or outside the resolved repository. | The stable path-rule precedence is: 1. `skill-entrypoint`. 2. `skill-local-support` inside a recognized Skill boundary. 3. Recognized asset roots: `context-root`, `lens-root`, and `agent-root`. 4. Repository support or configuration: `repository-tool` and `config-file`. 5. Generic nested rules: `generic-reference`, `generic-example`, and `generic-profile`. 6. `unknown`. #### Parent Skill Resolution `parentResolution` is meaningful for `skill-local-support`. Only `resolved` permits Renma to claim one parent Skill, and even then consumers must inspect `governance` to learn whether that parent supplies an owner or policy. | `parentResolution` | Meaning | Consumer behavior | | --- | --- | --- | | `structural-candidate` | Path classification derived a possible `parentAssetCandidatePath`, but repository evidence has not resolved it. | Do not claim inheritance. Resolve the repository and parent evidence first. | | `resolved` | Repository evidence found exactly one parent Skill and exposes it as `parentAssetPath`. | Inheritance may be reported only as supported by the accompanying governance evidence. | | `missing` | No parent Skill exists at the structurally implied location. | Do not claim inheritance; treat a related change recommendation as blocked until the layout is reviewed. | | `ambiguous` | More than one parent Skill candidate remains plausible; candidates may appear in `parentAssetCandidates`. | Do not choose a parent or claim inheritance; require layout or human resolution. | For example, these two files have the same semantic role and structural scope, but only the first has one resolved parent: ```json { "classification": { "kind": "reference", "scope": "skill-local", "matchedRule": "skill-local-support", "parentResolution": "resolved", "parentAssetPath": "skills/foo/SKILL.md" }, "governance": { "ownership": { "declaredOwner": null, "effectiveOwner": "docs", "source": "inherited" } } } ``` ```json { "classification": { "kind": "reference", "scope": "skill-local", "matchedRule": "skill-local-support", "parentResolution": "missing" }, "governance": { "ownership": { "declaredOwner": null, "effectiveOwner": null, "source": "unowned" } } } ``` The resolved example may inherit the owner shown by governance evidence. The missing example must not inherit merely because its scope remains `skill-local`. #### Reason Codes `reasonCode` narrows the primary structural result without replacing `matchedRule`. Representative groups are: - Skill boundary evidence: `under-canonical-skill-root`, `under-skill-support-directory`, `unsupported-skill-local-directory`, and `outside-recognized-skill-boundary`. - Independent asset roots: `under-recognized-context-root`, `under-legacy-context-root`, `under-recognized-lens-root`, and `under-recognized-agent-root`. - Repository support: `repository-tool-not-context` and `recognized-config-file`. - Generic or negative boundary evidence: `under-generic-support-directory`, `outside-recognized-context-root`, and `outside-recognized-asset-boundary`. Some negative reason codes occur inside `competingRules`, where `matched: false` records why a nearby interpretation did not apply. Human-readable `reason` wording may improve over time. Machine consumers should branch on `matchedRule` and `reasonCode`, retain unfamiliar future values, and never infer governance from a reason code alone. #### Governance and Decision Evidence Governance is separate from classification. `ownership` reports declared and effective owners plus whether the source is `declared`, `inherited`, or `unowned`. When available, `policySource`, `policyInheritedFrom`, and `metadataState` report equivalent provenance for policy and metadata. A resolved parent can still be unowned or have missing policy, so classification alone is never enough to construct governance. Commands that make recommendations expose one of these `decisionStatus` values: | `decisionStatus` | Meaning | Consumer behavior | | --- | --- | --- | | `deterministic` | Renma has enough supported evidence to construct the reported change candidate. | Review and apply only the reported candidate; do not infer additional changes. | | `human-confirmation-required` | Renma constructed candidate evidence, but human intent or semantics must be confirmed before application. | Do not apply until the required human confirmation occurs. | | `blocked` | Conflicting, incomplete, unsafe, or unresolved evidence prevents a change recommendation. | Do not apply a patch from this result, even if another payload field looks candidate-like. | | `no-change-recommended` | Renma successfully determined that no edit is recommended. | Treat as a successful no-edit result; do not manufacture a patch. | `decisionStatus` is the authoritative application gate. The accompanying decision `reasonCode` and `summary` explain that outcome; neither changes the structural classification. These statuses govern the recommendation and its dependent changes. A blocked candidate remains inapplicable while the agent investigates missing evidence or continues independent, already-authorized work. Do not relabel that candidate as separate work to bypass its application gate. A successful no-edit result does not end other requested work that remains outstanding. #### Safe Consumer Rules 1. Do not infer ownership from `kind`. 2. Do not infer inheritance from `scope: "skill-local"`. 3. Require `parentResolution: "resolved"` plus governance evidence before claiming inheritance. 4. Treat `decisionStatus: "blocked"` as a hard stop on applying that recommendation and its dependent changes. 5. Treat `decisionStatus: "no-change-recommended"` as a successful no-edit result. 6. Use `matchedRule` and `reasonCode` for machine branching, not the human-readable `reason`. 7. Preserve forward compatibility with unknown future enum values. Retain the raw value and fail closed rather than guessing its meaning. Example additive details: ```json { "classification": { "kind": "context", "scope": "independent", "matchedRule": "context-root", "reasonCode": "under-recognized-context-root", "recognizedRoot": "contexts", "ignoredNestedSegments": ["references"], "reason": "The file is under the recognized contexts/** root. The nested references/ segment does not change its classification." } } ``` Adding classification evidence does not emit a finding for every file, change diagnostic severity, or change scan pass/fail behavior. Existing `requires_human_decision` repair constraints remain the mechanism for intent that Renma cannot infer. `suggestedMode: "no-proposal"` with `no-change-recommended` is a successful result, especially for ordinary Skill-local support that inherits governance. Suggestion consumers should also handle unknown future `suggestedMode` values conservatively. These command-contract refinements do not change scan finding severity, scan pass/fail thresholds, or Readiness scoring. Example: ```json { "version": 2, "code": "META-DUPLICATE-ASSET-ID", "severity": "warning", "message": "Duplicate asset id", "repairPolicy": "preserve_semantics", "location": { "path": "contexts/alpha/overview.md", "startLine": 2, "endLine": 2, "snippet": "id: context.demo.duplicate" }, "repairConstraints": [ { "kind": "must_preserve", "text": "Preserve existing references where possible and update only references affected by the chosen canonical id." }, { "kind": "must_not_change", "text": "Do not rename every duplicate blindly; identify the canonical asset or ask for review when intent is ambiguous." } ], "verificationSteps": [ { "text": "Run renma scan.", "command": "renma scan", "expected": "No diagnostics with code META-DUPLICATE-ASSET-ID are reported." } ], "llmHint": "Find all assets with id \"context.demo.duplicate\", compare their scope and metadata, and propose a merge/deprecation path or unique replacement ids.", "details": { "assetId": "context.demo.duplicate", "duplicatePaths": [ "contexts/alpha/overview.md", "contexts/beta/overview.md" ], "sourcePath": "contexts/alpha/overview.md" } } ``` `repairConstraints` are deliberately conservative. A `must_preserve` constraint names repository intent or content that should survive the repair. `must_not_change` names unsafe shortcuts, such as creating fake dependencies or deleting orphaned context assets automatically. `allowed_change` describes safe edit shapes. `requires_human_decision` marks ambiguity that should not be guessed by automation. `risk` highlights security, data-handling, or destructive-action concerns. ## Presenting Renma Evidence to a User Raw Renma JSON is evidence for an LLM or coding agent, not usually the best user-facing explanation. The consumer should translate the relevant fields into plain language while preserving the boundary between confirmed facts, recommendations, and unresolved human intent. When a change is warranted, the evidence dependencies are: ```text Renma emits deterministic evidence -> LLM inspects applicable repository evidence and existing user decisions -> user supplies remaining required intent or approval only when needed -> LLM performs the smallest supported, authorized change -> Renma verifies the changed state -> LLM summarizes the new state ``` This is not a mandatory conversation sequence. A user's existing instructions may already supply the required intent, and a successful no-edit result may complete the requested task. In practice, an LLM or coding agent should: 1. Read Renma's deterministic evidence. 2. Inspect applicable evidence and existing user decisions before asking for missing intent. Use prior authorization only while it remains applicable to the same scope and action; preserve separate or immediate approval gates. 3. Separate confirmed facts from recommendations and unresolved intent. Ask only for required human decisions that remain unresolved after that review. 4. Make the smallest supported, authorized change or explain why no change is warranted. A diagnostic alone does not authorize semantic repair. 5. Run relevant validation after changes and complete repository-required checks for the current change and stage. 6. Summarize material outcomes, verification, and remaining blockers without mechanically repeating unchanged state. Finish when the requested outcome is satisfied and the applicable required checks pass. When a summary helps, include the material items from: - **Confirmed repository facts:** paths, declarations, resolved relationships, and other evidence Renma actually observed. - **Renma's deterministic interpretation:** the classification, governance, and decision evidence without added assumptions. - **Current recommendation:** the smallest change Renma supports, or an explicit successful no-change result. - **Unresolved human decisions:** only intent that repository evidence cannot determine. - **Next safe verification step:** the relevant structured Renma command, or a statement that no action for this recommendation is yet permitted. For example: ```text Renma classified this file as a Skill-local Reference. One parent Skill resolved at skills/foo/SKILL.md, and the effective owner is inherited from that Skill. No independent metadata change is currently recommended. A human decision is needed only if this knowledge is intended to be reused outside this Skill. If so, consider promoting it to contexts/** and then rerun Renma. ``` LLM consumers must follow these guardrails: - Do not expose raw diagnostics without summarizing their meaning when a user-facing explanation is expected. - Do not ask the user to decide facts that Renma or other applicable evidence already resolved. - Do not invent an owner, policy, lifecycle, reference, or source-of-truth claim. - Do not convert `structural-candidate` into `resolved`. - Do not claim inheritance without `parentResolution: "resolved"` and matching governance evidence. - Do not present `decisionStatus: "blocked"` as an applicable patch. - Do not assume every diagnostic requires an edit. - Do not hide unresolved human intent behind an automatic recommendation. - Treat `no-change-recommended` as a valid successful outcome. - Rerun Renma when command inputs, repository scope, or evidence applicability change, and after repairs. A clarification that changes none of these does not by itself require rerunning the same deterministic command. Required CI and release checks still apply. ### Iterative Example Initial Renma evidence: ```text kind: reference scope: skill-local parentResolution: resolved decisionStatus: no-change-recommended ``` LLM summary: ```text This file is local support for one Skill and already inherits its governance. No metadata change is needed. Should this knowledge remain local, or is it intended for reuse by other Skills? ``` User: ```text It should be reusable by three Skills. ``` LLM response: ```text That changes the repository-design intent. I will treat promotion to an independent Context Asset as the candidate direction, preserve the original meaning, and rerun Renma after the placement and references are updated. ``` After the intended patch, Renma verifies: ```text kind: context scope: independent matchedRule: context-root ``` LLM summary: ```text The knowledge is now an independent Context Asset under contexts/**. Renma verified the new classification. Ownership and references should now be reviewed as independent governance rather than inherited Skill-local state. ``` This example is conceptual. Renma does not automatically move files, invent references, or decide that local knowledge should be promoted. ## Review Bundles `renma scan --json` also includes `reviewBundles`, a deterministic grouping of related v2 diagnostics. Bundles help reviewers decide what to inspect together, which files or assets are involved, and what order to follow. Renma currently groups duplicate IDs by duplicated id, unresolved references by source, orphaned context assets separately from hard validation errors, and dependency/reference issues by affected source. Bundles are generated from structured `details` facts and source locations first, with human-facing prose parsing used only as a legacy fallback. Suppressed diagnostics are omitted from both the active `diagnostics` array and `reviewBundles`; they remain available in `suppressedDiagnostics` with their suppression evidence. Example: ```json { "id": "duplicate-id:context.demo.duplicate", "title": "Duplicate id review: context.demo.duplicate", "summary": "2 diagnostics report the same declared id and should be reviewed together before renaming or merging assets.", "severity": "warning", "diagnosticCodes": ["META-DUPLICATE-ASSET-ID"], "affectedAssets": ["context.demo.duplicate"], "affectedFiles": ["contexts/alpha/overview.md", "contexts/beta/overview.md"], "suggestedReviewOrder": [ "Inspect duplicate declaration in contexts/alpha/overview.md", "Inspect duplicate declaration in contexts/beta/overview.md", "Choose canonical id before editing references.", "Update references and rerun Renma scan." ], "llmHint": "Pick one canonical asset id before editing references; do not rename every duplicate in one blind pass." } ``` ## Scan Review Signals Renma scan findings always include `severity` and `confidence`. Security findings may also include `riskClass`, a human security-review interpretation. - `severity`: CI gating, urgency, and impact. Values are `low`, `medium`, `high`, and `critical`. - `confidence`: detector certainty. Values are `low`, `medium`, and `high`. - `riskClass`: human security-review interpretation for security findings. Values are `violation`, `suspicious`, and `advisory`. `violation` means a rule or safety contract is broken. Examples include unapproved network or upload destinations, policy contradictions, forbidden inputs, literal secrets, private keys, secret exposure, and dangerous commands. `suspicious` means a risky or ambiguous instruction should be reviewed but is not necessarily a direct policy violation. Examples include external upload instructions, cloud upload instructions, broad data sharing, overbroad context collection, unpinned remote scripts, unpinned dependency installs, privileged commands without guardrails, and risky temporary paths. `advisory` means a governance or hardening recommendation. For example, `SEC-MISSING-POLICY-METADATA` advises adding explicit policy metadata. Its eligibility is evaluated independently from other emitted findings: operational fetch, upload, or sensitive-input handling requires a declared policy, while benign local-only review and scaffold guidance does not. `riskClass` also powers aggregate security posture summaries in readiness and CI reports. `riskClass` does not replace `severity` and does not change `fail_on` behavior. Severity remains the CI threshold signal. Readiness and CI reports may include two security summaries: security posture from static findings, and security policy inventory from effective asset metadata, security profiles, and repository security config. The inventory is reporting-only and does not change scan `fail_on`, readiness scoring, or CI status. Semantic diff and CI reports may include security deltas, including added/resolved security findings grouped by `riskClass` and effective policy inventory count changes. These summaries are reporting-only and do not change scan `fail_on`, readiness scoring, or CI status. The Executable Surface Inventory is also reporting-only and does not define a diagnostic ID. A surface being uninvoked, dependency-unreached, dependency-transitive, non-canonical, or without an effective policy does not by itself introduce a finding or change an exit status. Missing, unsafe, ambiguous, non-canonical, not-inventory, or unavailable executable dependency rows expand informational review output but do not become findings. Existing path, support-reachability, symlink, and security diagnostics remain authoritative when their independent conditions match. The inventory correlates existing effective-policy fingerprints but does not replace security findings or claim a file is safe or malicious. Dangerous commands, remote scripts, destructive actions, dependency installation, network destinations, secrets, multilingual content checks, and hidden-Unicode checks remain separate diagnostic analyses. Enforcement and Trust Graph integration are intentionally deferred. Executable dependency rows do not become normal BOM Context Asset dependencies or Trust Graph edges. Invocation-context policy evidence is also informational. A recognized invocation may retain separate `source-artifact` and `owning-skill` policy relationships, no effective relationship, or multiple distinct effective fingerprints. None creates a diagnostic, readiness check, suppression requirement, policy requirement, or CI blocker. Caller evidence is not inherited by the target surface, and multiple fingerprints are not classified as a conflict. Invocation policy is never propagated through static executable dependency edges. Bounded inline helper recognition does not add a diagnostic family. A single-line mdast inline-code command immediately after the exact visible paragraph cue `Run` or `Run:` contributes the same invocation evidence as a fenced helper command only when the cue is structurally textual. Link labels, image alt text, inline code, non-comment HTML, and other unsupported nodes cannot establish the cue. Unsupported inline prose, ordinary code spans, blockquotes, other verbs or languages, and secondary spans are silently outside the grammar; Renma does not diagnose their non-recognition. Recognized missing, unsafe, unscoped, non-canonical, or unavailable inline targets retain existing informational invocation resolution and review behavior. Findings, Readiness, Security Policy Inventory, CI verdicts, suppression metadata, and exit thresholds are unchanged. ### Diagnostic and location JSON contract Each `diagnostics` entry contains `version`, `code`, `severity`, and `message`. It may also include `location`, `relatedLocations`, `repairPolicy`, `repairConstraints`, `verificationSteps`, `llmHint`, and structured `details`. Rule-specific finding severity, category, confidence, risk class, remediation, and rationale remain available as structured `details` where applicable. Consumers must tolerate absent optional fields and additive fields they do not recognize. A `location` contains `path` and may include one-based inclusive `startLine` and `endLine` values plus a `snippet`. Paths identify the scanned source reported by Renma; consumers should not parse `snippet` to recover identity or location. Renma anchors diagnostics to the most specific source evidence it has. When a diagnostic represents missing document-level guidance, the location identifies the affected document scope rather than pretending the missing content exists at a source line. Diagnostic order is deterministic but does not replace severity when prioritizing work. ## Discovery Diagnostics These diagnostics are emitted while renma discovers files. | Severity | Message | Meaning | Fix | | --------- | ---------------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------- | | `error` | `Could not evaluate glob "": ` | A configured discovery glob could not be evaluated. | Fix or remove the glob pattern in config or CLI input. | | `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 ().` | A file exceeded the configured size limit. | Raise `max_file_size_bytes`, exclude the file, or split the asset. | | `error` | `Could not read file: ` | The file matched discovery but could not be read. | Fix permissions, remove the bad path, or exclude the file. | ## Metadata And Catalog Diagnostics 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. 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 only after repository evidence resolves one parent Skill with an effective owner, and reports that inherited provenance separately from declared metadata. | Severity | Message | Meaning | Fix | | --------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | | `warning` | `Invalid status "". Expected one of: experimental, stable, suspended, revoked, deprecated, archived.` | An asset status does not match the accepted status values. | Replace the status with a supported value. | | `error` or `warning` | `Invalid status_changed_at "". Expected a real ISO calendar date in YYYY-MM-DD format.` | Lifecycle transition evidence has an invalid date; this is blocking while status is suspended or revoked and a warning otherwise. | Confirm and record the real reviewed transition date; do not infer it from Git or file timestamps. | | `error` | `Suspended lifecycle metadata is incomplete. Add with reviewed transition evidence.` | A suspended asset lacks a non-blank reason, a changed date, or both. | Add reviewed `status_reason` and `status_changed_at` evidence without automatically restoring the asset. | | `error` | `Revoked lifecycle metadata is incomplete (). Record a non-blank status_reason and a real status_changed_at date with reviewed revocation evidence.` | A revoked asset has missing or invalid explicit revocation evidence. | Record the reviewed reason/date without restoring, archiving, replacing, or deleting the asset. | | `warning` | `Invalid last_reviewed_at "". Expected ISO date YYYY-MM-DD.` | Freshness metadata has an invalid human review date. | Replace it with a real ISO date such as `2026-06-28`. | | `warning` | `Invalid expires_at "". Expected ISO date YYYY-MM-DD.` | Freshness metadata has an invalid expiration date. | Replace it with a real ISO date such as `2026-12-31`. | | `warning` | `Invalid review_cycle "". Expected supported ISO 8601 day duration such as P90D.` | Freshness metadata uses a review cycle renma cannot evaluate. | Use a day-based duration such as `P90D` or `P180D`. | | `warning` | `Metadata dependency "" 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 "" from "" targets a asset.` | A dependency points at a deprecated or archived catalog target. | Retarget the dependency to a stable replacement or document the migration. | | `error` | `Required declaration "" from "" resolves to suspended asset "".` | An active asset directly requires one exact suspended target. | Review the direct declaration or restore the target through a separate reviewed lifecycle change. | | `warning` | `Optional declaration "" from "" resolves to suspended asset "".` | An active asset directly references one exact suspended target optionally. | Keep it as review evidence, retarget/remove it after review, or separately restore the target. | | `error` | `Required declaration "" from "" resolves to revoked asset ""...` | An active asset directly requires one exact target whose trust or authorization was withdrawn. | Review the declaration and choose an evidence-backed outcome; do not propagate status or automatically alter the target. | | `warning` | `Optional declaration "" from "" resolves to revoked asset ""...` | An active asset optionally references one exact target whose trust or authorization was withdrawn. | Review whether to retain a justified exception, remove or retarget it, or handle the target in a separate lifecycle decision. | | `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 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 .` | 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. | | `warning` | `Shared context asset contains vague wording "".` | A canonical active shared context uses broad English wording such as usually, often, quickly, soon, as needed, or major. | Replace it with concrete applicability conditions, evidence, thresholds, or explicit uncertainty handling. | | `warning` | `Shared context asset contains currentness wording "" without an explicit date or version.` | A canonical active shared context uses relative English currentness wording such as recently, latest, currently, or as of now. | Add an explicit date, version, freshness metadata, or stable wording. | | `warning` | `Shared context asset contains prompt or runtime-selection wording "".` | A canonical active shared context looks like a prompt artifact or runtime context-selection rule. | Move prompt assembly, assistant role instructions, and runtime context selection outside shared context assets. | ## Context Lens Diagnostics Context Lens governance diagnostics use stable `code` values in JSON output. `error` diagnostics are blocking for readiness; `warning` diagnostics are reported by default for review. | Code | Severity | Meaning | Fix | | ------------------------------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | `CONTEXT-LENS-UNSUPPORTED-LEGACY-FIELD` | `error` | A lens declares `target`, `targets`, `output`, or `outputs`; the value is not interpreted. | Replace it with reviewed `applies_to` or `expected_outputs` metadata. | | `CONTEXT-LENS-DUPLICATE-ID` | `error` | Two or more lens definitions declare the same `id`. | Give each lens a unique stable ID and update references. | | `CONTEXT-LENS-EMPTY-DEFINITION` | `error` | A discovered lens file is empty. | Add required metadata and body guidance, or remove the file. | | `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` | The exact lens frontmatter envelope is unclosed, malformed YAML, not a mapping, or duplicates a recognized operational field. | Repair the exact envelope or YAML after confirming the intended value; do not choose a duplicate winner. | | `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/**` or `contexts/**`, and use `type: context_lens`. | | `CONTEXT-LENS-UNSUPPORTED-SCOPE` | `error` | A lens declares a value outside the supported `context` scope. | Use `scope: context` or omit the field. | | `CONTEXT-LENS-UNSUPPORTED-VERSION` | `error` | A lens declares a value outside supported schema version `1`. | Use `version: 1` or omit the field. | ## Readiness Diagnostics `renma readiness` converts lower-level data into workflow checks. These messages are produced by readiness checks and may wrap discovery, catalog, graph, ownership, status, or scan-finding data. | Severity | Message | Meaning | Fix | | -------------------- | ---------------------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------- | | `error` | discovery or catalog diagnostic message | A lower-level error diagnostic was present. | Fix the original diagnostic first. | | `warning` | discovery or catalog diagnostic message | A lower-level warning diagnostic was present. | Review and fix if it affects automation reliability. | | `warning` | `Missing owner metadata.` | A catalog asset has no declared owner metadata. | If ownership matters, choose an owner through human review or team policy. | | `error` | ` reference "" does not resolve.` | A graph edge points to a missing target. | Correct the reference or add the target asset. | | `error` | `Required context reference "" does not resolve.` | A required context reference is missing. | Add the context asset or correct `requires_context`. | | `error` | `Required context "" resolves to asset .` | Required context exists but is deprecated or archived. | Move the dependency to a stable context asset. | | `warning` | `Optional context reference "" does not resolve.` | An optional context reference is missing. | Correct it or remove it if it is no longer useful. | | `warning` | `Optional context "" resolves to asset .` | Optional context exists but is deprecated or archived. | Retarget or remove the optional dependency. | | `warning` | `Asset status is .` | A catalog asset is deprecated or archived. | Migrate dependents or update the asset status. | | `error` or `warning` | scan finding remediation text | A scan finding is severe enough to affect readiness. | Fix the finding listed in the readiness detail. | ## Scan Finding Identifiers `renma scan` emits finding IDs from the rule engine. A scan finding identifier is a machine-readable label for the kind of issue found during a scan. It is different from: - an asset ID, which identifies a context asset or other catalog entry - a file path, which identifies where the issue was found - a diagnostic message, which is written for humans and may contain contextual details Finding identifiers are useful when you want to group, filter, document, or automate responses to scan results. CI systems, editor integrations, docs, and LLM-assisted repair workflows can use the identifier to understand the category of problem without relying on the exact wording of the human-readable message. The identifiers below are stable scan output and are compatibility-sensitive. Integrations may group or filter on them without parsing human-readable titles or messages. Renaming or removing an identifier requires an intentional compatibility decision and a documented migration. Security diagnostics focus on high-signal heuristics for artifacts Renma already discovers. Raw hidden-Unicode analysis covers every discovered UTF-8 text artifact, including text scripts, configuration, and non-Markdown assets. Semantic instruction and command checks retain their narrower agent-facing Markdown boundary, such as skills, contexts, `AGENTS.md`, references, profiles, examples, and Markdown tool guidance. Defensive wording and nearby human approval, dry-run, backup, or rollback guidance may reduce or avoid command-risk findings when they are local to the risky instruction. When the effective human-approval policy is true, dry-run, backup, rollback, or restore guidance does not replace explicit human approval. Renma does not widen discovery to scan `package.json`, GitHub Actions workflows, Dockerfiles, dependency manifests, or repository-wide supply-chain metadata by default. Renma analyzes the security posture of LLM-facing Markdown instructions and metadata. Separately, the reporting-only Executable Surface Inventory uses bounded JS/TS, Python, POSIX shell, PowerShell `.ps1`, and Windows batch `.bat` / `.cmd` lexical collectors for documented explicit relative dependency evidence. Those collectors do not contribute security findings or analyze general executable behavior; use appropriate SAST and dependency-scanning tools for executable code. Dynamic expressions, runtime/PATH lookup, PowerShell module loading, and unsupported interpreter syntax remain unresolved. Markdown instructions that tell an agent to fetch, trust, execute, or invoke a script remain within this diagnostic boundary. These checks inspect repository knowledge and operational instructions. Selected command and JavaScript forms use bounded structure-aware recognition, not complete language interpretation. The checks are not language-specific SAST, dependency scanning, a safety proof, runtime monitoring, sandboxing, permission enforcement, or telemetry collection. A scan with no findings means only that the enabled deterministic checks found no matching evidence; it does not establish that an agent workflow is safe. `scan --format json` exposes this boundary as `renma.security-analysis-coverage.v1`. Its per-artifact rows are distinct from `renma.inspection-coverage.v1`: inspection coverage answers whether expected repository paths were inspectable, while security-analysis coverage answers which supported layers actually executed on artifacts that were scanned. `analyzed` records execution, not a match and not a safety verdict; `not-applicable` means the layer does not conceptually apply; `unsupported` makes a current format limitation visible; and `not-analyzable` means a conceptually applicable source surface was ambiguous or malformed. The schema also reserves `blocked`, while current read and traversal blockers remain in repository inspection coverage rather than creating synthetic artifact rows. In particular, discovered UTF-8 `.txt` Skill support receives semantic instruction analysis only when the existing repository-local static-reference graph proves it reachable from exactly one owning Skill. This eligibility supports direct and deterministically transitive references; it does not arise from directory placement, discovery, proximity, basename ambiguity, external URLs, absolute or escaping paths, unresolved targets, or symlinks. For this uniqueness decision, the repository retains safe regular-file identity across exact exclusion: a uniquely resolved excluded target remains expected and blocks inspection, while every excluded candidate still counts when a basename would otherwise be ambiguous. If an excluded Skill-local support directory makes that candidate set unknowable, the parsed basename reference produces blocking subtree evidence without inventing an exact child target. Excluded file contents remain unread and unparsed, and excluded directories remain untraversed. Symlink targets are never followed or treated as inspectable support; a referenced symlink path may still be retained as blocking repository evidence. A reachable plain-text file has no policy authority, and findings retain its original path, line, and snippet. Otherwise identical unreachable `.txt` remains `unsupported`. JSON, YAML, TOML, source code, executable support, and binary assets do not enter this semantic path. Successfully parsed closed frontmatter with no YAML comments reports comment analysis as `analyzed` and a zero surface count for Skills and eligible known non-Skill Markdown. Malformed frontmatter does not claim successful comment analysis, and arbitrary `unknown` Markdown does not gain this surface merely from containing delimiters. Absence of findings must not be interpreted as complete security-analysis coverage. ### Hidden Unicode source-integrity boundaries Hidden-Unicode checks inspect original `artifact.content` before Markdown visibility filtering, normalization, paragraph reconstruction, or command analysis. Frontmatter, prose, code fences, inline code, comments, scripts, configuration, and other discovered text assets use the same raw-source check. Binary artifacts remain excluded. Findings are aggregated at most once per diagnostic ID per source line, and evidence escapes reported characters as visible code points instead of retaining the raw hidden character. `SEC-SUSPICIOUS-BIDI-CONTROL` is `high` severity, `high` confidence, and `suspicious` risk class. It reports `U+202A`–`U+202E` and `U+2066`–`U+2069`: the bidirectional embedding, override, pop, and isolate controls that can visually reorder source. A finding requires explicit review; it does not assert that an occurrence is malicious. `SEC-SUSPICIOUS-INVISIBLE-CHARACTER` is `medium` severity, `high` confidence, and `suspicious` risk class. It always reports: - `U+0000`–`U+0008`, `U+000B`–`U+000C`, `U+000E`–`U+001F`, and `U+007F`–`U+009F`; - `U+00AD`, `U+034F`, `U+200B`, and `U+2060`; - deprecated directional formatting controls `U+206A`–`U+206F`; - interlinear annotation controls `U+FFF9`–`U+FFFB`. A single `U+FEFF` is allowed only at the beginning of the file; every other occurrence is reported. `U+200C` ZERO WIDTH NON-JOINER and `U+200D` ZERO WIDTH JOINER are reported only when the character immediately before and after is in the exact ASCII-like token set `A-Z`, `a-z`, `0-9`, `_`, `-`, `.`, `/`, `:`, `@`, `%`, `+`, or `=`. This catches insertions in commands, identifiers, URLs, metadata keys, and dependency names without reporting ordinary emoji joining or complex-script shaping. Three selector families use a separate conservative composition heuristic: - Mongolian Free Variation Selectors `U+180B`–`U+180D` and `U+180F`; - Variation Selectors `U+FE00`–`U+FE0F`; and - Variation Selectors Supplement `U+E0100`–`U+E01EF`. `U+180E` MONGOLIAN VOWEL SEPARATOR is not a Variation Selector and is not reported merely because it appears in legitimate Mongolian text. Renma reports a covered selector only when it belongs to a run of two or more consecutive selectors. A finding's escaped evidence names each reported selector, and `details.variationSelectorAnalysis` records the `consecutive-run` heuristic, minimum run length, sequence count, longest run, and exact represented ranges on that line. Consecutive selector-only runs are high-signal encoded-looking hidden text because ordinary presentation, ideographic variation, and Mongolian variation attach one selector to a base character. Unicode tag characters `U+E0000`–`U+E007F` use a separate bounded emoji sequence rule. Renma allows the three exact RGI subdivision flag sequences from the reviewed Unicode Emoji data: `U+1F3F4` BLACK FLAG, followed by the tag encoding of `gbeng`, `gbsct`, or `gbwls`, and terminated by `U+E007F` CANCEL TAG. An otherwise valid sequence embedded between ASCII-like token characters is still reported. Renma also continues to report standalone tags, tag runs without the black-flag base, missing terminators, non-RGI or non-permitted payloads, and all other malformed or encoded-looking tag usage. Evidence names and escapes every tag code point on a reported line rather than emitting the invisible payload. This is an exact structural exception, not general emoji or CLDR subdivision validation. The detector is not a general non-ASCII, normalization, or confusable-character rule. Japanese and other multilingual text, ordinary RTL text, `U+200E`, `U+200F`, `U+061C`, isolated Mongolian, emoji/text, or ideographic Variation Selectors, ordinary ZWJ sequences, combining marks in general, non-breaking and narrow non-breaking spaces, ideographic spaces, full-width characters, normalization differences, and homoglyphs are not reported solely because they exist. Normal tab, LF, and CR characters are also allowed. Repeated selectors separated by base characters are not reported solely by count or line density; this avoids broad findings on legitimate Unicode text, but means encoded forms that never place selectors consecutively remain outside current coverage. The covered candidates are intentionally not exhaustive and may gain additional deterministic, high-signal composition rules as Unicode hidden-text techniques evolve; Unicode-property membership alone does not produce a finding. Repair only the exact reported code point or replace it with the intended visible text; do not normalize or rewrite the file or remove legitimate multilingual content. Intentional bidirectional formatting requires human confirmation. A verified necessary occurrence can use the existing path-scoped suppression mechanism with a documented reason; Renma does not add a Unicode-specific allowlist. ### Instruction-integrity boundaries `SEC-HIDDEN-OPERATIONAL-INSTRUCTION` reports a security-sensitive operational instruction found inside a real HTML-comment span in agent-facing Markdown. Rendered-visible analysis continues to remove the comment, so ordinary comment text is not promoted into operational prose. Renma instead analyzes each comment in an isolated raw-agent-visible projection and reports the exact source span plus the underlying bounded diagnostic identity. Formatting notes, metadata markers, and explanatory documentation comments do not trigger unless they independently contain recognized security-sensitive operational evidence. The isolated projection uses the same structural negative-example boundaries as visible Markdown. A marker in the same node, a preceding `Unsafe example:` or `Negative example:` label, or a negative-example heading can make its bounded payload inert. A same-node inline marker masks only its punctuation-bounded clause, even when a later clause shares the physical line or the paragraph continues through a soft line break. The boundary does not extend to a later independent workflow instruction, and a trailing label cannot hide an earlier instruction. Use the existing narrow finding-ID and path-scoped suppression only for a reviewed intentional case. Raw hidden-Unicode inspection is independent and still includes comments. `SEC-HIDDEN-FRONTMATTER-INSTRUCTION` applies the same bounded projection to syntactic YAML comments in closed, successfully parsed Skill frontmatter and eligible known non-Skill Markdown frontmatter. Skills retain the Agent Skills envelope rules; non-Skills retain the exact Renma `---` envelope rules. Renma uses the YAML parser's concrete-syntax tokens, so a `#` inside a quoted value or block scalar is not a comment. Full-line and inline comments retain their original line and column evidence, and adjacent full-line comments form one deterministic projection for existing semantic correlation. Malformed or unclosed frontmatter produces no guessed YAML-comment evidence. Once the YAML parser identifies a comment, inner Markdown blockquotes, HTML-comment syntax, code presentation, and example labels cannot make its raw agent-visible text ineligible. The projected comment also has no policy authority over itself: policy-looking lines remain eligible evidence and logical-command input, but cannot grant permissions or allowlist a later line in the same projection. This projection-specific rule does not change ordinary Markdown quotation, example, or policy handling. It also does not broaden security analysis to `compatibility`, `license`, `allowed-tools`, arbitrary `metadata` or `metadata.renma.*` values, or any other scalar beyond the already-supported canonical Skill `description`; deciding which of those raw-agent-visible scalar surfaces warrant high-signal analysis remains a follow-up. `SEC-SAFEGUARD-BYPASS-INSTRUCTION` is a medium-severity advisory for explicit local guidance to disable or circumvent security checks, weaken policy to pass diagnostics, suppress warnings, replace approval with post-hoc review, choose a more dangerous permission fallback, or execute automatically after no user response. The safe repair is to keep the existing safeguard, stop and report missing authority, and rerun `renma scan` without relaxing policy or adding suppression. Direct prohibitions such as “Do not bypass human approval,” ordinary quoted examples, HTML-comment content, and fenced prose clearly bounded as an unsafe or negative example are excluded from this semantic prose rule. Visible text before or after an HTML comment span remains scannable. A fenced `text` or `markdown` payload explicitly routed by surrounding prose, an instruction label, or an operational instruction heading is scanned as an instruction. A blockquote is also scanned when its local surrounding prose or instruction label explicitly routes it for execution. Local quotation or bounded source attribution such as “the incident report says:” or “the audit states:” keeps an ordinary quote inert beneath a generic instruction heading without requiring the word “quote,” but an explicit local execution route takes precedence. Routed multiline shell analysis removes quote markers only in its logical-command projection; diagnostic evidence retains the exact quoted source lines. Routing does not cross an unrelated structural boundary. The recognizer evaluates one physical line and one punctuation-bounded clause at a time. Direct local prohibitions are defensive; it does not infer polarity, actors, or authority across clauses or lines. A later independently expressed unsafe action is evaluated separately. Comment-like `` text inside any fenced code block is literal fence content and never opens or closes an HTML comment for subsequent lines. Matched Markdown inline-code spans use the same literal treatment, including variable-length and multiline backtick delimiters. Eligible Markdown is parsed once with a CommonMark-compatible parser after YAML frontmatter. Renma derives positioned paragraphs and list-item boundaries, headings and sections, block quotes, thematic breaks, HTML, inline code, and fenced or indented code from the resulting structural ranges instead of reconstructing delimiter or container state. Default CommonMark ownership therefore determines blank-paragraph, ATX and Setext heading, thematic-break, HTML-block, fence, sibling-item, nested-item, padding, tab, ordered-marker, and lazy-continuation boundaries. Frontmatter is excluded from parser state while the parser's source positions are offset back to original artifact line numbers. `SEC-RISKY-OPERATION-ERROR-SUPPRESSION` reports explicit failure suppression only when the same bounded instruction contains an operation Renma already classifies as destructive, privileged, a security-sensitive upload, or a sensitive-data operation. Supported shell associations are the unquoted `|| true` and `|| :` branches immediately attached to the recognized operation; logical backslash continuations retain their complete source range. Destructive and privileged shell evidence requires the risky executable in command position; static absolute paths and bounded `command`, `env`, assignment, and `sudo` wrappers preserve that executable evidence. Upload classification continues to use the existing destination analysis rather than a separate tool allowlist. Quoting risky command text as a literal argument to `echo` or `printf`, including ordinary variable interpolation, does not establish that operation. Command substitution remains operational. Known lookup, help, and version modes for the bounded `command`, `env`, and `sudo` wrappers are treated as non-execution; unknown wrapper options retain conservative direct-command matching. Renma analyzes directly expressed shell operations. It does not reconstruct command text written to a file and later executed as a generated script. Indirect execution through generated files requires human review or a dedicated shell-analysis tool. Suppressing failure from an unanalyzed generated file does not, by itself, establish risky-operation error suppression. A separate line-local prose grammar covers both “If the destructive operation fails, ignore the error and continue” and the coordinated reverse order “continue and ignore the error.” Generic `|| true`, capability probes, ordinary error handling, `set +e`, `try/catch`, and stderr redirection do not produce this finding by themselves. Direct prohibitions remain defensive. The repair is to preserve the failure, stop and report the blocker, and explicitly verify or roll back partial effects rather than substituting another suppression. `SEC-INSTRUCTION-HIERARCHY-OVERRIDE` is a medium-severity advisory for an explicit line-local attempt to ignore, disregard, override, supersede, or take precedence over a narrow set of higher-authority targets: previous, prior, earlier, or preceding instructions; system or developer instructions or prompts; higher-level instructions; platform policy; or the host-agent instruction hierarchy. Base and bounded declarative verb forms are recognized. This is a bounded English recognizer, not a general prompt-injection or multilingual classifier. Ordinary persona wording, correct statements that higher authority supersedes lower authority, direct or indirect bounded hierarchy questions, and explicitly attributed or illustrative phrases are outside the rule. A bare mention of “the prompt,” “the statement,” or “the phrase” is not attribution by itself, and an attribution or illustrative cue does not govern a later independent clause. Direct prohibitions and explicit negative-subject forms remain defensive. Renma does not resolve an implied actor, pronoun, or earlier sentence. Quoted or non-operational unsafe examples follow the existing Markdown security-view boundaries. A recognized override inside an HTML or YAML frontmatter comment remains hidden operational evidence under the existing hidden-comment diagnostic rather than becoming a rendered-visible finding. Repair removes the priority claim, preserves system and developer authority, and states only the intended local behavior. `SEC-UNTRUSTED-CONTENT-AS-INSTRUCTION` is a medium-severity advisory for one physical line that explicitly makes an external page, issue body, log, tool output, attachment, downloaded document, or fetched Markdown authoritative or executes its embedded commands without review. Safe reading, quoting, summarizing, provenance capture, and locally reviewed or validated fact extraction are outside the rule. Repair the instruction by treating source content as untrusted data, preserving provenance, validating task-relevant facts, and keeping execution authority in reviewed repository guidance or explicit human approval. Source, execution action, and any review guard must occur on that same physical line. Renma does not combine soft-wrapped, lazy-continuation, adjacent, parent, or child lines for this prose rule, and it does not carry a guard from an earlier sentence or line. This deliberately leaves ambiguous and cross-line wording for human review instead of attempting general natural-language coreference. `SEC-EXECUTABLE-AS-POLICY-AUTHORITY` reports a narrower authority boundary in canonical Skill body instructions. It requires parser-owned evidence for an existing supported inline `Run` helper invocation and an immediate, explicit purpose that makes the helper determine whether a security-relevant operation is allowed, permitted, approved, authorized, or safe. The finding preserves the whole positioned paragraph plus the recognized launcher and raw target as details. Ordinary helper execution, linting, testing, validation, calculation, and reporting remain outside the rule. A helper may collect or validate evidence; reviewed Skill instructions and declarative Renma policy must retain the actual authorization decision. Fenced commands and later prose in another paragraph are not composed, generic executable-looking prose is not inferred, and Renma does not inspect or execute the helper. These deliberate false-negative boundaries keep the diagnostic deterministic rather than turning it into a general executable-policy classifier. `SEC-UNBOUNDED-EXTERNAL-SOURCE-TRAVERSAL` is an advisory for explicit recursive link, issue, attachment, page, or source traversal when the same bounded Markdown section states none of the expected scope, relevance, visited/cycle, depth/count/time, failure-stop, or unresolved-scope boundaries. A single named source read is not recursive traversal. A boundary in an unrelated peer section does not apply. The finding is normally low/advisory; it becomes medium/suspicious, not high, when the same local section also directs sensitive data disclosure or upload. Renma reports the missing governance but never crawls the sources itself. ### Data-sharing source and sink boundaries The bulk-data, overbroad-context, no-redaction, secret-material, sensitive-file, and upload diagnostics distinguish sources from local or disclosure sinks. Bounded source kinds cover environment files, private keys, certificates and signing material, credential stores, cloud credential files, other sensitive files, and environment-variable API access. The API form is not a file: `process.env.NAME` and `process.env["NAME"]` do not become `.env` evidence, while `readFileSync(".env")` and `fs.readFile(".env", callback)` remain actual file references. Bounded sink kinds distinguish local files, stdout or logs, prompt or Context inclusion, network access, external upload, and unknown destinations. A supported operation avoids a sensitive-file finding only when every sink is a local file and exact structurally associated wording forbids disclosure. The guard does not cross unrelated headings, thematic breaks, sibling items, or code blocks. It cannot neutralize a real disclosure sink, a contradictory instruction, an upload later in the same supported command, or unknown syntax. Unsupported syntax follows the conservative existing rule path. A local read of a whole repository may still be an overbroad context-collection advisory, but it is not bulk sharing without a prompt/context attachment, stdout/log output, or upload/share sink. Full logs, all environment variables, whole repositories, and credential directories become bulk-sharing evidence when instructions attach, print, log, paste, send, or upload them. Minimal task-relevant sanitized snippets and explicit defensive redaction wording are excluded. ### Dependency installation boundaries Dependency detection combines structured command and selector analysis with established bounded compatibility fallback: | Dependency form | Analysis level | | --- | --- | | npm, pnpm, and Yarn direct install/add commands | Structured command and selector analysis | | pip-style and `uv pip` direct install commands | Structured command and selector analysis | | Homebrew formula installs | Existing bounded compatibility fallback | | Docker image pull/run commands | Existing bounded compatibility fallback | | Other forms | Not currently analyzed | npm and PyPI requirements retain ecosystem, package manager, normalized package name, raw reference, selector kind, pinning kind, variables, source span, and exact asset-local allowance evidence. Selector classification remains separate from governance: an explicitly allowed floating selector stays `floating-literal`. Homebrew formula and Docker image commands retain their established conservative fallback behavior and do not receive npm/PyPI structured details. A form cannot become accepted merely because structured analysis does not cover it. npm registry versions are exact only when the complete selector is a bounded exact version, including valid prerelease and build metadata; a leading `v` or `=` is accepted only for an otherwise complete exact version. Bare packages, arbitrary dist-tags, comparator or caret/tilde ranges, partial versions, and wildcards are floating. Python uses bounded PEP 440/508-inspired semantics: literal `==` requires one supported PEP 440 version, while literal `===` accepts one non-empty arbitrary equality value and does not give `*` wildcard meaning. The Python rule does not require `major.minor.patch`; malformed or unsupported `==` values fail closed. Python name-based requirements accept optional horizontal whitespace around names, extras, operators, version identifiers, and commas. Classification and allowance keys remove only that insignificant whitespace while retaining the raw reference. URL, marker, arbitrary, and unsupported whitespace is not collapsed. Bounded pip general options may precede `install`, and the bounded post-install option table consumes known required values. Unknown, missing, or ambiguous options require fallback while retaining safely recoverable install and package evidence. `${NAME:?message}` remains the accepted fail-closed variable form when it is at the use site or in an exact structurally associated guard for the same case-sensitive variable. For Python it applies only to an exact-equality-shaped requirement. This proves a required external value, not that Renma parsed the runtime value as an exact registry version. A default, earlier assignment, ambient value, prose claim, different variable, later guard, range variable, or whole-requirement variable remains unverified. Canonical Skills may declare the asset-local JSON-array string `metadata.renma.allowed-floating-dependencies`; non-Skill assets use `allowed_floating_dependencies`. Every entry has an exact `npm:` or `pypi:` prefix and one package-selector pair. PyPI project names use standard lowercase-and-collapse normalization for `-`, `_`, and `.`, and valid specifier lists use only the documented insignificant-whitespace normalization. Selectors, ecosystems, and package identities otherwise match exactly. No wildcard, glob, fuzzy, or cross-ecosystem approval exists, and an npm/PyPI allowance cannot suppress Homebrew or Docker fallback findings. Invalid canonical encoding fails closed with `SEC-INVALID-CANONICAL-POLICY-METADATA`. The field is not profile-inherited and does not alter effective policy or policy fingerprints. Security Policy Inventory exposes it as local metadata and field evidence without adding it to effective-policy provenance, inheritance, repository configuration, or existing policy counts. Requirement and constraint files are retained as indirect evidence but are not parsed. URLs, VCS sources, editable or local installs, archives, npm aliases, workspace references, and ambiguous options are explicit unsupported evidence or require fallback; none can become exact merely because parsing stopped. Renma does not inspect manifests, lockfiles, requirements files, constraints files, or `pyproject.toml` in this diagnostic. Unapproved floating, variable-unverified, indirect, and unsupported references emit the existing `SEC-UNPINNED-DEPENDENCY-INSTALL`; no new diagnostic ID is introduced. Severity, confidence, risk class, evidence boundaries, source ordering, deduplication, suppression behavior, Diagnostics v2, and review bundles retain their compatibility behavior. Additive finding details describe the npm/PyPI structured classifications. No finding means only that Renma found no matching evidence within the documented structured and compatibility fallback boundaries. ### Security Policy Metadata The User Manual's [Authoritative Metadata Reference](user-manual.md#authoritative-metadata-reference) owns the complete canonical Skill/non-Skill security field mapping, supported value formats, applicability, authoring and compatibility status, and primary consumer projections. Security policy diagnostics use two serialization boundaries. Skills must be specification-valid Agent Skills and declare policy through flat, string-valued `metadata.renma.*` entries. Contexts and other non-Skill assets retain top-level snake_case security fields. Canonical Skill security booleans must use the exact strings `"true"` or `"false"`, and canonical Skill security lists must use JSON-array strings containing strings only. Non-Skill scalar, inline-list, and block-list behavior is unchanged. Pre-0.16 top-level Skill security fields are migration input only. Invalid recognized values emit `SEC-INVALID-CANONICAL-POLICY-METADATA` and fail closed. Renma preserves already-reviewed restrictive inherited policy while preventing permissive inheritance: allowed-data permissions remain unresolved, inherited forbidden inputs remain active, and invalid destination allowlists continue reporting concrete destinations as unapproved. 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. Scripts retain discovery, ownership, inherited-policy, Trust Graph, and BOM evidence, but their executable contents do not contribute Renma security findings. Ordinary assets and binary files also do not contribute instruction text. Orphan scripts receive no inherited repository-config policy 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 use the same exact canonical property spellings in JSONC and JSON configuration. Historical aliases are rejected with their replacement; Renma does not merge or compare alternate spellings. Artifact-local explicit denials remain stricter than inherited profile or repository allowances, and network approvals remain separate from upload approvals. See the [Security Policy Guide](security-policy.md) for complete examples by asset kind. Token-budget findings use deterministic `estimated_tokens`, not exact token counts for a particular model. `QUAL-SKILL-TOKEN-BUDGET` measures the Markdown body after frontmatter; `QUAL-SUPPORT-ASSET-TOKEN-BUDGET` measures the full Context, Reference, Profile, or Example file. The Renma defaults are Skill 6,400/8,000, Context 6,400/8,000, Reference 7,200/9,000, Profile 3,200/4,000, and Example 4,800/6,000. The portable Agent Skills recommendation remains 5,000 Skill body tokens; it is distinct from Renma's 6,400 repository warning. Each pair produces no finding through warning, Medium above warning through High, and High above High. Repositories may set every effective pair through the [authoritative configuration contract](user-manual.md#configuration). The Skill finding details retain `measured`, `warningThreshold`, `highThreshold`, `triggeredThreshold`, `effectiveSeverity`, `unit`, Markdown body measurement scope, quality-profile identity, overall `policySource`, and per-threshold sources. Overage evidence is calculated against the threshold that selected the result. Each exceeded-budget finding also retains up to three largest heading-based review candidates when useful structure exists. The candidates are ranked by estimated section size with source-line tie-breaking, and nested headings stay within the selected parent section. They locate material for semantic review; they do not direct an automatic split or infer a destination from a heading. `scan --fail-on high` gates the High result through Renma's normal severity model; no token-specific strict mode exists. Support-asset findings likewise expose repository and effective warning/High thresholds, the triggered threshold and severity, policy provenance, and overage. A valid per-file override raises the effective warning floor; the effective High threshold cannot fall below it. For support assets, repository configuration supplies the warning/High pair. An active override remains visible alongside the Renma default and repository policy and is not a suppression: exceeding the resulting effective thresholds still produces the finding. Invalid override metadata exposes its parser- provided reasons in human-facing guidance and leaves repository policy active. Splitting an asset, recording an override, or changing one requires an explicit human decision. Semantic ownership—not section size or heading text—determines whether content belongs in `SKILL.md`, `references/`, `scripts/`, `assets/`, or `contexts/`. `META-POLICY-REQUIRED-FIELD-MISSING` is a High finding backed by an `error` catalog diagnostic. Its structured details include `requiredField`, `assetPath`, `assetKind`, `expectedSerializedKey`, `presenceState` (`absent`, `empty`, `invalid`, or `ambiguous`), `policySource`, `configurationKey`, `configurationPath`, and the explicit declaration requirement. The source is always repository configuration and the responsible key is `metadata.required`. Skills receive the exact `metadata.renma.*` guidance; non-Skills receive the registered top-level spelling. No value is inferred or written during scanning. | Identifier | Meaning | Typical cause | How to fix | | ------------------------------------------------ | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | `COMPOSITION-DECLARED-CONFLICT` | Required declared composition contains conflicting assets. | Two assets connected to the same focused composition through required routes have an explicit `conflicts` declaration. | Review both inclusion routes and the conflict declaration; change relationships only from reviewed intent and never select a winner from order. | | `COMPOSITION-OPTIONAL-CONFLICT` | Declared composition has an optional conflict candidate. | At least one member of an explicit conflict pair is reachable only after an optional edge. | Keep the candidate visible to runtime consumers or revise the reviewed declarations; Renma does not select optional Context. | | `COMPOSITION-OPTIONAL-CYCLE` | Optional declared composition contains a cycle. | A cycle becomes reachable only after an optional route. | Review responsibility boundaries while preserving optional provenance; do not infer precedence or repeated loading. | | `COMPOSITION-REQUIRED-CYCLE` | Required declared composition contains a cycle. | Required `requires_context`, `requires_lens`, or Lens `applies_to` edges form a strongly connected component. | Split, consolidate, or relate assets differently after review; the finite closure may remain complete even while `cycleFree` is false. | | `DISCOVERY-DUPLICATE-DECLARED-ROUTE` | One Skill declares the same continuation more than once. | Repeated normalized spellings or different exact spellings resolve to the same target Skill. | Keep one declaration while preserving the intended continuation; declaration order is not priority. | | `DISCOVERY-ENTRYPOINT-WITHOUT-USABLE-BOUNDARIES` | A published entrypoint has a deterministic capability or selection-boundary gap. | Linked `RN-SKILL-*` evidence identifies a missing capability, positive usage boundary, or negative selection/routing boundary. Passing this warning is not proof of semantic completeness. | Improve the source Skill's bounded first-hop responsibility; do not remove publication solely to suppress the warning. | | `DISCOVERY-INACTIVE-ROUTE-TARGET` | A route-eligible Skill targets a deprecated or archived Skill. | An exact continuation is still declared after its target became inactive. | Retarget or remove the stale declaration after review; do not create or reactivate a placeholder Skill. | | `DISCOVERY-REVOKED-PUBLISHED-ENTRYPOINT` | A revoked Skill attempts publication. | A valid publication marker remains after trust or authorization for the Skill was explicitly withdrawn. | Remove the stale publication attempt or review the separate lifecycle decision; do not restore, clone, or replace the Skill merely to publish it. | | `DISCOVERY-REVOKED-ROUTE-TARGET` | An active route resolves to a revoked Skill. | The exact continuation remains auditable but unusable after explicit trust withdrawal. | Review whether to remove or retarget the direct route; do not restore or replace the target automatically. | | `DISCOVERY-SUSPENDED-PUBLISHED-ENTRYPOINT` | A suspended Skill attempts publication. | A valid publication marker is present while the specification-valid Skill is temporarily inactive. | Remove the stale publication attempt or review the lifecycle decision; do not reactivate or clone the Skill merely to publish it. | | `DISCOVERY-SUSPENDED-ROUTE-TARGET` | An active route resolves to a suspended Skill. | The exact continuation remains resolved and auditable but is unusable for Discovery. | Review the direct route or the separate lifecycle decision; do not infer a replacement or reactivate automatically. | | `DISCOVERY-INVALID-CONTINUATION-DECLARATION` | The canonical continuation field has an invalid value. | `metadata.renma.continues-with` is not a string containing a JSON array of non-empty strings. | Correct the JSON-array string or remove the stale declaration while preserving intended routing semantics. | | `DISCOVERY-INVALID-PUBLISHED-ENTRYPOINT` | A publication marker is invalid or ambiguous, or a specification-valid inactive Skill attempts publication. | Exact `metadata.renma.published-entrypoint` evidence, marker state/value, lifecycle where relevant, and rejection reasons identify the failed declaration. | Preserve the intended first-hop responsibility; use one exact string `"true"` marker or omit it, and require human review for ambiguity. Do not publish every structural root, fabricate a Skill, or reactivate one merely to publish it. | | `DISCOVERY-ROUTE-CYCLE` | Usable representative Skill continuations form a self-loop or multi-Skill strongly connected component. | Sorted member Skills and every internal usable route retain exact source/target paths, declaration indices, and evidence. The warning is static route evidence, not proof of runtime recursion. | Review every internal continuation and decide whether the loop is intentional and bounded or accidental. Do not remove an arbitrary route, change publication, or break a valid review loop merely to silence the warning. | | `DISCOVERY-ROUTE-TARGET-NOT-SKILL` | A Skill continuation resolves to a non-Skill asset. | The exact ID or path identifies Context, Lens, reference, profile, example, script, or another asset kind. | Use existing typed Context or Lens relationships, or correct the continuation to an exact real Skill. | | `DISCOVERY-UNREACHABLE-ELIGIBLE-SKILL` | An adopted repository has a Discovery-eligible Skill outside every published continuation graph. | No usable representative resolved Skill route path reaches the Skill from any effective published entrypoint. | Review whether the Skill is an independent entrypoint, belongs under a real source-owned continuation, or is outside the intended repository-wide policy. Do not add fake routes or publish every Skill. | | `DISCOVERY-UNRESOLVED-DECLARED-ROUTE` | An exact Skill continuation is missing or ambiguous. | No exact ID/path matches, duplicate IDs make ID lookup ambiguous, ID and path select different assets, or the path is absolute/escaping. | Correct the exact ID/path, remove a stale route, or add a real Skill only from source evidence; request human review for ambiguity. | | `DOCS-LAYOUT-INCONSISTENT` | Documentation contradicts the supported repository model. | Docs use deprecated roots, old prompt-library framing, or another independently stale statement. | Describe canonical Skill roots and valid local support separately from governed `contexts/**` assets and shared `tools/**` helpers. | | `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-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/`. | | `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. | | `MAINT-CONTEXT-PATH-NON-SEMANTIC` | Context path is not semantically grouped. | Context is stored under vague folders such as misc or general. | Move it under a meaningful path such as `contexts/tools/`, `contexts/domain/`, or `contexts/testing/`. | | `MAINT-ASSET-REVIEW-OVERDUE` | Asset freshness review is overdue. | `last_reviewed_at + review_cycle` is before today's date. | Revalidate the asset with a human owner, then update `last_reviewed_at` or review cadence. | | `MAINT-ORPHANED-CONTEXT-ASSET` | Shared context has no incoming references. | A first-class context asset is not used by skills or other assets. | Link it from consumers, archive it, or remove it after review. | | `MAINT-ORPHANED-CONTEXT-LENS` | Context lens has no skill references. | An active context lens is not referenced by any skill through `requires_lens` or `optional_lens`. | Link it from a skill, archive it, or leave it staged with reviewed lifecycle metadata. | | `MAINT-REFERENCE-DEPRECATED-ASSET` | Reference targets deprecated context. | Metadata dependency resolves to a deprecated asset. | Point dependents at a stable asset or finish the migration. | | `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` | 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` | 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. | | `META-CONTEXT-MISSING-WHEN-NOT-TO-USE` | Shared context negative boundary is missing. | An active, owned shared context asset lacks `when_not_to_use`. | Add compact exclusions so agents do not over-apply the context. | | `META-CONTEXT-PLACEHOLDER-USAGE-BOUNDARY` | Shared context usage boundary contains placeholders. | `when_to_use` or `when_not_to_use` contains TODO, TBD, unknown, none, or similar placeholder text. | Replace placeholders with reviewed boundaries. | | `META-DUPLICATE-ASSET-ID` | Asset ID is not unique. | Two catalog entries declare the same ID. | Give each asset a unique ID and update references. | | `META-DEPENDENCY-SOURCE-KIND-MISMATCH` | A relationship originates from the wrong asset kind. | `applies_to` is authored outside a Context Lens, independently of whether its target resolves or has the correct kind. | Move, change, or remove the declaration from reviewed repository intent; do not change or create a target merely to hide the source violation. | | `META-DEPENDENCY-TARGET-KIND-MISMATCH` | A resolved relationship targets the wrong asset kind. | For example, `requires_context` points to a Context Lens, `requires_lens` points to Context, or Lens `applies_to` points outside Context. | Correct the target or declaration using repository intent; do not create placeholders or reject valid Context-to-Context dependencies. | | `META-DUPLICATE-DECLARED-DEPENDENCY` | One metadata field repeats the same dependency value. | The exact target appears multiple times in the same `requires_context`, `optional_context`, Lens, conflict, or lifecycle declaration field. | Keep one exact value after review; preserve legitimate multi-parent routes and distinct stable IDs. | | `META-FRONTMATTER-TOO-LARGE` | Frontmatter metadata is too large. | Frontmatter has too many lines or characters to stay a compact index. | Move long prose, examples, procedures, or rationale into the body or referenced context assets. | | `META-INVALID-RENMA-FRONTMATTER` | Non-Skill Renma frontmatter is invalid or ambiguous. | The exact Renma envelope contains malformed YAML, a non-mapping root, or duplicate recognized operational keys. | Repair the YAML or duplicate declaration after confirming intent; do not recover values from raw lines. | | `META-UNSUPPORTED-CANONICAL-CONTEXT` | `canonical_context` is unsupported and uninterpreted. | A non-Skill asset retains the removed compatibility field. | Use existing `superseded_by` when the asset has a reviewed replacement, then update Skill Context relationships or placement as appropriate. | | `META-UNKNOWN-REFERENCE` | Metadata reference does not resolve. | A dependency points to a missing asset ID or path. | Fix the reference, add the missing asset, or remove the dependency. | | `PATH-HELPER-COMMAND-NON_TOOLS` | Helper command points outside supported helper locations. | A command references a script that is neither in the owning Skill's `scripts/**` nor under `tools/**`. | Keep a Skill-specific helper local or move a helper shared across workflows to `tools/**`, then update the command. | | `PATH-HELPER-COMMAND-UNRESOLVED` | Helper command path is missing or unsafe. | A referenced `tools/**` helper or Skill-local script is missing, or a relative path escapes its owning Skill. | Add the helper, correct the command path, or keep a relative local path inside the owning Skill. | | `PROF-MISSING-BASE` | Profile lacks base guidance. | A profile does not clearly relate to base skill behavior. | Add base-profile context or inheritance guidance. | | `QUAL-LOW-HEADING-DENSITY` | Asset has too little structure. | Long content has few headings. | Add meaningful headings or split the asset. | | `QUAL-MISSING-COMPLETION-CRITERIA` | Completion criteria are missing. | The asset does not say when work is done. | Add explicit completion or acceptance criteria. | | `QUAL-MISSING-DESCRIPTION` | Description is missing. | Metadata or introductory purpose is absent. | Add a concise description. | | `QUAL-MISSING-EXAMPLES` | Examples are missing. | Instructional content has no concrete example. | Add representative positive examples. | | `QUAL-MISSING-NEGATIVE-ROUTING` | Negative routing is missing. | Skill guidance omits when not to use it. | Add exclusions or handoff guidance. | | `QUAL-MISSING-PREFLIGHT` | Preflight guidance is missing. | The asset omits checks to run before acting. | Add required inputs, checks, or setup steps. | | `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 or Agent lacks explicit selection language in its effective description or Markdown body. | Add a bounded phrase such as `Use when`, `When to use`, or another clear trigger, role, or routing statement. | | `QUAL-MISSING-VERIFICATION` | Verification guidance is missing. | Markdown headings and body text lack recognizable static guidance for checking the workflow result. | Add verification or validation steps, tests, or an expected output/result. | | `QUAL-RENMA-SCAFFOLD-PLACEHOLDER` | Exact Renma-generated scaffold prose remains unresolved. | A canonical Skill description or complete Skill/Context body line still equals one of Renma's own starter markers. | Replace the evidenced marker with repository-grounded content; do not infer missing domain or governance truth. Clearing exact markers does not certify semantic completeness. | | `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-DESCRIPTION-HIGH-RISK-LITERAL` | Canonical Skill description contains a high-risk routing literal. | A bounded quoted routing example is non-operational but existing command, disclosure, policy, or safeguard classifiers recognize its concrete payload. | Replace the literal with semantic routing wording. If exact evidence is necessary, move it to a clearly non-operational unsafe-example or review-evidence body section; do not automatically rewrite owner-authored prose. | | `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 its effective repository token-budget threshold. | Markdown body is above the effective warning threshold or above the effective High threshold. | Review progressive disclosure while retaining core workflow, constraints, and completion criteria; never split or move 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 token-budget threshold. | A Context, Reference, Profile, or Example exceeds its effective warning threshold (Medium) or High threshold (High). | 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` | 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. | | `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-INACTIVE-DEPENDENCY` | Metadata points to an inactive asset. | A dependency targets a deprecated or archived asset. | Retarget the dependency to a stable asset or update asset status intentionally. | | `META-INVALID-STATUS-CHANGED-AT` | Lifecycle transition date is invalid. | `status_changed_at` is present but is not a real `YYYY-MM-DD` date; severity is error for suspended or revoked status and warning otherwise. | Confirm the real reviewed transition date; do not derive it from Git or filesystem timestamps. | | `META-INVALID-EXPIRES-AT` | Freshness expiration date is invalid. | `expires_at` is present but is not a real `YYYY-MM-DD` date. | Replace it with a valid ISO date or remove the field until reviewed. | | `META-INVALID-LAST-REVIEWED-AT` | Freshness review date is invalid. | `last_reviewed_at` is present but is not a real `YYYY-MM-DD` date. | Replace it with a valid ISO date or remove the field until reviewed. | | `META-INVALID-REVIEW-CYCLE` | Freshness review cycle is unsupported. | `review_cycle` is present but is not a supported day duration. | Use a duration such as `P90D` or `P180D`. | | `META-INVALID-STATUS` | Metadata status is invalid. | An asset declares an unsupported status value. | Replace it with a supported lifecycle status. | | `META-OPTIONAL-REVOKED-DEPENDENCY` | Optional metadata points to a revoked asset. | An active asset has one exact optional Context or Lens declaration targeting an explicitly untrusted or unauthorized asset. | Review a justified exception, removal, retargeting, or separate target lifecycle decision. | | `META-OPTIONAL-SUSPENDED-DEPENDENCY` | Optional metadata points to a suspended asset. | An active asset has one exact optional Context or Lens declaration targeting a suspended asset. | Preserve it for review, retarget or remove it with evidence, or restore the target separately. | | `META-REQUIRED-REVOKED-DEPENDENCY` | Required metadata points to a revoked asset. | An active asset has one exact required Context, Lens, or `applies_to` declaration targeting an explicitly untrusted or unauthorized asset. | Review the direct declaration and choose an evidence-backed outcome without automatic propagation or target mutation. | | `META-REQUIRED-SUSPENDED-DEPENDENCY` | Required metadata points to a suspended asset. | An active asset has one exact required Context, Lens, or `applies_to` declaration targeting a suspended asset. | Review the direct declaration or restore the target through a separate reviewed lifecycle decision. | | `META-REVOKED-STATUS-METADATA-INCOMPLETE` | Revoked lifecycle evidence is incomplete. | A revoked asset lacks a non-blank reason or real transition date, including invalid declared values. | Add human-reviewed revocation reason/date evidence without changing lifecycle status merely to clear the finding. | | `META-SUSPENDED-STATUS-METADATA-INCOMPLETE` | Suspended lifecycle evidence is incomplete. | A suspended asset lacks a non-blank transition reason, a changed date, or both. | Add human-reviewed reason and real transition-date evidence without restoring, archiving, deleting, or cloning the asset. | | `META-LIST-ITEM-TOO-LONG` | Metadata list item is too long. | A block-list metadata item contains routing prose or detailed conditions. | Keep the item short and move detailed guidance into body sections or referenced context assets. | | `META-MISSING-ID` | Metadata is missing an asset ID. | A cataloged asset has no stable `id`. | Add an `id` metadata field. | | `META-POLICY-REQUIRED-FIELD-MISSING` | Repository-required metadata is absent, empty, invalid, or ambiguous. | An applicable catalog asset does not explicitly declare a valid non-empty field named by `metadata.required`. | Add the reviewed value using the finding's exact canonical Skill or top-level non-Skill spelling; do not infer or fabricate it. | | `META-UNKNOWN-DEPENDENCY` | Metadata dependency is unresolved. | A dependency points at an asset renma did not discover. | Correct the dependency, add the missing asset, or update discovery config. | | `SEC-BODY-POLICY-CONTRADICTION` | Body text contradicts a security policy. | Asset instructions override or weaken policy expectations. | Align the asset content with the active policy profile. | | `SEC-BULK-DATA-SHARING-INSTRUCTION` | Instructions allow broad data sharing. | Content tells an agent to share large or sensitive data without bounds. | Narrow the sharing scope and add approval or redaction guidance. | | `SEC-CLOUD-UPLOAD-INSTRUCTION` | Instructions allow cloud upload. | Content sends files or data to cloud storage without policy controls. | Add approved destinations, limits, and approval requirements. | | `SEC-CREDENTIAL-IN-COMMAND-ARG` | Command embeds a credential-like value. | Example commands include secrets in arguments. | Move credentials to secure environment or secret-management guidance. | | `SEC-DANGEROUS-TOOL-INSTRUCTION` | Instructions permit dangerous tool use. | Content allows destructive or high-risk commands without guardrails. | Require review, dry runs, or explicit user approval before execution. | | `SEC-EXECUTABLE-AS-POLICY-AUTHORITY` | A recognized Skill helper becomes policy authority. | A supported inline helper invocation explicitly decides whether a security-relevant operation is allowed, approved, authorized, or safe. | Keep authorization in reviewed Skill instructions and declarative Renma policy; use the helper only for bounded evidence. | | `SEC-EXTERNAL-UPLOAD-INSTRUCTION` | Instructions allow external upload. | Content sends artifacts to external services without controls. | Restrict uploads to approved destinations and document review steps. | | `SEC-FORBIDDEN-INPUT-INSTRUCTION` | Instructions request forbidden input. | Content asks for secrets or other disallowed sensitive values. | Remove the request or replace it with safe placeholder guidance. | | `SEC-HIDDEN-FRONTMATTER-INSTRUCTION` | YAML frontmatter comment hides an operational instruction. | Raw eligible agent-facing Markdown contains a bounded recognized security-sensitive instruction that metadata consumers ignore. | Remove it or make intentional guidance visible with explicit policy and safeguards. | | `SEC-HIDDEN-OPERATIONAL-INSTRUCTION` | HTML comment hides an operational instruction. | Raw agent-visible source contains a bounded recognized security-sensitive instruction that rendered Markdown omits. | Remove it or make intentional guidance visible with explicit policy and safeguards. | | `SEC-INSTRUCTION-HIERARCHY-OVERRIDE` | Instructions attempt to supersede higher authority. | Agent-facing text explicitly ignores, overrides, supersedes, or claims precedence over system, developer, platform, prior, or higher-level instructions. | Remove the hierarchy override, preserve host authority, and state only bounded local behavior. | | `SEC-INSTRUCTION-VIOLATES-POLICY` | Instruction conflicts with active policy. | Asset content violates a configured security profile. | Update the instruction or policy metadata so they agree. | | `SEC-INVALID-CANONICAL-POLICY-METADATA` | Canonical Skill security metadata is invalid. | A recognized `metadata.renma.*` field has an invalid boolean, list, or profile encoding. | Confirm the intended policy and replace it with the exact documented string encoding; do not guess. | | `SEC-INVALID-RENMA-POLICY-METADATA` | Non-Skill Renma security metadata is invalid. | A recognized top-level policy field is malformed, duplicated, ambiguous, or has an unsupported YAML value shape. | Repair the exact Renma YAML declaration after confirming intent; do not infer a permissive value. | | `SEC-MISSING-HUMAN-APPROVAL-GUARD` | High-risk operation lacks approval guidance. | Content describes sensitive actions without human confirmation. | Add explicit approval requirements before the action. | | `SEC-MISSING-POLICY-METADATA` | Security policy metadata is missing. | Asset content needs a policy profile but does not declare one. | Add the appropriate security policy metadata. | | `SEC-NO-REDACTION-INSTRUCTION` | Sensitive data flow lacks redaction guidance. | Content shares logs, files, or context without redaction steps. | Add instructions to redact or minimize sensitive data before sharing. | | `SEC-OVERBROAD-CONTEXT-INSTRUCTION` | Instructions request excessive context. | Content tells an agent to include broad repository or user data. | Scope context collection to the minimum required files and fields. | | `SEC-POLICY-CONTRADICTION` | Security policy settings contradict each other. | Profile rules define incompatible requirements. | Resolve the conflicting policy fields. | | `SEC-POLICY-OVERRIDE-CONTRADICTION` | Policy override contradicts inherited policy. | An override weakens or conflicts with the base profile. | Adjust the override or split the profile intentionally. | | `SEC-POLICY-PROFILE-CYCLE` | Policy profiles form a cycle. | Profile inheritance refers back to itself. | Break the cycle in policy profile inheritance. | | `SEC-POLICY-PROFILE-NOT-FOUND` | Referenced policy profile is missing. | Metadata names a profile renma cannot resolve. | Add the profile or correct the reference. | | `SEC-PREDICTABLE-TEMP-PATH` | Command uses a predictable temp path. | Examples write to fixed `/tmp` paths or similar locations. | Use a unique temporary directory or safe temp-file helper. | | `SEC-PRIVILEGED-COMMAND-WITHOUT-GUARD` | Privileged command lacks guardrails. | Content runs `sudo` or equivalent privileged actions without checks. | Add prerequisites, confirmation, and rollback guidance. | | `SEC-RISKY-OPERATION-ERROR-SUPPRESSION` | Risky operation failure is explicitly ignored. | A destructive, privileged, upload, or sensitive-data operation uses a bounded shell or prose failure-suppression form. | Preserve the failure, stop and report it, and verify or roll back partial effects. | | `SEC-SAFEGUARD-BYPASS-INSTRUCTION` | Instructions explicitly bypass a security safeguard. | Content disables checks, weakens policy, skips approval, suppresses warnings, or uses a riskier fallback. | Preserve the safeguard, stop and report missing authority, and verify again without policy relaxation. | | `SEC-SECRET-MATERIAL-INSTRUCTION` | Instructions expose or request secret material. | Content includes or asks for private keys, tokens, or credentials. | Remove secret material and describe secure handling instead. | | `SEC-SENSITIVE-FILE-REFERENCE` | Instructions reference sensitive files. | Content points at credentials, keys, or local secret paths. | Replace with safe examples or redacted placeholders. | | `SEC-SUSPICIOUS-BIDI-CONTROL` | Bidirectional formatting control requires review. | Original source contains a bidi embedding, override, pop, or isolate control that can reorder displayed text. | Inspect the escaped code point and make the smallest character-level correction; require human confirmation if intentional. | | `SEC-SUSPICIOUS-INVISIBLE-CHARACTER` | Invisible Unicode character requires review. | Original source contains a high-signal invisible/deprecated format control, a non-leading BOM, or token-internal ZWJ/ZWNJ. | Inspect the escaped code point and remove or visibly replace only that character while preserving legitimate multilingual text. | | `SEC-UNBOUNDED-EXTERNAL-SOURCE-TRAVERSAL` | Recursive external traversal has no local boundary. | Content recursively follows links, issues, pages, or attachments without any stated scope or termination control. | Add source, relevance, visited/cycle, cap, failure-stop, and unresolved-scope guidance in the same section. | | `SEC-UNAPPROVED-NETWORK-DESTINATION` | Network destination is not approved. | Instructions contact a host outside the allowed list. | Enumerate the actual required domains in approved network destinations after review. | | `SEC-UNAPPROVED-UPLOAD-DESTINATION` | Upload destination is not approved. | Instructions upload data to an unapproved service or host. | Use an approved destination or update policy intentionally. | | `SEC-UNPINNED-DEPENDENCY-INSTALL` | Dependency install is not pinned. | A structured npm/PyPI install or compatibility-fallback Homebrew/Docker command contains floating or unresolved dependency evidence. | Use repository evidence and established conventions for a reviewed exact package selector, supported versioned formula, or explicit non-floating image tag/digest. Fail-closed variables apply only where structurally supported, and allowances only to exact asset-local `npm:`/`pypi:` selectors. Never invent a value or claim uninspected sources were verified. | | `SEC-UNPINNED-REMOTE-SCRIPT` | Remote script execution is unpinned. | Commands pipe or execute remote scripts without an immutable reference. | Pin the script source and verify it before execution. | | `SEC-UNTRUSTED-CONTENT-AS-INSTRUCTION` | Untrusted source content becomes executable guidance. | Content follows fetched, downloaded, attached, logged, or tool-produced instructions as authority without review. | Treat the content as data, preserve provenance, validate facts, and use reviewed local authority for actions. | ## How To Fix Results 1. Fix `error` diagnostics first. They usually mean renma could not build a deterministic view of the repository. 2. Fix unresolved references before quality findings. Reference failures can hide or distort later reports. 3. For scan findings, use the finding ID, evidence path, line number, snippet, and remediation text in the JSON output. 4. Re-run the same command with `--format json` when a markdown or text report does not contain enough detail.