renma 0.15.2 → 0.17.0

package/dist/rules.js

@@ -1,7 +1,10 @@
 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, normalizeRepositoryRelativePath, } from "./discovery.js";
+import { helperScriptPath, resolveHelperScriptPath, } from "./repository-paths.js";
+import { parseAssetMetadata } from "./metadata.js";
 import { runRuleRegistry } from "./rule-engine.js";
 const SECRET_PATTERN = /\b(?:password|passwd|token|api[_-]?key|secret|credential|private[_-]?key)\b\s*[:=]\s*["']?([A-Za-z0-9_./+=-]{8,})/i;
 const PRIVATE_KEY_PATTERN = /-----BEGIN (?:RSA |OPENSSH |EC |DSA )?PRIVATE KEY-----/;
@@ -131,7 +134,7 @@ function rulesForEvaluationDate(evaluationDate, repositoryPaths) {
     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",
@@ -434,7 +437,7 @@ function orphanedContextLensFindings(entries, resolver) {
                 confidence: "medium",
                 evidence: metadataFindingEvidence(entry.sourcePath, "Active context lens has no incoming requires_lens or optional_lens references from skills."),
                 whyItMatters: "Context lenses are easier to review when a skill declares how the purpose-oriented interpretation is used. An unreferenced active lens may be newly created, intentionally staged, or stale.",
-                remediation: "If the lens should be used, reference it from a skill with requires_lens or optional_lens. If it is not ready or no longer needed, update its lifecycle status after review.",
+                remediation: "If the lens should be used, reference it from a canonical Skill with metadata.renma.requires-lens or metadata.renma.optional-lens JSON-array metadata. Pre-0.16-only Skills use requires_lens or optional_lens only during migration. If the lens is not ready or no longer needed, update its lifecycle status after review.",
                 constraints: [
                     "Do not make Renma select runtime lenses.",
                     "Do not rank or retrieve lenses semantically.",
@@ -446,7 +449,7 @@ function orphanedContextLensFindings(entries, resolver) {
                     "Run renma catalog.",
                     "Run renma graph focused on the lens or owning skill.",
                 ],
-                llmHint: `Search for skills that should declare "${entry.id}" in requires_lens or optional_lens. Do not add runtime selection logic or prompt assembly.`,
+                llmHint: `Search for Skills that should declare "${entry.id}" as a required or optional lens. For canonical Skills, update metadata.renma.requires-lens or metadata.renma.optional-lens as a JSON-array string; use requires_lens or optional_lens only for pre-0.16 migration inputs. Do not add runtime selection logic or prompt assembly.`,
                 details: {
                     assetId: entry.id,
                     sourcePath: entry.sourcePath,
@@ -640,7 +643,9 @@ function shapeFindings(document) {
         return [];
     const text = document.artifact.content.toLowerCase();
     const findings = [];
-    const description = document.metadata.description ?? "";
+    const description = document.artifact.kind === "skill"
+        ? (resolvedAgentSkillDescription(document) ?? "")
+        : (document.metadata.description ?? "");
     const tokenCount = approximateTokenCount(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."));
@@ -804,7 +809,10 @@ function reusableContextCandidateFinding(document, tokenCount) {
 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);
@@ -936,7 +944,8 @@ function contextPathNonSemanticFindings(document) {
 function skillContextReferenceNotDeclaredFindings(document) {
     if (document.artifact.kind !== "skill")
         return [];
-    const declaredContexts = new Set(listMetadataValue(document.metadata.requires_context));
+    const operationalMetadata = parseAssetMetadata(document).metadata;
+    const declaredContexts = new Set(operationalMetadata.requiresContext);
     const bodyLineIndexes = markdownBodyLineIndexes(document);
     const matches = new Map();
     for (const index of bodyLineIndexes) {
@@ -961,7 +970,7 @@ function skillContextReferenceNotDeclaredFindings(document) {
         confidence: "high",
         evidence: evidence(document, match.line, match.text),
         whyItMatters: "Declared context references make skill/context relationships visible to catalog, graph, and validation reports. If a skill only mentions a context in prose, humans may see the dependency but repository tooling cannot validate it.",
-        remediation: "Add the referenced shared context asset to the skill metadata using requires_context, or remove the prose reference if it is no longer needed.",
+        remediation: "Add the referenced shared context asset to metadata.renma.requires-context as a JSON-array string, or remove the prose reference if it is no longer needed. Pre-0.16 requires_context is migration input only and is not operational in Renma 0.16.0.",
         constraints: [
             "Do not select runtime context.",
             "Do not assemble prompt packages.",
@@ -973,9 +982,9 @@ function skillContextReferenceNotDeclaredFindings(document) {
             "Run renma catalog.",
             "Confirm the skill/context relationship appears in metadata and catalog output.",
         ],
-        llmHint: `Find context paths mentioned in the skill body and add them to requires_context using the metadata syntax currently supported by Renma. Missing declaration: ${referencedPath}`,
+        llmHint: `Find context paths mentioned in the Skill body and add the missing declaration using metadata.renma.requires-context as a JSON-array string. Pre-0.16 requires_context is accepted only by suggest-metadata and is not operational. Missing declaration: ${referencedPath}`,
         details: {
-            source: metadataText(document.metadata.id) ?? document.artifact.path,
+            source: operationalMetadata.id ?? document.artifact.path,
             target: referencedPath,
             referenceKind: "requires_context",
             sourcePath: document.artifact.path,
@@ -1002,6 +1011,7 @@ function skillReferencesSupersededAssetFindings(documents) {
         const skill = skillsByPath.get(skillPath);
         if (!skill)
             return [];
+        const skillMetadata = parseAssetMetadata(skill).metadata;
         const referencedFrom = skillReferenceLine(skill, document.artifact.path);
         if (!referencedFrom)
             return [];
@@ -1042,7 +1052,7 @@ function skillReferencesSupersededAssetFindings(documents) {
                 ],
                 llmHint: "Inspect the deprecated local support file and its superseded_by or canonical_context metadata. If the shared context asset is now canonical, update skill guidance and metadata to reference the shared context directly. Keep the local reference only if it contains truly local notes or is intentionally preserved as a compatibility shim.",
                 details: {
-                    source: metadataText(skill.metadata.id) ?? skill.artifact.path,
+                    source: skillMetadata.id ?? skill.artifact.path,
                     target: metadataText(document.metadata.id) ?? document.artifact.path,
                     referenceKind: "body_reference",
                     sourcePath: skill.artifact.path,
@@ -1055,20 +1065,24 @@ 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;
     return [
-        ...listMetadataValue(document.metadata.superseded_by),
+        ...operationalMetadata.supersededBy,
         ...listMetadataValue(document.metadata.canonical_context),
     ].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);
@@ -1084,18 +1098,23 @@ function skillReferenceLine(skill, referencePath) {
 }
 function assetReferencesSupersededAssetFindings(documents) {
     const supersededAssets = documents
-        .map((document) => ({
-        document,
-        canonicalTargets: sharedContextTargets(document),
-    }))
-        .filter(({ document, canonicalTargets }) => metadataText(document.metadata.status) === "deprecated" ||
-        metadataText(document.metadata.status) === "archived" ||
+        .map((document) => {
+        const metadata = parseAssetMetadata(document).metadata;
+        return {
+            document,
+            metadata,
+            canonicalTargets: sharedContextTargets(document),
+        };
+    })
+        .filter(({ metadata, canonicalTargets }) => metadata.status === "deprecated" ||
+        metadata.status === "archived" ||
         canonicalTargets.length > 0)
         .filter(({ canonicalTargets }) => canonicalTargets.length > 0);
     return documents.flatMap((referencingDocument) => {
         if (referencingDocument.artifact.kind === "skill")
             return [];
-        return supersededAssets.flatMap(({ document, canonicalTargets }) => {
+        const referencingMetadata = parseAssetMetadata(referencingDocument).metadata;
+        return supersededAssets.flatMap(({ document, metadata, canonicalTargets }) => {
             if (document.artifact.path === referencingDocument.artifact.path) {
                 return [];
             }
@@ -1139,13 +1158,12 @@ function assetReferencesSupersededAssetFindings(documents) {
                     ],
                     llmHint: "Inspect the referenced deprecated asset and its superseded_by or canonical context metadata. If the canonical shared context is the intended source of truth, update this asset to reference that context directly. Keep the superseded file only when it serves a deliberate compatibility or migration role.",
                     details: {
-                        source: metadataText(referencingDocument.metadata.id) ??
-                            referencingDocument.artifact.path,
-                        target: metadataText(document.metadata.id) ?? document.artifact.path,
+                        source: referencingMetadata.id ?? referencingDocument.artifact.path,
+                        target: metadata.id ?? document.artifact.path,
                         referenceKind: "body_reference",
                         sourcePath: referencingDocument.artifact.path,
                         targetPath: document.artifact.path,
-                        targetStatus: metadataText(document.metadata.status),
+                        targetStatus: metadata.status,
                         replacementTargets: canonicalTargets,
                     },
                 },
@@ -1336,14 +1354,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));
@@ -1353,34 +1370,9 @@ 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;
@@ -1391,42 +1383,50 @@ function thinSkillLayoutFindings(document) {
     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.",
+            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 requires_context or optional_context references, and keep SKILL.md focused on when to use or not use the skill.",
+            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.",
+        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 points under tools/**.",
+                "If the command invokes a helper script, ensure it resolves to local scripts/** in the owning Skill or a shared tools/** helper.",
             ],
         }));
     }
     return findings;
 }
-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.",
@@ -1434,9 +1434,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;
@@ -1456,10 +1454,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.",
@@ -1470,10 +1464,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.",
             ],
         }));
@@ -1491,6 +1485,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 [
@@ -1511,7 +1510,7 @@ function declaredDependencyLayoutFindings(catalog, paths) {
             continue;
         }
         if (target.startsWith("contexts/") ||
-            target.startsWith("skills/") ||
+            normalizeRepositoryRelativePath(target) !== undefined ||
             target.startsWith("tools/")) {
             continue;
         }
@@ -1525,8 +1524,8 @@ 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.",
-            remediation: "Rewrite declared requires_context or optional_context values to canonical repo-root 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: {
                 source: dependency.from,
@@ -1550,27 +1549,18 @@ function executableCommands(document) {
 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 {