renma 0.5.1 → 0.6.0

package/dist/rules.js

@@ -1,5 +1,7 @@
 import { existsSync } from "node:fs";
 import path from "node:path";
+import { addDaysIsoDate, isIsoDate, parseDayDuration, todayIsoDate, } from "./freshness.js";
+import { DIAGNOSTIC_IDS } from "./diagnostic-ids.js";
 import { runRuleRegistry } from "./rule-engine.js";
 const SECRET_PATTERN = /\b(?:password|passwd|token|api[_-]?key|secret|credential|private[_-]?key)\b\s*[:=]\s*["']?([A-Za-z0-9_./+=-]{8,})/i;
 const PRIVATE_KEY_PATTERN = /-----BEGIN (?:RSA |OPENSSH |EC |DSA )?PRIVATE KEY-----/;
@@ -184,9 +186,83 @@ function catalogDeclaredReferenceGovernanceFindings(catalog) {
         ...unknownReferenceFindings(catalog.dependencies, resolver),
         ...referenceDeprecatedAssetFindings(catalog.dependencies, resolver),
         ...orphanedContextAssetFindings(catalog.entries, catalog.dependencies, resolver),
+        ...freshnessGovernanceFindings(catalog.entries),
     ];
     return findings;
 }
+function freshnessGovernanceFindings(entries, today = todayIsoDate()) {
+    return entries
+        .filter((entry) => entry.kind === "context" || entry.kind === "skill")
+        .flatMap((entry) => [
+        ...expiredAssetFindings(entry, today),
+        ...reviewOverdueAssetFindings(entry, today),
+    ]);
+}
+function expiredAssetFindings(entry, today) {
+    const expiresAt = entry.metadata.expiresAt;
+    if (!expiresAt || !isIsoDate(expiresAt) || expiresAt >= today)
+        return [];
+    return [
+        {
+            id: DIAGNOSTIC_IDS.MAINT_ASSET_EXPIRED,
+            title: "Asset freshness metadata is expired",
+            category: "maintenance",
+            severity: "medium",
+            confidence: "high",
+            evidence: metadataFieldFindingEvidence(entry, "expires_at", `expires_at: ${expiresAt}`),
+            whyItMatters: "Freshness metadata is a human review contract. Expired assets may contain guidance that has not been intentionally revalidated for current use.",
+            remediation: "Review the asset with a human owner, then update expires_at, last_reviewed_at, review_cycle, status, or dependent references as appropriate.",
+            constraints: [
+                "Do not infer freshness from file modification time.",
+                "Do not introduce runtime context selection.",
+                "Do not create prompt packages.",
+            ],
+            verificationSteps: [
+                "Run renma scan.",
+                "Run renma catalog.",
+                "Confirm the freshness metadata reflects human review.",
+            ],
+            llmHint: `Review ${entry.sourcePath} for stale assumptions, then update explicit freshness metadata only after human review.`,
+        },
+    ];
+}
+function reviewOverdueAssetFindings(entry, today) {
+    const lastReviewedAt = entry.metadata.lastReviewedAt;
+    const reviewCycle = entry.metadata.reviewCycle;
+    if (!lastReviewedAt || !reviewCycle)
+        return [];
+    if (!isIsoDate(lastReviewedAt))
+        return [];
+    const cycleDays = parseDayDuration(reviewCycle);
+    if (cycleDays === undefined)
+        return [];
+    const dueAt = addDaysIsoDate(lastReviewedAt, cycleDays);
+    if (dueAt >= today)
+        return [];
+    return [
+        {
+            id: DIAGNOSTIC_IDS.MAINT_ASSET_REVIEW_OVERDUE,
+            title: "Asset freshness review is overdue",
+            category: "maintenance",
+            severity: "medium",
+            confidence: "high",
+            evidence: metadataFieldFindingEvidence(entry, "last_reviewed_at", `last_reviewed_at: ${lastReviewedAt}; review_cycle: ${reviewCycle}`),
+            whyItMatters: "Review cycles make human freshness expectations explicit. Overdue assets may no longer match current product, policy, or workflow behavior.",
+            remediation: "Review the asset with a human owner, then update last_reviewed_at or review_cycle if the guidance is still current.",
+            constraints: [
+                "Do not infer freshness from Git history or file modification time.",
+                "Do not introduce runtime context selection.",
+                "Do not create prompt packages.",
+            ],
+            verificationSteps: [
+                "Run renma scan.",
+                "Run renma catalog.",
+                "Confirm the next review date is not overdue.",
+            ],
+            llmHint: `The next review date for ${entry.sourcePath} was ${dueAt}. Revalidate the asset before updating freshness metadata.`,
+        },
+    ];
+}
 function duplicateAssetIdFindings(entries) {
     const entriesById = new Map();
     for (const entry of entries) {
@@ -197,7 +273,7 @@ function duplicateAssetIdFindings(entries) {
             return [];
         const paths = duplicates.map((entry) => entry.sourcePath).sort();
         return duplicates.map((entry) => ({
-            id: "META-DUPLICATE-ASSET-ID",
+            id: DIAGNOSTIC_IDS.META_DUPLICATE_ASSET_ID,
             title: "Duplicate asset id",
             category: "maintenance",
             severity: "medium",
@@ -228,7 +304,7 @@ function unknownReferenceFindings(dependencies, resolver) {
             return [];
         return [
             {
-                id: "META-UNKNOWN-REFERENCE",
+                id: DIAGNOSTIC_IDS.META_UNKNOWN_REFERENCE,
                 title: "Declared reference does not resolve to a known asset",
                 category: "maintenance",
                 severity: "medium",
@@ -264,7 +340,7 @@ function referenceDeprecatedAssetFindings(dependencies, resolver) {
         }
         return [
             {
-                id: "MAINT-REFERENCE-DEPRECATED-ASSET",
+                id: DIAGNOSTIC_IDS.MAINT_REFERENCE_DEPRECATED_ASSET,
                 title: "Declared reference targets a deprecated or archived asset",
                 category: "maintenance",
                 severity: "medium",
@@ -311,7 +387,7 @@ function orphanedContextAssetFindings(entries, dependencies, resolver) {
             return [];
         return [
             {
-                id: "MAINT-ORPHANED-CONTEXT-ASSET",
+                id: DIAGNOSTIC_IDS.MAINT_ORPHANED_CONTEXT_ASSET,
                 title: "Shared context asset is not referenced by other assets",
                 category: "maintenance",
                 severity: "low",
@@ -392,10 +468,10 @@ export function severityMeets(value, threshold) {
 function secretFindings(document) {
     return matchingLineFindings(document, (line) => {
         if (PRIVATE_KEY_PATTERN.test(line)) {
-            return finding("SEC-PRIVATE-KEY", "Private key material appears in repository text", "safety", "critical", document, "Remove the key, rotate it if real, and keep only setup instructions or placeholders.");
+            return finding(DIAGNOSTIC_IDS.SEC_PRIVATE_KEY, "Private key material appears in repository text", "safety", "critical", document, "Remove the key, rotate it if real, and keep only setup instructions or placeholders.");
         }
         if (SECRET_PATTERN.test(line) && !isPlaceholder(line)) {
-            return finding("SEC-LITERAL-SECRET", "Literal credential-like value appears in repository text", "safety", "high", document, "Move secrets to user-approved inputs or a secret manager, and keep only placeholders in repository files.");
+            return finding(DIAGNOSTIC_IDS.SEC_LITERAL_SECRET, "Literal credential-like value appears in repository text", "safety", "high", document, "Move secrets to user-approved inputs or a secret manager, and keep only placeholders in repository files.");
         }
         return undefined;
     });
@@ -406,13 +482,13 @@ function commandFindings(document) {
             return undefined;
         if (DESTRUCTIVE_PATTERN.test(line) &&
             !hasNearbyConfirmation(document.lines, line)) {
-            return finding("SEC-DESTRUCTIVE-COMMAND", "Dangerous command lacks explicit confirmation or recovery guard", "safety", "high", document, "Require explicit user confirmation, add dry-run/backup guidance, and describe rollback or verification.");
+            return finding(DIAGNOSTIC_IDS.SEC_DESTRUCTIVE_COMMAND, "Dangerous command lacks explicit confirmation or recovery guard", "safety", "high", document, "Require explicit user confirmation, add dry-run/backup guidance, and describe rollback or verification.");
         }
         if (REMOTE_PATTERN.test(line)) {
-            return finding("SEC-REMOTE-DEFAULT", "Remote command example uses unsafe default", "safety", "medium", document, "Avoid production placeholders, insecure transport flags, and pipe-to-shell patterns unless paired with verification and confirmation.");
+            return finding(DIAGNOSTIC_IDS.SEC_REMOTE_DEFAULT, "Remote command example uses unsafe default", "safety", "medium", document, "Avoid production placeholders, insecure transport flags, and pipe-to-shell patterns unless paired with verification and confirmation.");
         }
         if (ENV_COPY_PATTERN.test(line)) {
-            return finding("SEC-ENV-COPY", "Command may pass broad environment into subprocess execution", "safety", "medium", document, "Pass only required environment variables to subprocesses and avoid forwarding secrets by default.");
+            return finding(DIAGNOSTIC_IDS.SEC_ENV_COPY, "Command may pass broad environment into subprocess execution", "safety", "medium", document, "Pass only required environment variables to subprocesses and avoid forwarding secrets by default.");
         }
         return undefined;
     });
@@ -425,17 +501,17 @@ function shapeFindings(document) {
     const description = document.metadata.description ?? "";
     const tokenCount = approximateTokenCount(document.artifact.content);
     if (!description) {
-        findings.push(documentFinding(document, "QUAL-MISSING-DESCRIPTION", "Skill is missing an explicit description", "quality", "medium", "Add frontmatter description so agents can route to the skill intentionally."));
+        findings.push(documentFinding(document, DIAGNOSTIC_IDS.QUAL_MISSING_DESCRIPTION, "Skill is missing an explicit description", "quality", "medium", "Add frontmatter description so agents can route to the skill intentionally."));
     }
     else if (document.artifact.kind === "skill" &&
         description.length < DESCRIPTION_MIN_CHARS) {
-        findings.push(documentFinding(document, "QUAL-SHORT-DESCRIPTION", "Skill description is too short for routing clarity", "quality", "low", `Expand frontmatter description to at least ${DESCRIPTION_MIN_CHARS} characters with usage routing guidance.`));
+        findings.push(documentFinding(document, DIAGNOSTIC_IDS.QUAL_SHORT_DESCRIPTION, "Skill description is too short for routing clarity", "quality", "low", `Expand frontmatter description to at least ${DESCRIPTION_MIN_CHARS} characters with usage routing guidance.`));
     }
     const reusableContextFinding = reusableContextCandidateFinding(document, tokenCount);
     if (reusableContextFinding)
         findings.push(reusableContextFinding);
     if (document.artifact.kind === "skill" && tokenCount > SKILL_TOKEN_LIMIT) {
-        findings.push(documentFinding(document, "QUAL-SKILL-TOKEN-BUDGET", "Skill entrypoint exceeds token budget", "quality", "medium", `Keep SKILL.md under about ${SKILL_TOKEN_LIMIT} tokens as a compact usage guide. Move detailed procedures into reference files, but preserve them losslessly in ordered parts when needed. Do not delete, summarize, or merge away procedural steps. SKILL.md should reference every required support file or index without embedding the full procedure.`, {
+        findings.push(documentFinding(document, DIAGNOSTIC_IDS.QUAL_SKILL_TOKEN_BUDGET, "Skill entrypoint exceeds token budget", "quality", "medium", `Keep SKILL.md under about ${SKILL_TOKEN_LIMIT} tokens as a compact usage guide. Move detailed procedures into reference files, but preserve them losslessly in ordered parts when needed. Do not delete, summarize, or merge away procedural steps. SKILL.md should reference every required support file or index without embedding the full procedure.`, {
             whyItMatters: "Large skills can mix LLM-facing usage guidance with reusable domain knowledge. Skills should remain concise routing contracts and usage guides, while reusable QA heuristics, domain rules, and tool guidance live in independently owned shared context assets.",
             constraints: [
                 "Do not introduce runtime context resolution.",
@@ -454,23 +530,23 @@ function shapeFindings(document) {
     }
     if (document.artifact.kind === "skill" &&
         USER_LOCAL_PATH_PATTERN.test(text)) {
-        findings.push(documentFinding(document, "QUAL-USER-LOCAL-PATHS", "Skill uses hardcoded user home paths in instructions", "quality", "medium", "Use repo-relative or environment-agnostic paths in skill instructions. If a local path is unavoidable, parameterize it and avoid hardcoding a user-specific home directory such as `/Users/alice/...` or `/home/alice/...`."));
+        findings.push(documentFinding(document, DIAGNOSTIC_IDS.QUAL_USER_LOCAL_PATHS, "Skill uses hardcoded user home paths in instructions", "quality", "medium", "Use repo-relative or environment-agnostic paths in skill instructions. If a local path is unavoidable, parameterize it and avoid hardcoding a user-specific home directory such as `/Users/alice/...` or `/home/alice/...`."));
     }
     if (!/do not use for|non-goals|out of scope/.test(text)) {
-        findings.push(documentFinding(document, "QUAL-MISSING-NEGATIVE-ROUTING", "Skill lacks negative routing guidance", "structure", "medium", "Add a DO NOT USE FOR or non-goals section so agents know when to choose another path."));
+        findings.push(documentFinding(document, DIAGNOSTIC_IDS.QUAL_MISSING_NEGATIVE_ROUTING, "Skill lacks negative routing guidance", "structure", "medium", "Add a DO NOT USE FOR or non-goals section so agents know when to choose another path."));
     }
     if (!/use this skill|when to use|trigger|routing|context route|mixin/.test(text)) {
-        findings.push(documentFinding(document, "QUAL-MISSING-ROUTING-CLARITY", "Skill lacks routing clarity", "quality", "low", "Add concise routing language: when to use the skill, whether it invokes other skills, or whether it is a utility skill for single operations."));
+        findings.push(documentFinding(document, DIAGNOSTIC_IDS.QUAL_MISSING_ROUTING_CLARITY, "Skill lacks routing clarity", "quality", "low", "Add concise routing language: when to use the skill, whether it invokes other skills, or whether it is a utility skill for single operations."));
     }
     if (!/example|input|output/.test(text)) {
-        findings.push(documentFinding(document, "QUAL-MISSING-EXAMPLES", "Skill lacks examples", "quality", "low", "Add examples that show representative inputs, outputs, or behavior."));
+        findings.push(documentFinding(document, DIAGNOSTIC_IDS.QUAL_MISSING_EXAMPLES, "Skill lacks examples", "quality", "low", "Add examples that show representative inputs, outputs, or behavior."));
     }
     if (!/preflight|before you begin|first check|prerequisite|context/.test(text)) {
-        findings.push(documentFinding(document, "QUAL-MISSING-PREFLIGHT", "Skill lacks a preflight step", "quality", "medium", "Add a preflight section that captures environment, permissions, target files, and assumptions before acting."));
+        findings.push(documentFinding(document, DIAGNOSTIC_IDS.QUAL_MISSING_PREFLIGHT, "Skill lacks a preflight step", "quality", "medium", "Add a preflight section that captures environment, permissions, target files, and assumptions before acting."));
     }
     if (document.artifact.kind === "skill" &&
         !REQUIRED_INPUTS_PATTERN.test(text)) {
-        findings.push(documentFinding(document, "QUAL-MISSING-REQUIRED-INPUTS", "Skill does not state required inputs", "quality", "medium", "Add a Required inputs or Prerequisites section that states the user-provided inputs, target files, repository state, permissions, credentials, or environment assumptions needed before the workflow can start.", {
+        findings.push(documentFinding(document, DIAGNOSTIC_IDS.QUAL_MISSING_REQUIRED_INPUTS, "Skill does not state required inputs", "quality", "medium", "Add a Required inputs or Prerequisites section that states the user-provided inputs, target files, repository state, permissions, credentials, or environment assumptions needed before the workflow can start.", {
             whyItMatters: "Agents need explicit input requirements before starting a workflow. Missing required inputs can cause the agent to guess targets, assume permissions, or start without enough repository context.",
             constraints: [
                 "Do not infer runtime context.",
@@ -489,7 +565,7 @@ function shapeFindings(document) {
     }
     if (document.artifact.kind === "skill" &&
         !COMPLETION_CRITERIA_PATTERN.test(text)) {
-        findings.push(documentFinding(document, "QUAL-MISSING-COMPLETION-CRITERIA", "Skill does not state completion criteria", "quality", "medium", "Add a Completion criteria, Success requirements, Deliverables, or Final response section that states the observable outputs or conditions that mean the workflow is complete.", {
+        findings.push(documentFinding(document, DIAGNOSTIC_IDS.QUAL_MISSING_COMPLETION_CRITERIA, "Skill does not state completion criteria", "quality", "medium", "Add a Completion criteria, Success requirements, Deliverables, or Final response section that states the observable outputs or conditions that mean the workflow is complete.", {
             whyItMatters: "Agents need explicit completion criteria before finishing a workflow. Missing completion criteria can cause incomplete delivery, unnecessary follow-up work, or inconsistent final responses.",
             constraints: [
                 "Do not infer runtime context.",
@@ -507,11 +583,11 @@ function shapeFindings(document) {
         }));
     }
     if (!/verify|validation|test|confirm result|expected output/.test(text)) {
-        findings.push(documentFinding(document, "QUAL-MISSING-VERIFICATION", "Skill lacks verification guidance", "quality", "medium", "State how to verify success with a command, check, or observable result."));
+        findings.push(documentFinding(document, DIAGNOSTIC_IDS.QUAL_MISSING_VERIFICATION, "Skill lacks verification guidance", "quality", "medium", "State how to verify success with a command, check, or observable result."));
     }
     if (document.headings.length < 2 &&
         document.artifact.content.split(/\s+/).length > 120) {
-        findings.push(documentFinding(document, "QUAL-LOW-HEADING-DENSITY", "Long instruction file has few headings", "structure", "low", "Split long prose into task-oriented headings so agents can navigate it reliably."));
+        findings.push(documentFinding(document, DIAGNOSTIC_IDS.QUAL_LOW_HEADING_DENSITY, "Long instruction file has few headings", "structure", "low", "Split long prose into task-oriented headings so agents can navigate it reliably."));
     }
     return findings;
 }
@@ -561,7 +637,7 @@ function reusableContextCandidateFinding(document, tokenCount) {
             : undefined,
     ].filter((part) => Boolean(part));
     return {
-        id: "MAINT-SKILL-REUSABLE-CONTEXT-CANDIDATE",
+        id: DIAGNOSTIC_IDS.MAINT_SKILL_REUSABLE_CONTEXT_CANDIDATE,
         title: "Skill may contain reusable context worth extracting",
         category: "maintenance",
         severity: "low",
@@ -647,7 +723,7 @@ function supportSharedContextCandidateFindings(document) {
     ].join("\n");
     return [
         {
-            id: "MAINT-SUPPORT-ASSET-SHARED-CONTEXT-CANDIDATE",
+            id: DIAGNOSTIC_IDS.MAINT_SUPPORT_ASSET_SHARED_CONTEXT_CANDIDATE,
             title: "Skill-local support file may be a shared context candidate",
             category: "maintenance",
             severity: "low",
@@ -688,7 +764,7 @@ function contextPathNonSemanticFindings(document) {
         return [];
     return [
         {
-            id: "MAINT-CONTEXT-PATH-NON-SEMANTIC",
+            id: DIAGNOSTIC_IDS.MAINT_CONTEXT_PATH_NON_SEMANTIC,
             title: "Context asset path appears process-oriented rather than semantic",
             category: "maintenance",
             severity: "low",
@@ -736,7 +812,7 @@ function skillContextReferenceNotDeclaredFindings(document) {
     return [...matches.entries()]
         .filter(([referencedPath]) => !declaredContexts.has(referencedPath))
         .map(([referencedPath, match]) => ({
-        id: "MAINT-SKILL-CONTEXT-REFERENCE-NOT-DECLARED",
+        id: DIAGNOSTIC_IDS.MAINT_SKILL_CONTEXT_REFERENCE_NOT_DECLARED,
         title: "Skill references a shared context without declaring it",
         category: "maintenance",
         severity: "low",
@@ -793,7 +869,7 @@ function skillReferencesSupersededAssetFindings(documents) {
         ].join("\n");
         return [
             {
-                id: "MAINT-SKILL-REFERENCES-SUPERSEDED-ASSET",
+                id: DIAGNOSTIC_IDS.MAINT_SKILL_REFERENCES_SUPERSEDED_ASSET,
                 title: "Skill references a superseded local support asset",
                 category: "maintenance",
                 severity: "low",
@@ -881,7 +957,7 @@ function assetReferencesSupersededAssetFindings(documents) {
             ].join("\n");
             return [
                 {
-                    id: "MAINT-ASSET-REFERENCES-SUPERSEDED-ASSET",
+                    id: DIAGNOSTIC_IDS.MAINT_ASSET_REFERENCES_SUPERSEDED_ASSET,
                     title: "Asset references a superseded support file",
                     category: "maintenance",
                     severity: "low",
@@ -951,7 +1027,7 @@ function contextBudgetFindings(document) {
     if (tokenCount <= limit)
         return [];
     return [
-        documentFinding(document, "QUAL-SUPPORT-ASSET-TOKEN-BUDGET", "Support asset exceeds token guidance", "quality", "low", `Keep ${document.artifact.kind} assets under about ${limit} tokens where practical. If a file is too large, run \`renma suggest-semantic-split ${document.artifact.path}\` to get a semantic split proposal, then split it losslessly into meaning-based ordered part files. Do not delete, summarize, or merge away procedural steps. The parent file or SKILL.md should reference every part in order, and the split should preserve the original procedure text exactly. Verify by reconstructing the parts and comparing them to the original content before accepting the fix.`, {
+        documentFinding(document, DIAGNOSTIC_IDS.QUAL_SUPPORT_ASSET_TOKEN_BUDGET, "Support asset exceeds token guidance", "quality", "low", `Keep ${document.artifact.kind} assets under about ${limit} tokens where practical. If a file is too large, run \`renma suggest-semantic-split ${document.artifact.path}\` to get a semantic split proposal, then split it losslessly into meaning-based ordered part files. Do not delete, summarize, or merge away procedural steps. The parent file or SKILL.md should reference every part in order, and the split should preserve the original procedure text exactly. Verify by reconstructing the parts and comparing them to the original content before accepting the fix.`, {
             whyItMatters: "Oversized support assets are harder for humans and LLM coding agents to review safely. Shared context and local support files should stay modular enough that ownership, scope, and static references remain clear.",
             constraints: [
                 "Do not introduce runtime context resolution.",
@@ -975,7 +1051,7 @@ function profileFindings(document) {
     if (/base[_ -]?skill|extends/.test(text))
         return [];
     return [
-        documentFinding(document, "PROF-MISSING-BASE", "Profile overlay does not declare its base skill", "structure", "medium", "Declare the base skill or compatibility target so routing conflicts are auditable."),
+        documentFinding(document, DIAGNOSTIC_IDS.PROF_MISSING_BASE, "Profile overlay does not declare its base skill", "structure", "medium", "Declare the base skill or compatibility target so routing conflicts are auditable."),
     ];
 }
 function skillLocalSupportReachabilityFindings(documents) {
@@ -990,7 +1066,7 @@ function skillLocalSupportReachabilityFindings(documents) {
         const text = skill.artifact.content.toLowerCase();
         const hasLocalSupportGuidance = /support file|local support|context route|context map|mixin|profiles?\/|references?\/|examples?\/|load .*?(?:profile|reference|example)|reference .*?(?:profile|reference|example)/.test(text);
         if (!hasLocalSupportGuidance) {
-            findings.push(documentFinding(skill, "SUPPORT-MISSING-REACHABILITY-GUIDANCE", "Skill has local support files but no reachability guidance", "structure", "medium", "Add local support file reachability guidance so the top-level skill declares when profiles, references, examples, or scripts are reachable. If support content was split into ordered parts, reference the index or all parts in order. Preserve original concrete steps. Do not delete, summarize, or merge away procedural steps.", {
+            findings.push(documentFinding(skill, DIAGNOSTIC_IDS.SUPPORT_MISSING_REACHABILITY_GUIDANCE, "Skill has local support files but no reachability guidance", "structure", "medium", "Add local support file reachability guidance so the top-level skill declares when profiles, references, examples, or scripts are reachable. If support content was split into ordered parts, reference the index or all parts in order. Preserve original concrete steps. Do not delete, summarize, or merge away procedural steps.", {
                 whyItMatters: "Local support files should be statically discoverable from the skill so humans and LLM coding agents can tell which repository evidence belongs to the skill without relying on runtime context selection.",
                 constraints: [
                     "Do not introduce runtime context resolution.",
@@ -1117,7 +1193,7 @@ function disallowedSkillAssetFindings(document, config) {
     const [, skillName = "", assetRoot = "", rest = ""] = match;
     const target = canonicalSkillAssetTarget(config, skillName, assetRoot, rest);
     return [
-        documentFinding(document, "LAYOUT-DISALLOWED-SKILL-ASSET", `Disallowed skill-local ${assetRoot} asset`, "structure", assetRoot === "scripts" ? "medium" : "low", `Move this file to \`${target}\` and update every repo-local reference to the new canonical path.`, {
+        documentFinding(document, DIAGNOSTIC_IDS.LAYOUT_DISALLOWED_SKILL_ASSET, `Disallowed skill-local ${assetRoot} asset`, "structure", assetRoot === "scripts" ? "medium" : "low", `Move this file to \`${target}\` and update every repo-local reference to the new canonical path.`, {
             whyItMatters: "Strict layout keeps skills as thin entrypoints, shared context under contexts/, and executable helpers under tools/ so agents can migrate repositories deterministically.",
             verificationSteps: [
                 `Move ${document.artifact.path} to ${target}.`,
@@ -1147,7 +1223,7 @@ function thinSkillLayoutFindings(document) {
     ];
     if (wordCount > 450 ||
         procedureSignals.some((pattern) => pattern.test(document.artifact.content))) {
-        findings.push(documentFinding(document, "LAYOUT-SKILL-NOT-THIN", "Skill entrypoint contains procedure content", "structure", wordCount > 700 ? "medium" : "low", "Move reusable procedure content into contexts/** and keep SKILL.md as a concise router that points to the required context assets.", {
+        findings.push(documentFinding(document, DIAGNOSTIC_IDS.LAYOUT_SKILL_NOT_THIN, "Skill entrypoint contains procedure content", "structure", wordCount > 700 ? "medium" : "low", "Move reusable procedure content into contexts/** and keep SKILL.md as a concise router that points to the required context assets.", {
             whyItMatters: "Strict layout expects skills/*/SKILL.md to route agents, not own canonical references, profiles, examples, scripts, or detailed procedures.",
             verificationSteps: [
                 "Confirm SKILL.md contains routing guidance and required context references only.",
@@ -1158,7 +1234,7 @@ function thinSkillLayoutFindings(document) {
     }
     const command = firstExecutableCommand(document);
     if (command) {
-        findings.push(findingAt(document, "LAYOUT-SKILL-EXECUTABLE-COMMAND", "Skill entrypoint contains executable command", "structure", "low", command.line, command.command, "Move executable setup commands into contexts/** procedures or tools/** helper documentation, and keep SKILL.md as a router.", {
+        findings.push(findingAt(document, DIAGNOSTIC_IDS.LAYOUT_SKILL_EXECUTABLE_COMMAND, "Skill entrypoint contains executable command", "structure", "low", command.line, command.command, "Move executable setup commands into contexts/** procedures or tools/** helper documentation, and keep SKILL.md as a router.", {
             whyItMatters: "Executable setup commands in SKILL.md make the entrypoint procedural and harder to migrate to the strict three-root layout.",
             verificationSteps: [
                 "Move the command guidance to a context/reference/procedure.",
@@ -1175,7 +1251,7 @@ function helperCommandFindings(document, root, paths, config) {
         if (!scriptPath)
             continue;
         if (/^skills\/[^/]+\/scripts\//.test(scriptPath)) {
-            findings.push(findingAt(document, "PATH-HELPER-COMMAND-SKILL-SCRIPTS", "Helper command points to skill-local scripts", "structure", "medium", command.line, command.command, `Move the helper script to \`${canonicalHelperTarget(config, scriptPath)}\` and update this command to use the tools/** path.`, {
+            findings.push(findingAt(document, DIAGNOSTIC_IDS.PATH_HELPER_COMMAND_SKILL_SCRIPTS, "Helper command points to skill-local scripts", "structure", "medium", command.line, command.command, `Move the helper script to \`${canonicalHelperTarget(config, scriptPath)}\` and update this command to use the tools/** path.`, {
                 whyItMatters: "Strict layout keeps executable helper assets under tools/**, not under skills/**.",
                 verificationSteps: [
                     `Confirm ${canonicalHelperTarget(config, scriptPath)} exists.`,
@@ -1185,7 +1261,7 @@ function helperCommandFindings(document, root, paths, config) {
             continue;
         }
         if (scriptPath.includes("/scripts/") && !scriptPath.startsWith("tools/")) {
-            findings.push(findingAt(document, "PATH-HELPER-COMMAND-NON_TOOLS", "Helper command does not use tools root", "structure", "low", command.line, command.command, "Update helper script commands to reference scripts under tools/**.", {
+            findings.push(findingAt(document, DIAGNOSTIC_IDS.PATH_HELPER_COMMAND_NON_TOOLS, "Helper command does not use tools root", "structure", "low", command.line, command.command, "Update helper script commands to reference scripts under tools/**.", {
                 whyItMatters: "Helper commands should resolve to non-context helper assets in tools/** so contexts remain LLM-readable guidance.",
             }));
             continue;
@@ -1193,7 +1269,7 @@ function helperCommandFindings(document, root, paths, config) {
         if (scriptPath.startsWith("tools/") &&
             !paths.has(scriptPath) &&
             !(root && existsSync(path.join(root, scriptPath)))) {
-            findings.push(findingAt(document, "PATH-HELPER-COMMAND-UNRESOLVED", "Helper command target does not resolve", "structure", "medium", command.line, command.command, `Create \`${scriptPath}\` or update this command to the correct tools/** helper path.`, {
+            findings.push(findingAt(document, DIAGNOSTIC_IDS.PATH_HELPER_COMMAND_UNRESOLVED, "Helper command target does not resolve", "structure", "medium", command.line, command.command, `Create \`${scriptPath}\` or update this command to the correct tools/** helper path.`, {
                 whyItMatters: "Agents need helper commands in markdown procedures to resolve deterministically before running them.",
             }));
         }
@@ -1229,7 +1305,7 @@ function layoutConsistencyFindings(document) {
         if (!match)
             continue;
         const line = lineForOffset(text, match.index ?? 0);
-        findings.push(findingAt(document, "DOCS-LAYOUT-INCONSISTENT", "Repository docs describe a non-canonical layout", "maintenance", "low", line, lineText(document, line), stale.message, {
+        findings.push(findingAt(document, DIAGNOSTIC_IDS.DOCS_LAYOUT_INCONSISTENT, "Repository docs describe a non-canonical layout", "maintenance", "low", line, lineText(document, line), stale.message, {
             whyItMatters: "README.md and AGENTS.md should teach agents the same strict three-root layout that Renma enforces.",
             verificationSteps: [
                 "Update README.md and AGENTS.md to mention skills/, contexts/, and tools/ canonical roots.",
@@ -1242,7 +1318,7 @@ function layoutConsistencyFindings(document) {
 function contextRootFindings(document) {
     if (document.artifact.path.startsWith("context/")) {
         return [
-            documentFinding(document, "LAYOUT-CONTEXT-LEGACY-ROOT", "Context asset uses legacy context/ root", "structure", "low", "Move canonical LLM-readable context assets under contexts/**.", {
+            documentFinding(document, DIAGNOSTIC_IDS.LAYOUT_CONTEXT_LEGACY_ROOT, "Context asset uses legacy context/ root", "structure", "low", "Move canonical LLM-readable context assets under contexts/**.", {
                 whyItMatters: "The strict repository layout uses contexts/**/*.md as canonical LLM-readable context assets.",
             }),
         ];
@@ -1253,7 +1329,7 @@ function helperRootFindings(document) {
     if (document.artifact.path.includes("/scripts/") &&
         !document.artifact.path.startsWith("tools/")) {
         return [
-            documentFinding(document, "LAYOUT-HELPER-NON_TOOLS", "Helper script is outside tools root", "structure", "medium", "Move non-context helper assets under tools/** and update command references.", {
+            documentFinding(document, DIAGNOSTIC_IDS.LAYOUT_HELPER_NON_TOOLS, "Helper script is outside tools root", "structure", "medium", "Move non-context helper assets under tools/** and update command references.", {
                 whyItMatters: "The strict repository layout reserves tools/** for executable and non-context helper assets.",
             }),
         ];
@@ -1278,7 +1354,7 @@ function declaredDependencyLayoutFindings(catalog, paths, root) {
         if (!source)
             continue;
         findings.push({
-            id: "LAYOUT-CONTEXT-REFERENCE-NON_CANONICAL",
+            id: DIAGNOSTIC_IDS.LAYOUT_CONTEXT_REFERENCE_NON_CANONICAL,
             title: "Declared context path is not under canonical roots",
             category: "structure",
             severity: "low",
@@ -1401,10 +1477,10 @@ function evidence(document, line, snippet) {
 }
 function localSupportUnreachableRuleId(kind) {
     if (kind === "profile")
-        return "SUPPORT-UNREACHABLE-PROFILE";
+        return DIAGNOSTIC_IDS.SUPPORT_UNREACHABLE_PROFILE;
     if (kind === "example")
-        return "SUPPORT-UNREACHABLE-EXAMPLE";
-    return "SUPPORT-UNREACHABLE-REFERENCE";
+        return DIAGNOSTIC_IDS.SUPPORT_UNREACHABLE_EXAMPLE;
+    return DIAGNOSTIC_IDS.SUPPORT_UNREACHABLE_REFERENCE;
 }
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");