renma 0.15.1 → 0.16.0

package/dist/repository-evidence.d.ts

@@ -1,7 +1,7 @@
 import { type ConfigOverrides } from "./config.js";
 import { type ContextLensSummary } from "./context-lens.js";
 import type { Catalog } from "./model.js";
-import type { Diagnostic } from "./types.js";
+import type { Artifact, Diagnostic, ParsedDocument, ScanConfig } from "./types.js";
 export interface RepositoryEvidence {
     root: string;
     configPath?: string;
@@ -10,5 +10,15 @@ export interface RepositoryEvidence {
     contextLens: ContextLensSummary;
     diagnostics: Diagnostic[];
 }
+export interface RepositorySnapshot extends RepositoryEvidence {
+    config: ScanConfig;
+    artifacts: Artifact[];
+    documents: ParsedDocument[];
+    repositoryPaths: ReadonlySet<string>;
+    discoveryDiagnostics: Diagnostic[];
+    catalogDiagnostics: Diagnostic[];
+    contextLensDiagnostics: Diagnostic[];
+}
 export declare function collectRepositoryEvidence(targetPath: string, overrides?: ConfigOverrides): Promise<RepositoryEvidence>;
+export declare function collectRepositorySnapshot(targetPath: string, overrides?: ConfigOverrides): Promise<RepositorySnapshot>;
 //# sourceMappingURL=repository-evidence.d.ts.map

package/dist/repository-evidence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repository-evidence.d.ts","sourceRoot":"","sources":["../src/repository-evidence.ts"],"names":[],"mappings":"AAEA,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,kBAAkB,CAAC;IAChC,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B;AAED,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,eAAoB,GAC9B,OAAO,CAAC,kBAAkB,CAAC,CAoB7B"}
+{"version":3,"file":"repository-evidence.d.ts","sourceRoot":"","sources":["../src/repository-evidence.ts"],"names":[],"mappings":"AAEA,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,OAAO,KAAK,EACV,QAAQ,EACR,UAAU,EACV,cAAc,EACd,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,kBAAkB,CAAC;IAChC,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAmB,SAAQ,kBAAkB;IAC5D,MAAM,EAAE,UAAU,CAAC;IACnB,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,eAAe,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACrC,oBAAoB,EAAE,UAAU,EAAE,CAAC;IACnC,kBAAkB,EAAE,UAAU,EAAE,CAAC;IACjC,sBAAsB,EAAE,UAAU,EAAE,CAAC;CACtC;AAED,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,eAAoB,GAC9B,OAAO,CAAC,kBAAkB,CAAC,CAU7B;AAED,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,eAAoB,GAC9B,OAAO,CAAC,kBAAkB,CAAC,CAkC7B"}

package/dist/repository-evidence.js

@@ -4,21 +4,41 @@ import { loadConfig } from "./config.js";
 import { summarizeContextLensGovernance, } from "./context-lens.js";
 import { discoverArtifacts } from "./discovery.js";
 import { parseDocument } from "./markdown.js";
+import { collectRepositoryPaths } from "./repository-paths.js";
 export async function collectRepositoryEvidence(targetPath, overrides = {}) {
+    const snapshot = await collectRepositorySnapshot(targetPath, overrides);
+    return {
+        root: snapshot.root,
+        ...(snapshot.configPath ? { configPath: snapshot.configPath } : {}),
+        scannedFileCount: snapshot.scannedFileCount,
+        catalog: snapshot.catalog,
+        contextLens: snapshot.contextLens,
+        diagnostics: snapshot.diagnostics,
+    };
+}
+export async function collectRepositorySnapshot(targetPath, overrides = {}) {
     const root = path.resolve(targetPath);
     const { config, configPath } = await loadConfig(root, overrides);
-    const { artifacts, diagnostics } = await discoverArtifacts(root, config);
+    const { artifacts, diagnostics: discoveryDiagnostics } = await discoverArtifacts(root, config);
     const documents = artifacts.map(parseDocument);
     const built = buildCatalog(documents);
     const contextLens = summarizeContextLensGovernance(documents, built.catalog);
+    const repositoryPaths = await collectRepositoryPaths(root, artifacts, documents, built.catalog);
     return {
         root,
         ...(configPath ? { configPath } : {}),
+        config,
+        artifacts,
+        documents,
+        repositoryPaths,
         scannedFileCount: artifacts.length,
         catalog: built.catalog,
         contextLens: contextLens.summary,
+        discoveryDiagnostics,
+        catalogDiagnostics: built.diagnostics,
+        contextLensDiagnostics: contextLens.diagnostics,
         diagnostics: [
-            ...diagnostics,
+            ...discoveryDiagnostics,
             ...built.diagnostics,
             ...contextLens.diagnostics,
         ],

package/dist/repository-evidence.js.map

@@ -1 +1 @@
-{"version":3,"file":"repository-evidence.js","sourceRoot":"","sources":["../src/repository-evidence.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAwB,MAAM,aAAa,CAAC;AAC/D,OAAO,EACL,8BAA8B,GAE/B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAa9C,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,UAAkB,EAClB,YAA6B,EAAE;IAE/B,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACtC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACjE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,GAAG,MAAM,iBAAiB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACzE,MAAM,SAAS,GAAG,SAAS,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAC/C,MAAM,KAAK,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;IACtC,MAAM,WAAW,GAAG,8BAA8B,CAAC,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IAE7E,OAAO;QACL,IAAI;QACJ,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrC,gBAAgB,EAAE,SAAS,CAAC,MAAM;QAClC,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,WAAW,EAAE,WAAW,CAAC,OAAO;QAChC,WAAW,EAAE;YACX,GAAG,WAAW;YACd,GAAG,KAAK,CAAC,WAAW;YACpB,GAAG,WAAW,CAAC,WAAW;SAC3B;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"repository-evidence.js","sourceRoot":"","sources":["../src/repository-evidence.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAwB,MAAM,aAAa,CAAC;AAC/D,OAAO,EACL,8BAA8B,GAE/B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AA2B/D,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,UAAkB,EAClB,YAA6B,EAAE;IAE/B,MAAM,QAAQ,GAAG,MAAM,yBAAyB,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IACxE,OAAO;QACL,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnE,gBAAgB,EAAE,QAAQ,CAAC,gBAAgB;QAC3C,OAAO,EAAE,QAAQ,CAAC,OAAO;QACzB,WAAW,EAAE,QAAQ,CAAC,WAAW;QACjC,WAAW,EAAE,QAAQ,CAAC,WAAW;KAClC,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,UAAkB,EAClB,YAA6B,EAAE;IAE/B,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACtC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACjE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,oBAAoB,EAAE,GACpD,MAAM,iBAAiB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACxC,MAAM,SAAS,GAAG,SAAS,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAC/C,MAAM,KAAK,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;IACtC,MAAM,WAAW,GAAG,8BAA8B,CAAC,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IAC7E,MAAM,eAAe,GAAG,MAAM,sBAAsB,CAClD,IAAI,EACJ,SAAS,EACT,SAAS,EACT,KAAK,CAAC,OAAO,CACd,CAAC;IAEF,OAAO;QACL,IAAI;QACJ,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrC,MAAM;QACN,SAAS;QACT,SAAS;QACT,eAAe;QACf,gBAAgB,EAAE,SAAS,CAAC,MAAM;QAClC,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,WAAW,EAAE,WAAW,CAAC,OAAO;QAChC,oBAAoB;QACpB,kBAAkB,EAAE,KAAK,CAAC,WAAW;QACrC,sBAAsB,EAAE,WAAW,CAAC,WAAW;QAC/C,WAAW,EAAE;YACX,GAAG,oBAAoB;YACvB,GAAG,KAAK,CAAC,WAAW;YACpB,GAAG,WAAW,CAAC,WAAW;SAC3B;KACF,CAAC;AACJ,CAAC"}

package/dist/repository-paths.d.ts

@@ -0,0 +1,6 @@
+import type { Catalog } from "./model.js";
+import type { Artifact, ParsedDocument } from "./types.js";
+/** Collect immutable repository-relative path existence evidence for rules. */
+export declare function collectRepositoryPaths(root: string, artifacts: Artifact[], documents: ParsedDocument[], catalog: Catalog): Promise<ReadonlySet<string>>;
+export declare function helperScriptPath(command: string): string | undefined;
+//# sourceMappingURL=repository-paths.d.ts.map

package/dist/repository-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository-paths.d.ts","sourceRoot":"","sources":["../src/repository-paths.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE3D,+EAA+E;AAC/E,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,QAAQ,EAAE,EACrB,SAAS,EAAE,cAAc,EAAE,EAC3B,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAa9B;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKpE"}

package/dist/repository-paths.js

@@ -0,0 +1,62 @@
+import { access } from "node:fs/promises";
+import path from "node:path";
+/** Collect immutable repository-relative path existence evidence for rules. */
+export async function collectRepositoryPaths(root, artifacts, documents, catalog) {
+    const paths = new Set(artifacts
+        .map((artifact) => normalizeRepositoryPath(artifact.path))
+        .filter((candidate) => candidate !== undefined));
+    for (const candidate of repositoryPathCandidates(documents, catalog)) {
+        if (paths.has(candidate))
+            continue;
+        if (await repositoryPathExists(root, candidate))
+            paths.add(candidate);
+    }
+    return paths;
+}
+export function helperScriptPath(command) {
+    const parts = command.split(/\s+/).slice(1);
+    return parts.find((part) => /(?:^|\/)scripts\/.+\.(?:mjs|js|cjs|sh|bash|py)$/.test(part));
+}
+function repositoryPathCandidates(documents, catalog) {
+    return [
+        ...helperCommandPathCandidates(documents),
+        ...catalog.dependencies
+            .map((dependency) => dependency.to)
+            .map(normalizeRepositoryPath)
+            .filter((candidate) => candidate !== undefined)
+            .filter(isRepoPathLike),
+    ].filter((candidate, index, candidates) => candidates.indexOf(candidate) === index);
+}
+function helperCommandPathCandidates(documents) {
+    return documents.flatMap((document) => document.codeFences.flatMap((fence) => fence.content
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((command) => /^(node|bash|sh|python|python3)\s+/.test(command))
+        .map(helperScriptPath)
+        .map((candidate) => candidate ? normalizeRepositoryPath(candidate) : undefined)
+        .filter((candidate) => candidate !== undefined)));
+}
+function normalizeRepositoryPath(value) {
+    const normalized = value.replace(/\\/g, "/").replace(/^\.\//, "");
+    if (!normalized ||
+        path.posix.isAbsolute(normalized) ||
+        normalized === ".." ||
+        normalized.startsWith("../") ||
+        normalized.split("/").includes("..")) {
+        return undefined;
+    }
+    return normalized;
+}
+async function repositoryPathExists(root, relativePath) {
+    try {
+        await access(path.join(root, relativePath));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isRepoPathLike(value) {
+    return /^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)+$/.test(value);
+}
+//# sourceMappingURL=repository-paths.js.map

package/dist/repository-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository-paths.js","sourceRoot":"","sources":["../src/repository-paths.ts"],"names":[],"mappings":"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"}

package/dist/rules.d.ts

@@ -1,7 +1,12 @@
 import type { Catalog } from "./model.js";
 import type { Finding, ParsedDocument, ScanConfig, Severity } from "./types.js";
+interface RuleOptions {
+    evaluationDate?: Date | string;
+    repositoryPaths?: ReadonlySet<string>;
+}
 /** Run all deterministic rules and return findings in stable source order. */
-export declare function runRules(documents: ParsedDocument[], config: ScanConfig, catalog?: Catalog): Finding[];
+export declare function runRules(documents: ParsedDocument[], config: ScanConfig, catalog?: Catalog, options?: RuleOptions): Finding[];
 /** Return whether a severity is at least as severe as a configured threshold. */
 export declare function severityMeets(value: Severity, threshold: Severity): boolean;
+export {};
 //# sourceMappingURL=rules.d.ts.map

package/dist/rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAA4B,MAAM,YAAY,CAAC;AASpE,OAAO,KAAK,EAEV,OAAO,EAEP,cAAc,EACd,UAAU,EACV,QAAQ,EACT,MAAM,YAAY,CAAC;AA2IpB,8EAA8E;AAC9E,wBAAgB,QAAQ,CACtB,SAAS,EAAE,cAAc,EAAE,EAC3B,MAAM,EAAE,UAAU,EAClB,OAAO,CAAC,EAAE,OAAO,GAChB,OAAO,EAAE,CAOX;AA6kBD,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,GAAG,OAAO,CAQ3E"}
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAA4B,MAAM,YAAY,CAAC;AAWpE,OAAO,KAAK,EAEV,OAAO,EAEP,cAAc,EACd,UAAU,EACV,QAAQ,EACT,MAAM,YAAY,CAAC;AAcpB,UAAU,WAAW;IACnB,cAAc,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IAC/B,eAAe,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACvC;AA+HD,8EAA8E;AAC9E,wBAAgB,QAAQ,CACtB,SAAS,EAAE,cAAc,EAAE,EAC3B,MAAM,EAAE,UAAU,EAClB,OAAO,CAAC,EAAE,OAAO,EACjB,OAAO,GAAE,WAAgB,GACxB,OAAO,EAAE,CAeX;AAmmBD,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,GAAG,OAAO,CAQ3E"}

package/dist/rules.js

@@ -1,7 +1,9 @@
-import { existsSync } from "node:fs";
 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 { 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-----/;
@@ -118,8 +120,8 @@ const CONTEXT_TOKEN_LIMITS = {
     example: 800,
 };
 /** Run all deterministic rules and return findings in stable source order. */
-export function runRules(documents, config, catalog) {
-    const findings = runRuleRegistry(documents, RULES, catalog, config);
+export function runRules(documents, config, catalog, options = {}) {
+    const findings = runRuleRegistry(documents, rulesForEvaluationDate(evaluationDay(options.evaluationDate), options.repositoryPaths), catalog, config);
     return findings.sort((a, b) => {
         const byPath = a.evidence.path.localeCompare(b.evidence.path);
         if (byPath !== 0)
@@ -127,56 +129,71 @@ export function runRules(documents, config, catalog) {
         return a.evidence.startLine - b.evidence.startLine;
     });
 }
-const RULES = [
-    {
-        id: "strict-layout-policy",
-        run: (context) => strictLayoutPolicyFindings(context.documents, context.config, context.catalog),
-    },
-    {
-        id: "security",
-        run: ({ documents }) => documents.flatMap((document) => [
-            ...secretFindings(document),
-            ...commandFindings(document),
-        ]),
-    },
-    {
-        id: "shape",
-        run: ({ documents }) => documents.flatMap((document) => [
-            ...shapeFindings(document),
-            ...contextBudgetFindings(document),
-            ...profileFindings(document),
-        ]),
-    },
-    {
-        id: "skill-local-support-reachability",
-        run: ({ documents }) => skillLocalSupportReachabilityFindings(documents),
-    },
-    {
-        id: "support-asset-shared-context-candidate",
-        run: ({ documents }) => documents.flatMap((document) => supportSharedContextCandidateFindings(document)),
-    },
-    {
-        id: "context-path-non-semantic",
-        run: ({ documents }) => documents.flatMap((document) => contextPathNonSemanticFindings(document)),
-    },
-    {
-        id: "skill-context-reference-not-declared",
-        run: ({ documents }) => documents.flatMap((document) => skillContextReferenceNotDeclaredFindings(document)),
-    },
-    {
-        id: "skill-references-superseded-asset",
-        run: ({ documents }) => skillReferencesSupersededAssetFindings(documents),
-    },
-    {
-        id: "asset-references-superseded-asset",
-        run: ({ documents }) => assetReferencesSupersededAssetFindings(documents),
-    },
-    {
-        id: "catalog-declared-reference-governance",
-        run: ({ catalog }) => catalogDeclaredReferenceGovernanceFindings(catalog),
-    },
-];
-function catalogDeclaredReferenceGovernanceFindings(catalog) {
+function rulesForEvaluationDate(evaluationDate, repositoryPaths) {
+    return [
+        {
+            id: "strict-layout-policy",
+            run: (context) => strictLayoutPolicyFindings(context.documents, context.config, context.catalog, repositoryPaths),
+        },
+        {
+            id: "security",
+            run: ({ documents }) => documents.flatMap((document) => [
+                ...secretFindings(document),
+                ...commandFindings(document),
+            ]),
+        },
+        {
+            id: "shape",
+            run: ({ documents }) => documents.flatMap((document) => [
+                ...shapeFindings(document),
+                ...contextBudgetFindings(document),
+                ...profileFindings(document),
+            ]),
+        },
+        {
+            id: "skill-local-support-reachability",
+            run: ({ documents }) => skillLocalSupportReachabilityFindings(documents),
+        },
+        {
+            id: "support-asset-shared-context-candidate",
+            run: ({ documents }) => documents.flatMap((document) => supportSharedContextCandidateFindings(document)),
+        },
+        {
+            id: "context-path-non-semantic",
+            run: ({ documents }) => documents.flatMap((document) => contextPathNonSemanticFindings(document)),
+        },
+        {
+            id: "skill-context-reference-not-declared",
+            run: ({ documents }) => documents.flatMap((document) => skillContextReferenceNotDeclaredFindings(document)),
+        },
+        {
+            id: "skill-references-superseded-asset",
+            run: ({ documents }) => skillReferencesSupersededAssetFindings(documents),
+        },
+        {
+            id: "asset-references-superseded-asset",
+            run: ({ documents }) => assetReferencesSupersededAssetFindings(documents),
+        },
+        {
+            id: "catalog-declared-reference-governance",
+            run: ({ catalog }) => catalogDeclaredReferenceGovernanceFindings(catalog, evaluationDate),
+        },
+    ];
+}
+function evaluationDay(value) {
+    if (value === undefined)
+        return todayIsoDate();
+    if (value instanceof Date)
+        return todayIsoDate(value);
+    if (isIsoDate(value))
+        return value;
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.getTime())) {
+        throw new Error(`Invalid internal evaluation date: ${value}`);
+    }
+    return todayIsoDate(parsed);
+}
+function catalogDeclaredReferenceGovernanceFindings(catalog, today) {
     if (!catalog)
         return [];
     const resolver = createCatalogReferenceResolver(catalog.entries);
@@ -187,7 +204,7 @@ function catalogDeclaredReferenceGovernanceFindings(catalog) {
         ...orphanedContextAssetFindings(catalog.entries, catalog.dependencies, resolver),
         ...orphanedContextLensFindings(catalog.entries, resolver),
         ...contextLensAppliesToInactiveContextFindings(catalog.dependencies, resolver),
-        ...freshnessGovernanceFindings(catalog.entries),
+        ...freshnessGovernanceFindings(catalog.entries, today),
     ];
     return findings;
 }
@@ -419,7 +436,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.",
@@ -431,7 +448,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,
@@ -625,7 +642,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."));
@@ -921,7 +940,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) {
@@ -946,7 +966,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.",
@@ -958,9 +978,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,
@@ -987,6 +1007,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 [];
@@ -1027,7 +1048,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,
@@ -1044,8 +1065,9 @@ function isSkillLocalReference(document) {
         /^skills\/[^/]+\/references\/.+\.md$/u.test(document.artifact.path));
 }
 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);
 }
@@ -1069,18 +1091,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 [];
             }
@@ -1124,13 +1151,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,
                     },
                 },
@@ -1321,20 +1347,20 @@ function matchingLineFindings(document, matcher) {
         ];
     });
 }
