renma 0.16.0 → 0.18.0

package/dist/rules.js

@@ -2,95 +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 { helperScriptPath } from "./repository-paths.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",
@@ -113,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)
@@ -129,11 +81,11 @@ 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",
-            run: (context) => strictLayoutPolicyFindings(context.documents, context.config, context.catalog, repositoryPaths),
+            run: (context) => strictLayoutPolicyFindings(context.documents, context.catalog, repositoryPaths),
         },
         {
             id: "security",
@@ -152,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",
@@ -645,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" &&
@@ -731,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,
@@ -765,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 ??
@@ -783,37 +764,51 @@ 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) {
     if (document.artifact.kind !== "reference")
         return [];
-    if (!/^skills\/[^/]+\/references\/.+\.md$/u.test(document.artifact.path)) {
+    const skillPath = classifyRepositorySkillPath(document.artifact.path);
+    if (skillPath?.kind !== "support" ||
+        skillPath.supportDirectory !== "references" ||
+        !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);
@@ -848,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
@@ -893,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",
+            },
         },
     ];
 }
@@ -1061,8 +1071,11 @@ function skillReferencesSupersededAssetFindings(documents) {
     });
 }
 function isSkillLocalReference(document) {
+    const skillPath = classifyRepositorySkillPath(document.artifact.path);
     return (document.artifact.kind === "reference" &&
-        /^skills\/[^/]+\/references\/.+\.md$/u.test(document.artifact.path));
+        skillPath?.kind === "support" &&
+        skillPath.supportDirectory === "references" &&
+        document.artifact.path.endsWith(".md"));
 }
 function sharedContextTargets(document) {
     const operationalMetadata = parseAssetMetadata(document).metadata;
@@ -1072,13 +1085,15 @@ function sharedContextTargets(document) {
     ].filter((target, index, targets) => /^contexts?\//u.test(target) && targets.indexOf(target) === index);
 }
 function parentSkillPath(referencePath) {
-    const segments = referencePath.split("/");
-    if (segments.length < 4 || segments[0] !== "skills")
-        return undefined;
-    return `skills/${segments[1]}/SKILL.md`;
+    const skillPath = classifyRepositorySkillPath(referencePath);
+    return skillPath?.kind === "support"
+        ? `${skillPath.skillDirectory}/SKILL.md`
+        : 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)) {
@@ -1201,16 +1216,17 @@ function contextBudgetFindings(document) {
         return [];
     }
     const limit = CONTEXT_TOKEN_LIMITS[document.artifact.kind];
-    const tokenCount = approximateTokenCount(document.artifact.content);
-    if (tokenCount <= limit)
+    const estimatedTokens = estimateTokens(document.artifact.content);
+    if (estimatedTokens <= 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.",
+        documentFinding(document, DIAGNOSTIC_IDS.QUAL_SUPPORT_ASSET_TOKEN_BUDGET, "Support asset exceeds token guidance", "quality", "low", `Review whether this ${document.artifact.kind} asset still has one coherent scope. Size alone does not require a split. Consider headings, read conditions, reference depth, mixed responsibilities, and maintained duplication before using \`renma suggest-semantic-split ${document.artifact.path}\`.`, {
+            whyItMatters: "Large content assets deserve a low-advisory coherence review, but an intentionally focused asset can remain intact above the threshold.",
             constraints: [
                 "Do not introduce runtime context resolution.",
                 "Do not create prompt packages.",
-                "Preserve concrete procedural steps losslessly.",
+                "Do not split based on size alone.",
+                "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: [
@@ -1218,7 +1234,14 @@ function contextBudgetFindings(document) {
                 "Run the repository-specific validation or test command, if one exists.",
                 "Confirm the finding is resolved or reduced and every split part remains reachable.",
             ],
-            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.",
+            llmHint: "Review scope, headings, read conditions, reference depth, responsibilities, and duplication. Propose a semantic split only when those signals justify it.",
+            details: {
+                measured: estimatedTokens,
+                limit,
+                unit: "estimated_tokens",
+                profile: QUALITY.profile,
+                measurement: "full_file",
+            },
         }),
     ];
 }
@@ -1232,19 +1255,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.",
@@ -1255,14 +1290,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: [
@@ -1279,36 +1315,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() !== "---") {
@@ -1347,14 +1473,13 @@ function matchingLineFindings(document, matcher) {
         ];
     });
 }
