renma 0.17.0 → 0.18.1

package/dist/rules.js

@@ -2,96 +2,52 @@ import path from "node:path";
 import { resolvedAgentSkillDescription } from "./agent-skills.js";
 import { addDaysIsoDate, isIsoDate, parseDayDuration, todayIsoDate, } from "./freshness.js";
 import { DIAGNOSTIC_IDS } from "./diagnostic-ids.js";
-import { classifyRepositorySkillEntrypointPath, classifyRepositorySkillPath, normalizeRepositoryRelativePath, } from "./discovery.js";
+import { classifyRepositorySkillEntrypointPath, classifyRepositorySkillPath, logicalSkillDirectory, normalizeRepositoryRelativePath, } from "./discovery.js";
 import { helperScriptPath, resolveHelperScriptPath, } from "./repository-paths.js";
 import { parseAssetMetadata } from "./metadata.js";
 import { runRuleRegistry } from "./rule-engine.js";
+import { DEFAULT_QUALITY_PROFILE } from "./quality-profile.js";
+import { estimateTokens, markdownBody } from "./token-estimator.js";
+import { staticSupportReferences } from "./static-support.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-----/;
 const REMOTE_PATTERN = /\b(?:curl|wget)\b.*(?:\|\s*(?:sh|bash)|\b(?:example\.com|prod|production|--insecure|-k)\b)|\b(?:ssh|scp)\b.*\b(?:example\.com|prod|production|root@|--insecure|-k|StrictHostKeyChecking=no|UserKnownHostsFile=\/dev\/null)\b/i;
 const ENV_COPY_PATTERN = /\b(?:process\.env|env)\b.*\b(?:spawn|exec|execFile|system|subprocess|child_process)\b|\b(?:spawn|exec|execFile|system|subprocess|child_process)\b.*\b(?:process\.env|env)\b/i;
 const USER_LOCAL_PATH_PATTERN = /(?:^|[^a-z0-9_])(?:\/Users\/[^\s/\\]+|\/home\/[^\s/\\]+|[A-Za-z]:\\Users\\[^\s\\]+)(?:\/|$)/iu;
-const SKILL_TOKEN_LIMIT = 500;
-const DESCRIPTION_MIN_CHARS = 150;
-const REUSABLE_CONTEXT_MIN_LINES = 24;
-const REUSABLE_CONTEXT_MIN_TOKENS = 180;
+const QUALITY = DEFAULT_QUALITY_PROFILE;
+const MAX_LOCAL_SUPPORT_REFERENCE_HOPS = QUALITY.agentSkills.recommendedReferenceDepth + 1;
 const REQUIRED_INPUTS_PATTERN = /\b(?:required inputs?|inputs|input requirements?|required information|prerequisites?|required context|required files|required permissions?|permission requirements?|environment requirements?|before running,\s*provide|before you begin,\s*provide|the user must provide|needs the following|target files|permissions required|environment required)\b|\brequires:/;
 const COMPLETION_CRITERIA_PATTERN = /\b(?:completion criteria|completion checklist|success criteria|success requirements|done criteria|done when|definition of done|acceptance criteria|deliverables?|final response|final answer|expected outcomes?|expected results?|expected output|required output|output requirements?|report should include|patch should include|when complete|workflow is complete|the workflow is complete after|task is complete|counts as complete|completion requirements?|stop when|do not finish until)\b/;