-function strictLayoutPolicyFindings(documents, config, catalog) {
+function strictLayoutPolicyFindings(documents, config, catalog, repositoryPaths) {
     const findings = [];
-    const root = repositoryRoot(documents);
-    const paths = new Set(documents.map((document) => document.artifact.path));
+    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, root, paths, config));
+        findings.push(...helperCommandFindings(document, paths, config));
         findings.push(...layoutConsistencyFindings(document));
         findings.push(...contextRootFindings(document));
         findings.push(...helperRootFindings(document));
     }
     if (catalog) {
-        findings.push(...declaredDependencyLayoutFindings(catalog, paths, root));
+        findings.push(...declaredDependencyLayoutFindings(catalog, paths));
     }
     return findings;
 }
@@ -1381,7 +1407,7 @@ function thinSkillLayoutFindings(document) {
                 "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);
@@ -1396,7 +1422,7 @@ function thinSkillLayoutFindings(document) {
     }
     return findings;
 }
-function helperCommandFindings(document, root, paths, config) {
+function helperCommandFindings(document, paths, config) {
     const findings = [];
     for (const command of executableCommands(document)) {
         const scriptPath = helperScriptPath(command.command);
@@ -1418,9 +1444,7 @@ function helperCommandFindings(document, root, paths, config) {
             }));
             continue;
         }
