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. 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.

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.

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.

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:

{
  "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"
    }
  }
}

{
  "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:

{
  "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:

{
  "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:

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:

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:

kind: reference
scope: skill-local
parentResolution: resolved
decisionStatus: no-change-recommended

LLM summary:

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:

It should be reusable by three Skills.

LLM response:

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:

kind: context
scope: independent
matchedRule: context-root

LLM summary:

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:

{
  "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 "<pattern>": <error>	A configured discovery glob could not be evaluated.	Fix or remove the glob pattern in config or CLI input.
warning	Skipping symbolic link; repository discovery never follows symlink targets.	Renma found a leaf or directory symlink and skipped it without reading or enumerating its target.	Replace it with a regular repository file or directory. A referenced path at or below the symlink also emits SUPPORT-SYMLINK-PATH.
warning	Skipping file larger than max_file_size_bytes (<bytes>).	A file exceeded the configured size limit.	Raise max_file_size_bytes, exclude the file, or split the asset.
error	Could not read file: <error>	The file matched discovery but could not be read.	Fix permissions, remove the bad path, or exclude the file.

Metadata And Catalog Diagnostics

These diagnostics are emitted after files are parsed into catalog entries. For shared-context wording details, see Context Language Diagnostics.

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 "<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 "<date>". 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 <fields> 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 (<issues>). 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 "<date>". 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 "<date>". 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 "<duration>". 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 "<to>" from "<from>" does not match a catalog entry.	A metadata dependency points at an asset renma did not discover.	Correct the reference, add the missing asset, or update include/exclude config.
warning	Metadata dependency "<to>" from "<from>" targets a <status> asset.	A dependency points at a deprecated or archived catalog target.	Retarget the dependency to a stable replacement or document the migration.
error	Required <relationship> declaration "<to>" from "<from>" resolves to suspended asset "<target>".	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 <relationship> declaration "<to>" from "<from>" resolves to suspended asset "<target>".	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 <relationship> declaration "<to>" from "<from>" resolves to revoked asset "<target>"...	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 <relationship> declaration "<to>" from "<from>" resolves to revoked asset "<target>"...	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 <field>.	Usage-boundary metadata is present but still says TODO, TBD, unknown, none, or similar.	Replace placeholders with reviewed scope boundaries, or remove the field until it can be completed.
warning	Shared context asset contains vague wording "<term>".	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 "<term>" 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 "<term>".	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	<kind> reference "<target>" does not resolve.	A graph edge points to a missing target.	Correct the reference or add the target asset.
error	Required context reference "<target>" does not resolve.	A required context reference is missing.	Add the context asset or correct requires_context.
error	Required context "<target>" resolves to <status> asset <path>.	Required context exists but is deprecated or archived.	Move the dependency to a stable context asset.
warning	Optional context reference "<target>" does not resolve.	An optional context reference is missing.	Correct it or remove it if it is no longer useful.
warning	Optional context "<target>" resolves to <status> asset <path>.	Optional context exists but is deprecated or archived.	Retarget or remove the optional dependency.
warning	Asset status is <status>.	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 <!-- and --> 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 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 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.

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.