-const REUSABLE_CONTEXT_MIN_SIGNALS = 3;
-const SUPPORT_SHARED_CONTEXT_MIN_LINES = 18;
-const SUPPORT_SHARED_CONTEXT_MIN_TOKENS = 140;
-const SUPPORT_SHARED_CONTEXT_MIN_HEADINGS = 2;
-const SUPPORT_SHARED_CONTEXT_MIN_PHRASES = 2;
 const REUSABLE_CONTEXT_HEADING_PATTERNS = [
-    [/\bsetup\b/i, "Setup"],
-    [/\binstallation\b/i, "Installation"],
-    [/\bconfiguration\b/i, "Configuration"],
-    [/\benvironment\b/i, "Environment"],
-    [/\bprerequisites?\b/i, "Prerequisites"],
-    [/\bplatform\b/i, "Platform"],
-    [/\btroubleshooting\b/i, "Troubleshooting"],
+    [/\bplatform facts?\b/i, "Platform Facts"],
+    [/\breusable troubleshooting\b/i, "Reusable Troubleshooting"],
     [/\bknown issues?\b/i, "Known Issues"],
-    [/\blimitations?\b/i, "Limitations"],
-    [/\bbest practices?\b/i, "Best Practices"],
-    [/\btesting heuristics?\b/i, "Testing Heuristics"],
-    [/\btest strategy\b/i, "Test Strategy"],
-    [/\bverification\b/i, "Verification"],
-    [/\bexamples?\b/i, "Examples"],
-    [/\bedge cases?\b/i, "Edge Cases"],
-    [/\brisks?\b/i, "Risks"],
     [/\bdomain rules?\b/i, "Domain Rules"],
-    [/\bfailure modes?\b/i, "Failure Modes"],
-    [/\bflaky tests?\b/i, "Flaky Tests"],
+    [/\bcompatibility (?:matrix|matrices)\b/i, "Compatibility Matrix"],
+    [/\bproduct polic(?:y|ies)\b/i, "Product Policy"],
+    [/\bshared testing heuristics?\b/i, "Shared Testing Heuristics"],
 ];
 const REUSABLE_CONTEXT_PHRASE_PATTERNS = [
-    [/\buse this when\b/i, "use this when"],
     [/\bknown issue\b/i, "known issue"],
-    [/\blimitation\b/i, "limitation"],
-    [/\btroubleshooting\b/i, "troubleshooting"],
-    [/\bflaky\b/i, "flaky"],
-    [/\bretry\b/i, "retry"],
+    [/\breusable troubleshooting\b/i, "reusable troubleshooting"],
     [/\bplatform-specific\b/i, "platform-specific"],
-    [/\bedge case\b/i, "edge case"],
-    [/\brisk\b/i, "risk"],
-    [/\bheuristic\b/i, "heuristic"],
-    [/\bbest practice\b/i, "best practice"],
-    [/\bdo not\b/i, "do not"],
-    [/\bavoid\b/i, "avoid"],
-    [/\balways\b/i, "always"],
-    [/\bnever\b/i, "never"],
+    [/\bsource of truth\b/i, "source of truth"],
+    [/\bused by (?:multiple|several) skills\b/i, "cross-Skill use"],
+    [/\bshared (?:rule|policy|heuristic|knowledge)\b/i, "shared knowledge"],
 ];
 const SUPPORT_SHARED_CONTEXT_HEADING_PATTERNS = [
     ...REUSABLE_CONTEXT_HEADING_PATTERNS,
-    [/\bdecision logic\b/i, "Decision Logic"],
-    [/\bsafety notes?\b/i, "Safety Notes"],
-    [/\bvalidation\b/i, "Validation"],
-    [/\boperating model\b/i, "Operating Model"],
     [/\bpolicy\b/i, "Policy"],
-    [/\bguidelines?\b/i, "Guidelines"],
-    [/\bprocedures?\b/i, "Procedure"],
-    [/\bchecklist\b/i, "Checklist"],
     [/\bcompatibility\b/i, "Compatibility"],
-    [/\bconstraints?\b/i, "Constraints"],
+    [/\bsource of truth\b/i, "Source of Truth"],
 ];
 const SUPPORT_SHARED_CONTEXT_PHRASE_PATTERNS = [
-    [/\bmust\b/i, "must"],
-    [/\bshould\b/i, "should"],
-    [/\balways\b/i, "always"],
-    [/\bnever\b/i, "never"],
-    [/\bavoid\b/i, "avoid"],
-    [/\bprefer\b/i, "prefer"],
-    [/\bdo not\b/i, "do not"],
-    [/\brequired\b/i, "required"],
-    [/\brecommended\b/i, "recommended"],
     [/\bknown issue\b/i, "known issue"],
-    [/\blimitation\b/i, "limitation"],
-    [/\bfailure mode\b/i, "failure mode"],
-    [/\btroubleshooting\b/i, "troubleshooting"],
-    [/\bedge case\b/i, "edge case"],
-    [/\brisk\b/i, "risk"],
-    [/\bbest practice\b/i, "best practice"],
-    [/\bvalidate\b/i, "validate"],
-    [/\bverify\b/i, "verify"],
+    [/\breusable troubleshooting\b/i, "reusable troubleshooting"],
+    [/\bsource of truth\b/i, "source of truth"],
+    [/\bused by (?:multiple|several) skills\b/i, "cross-Skill use"],
+    [/\bindependent (?:owner|ownership|lifecycle)\b/i, "independent ownership"],
+    [/\bshared (?:rule|policy|heuristic|knowledge)\b/i, "shared knowledge"],
 ];
 const NON_SEMANTIC_CONTEXT_PATH_SEGMENTS = new Set([
     "promoted",
@@ -114,15 +70,10 @@ const NON_SEMANTIC_CONTEXT_PATH_SEGMENTS = new Set([
     "candidate",
     "candidates",
 ]);
-const CONTEXT_TOKEN_LIMITS = {
-    context: 1200,
-    profile: 500,
-    reference: 800,
-    example: 800,
-};
+const CONTEXT_TOKEN_LIMITS = QUALITY.contentTokenWarn;
 /** Run all deterministic rules and return findings in stable source order. */
 export function runRules(documents, config, catalog, options = {}) {
-    const findings = runRuleRegistry(documents, rulesForEvaluationDate(evaluationDay(options.evaluationDate), options.repositoryPaths), catalog, config);
+    const findings = runRuleRegistry(documents, rulesForEvaluationDate(evaluationDay(options.evaluationDate), options.repositoryPaths, options.repositoryPathStates), catalog, config);
     return findings.sort((a, b) => {
         const byPath = a.evidence.path.localeCompare(b.evidence.path);
         if (byPath !== 0)
@@ -130,7 +81,7 @@ export function runRules(documents, config, catalog, options = {}) {
         return a.evidence.startLine - b.evidence.startLine;
     });
 }
-function rulesForEvaluationDate(evaluationDate, repositoryPaths) {
+function rulesForEvaluationDate(evaluationDate, repositoryPaths, repositoryPathStates) {
     return [
         {
             id: "strict-layout-policy",
@@ -153,7 +104,7 @@ function rulesForEvaluationDate(evaluationDate, repositoryPaths) {
         },
         {
             id: "skill-local-support-reachability",
-            run: ({ documents }) => skillLocalSupportReachabilityFindings(documents),
+            run: ({ documents }) => skillLocalSupportReachabilityFindings(documents, repositoryPaths, repositoryPathStates),
         },
         {
             id: "support-asset-shared-context-candidate",
@@ -646,33 +597,51 @@ function shapeFindings(document) {
     const description = document.artifact.kind === "skill"
         ? (resolvedAgentSkillDescription(document) ?? "")
         : (document.metadata.description ?? "");
-    const tokenCount = approximateTokenCount(document.artifact.content);
+    // Skill budgets measure only Markdown after frontmatter. Agent Skills loads
+    // metadata separately, and Renma applies independent metadata budgets.
+    const bodyTokenCount = estimateTokens(markdownBody(document.artifact.content));
     if (!description) {
         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, 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.`));
+        QUALITY.descriptionMinChars > 0 &&
+        description.length < QUALITY.descriptionMinChars) {
+        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 ${QUALITY.descriptionMinChars} characters with usage routing guidance.`));
     }
-    const reusableContextFinding = reusableContextCandidateFinding(document, tokenCount);
+    const reusableContextFinding = reusableContextCandidateFinding(document, bodyTokenCount);
     if (reusableContextFinding)
         findings.push(reusableContextFinding);
-    if (document.artifact.kind === "skill" && tokenCount > SKILL_TOKEN_LIMIT) {
-        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.",
+    if (document.artifact.kind === "skill" &&
+        bodyTokenCount > QUALITY.skillTokenWarn) {
+        const limit = bodyTokenCount > QUALITY.skillTokenStrongWarn
+            ? QUALITY.skillTokenStrongWarn
+            : QUALITY.skillTokenWarn;
+        const severity = bodyTokenCount > QUALITY.skillTokenStrongWarn ? "medium" : "low";
+        findings.push(documentFinding(document, DIAGNOSTIC_IDS.QUAL_SKILL_TOKEN_BUDGET, "Skill body exceeds advisory token budget", "quality", severity, "Review progressive disclosure without deleting workflow steps. Keep selection boundaries, read conditions, ordered workflow, constraints, and completion criteria in SKILL.md. Move Skill-specific conditional detail to references/, deterministic repeated implementation to scripts/, output material to assets/, and independently owned cross-Skill knowledge to contexts/.", {
+            whyItMatters: "Long Skill bodies can make activated workflows harder to navigate. Size is advisory evidence only; Agent Skills recommends staying under 5,000 tokens and Renma adds an earlier low review point at 2,000 estimated tokens.",
             constraints: [
                 "Do not introduce runtime context resolution.",
                 "Do not create prompt packages.",
                 "Do not make Renma responsible for selecting context.",
-                "Preserve the skill as an LLM-facing entrypoint / usage guide.",
-                "Give extracted context assets stable metadata such as id, owner, and status.",
+                "Preserve ordered workflow steps, constraints, and completion criteria.",
+                "Choose a destination by semantic ownership, not by size alone.",
             ],
             verificationSteps: [
                 "Run renma scan.",
                 "Run any project-specific validation checks that apply to this repository.",
-                "Confirm the skill is shorter and extracted knowledge is represented as shared context assets.",
+                "Confirm any moved material remains statically reachable and semantically owned by its destination.",
             ],
-            llmHint: "If this skill mixes reusable knowledge with usage guidance, split reusable knowledge into first-class context assets under contexts/ and update the skill metadata or text to reference them.",
+            llmHint: "Review the Skill for progressive disclosure. Keep core workflow in SKILL.md; use references/ for local detail, scripts/ for deterministic implementation, assets/ for output resources, and contexts/ only for independently owned shared knowledge.",
+            details: {
+                measured: bodyTokenCount,
+                limit,
+                unit: "estimated_tokens",
+                profile: QUALITY.profile,
+                measurement: "markdown_body_after_frontmatter",
+                source: limit === QUALITY.skillTokenStrongWarn
+                    ? "agent_skills_recommendation_and_renma_severity"
+                    : "renma_quality_policy",
+            },
         }));
     }
     if (document.artifact.kind === "skill" &&
@@ -732,17 +701,25 @@ function shapeFindings(document) {
     if (!/verify|validation|test|confirm result|expected output/.test(text)) {
         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, 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."));
+    if (document.headings.length < QUALITY.lowHeadingDensityMinHeadings &&
+        bodyTokenCount >= QUALITY.lowHeadingDensityMinTokens) {
+        findings.push(documentFinding(document, DIAGNOSTIC_IDS.QUAL_LOW_HEADING_DENSITY, "Long instruction file has few headings", "structure", "low", "Add task-oriented headings so agents can navigate the body reliably.", {
+            details: {
+                measured: bodyTokenCount,
+                limit: QUALITY.lowHeadingDensityMinTokens,
+                unit: "estimated_tokens",
+                profile: QUALITY.profile,
+                measurement: "markdown_body_after_frontmatter",
+            },
+        }));
     }
     return findings;
 }
-function reusableContextCandidateFinding(document, tokenCount) {
+function reusableContextCandidateFinding(document, estimatedTokens) {
     if (document.artifact.kind !== "skill")
         return undefined;
-    if (document.lines.length < REUSABLE_CONTEXT_MIN_LINES &&
-        tokenCount < REUSABLE_CONTEXT_MIN_TOKENS)
+    if (document.lines.length < QUALITY.reusableContextCandidate.minLines &&
+        estimatedTokens < QUALITY.reusableContextCandidate.minTokens)
         return undefined;
     const headingMatches = document.headings.flatMap((heading) => REUSABLE_CONTEXT_HEADING_PATTERNS.filter(([pattern]) => pattern.test(heading.text)).map(([, label]) => ({
         label,
@@ -766,7 +743,10 @@ function reusableContextCandidateFinding(document, tokenCount) {
     ];
     const phraseLabels = [...new Set(phraseMatches.map((match) => match.label))];
     const signalCount = new Set([...headingLabels, ...phraseLabels]).size;
-    if (signalCount < REUSABLE_CONTEXT_MIN_SIGNALS)
+    // All patterns above are reusable-knowledge evidence. Ordinary workflow
+    // headings such as Verification, Examples, Steps, Risks, and Constraints are
+    // intentionally excluded and cannot qualify a Skill by themselves.
+    if (signalCount < QUALITY.reusableContextCandidate.minSignals)
         return undefined;
     const evidenceLine = headingMatches[0]?.line ??
         phraseMatches[0]?.line ??
@@ -784,26 +764,37 @@ function reusableContextCandidateFinding(document, tokenCount) {
             : undefined,
     ].filter((part) => Boolean(part));
     return {
-        id: DIAGNOSTIC_IDS.MAINT_SKILL_REUSABLE_CONTEXT_CANDIDATE,
-        title: "Skill may contain reusable context worth extracting",
+        id: DIAGNOSTIC_IDS.QUAL_SKILL_MIXED_RESPONSIBILITY,
+        title: "Skill may mix its workflow with reusable knowledge",
         category: "maintenance",
         severity: "low",
         confidence: "medium",
         evidence: evidence(document, evidenceLine, evidenceParts.join("; ")),
         whyItMatters: "Reusable setup notes, troubleshooting, platform guidance, testing heuristics, or domain rules are easier to own, review, and reuse when they live in shared context assets instead of only inside one skill.",
-        remediation: "Review the matched headings and phrases. If they describe reusable knowledge, extract that knowledge into first-class shared context assets under contexts/ and keep SKILL.md as a concise LLM-facing usage guide.",
+        remediation: "Review the matched headings and phrases. Promote content to contexts/ only when it needs cross-Skill reuse, independent ownership, lifecycle, or source-of-truth status; otherwise keep Skill-specific detail in SKILL.md or references/.",
         constraints: [
             "Do not make Renma select runtime context.",
             "Do not assemble prompt packages.",
             "Do not automatically rewrite or split skills.",
-            "Preserve SKILL.md as the routing contract / usage guide.",
+            "Preserve SKILL.md as a focused workflow entrypoint.",
             "Give extracted context assets stable metadata such as id, owner, and status.",
         ],
         verificationSteps: [
             "Run renma scan.",
             "Confirm the advisory is resolved or intentionally accepted after reusable knowledge is represented as shared context assets.",
         ],
-        llmHint: "Look for reusable setup, troubleshooting, platform, testing, or domain guidance in this skill. If reusable, move it into owned contexts/ assets and update the skill to reference those assets without adding runtime context selection.",
+        llmHint: "Check whether the matched knowledge is used across Skills or needs independent ownership. Use contexts/ only for shared knowledge; keep Skill-local procedures and edge cases in SKILL.md or references/.",
+        details: {
+            measured: estimatedTokens,
+            limit: QUALITY.reusableContextCandidate.minTokens,
+            unit: "estimated_tokens",
+            lines: document.lines.length,
+            minLines: QUALITY.reusableContextCandidate.minLines,
+            distinctSignals: signalCount,
+            minSignals: QUALITY.reusableContextCandidate.minSignals,
+            profile: QUALITY.profile,
+            measurement: "markdown_body_after_frontmatter",
+        },
     };
 }
 function supportSharedContextCandidateFindings(document) {
@@ -815,9 +806,9 @@ function supportSharedContextCandidateFindings(document) {
         !document.artifact.path.endsWith(".md")) {
         return [];
     }
-    const tokenCount = approximateTokenCount(document.artifact.content);
-    if (document.lines.length < SUPPORT_SHARED_CONTEXT_MIN_LINES &&
-        tokenCount < SUPPORT_SHARED_CONTEXT_MIN_TOKENS) {
+    const estimatedTokens = estimateTokens(markdownBody(document.artifact.content));
+    if (document.lines.length < QUALITY.sharedSupportCandidate.minLines &&
+        estimatedTokens < QUALITY.sharedSupportCandidate.minTokens) {
         return [];
     }
     const contentLineIndexes = markdownBodyLineIndexes(document);
@@ -852,8 +843,10 @@ function supportSharedContextCandidateFindings(document) {
         ];
     });
     const sourceSignals = [...headingMatches, ...phraseMatches];
-    if (headingMatches.length < SUPPORT_SHARED_CONTEXT_MIN_HEADINGS ||
-        phraseMatches.length < SUPPORT_SHARED_CONTEXT_MIN_PHRASES) {
+    if (new Set(headingMatches.map((match) => match.label)).size <
+        QUALITY.sharedSupportCandidate.minHeadings ||
+        new Set(phraseMatches.map((match) => match.label)).size <
+            QUALITY.sharedSupportCandidate.minPhrases) {
         return [];
     }
     const evidenceMatches = sourceSignals
@@ -897,6 +890,19 @@ function supportSharedContextCandidateFindings(document) {
                 "Confirm reusable source-of-truth knowledge lives in contexts/ and skill-local references only contain local support guidance.",
             ],
             llmHint: "Search the repository for similar headings, filenames, repeated procedures, commands, constraints, or overlapping guidance. If this support file appears reusable, propose a first-class context asset under contexts/, move the reusable details without losing information, keep truly local notes in the skill directory, and update declared context references.",
+            details: {
+                measured: estimatedTokens,
+                limit: QUALITY.sharedSupportCandidate.minTokens,
+                unit: "estimated_tokens",
+                lines: document.lines.length,
+                minLines: QUALITY.sharedSupportCandidate.minLines,
+                headings: new Set(headingMatches.map((match) => match.label)).size,
+                minHeadings: QUALITY.sharedSupportCandidate.minHeadings,
+                phrases: new Set(phraseMatches.map((match) => match.label)).size,
+                minPhrases: QUALITY.sharedSupportCandidate.minPhrases,
+                profile: QUALITY.profile,
+                measurement: "full_file",
+            },
         },
     ];
 }
@@ -1085,7 +1091,9 @@ function parentSkillPath(referencePath) {
         : undefined;
 }
 function skillReferenceLine(skill, referencePath) {
-    const skillDir = path.posix.dirname(skill.artifact.path);
+    const skillDir = logicalSkillDirectory(skill.artifact.path);
+    if (!skillDir)
+        return undefined;
     const relativePath = path.posix.relative(skillDir, referencePath);
     const referencedTokens = [referencePath, relativePath];
     for (const index of markdownBodyLineIndexes(skill)) {
@@ -1207,27 +1215,81 @@ function contextBudgetFindings(document) {
         document.artifact.kind !== "example") {
         return [];
     }
-    const limit = CONTEXT_TOKEN_LIMITS[document.artifact.kind];
-    const tokenCount = approximateTokenCount(document.artifact.content);
-    if (tokenCount <= limit)
-        return [];
-    return [
-        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.",
+    const tokenBudget = parseAssetMetadata(document).tokenBudgetDecision;
+    const defaultLimit = tokenBudget.defaultLimit ?? CONTEXT_TOKEN_LIMITS[document.artifact.kind];
+    const estimatedTokens = tokenBudget.estimatedTokens ?? estimateTokens(document.artifact.content);
+    const effectiveLimit = tokenBudget.effectiveLimit ?? defaultLimit;
+    const overrideActive = tokenBudget.status === "active";
+    const findings = [];
+    if (tokenBudget.status === "invalid") {
+        const invalidFinding = documentFinding(document, DIAGNOSTIC_IDS.QUAL_INVALID_TOKEN_BUDGET_OVERRIDE, "Support asset has invalid token-budget override metadata", "quality", "low", "Correct or remove the malformed token-budget decision metadata. An override is valid only after a human decides the asset should remain intentionally coherent or ordered; do not add or increase an override merely to make diagnostics pass.", {
+            whyItMatters: "Token-budget overrides record a declared human decision. Malformed, ambiguous, incomplete, orphaned, or unnecessary metadata cannot safely replace the default advisory limit.",
             constraints: [
-                "Do not introduce runtime context resolution.",
-                "Do not create prompt packages.",
-                "Preserve concrete procedural steps losslessly.",
-                "Keep static references from the parent file or SKILL.md to every split part.",
-            ],
-            verificationSteps: [
-                "Run renma scan.",
-                "Run the repository-specific validation or test command, if one exists.",
-                "Confirm the finding is resolved or reduced and every split part remains reachable.",
+                "Do not automatically insert token-budget override metadata.",
+                "Do not treat the override as a general ignore mechanism.",
+                "Ask whether a meaningful split preserves coherence and execution order before proposing an override.",
             ],
-            llmHint: "Split oversized support content into meaning-based ordered part files, keep the original procedure text intact, and update static references so Renma can validate reachability.",
-        }),
-    ];
+            verificationSteps: ["Run renma scan."],
+            llmHint: "Report the invalid fields to the user. First ask whether the asset can be split along meaningful boundaries without harming coherence or execution order. Only if the user confirms it should remain long should you repair explicit override metadata with their rationale.",
+            details: {
+                estimatedTokens,
+                defaultLimit,
+                ...(tokenBudget.overrideLimit !== undefined
+                    ? { overrideLimit: tokenBudget.overrideLimit }
+                    : {}),
+                effectiveLimit,
+                overrideActive,
+                ...(tokenBudget.tokenBudgetRationale
+                    ? { tokenBudgetRationale: tokenBudget.tokenBudgetRationale }
+                    : {}),
+                invalidReasons: tokenBudget.invalidReasons,
+                profile: QUALITY.profile,
+                measurement: "full_file",
+            },
+        });
+        findings.push({
+            ...invalidFinding,
+            ...(tokenBudget.evidence ? { evidence: tokenBudget.evidence } : {}),
+        });
+    }
+    if (estimatedTokens <= effectiveLimit)
+        return findings;
+    findings.push(documentFinding(document, DIAGNOSTIC_IDS.QUAL_SUPPORT_ASSET_TOKEN_BUDGET, "Support asset exceeds token guidance", "quality", "low", `Ask the user whether this ${document.artifact.kind} asset can be split along meaningful boundaries without harming coherence or execution order. Split it only after the user agrees. If the user confirms it should remain intentionally long, they may record an explicit token-budget override and rationale; do not recommend an override merely to make this diagnostic pass.`, {
+        whyItMatters: "Large content assets deserve a low-advisory coherence review. A meaningful split is preferred when it preserves semantic boundaries, while an explicit override can record the user's declared decision for an intentionally coherent or ordered long-form asset.",
+        constraints: [
+            "Do not introduce runtime context resolution.",
+            "Do not create prompt packages.",
+            "Do not split based on size alone.",
+            "Require the user's decision before splitting or treating the asset as intentionally long.",
+            "Do not automatically add or increase token-budget override metadata.",
+            "Preserve concrete procedural steps losslessly if a semantic split is chosen.",
+            "Keep static references from the parent file or SKILL.md to every split part.",
+        ],
+        verificationSteps: [
+            "Run renma scan.",
+            "Run the repository-specific validation or test command, if one exists.",
+            "Confirm every agreed split part remains reachable, or that an intentional-long decision uses valid declared metadata.",
+        ],
+        llmHint: "Ask the user whether the asset can be split along meaningful boundaries without harming coherence or execution order. Split only with agreement. If the user confirms it must remain intentionally long, use their explicit rationale for a valid override; never add one only to silence the finding.",
+        details: {
+            estimatedTokens,
+            defaultLimit,
+            ...(tokenBudget.overrideLimit !== undefined
+                ? { overrideLimit: tokenBudget.overrideLimit }
+                : {}),
+            effectiveLimit,
+            overrideActive,
+            ...(tokenBudget.tokenBudgetRationale
+                ? { tokenBudgetRationale: tokenBudget.tokenBudgetRationale }
+                : {}),
+            measured: estimatedTokens,
+            limit: effectiveLimit,
+            unit: "estimated_tokens",
+            profile: QUALITY.profile,
+            measurement: "full_file",
+        },
+    }));
+    return findings;
 }
 function profileFindings(document) {
     if (document.artifact.kind !== "profile")
@@ -1239,19 +1301,31 @@ function profileFindings(document) {
         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) {
+function skillLocalSupportReachabilityFindings(documents, repositoryPaths, repositoryPathStates) {
     const skills = documents.filter((document) => document.artifact.kind === "skill");
     return skills.flatMap((skill) => {
-        const skillDir = path.posix.dirname(skill.artifact.path);
-        const localSupportDocs = documents.filter((document) => ["profile", "reference", "example"].includes(document.artifact.kind) &&
-            document.artifact.path.startsWith(`${skillDir}/`));
-        if (localSupportDocs.length === 0)
+        const skillDir = logicalSkillDirectory(skill.artifact.path);
+        if (!skillDir)
             return [];
+        const localSupportDocs = documents.filter((document) => {
+            if (!["profile", "reference", "example", "script", "asset"].includes(document.artifact.kind)) {
+                return false;
+            }
+            const classified = classifyRepositorySkillPath(document.artifact.path);
+            return (classified?.kind === "support" && classified.skillDirectory === skillDir);
+        });
+        const localSupportPaths = repositoryPaths
+            ? [...repositoryPaths].filter((candidate) => {
+                const classified = classifyRepositorySkillPath(candidate);
+                return (classified?.kind === "support" &&
+                    classified.skillDirectory === skillDir);
+            })
+            : localSupportDocs.map((document) => document.artifact.path);
         const findings = [];
         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, 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.", {
+        const hasLocalSupportGuidance = /support file|local support|context route|context map|mixin|profiles?\/|references?\/|examples?\/|scripts?\/|assets?\/|load .*?(?:profile|reference|example|script|asset)|(?:read|run|reference) .*?(?:profile|reference|example|script|asset)/.test(text);
+        if (localSupportDocs.length > 0 && !hasLocalSupportGuidance) {
+            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, scripts, or assets 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.",
@@ -1262,14 +1336,15 @@ function skillLocalSupportReachabilityFindings(documents) {
                 verificationSteps: [
                     "Run renma scan.",
                     "Run any project-specific validation checks that apply to this repository.",
-                    "Confirm each local profile, reference, or example is reachable from SKILL.md or from a referenced parent support file.",
+                    "Confirm each local profile, reference, example, script, or asset is reachable from SKILL.md or from a referenced parent support file.",
                 ],
-                llmHint: "Add concise reachability guidance in SKILL.md that references local profiles, references, examples, or ordered support indexes without adding runtime routing behavior.",
+                llmHint: "Add concise reachability guidance in SKILL.md that references local profiles, references, examples, scripts, assets, or ordered support indexes without adding runtime routing behavior.",
             }));
         }
-        const reachableLocalSupportPaths = reachableLocalSupportDocuments(skill, localSupportDocs);
+        const reachabilityDepth = localSupportReachabilityDepth(skill, skillDir, localSupportDocs, localSupportPaths);
         for (const document of localSupportDocs) {
-            if (!reachableLocalSupportPaths.has(document.artifact.path)) {
+            const depth = reachabilityDepth.get(document.artifact.path);
+            if (depth === undefined) {
                 findings.push(documentFinding(document, localSupportUnreachableRuleId(document.artifact.kind), "Local support file is not reachable from the skill", "structure", "low", "Reference this local support file from SKILL.md or from a referenced parent support file with clear reachability guidance. If this file is a split part, ensure the parent skill references the index or all ordered parts so preserved details remain reachable. Do not delete, summarize, or merge away procedural steps just to satisfy the check.", {
                     whyItMatters: "Unreachable local support files can drift outside review and be missed by humans or LLM coding agents. Reachability should be static repository evidence, not runtime context assembly.",
                     constraints: [
@@ -1286,36 +1361,126 @@ function skillLocalSupportReachabilityFindings(documents) {
                     llmHint: "Update SKILL.md or a referenced support index to mention this file by path, basename, or clear title so the static reachability graph can find it.",
                 }));
             }
+            else if (depth > MAX_LOCAL_SUPPORT_REFERENCE_HOPS) {
+                findings.push(documentFinding(document, DIAGNOSTIC_IDS.SUPPORT_DEEP_REFERENCE_CHAIN, "Skill-local resource is behind a deep reference chain", "structure", "low", "Reference this resource directly from SKILL.md or through one directly referenced index/reference. Agent Skills recommends shallow file-reference chains.", {
+                    details: {
+                        measured: depth,
+                        limit: MAX_LOCAL_SUPPORT_REFERENCE_HOPS,
+                        unit: "static_reference_hops",
+                        profile: QUALITY.profile,
+                    },
+                }));
+            }
+        }
+        const missingPathSources = [
+            skill,
+            ...localSupportDocs.filter((document) => (reachabilityDepth.get(document.artifact.path) ?? 99) <=
+                MAX_LOCAL_SUPPORT_REFERENCE_HOPS),
+        ];
+        const reportedMissingPaths = new Set();
+        const reportedSymlinkBoundaries = new Set();
+        for (const source of missingPathSources) {
+            for (const reference of localSupportPathReferences(source, skillDir, localSupportPaths)) {
+                if (reference.relative.startsWith("examples/") &&
+                    !path.posix.basename(reference.relative).includes(".")) {
+                    continue;
+                }
+                const symlinkBoundary = referencedSymlinkBoundary(reference.target, repositoryPathStates);
+                if (symlinkBoundary) {
+                    const key = `${source.artifact.path}:${symlinkBoundary}`;
+                    if (reportedSymlinkBoundaries.has(key))
+                        continue;
+                    reportedSymlinkBoundaries.add(key);
+                    findings.push(findingAt(source, DIAGNOSTIC_IDS.SUPPORT_SYMLINK_PATH, "Skill-local resource path is an unusable symbolic link", "structure", "medium", reference.line, reference.raw, `Replace ${reference.relative} with a regular repository file or directory; Renma never follows symbolic links.`, {
+                        details: {
+                            sourcePath: source.artifact.path,
+                            target: reference.target,
+                            state: "symlink",
+                            symlinkBoundary,
+                            profile: QUALITY.profile,
+                        },
+                    }));
+                    continue;
+                }
+                if (repositoryPathExists(repositoryPaths, reference.target, repositoryPathStates) ||
+                    repositoryPathExists(repositoryPaths, reference.relative, repositoryPathStates) ||
+                    reportedMissingPaths.has(`${source.artifact.path}:${reference.target}`))
+                    continue;
+                reportedMissingPaths.add(`${source.artifact.path}:${reference.target}`);
+                findings.push(findingAt(source, DIAGNOSTIC_IDS.SUPPORT_MISSING_PATH, "Skill-local resource path does not exist", "structure", "medium", reference.line, reference.raw, `Create ${reference.relative} under the Skill root or correct the relative path.`, {
+                    details: {
+                        target: reference.target,
+                        profile: QUALITY.profile,
+                    },
+                }));
+            }
         }
         return findings;
     });
 }
-function reachableLocalSupportDocuments(skill, localSupportDocs) {
-    const reachable = new Set();
+function repositoryPathExists(repositoryPaths, candidate, repositoryPathStates) {
+    const state = repositoryPathStates?.get(candidate);
+    if (state !== undefined)
+        return state !== "absent";
+    if (!repositoryPaths)
+        return false;
+    if (repositoryPaths.has(candidate))
+        return true;
+    const directoryPrefix = `${candidate.replace(/\/$/, "")}/`;
+    for (const filePath of repositoryPaths) {
+        if (filePath.startsWith(directoryPrefix))
+            return true;
+    }
+    return false;
+}
+function referencedSymlinkBoundary(candidate, repositoryPathStates) {
+    if (!repositoryPathStates)
+        return undefined;
+    const segments = candidate.split("/");
+    for (let length = 1; length <= segments.length; length += 1) {
+        const prefix = segments.slice(0, length).join("/");
+        if (repositoryPathStates.get(prefix) === "symlink")
+            return prefix;
+    }
+    return undefined;
+}
+function localSupportReachabilityDepth(skill, skillDirectory, localSupportDocs, candidatePaths) {
+    const reachable = new Map();
+    const references = new Map([skill, ...localSupportDocs].map((document) => [
+        document.artifact.path,
+        new Set(staticSupportReferences(document, skillDirectory, candidatePaths).map((reference) => reference.targetPath)),
+    ]));
     let changed = true;
     while (changed) {
         changed = false;
         for (const document of localSupportDocs) {
             if (reachable.has(document.artifact.path))
                 continue;
-            const possibleRouters = [
-                skill,
-                ...localSupportDocs.filter((candidate) => reachable.has(candidate.artifact.path)),
-            ];
-            if (possibleRouters.some((router) => referencesDocument(router, document))) {
-                reachable.add(document.artifact.path);
+            if (references.get(skill.artifact.path)?.has(document.artifact.path)) {
+                reachable.set(document.artifact.path, 1);
+                changed = true;
+                continue;
+            }
+            const parent = localSupportDocs
+                .filter((candidate) => reachable.has(candidate.artifact.path))
+                .sort((left, right) => (reachable.get(left.artifact.path) ?? 0) -
+                (reachable.get(right.artifact.path) ?? 0))
+                .find((candidate) => references.get(candidate.artifact.path)?.has(document.artifact.path));
+            if (parent) {
+                reachable.set(document.artifact.path, (reachable.get(parent.artifact.path) ?? 0) + 1);
                 changed = true;
             }
         }
     }
     return reachable;
 }
-function referencesDocument(source, target) {
-    const name = path.posix.basename(target.artifact.path, path.posix.extname(target.artifact.path));
-    const basename = path.posix.basename(target.artifact.path);
-    return (source.artifact.content.includes(target.artifact.path) ||
-        source.artifact.content.includes(basename) ||
-        new RegExp(`\\b${escapeRegExp(name)}\\b`, "i").test(source.artifact.content));
+function localSupportPathReferences(document, skillDir, candidatePaths) {
+    return staticSupportReferences(document, skillDir, candidatePaths).map((reference) => ({
+        raw: reference.raw,
+        relative: reference.relativePath,
+        target: reference.targetPath,
+        line: reference.line,
+    }));
 }
 function markdownBodyLineIndexes(document) {
     if (document.lines[0]?.trim() !== "---") {
@@ -1374,34 +1539,11 @@ function thinSkillLayoutFindings(document) {
     if (classifyRepositorySkillEntrypointPath(document.artifact.path)?.kind !==
         "canonical")
         return [];
-    const findings = [];
-    const wordCount = words(document.artifact.content).length;
-    const procedureSignals = [
-        /^#{2,}\s+(procedure|steps?|install|configure|troubleshoot|diagnose|setup)\b/im,
-        /\b(step\s+\d+|first,|next,|finally)\b/i,
-    ];
-    if (wordCount > 450 ||
-        procedureSignals.some((pattern) => pattern.test(document.artifact.content))) {
-        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: "Canonical Skill entrypoints should route agents instead of owning reusable knowledge, helper implementations, or detailed procedures.",
-            verificationSteps: [
-                "Confirm SKILL.md contains routing guidance and required context references only.",
-                "Run renma readiness and check layout.skills_thin.",
-            ],
-            llmHint: "Extract long procedure sections into contexts/**, add metadata.renma.requires-context or metadata.renma.optional-context JSON-array strings, and keep SKILL.md focused on when to use or not use the Skill. Pre-0.16 top-level references are migration input only.",
-        }));
-    }
-    const command = firstExecutableCommand(document);
-    if (command) {
-        findings.push(findingAt(document, DIAGNOSTIC_IDS.LAYOUT_SKILL_EXECUTABLE_COMMAND, "Skill entrypoint contains executable command", "structure", "low", command.line, command.command, "Move executable command detail into Skill-local references or governed contexts/** procedures, and keep SKILL.md as a router.", {
-            whyItMatters: "Executable setup commands in SKILL.md make the entrypoint procedural instead of a concise routing layer.",
-            verificationSteps: [
-                "Move the command guidance to a context/reference/procedure.",
-                "If the command invokes a helper script, ensure it resolves to local scripts/** in the owning Skill or a shared tools/** helper.",
-            ],
-        }));
-    }
-    return findings;
+    // Agent Skills explicitly permits step-by-step instructions and command
+    // examples in SKILL.md. Focused-workflow quality is evaluated by dedicated
+    // routing, input, completion, progressive-disclosure, and mixed-knowledge
+    // rules instead of the removed 0.17 thin-router heuristic.
+    return [];
 }
 function helperCommandFindings(document, paths) {
     const findings = [];
@@ -1546,9 +1688,6 @@ function executableCommands(document) {
     }))
         .filter(({ command }) => /^(node|bash|sh|python|python3)\s+/.test(command)));
 }
-function firstExecutableCommand(document) {
-    return executableCommands(document)[0];
-}
 function unresolvedHelperCommandFinding(document, command, scriptPath, details = {}) {
     const unsafePath = details.details?.unsafePath === true;
     return findingAt(document, DIAGNOSTIC_IDS.PATH_HELPER_COMMAND_UNRESOLVED, "Helper command target does not resolve", "structure", "medium", command.line, command.command, unsafePath
@@ -1578,9 +1717,6 @@ function lineText(document, line) {
 function isRepoPathLike(value) {
     return /^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)+$/.test(value);
 }
-function words(text) {
-    return text.match(/[A-Za-z0-9_./+=-]+|[^\sA-Za-z0-9_./+=-]/g) ?? [];
-}
 function finding(id, title, category, severity, document, remediation, details = {}) {
     return {
         id,
@@ -1635,15 +1771,12 @@ function localSupportUnreachableRuleId(kind) {
         return DIAGNOSTIC_IDS.SUPPORT_UNREACHABLE_PROFILE;
     if (kind === "example")
         return DIAGNOSTIC_IDS.SUPPORT_UNREACHABLE_EXAMPLE;
+    if (kind === "script")
+        return DIAGNOSTIC_IDS.SUPPORT_UNREACHABLE_SCRIPT;
+    if (kind === "asset")
+        return DIAGNOSTIC_IDS.SUPPORT_UNREACHABLE_ASSET;
     return DIAGNOSTIC_IDS.SUPPORT_UNREACHABLE_REFERENCE;
 }
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-function approximateTokenCount(text) {
-    const matches = text.match(/[A-Za-z0-9_./+=-]+|[^\sA-Za-z0-9_./+=-]/g);
-    return matches?.length ?? 0;
-}
 function isPlaceholder(line) {
     return /(?:example|placeholder|your_|<[^>]+>|\$\{[^}]+})/i.test(line);
 }