-function strictLayoutPolicyFindings(documents, config, catalog, repositoryPaths) {
+function strictLayoutPolicyFindings(documents, catalog, repositoryPaths) {
     const findings = [];
     const paths = repositoryPaths ??
         new Set(documents.map((document) => document.artifact.path));
     for (const document of documents) {
-        findings.push(...disallowedSkillAssetFindings(document, config));
         findings.push(...thinSkillLayoutFindings(document));
-        findings.push(...helperCommandFindings(document, paths, config));
+        findings.push(...helperCommandFindings(document, paths));
         findings.push(...layoutConsistencyFindings(document));
         findings.push(...contextRootFindings(document));
         findings.push(...helperRootFindings(document));
@@ -1364,80 +1489,40 @@ function strictLayoutPolicyFindings(documents, config, catalog, repositoryPaths)
     }
     return findings;
 }
-function disallowedSkillAssetFindings(document, config) {
-    const match = document.artifact.path.match(/^skills\/([^/]+)\/(references|profiles|examples|scripts)\/(.+)$/);
-    if (!match)
-        return [];
-    const [, skillName = "", assetRoot = "", rest = ""] = match;
-    const target = canonicalSkillAssetTarget(config, skillName, assetRoot, rest);
-    return [
-        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}.`,
-                "Run renma scan and renma readiness again.",
-            ],
-            llmHint: `Move ${document.artifact.path} to ${target}, then rewrite references from the old path to the new path. Do not leave a compatibility shim unless another Renma finding requires it.`,
-        }),
-    ];
-}
-function canonicalSkillAssetTarget(config, skillName, assetRoot, rest) {
-    const workflow = canonicalWorkflowName(config, skillName);
-    if (assetRoot === "scripts")
-        return helperAssetPath(config, workflow, `scripts/${rest}`);
-    return contextAssetPath(config, workflow, `${assetRoot}/${rest}`);
-}
-function canonicalWorkflowName(config, skillName) {
-    return config.layout.workflowAliases[skillName] ?? skillName;
-}
 function thinSkillLayoutFindings(document) {
-    if (!isCanonicalSkillEntrypoint(document.artifact.path))
+    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: "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.",
-                "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 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.",
-                "If the command invokes a helper script, ensure it points under tools/**.",
-            ],
-        }));
-    }
-    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, config) {
+function helperCommandFindings(document, paths) {
     const findings = [];
     for (const command of executableCommands(document)) {
-        const scriptPath = helperScriptPath(command.command);
-        if (!scriptPath)
+        const commandPath = helperScriptPath(command.command);
+        if (!commandPath)
             continue;
-        if (/^skills\/[^/]+\/scripts\//.test(scriptPath)) {
-            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.`,
-                    "Run renma scan and renma readiness again.",
-                ],
+        const resolution = resolveHelperScriptPath(document.artifact.path, commandPath);
+        if (resolution.kind === "unscoped")
+            continue;
+        if (resolution.kind === "unsafe") {
+            findings.push(unresolvedHelperCommandFinding(document, command, commandPath, {
+                details: { unsafePath: true },
             }));
             continue;
         }
+        const scriptPath = resolution.path;
+        const skillPath = classifyRepositorySkillPath(scriptPath);
+        if (skillPath?.kind === "support" &&
+            skillPath.supportDirectory === "scripts") {
+            if (!paths.has(scriptPath)) {
+                findings.push(unresolvedHelperCommandFinding(document, command, scriptPath));
+            }
+            continue;
+        }
         if (scriptPath.includes("/scripts/") && !scriptPath.startsWith("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.",
@@ -1445,9 +1530,7 @@ function helperCommandFindings(document, paths, config) {
             continue;
         }
         if (scriptPath.startsWith("tools/") && !paths.has(scriptPath)) {
-            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.",
-            }));
+            findings.push(unresolvedHelperCommandFinding(document, command, scriptPath));
         }
     }
     return findings;
@@ -1467,10 +1550,6 @@ function layoutConsistencyFindings(document) {
             pattern: /Each skill includes a self-improvement prompt/i,
             message: "Describe self-improvement prompts as loaded context/reference/procedure workflow prompts instead of SKILL.md-only content.",
         },