-        if (scriptPath.startsWith("tools/") &&
-            !paths.has(scriptPath) &&
-            !(root && existsSync(path.join(root, scriptPath)))) {
+        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.",
             }));
@@ -1488,13 +1512,13 @@ function helperRootFindings(document) {
     }
     return [];
 }
-function declaredDependencyLayoutFindings(catalog, paths, root) {
+function declaredDependencyLayoutFindings(catalog, paths) {
     const findings = [];
     for (const dependency of catalog.dependencies) {
         const target = dependency.to;
         if (!isRepoPathLike(target))
             continue;
-        if (!paths.has(target) && !(root && existsSync(path.join(root, target)))) {
+        if (!paths.has(target)) {
             continue;
         }
         if (target.startsWith("contexts/") ||
@@ -1513,7 +1537,7 @@ function declaredDependencyLayoutFindings(catalog, paths, root) {
             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.",
+            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,
@@ -1537,10 +1561,6 @@ function executableCommands(document) {
 function firstExecutableCommand(document) {
     return executableCommands(document)[0];
 }
-function helperScriptPath(command) {
-    const parts = command.split(/\s+/).slice(1);
-    return parts.find((part) => /(?:^|\/)scripts\/.+\.(?:mjs|js|cjs|sh|bash|py)$/.test(part));
-}
 function canonicalHelperTarget(config, scriptPath) {
     const parts = scriptPath.split("/");
     const skillName = parts[1] ?? "unknown";
@@ -1563,12 +1583,6 @@ function helperAssetPath(config, workflow, rest) {
 function isCanonicalSkillEntrypoint(pathValue) {
     return /^skills\/[^/]+\/SKILL\.md$/.test(pathValue);
 }
-function repositoryRoot(documents) {
-    const document = documents[0];
-    if (!document)
-        return undefined;
-    return document.artifact.absolutePath.slice(0, document.artifact.absolutePath.length - document.artifact.path.length);
-}
 function findingAt(document, id, title, category, severity, line, snippet, remediation, details = {}) {
     return {
         ...finding(id, title, category, severity, document, remediation, details),