-        {
-            pattern: /skills\/[^/\s`]+\/(?:references|profiles|examples|scripts)\//,
-            message: "Update docs to point to canonical contexts/** assets or tools/** helper scripts instead of skill-local support directories.",
-        },
         {
             pattern: /\]\(contexts\/tools\//,
             message: "Use backtick repo-root paths for contexts/tools/... references instead of file-relative Markdown links.",
@@ -1481,10 +1560,10 @@ function layoutConsistencyFindings(document) {
         if (!match)
             continue;
         const line = lineForOffset(text, match.index ?? 0);
-        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.",
+        findings.push(findingAt(document, DIAGNOSTIC_IDS.DOCS_LAYOUT_INCONSISTENT, "Repository docs contradict the supported layout", "maintenance", "low", line, lineText(document, line), stale.message, {
+            whyItMatters: "README.md and AGENTS.md should describe the current repository model without treating valid Skill-local support as stale.",
             verificationSteps: [
-                "Update README.md and AGENTS.md to mention skills/, contexts/, and tools/ canonical roots.",
+                "Confirm docs distinguish canonical Skill roots and valid local support from governed contexts/** assets and shared tools/** helpers.",
                 "Run renma scan again.",
             ],
         }));
@@ -1502,6 +1581,11 @@ function contextRootFindings(document) {
     return [];
 }
 function helperRootFindings(document) {
+    const skillPath = classifyRepositorySkillPath(document.artifact.path);
+    if (skillPath?.kind === "support" &&
+        skillPath.supportDirectory === "scripts") {
+        return [];
+    }
     if (document.artifact.path.includes("/scripts/") &&
         !document.artifact.path.startsWith("tools/")) {
         return [
@@ -1522,7 +1606,7 @@ function declaredDependencyLayoutFindings(catalog, paths) {
             continue;
         }
         if (target.startsWith("contexts/") ||
-            target.startsWith("skills/") ||
+            normalizeRepositoryRelativePath(target) !== undefined ||
             target.startsWith("tools/")) {
             continue;
         }
@@ -1536,7 +1620,7 @@ function declaredDependencyLayoutFindings(catalog, paths) {
             severity: "low",
             confidence: "medium",
             evidence: metadataFindingEvidence(source.sourcePath, target),
-            whyItMatters: "Declared context references should resolve through canonical contexts/**, skills/**, or tools/** repo paths.",
+            whyItMatters: "Declared context references should resolve through canonical contexts/**, skills/**, .agents/skills/**, or tools/** repository paths.",
             remediation: "Rewrite declared required or optional context dependency values to canonical repo-root paths without changing the Skill's operational metadata format.",
             verificationSteps: ["Run renma graph and confirm all edges resolve."],
             details: {
@@ -1558,30 +1642,18 @@ function executableCommands(document) {
     }))
         .filter(({ command }) => /^(node|bash|sh|python|python3)\s+/.test(command)));
 }
-function firstExecutableCommand(document) {
-    return executableCommands(document)[0];
-}
-function canonicalHelperTarget(config, scriptPath) {
-    const parts = scriptPath.split("/");
-    const skillName = parts[1] ?? "unknown";
-    const rest = parts.slice(3).join("/");
-    const workflow = canonicalWorkflowName(config, skillName);
-    return helperAssetPath(config, workflow, `scripts/${rest}`);
-}
-function contextAssetPath(config, workflow, rest) {
-    const namespace = config.layout.toolNamespace;
-    if (namespace)
-        return `contexts/tools/${namespace}/${workflow}/${rest}`;
-    return `contexts/${workflow}/${rest}`;
-}
-function helperAssetPath(config, workflow, rest) {
-    const namespace = config.layout.toolNamespace;
-    if (namespace)
-        return `tools/${namespace}/${workflow}/${rest}`;
-    return `tools/${workflow}/${rest}`;
-}
-function isCanonicalSkillEntrypoint(pathValue) {
-    return /^skills\/[^/]+\/SKILL\.md$/.test(pathValue);
+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
+        ? "Update this command to a path inside the owning Skill's scripts/** directory or to a repository-root tools/** helper; do not escape the Skill with `..`."
+        : `Create \`${scriptPath}\` or update this command to the correct local helper path.`, {
+        whyItMatters: "Agents need shared tools/** helpers and Skill-local scripts to resolve deterministically before running them.",
+        verificationSteps: [
+            "Confirm the command resolves to an existing tools/** helper or to scripts/** inside its owning Skill.",
+            "Run renma readiness and check paths.helper_commands.",
+        ],
+        ...details,
+    });
 }
 function findingAt(document, id, title, category, severity, line, snippet, remediation, details = {}) {
     return {
@@ -1599,9 +1671,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,
@@ -1656,15 +1725,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);
 }