@adammcarter/use-cases 0.1.0

package/packages/core/dist/skills/validateSkillAssets.js

@@ -0,0 +1,218 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { diagnostic, parseYamlToJson } from "../schema/index.js";
+import { CANONICAL_SKILLS } from "./canonicalSkills.js";
+const BOOTSTRAP_SECTIONS = [
+    "When to apply",
+    "When not to apply",
+    "Trusted boundaries",
+    "Default lifecycle",
+    "Core commands",
+    "Never claim"
+];
+const KNOWN_CLI_COMMANDS = new Set([
+    "capsule list",
+    "capsule plan",
+    "capsule validate",
+    "doctor roots",
+    "doctor skills",
+    "evidence record",
+    "evidence status",
+    "evidence void",
+    "matrix list",
+    "matrix remove",
+    "matrix status",
+    "matrix upsert",
+    "matrix validate",
+    "plan showcase",
+    "plan walkthrough",
+    "showcase approve",
+    "showcase correct",
+    "showcase decide",
+    "showcase finish",
+    "showcase pause",
+    "showcase record-observation",
+    "showcase record-verdict",
+    "showcase reject",
+    "showcase resume",
+    "showcase start",
+    "showcase status",
+    "workflow mode",
+    "workflow set-mode"
+]);
+// Flat, single-segment commands (no subcommand) shipped by the marker / keyless
+// tier. A reference like `uc bind --repo ...` has a flag as its second token, so
+// it is validated by its bare command name, not a `command subcommand` pair.
+const KNOWN_FLAT_CLI_COMMANDS = new Set([
+    "init",
+    "bind",
+    "scan",
+    "verify",
+    "recover",
+    "keygen",
+    "prove",
+    "validate-ledger"
+]);
+const FORBIDDEN_PATTERNS = [
+    {
+        code: "skills.mandatory_showcase_claim",
+        pattern: /showcase\s+is\s+mandatory|required\s+showcase\s+for\s+all\s+work/i,
+        message: "Skill text must not make showcase mandatory for all work."
+    },
+    {
+        code: "skills.generated_material_claim",
+        pattern: /generated\s+(plan|walkthrough|capsule|runbook)\s+is\s+proof/i,
+        message: "Generated material must not be described as proof."
+    },
+    {
+        code: "skills.agent_user_approval_claim",
+        pattern: /agents?\s+may\s+(claim|record)\s+(user approval|user sign-off)/i,
+        message: "Agents must not be permitted to claim user approval."
+    },
+    {
+        code: "skills.host_support_claim",
+        pattern: /\bhost\s+support\s+is\s+verified\./i,
+        message: "Host support must not be claimed without evidence."
+    }
+];
+export function validateSkillAssets(options) {
+    const root = options.context.workspace_root;
+    const diagnostics = [];
+    const skills = [];
+    const commandReferences = [];
+    const skillRoot = join(root, ".agents", "skills");
+    if (!existsSync(skillRoot)) {
+        diagnostics.push(diagnostic("skills.root_missing", "Missing .agents/skills directory.", ".agents/skills"));
+    }
+    else {
+        const actualSkillNames = readdirSync(skillRoot).sort();
+        for (const expected of CANONICAL_SKILLS) {
+            if (!actualSkillNames.includes(expected)) {
+                diagnostics.push(diagnostic("skills.missing", `Missing canonical skill '${expected}'.`, `.agents/skills/${expected}/SKILL.md`, expected));
+            }
+        }
+    }
+    const names = new Set();
+    for (const skillName of CANONICAL_SKILLS) {
+        const sourcePath = `.agents/skills/${skillName}/SKILL.md`;
+        const fullPath = join(root, sourcePath);
+        if (!existsSync(fullPath)) {
+            continue;
+        }
+        const source = readFileSync(fullPath, "utf8");
+        const frontmatter = parseFrontmatter(source, sourcePath, diagnostics);
+        const name = frontmatter?.name ?? "";
+        const description = frontmatter?.description ?? "";
+        if (name !== skillName) {
+            diagnostics.push(diagnostic("skills.name_mismatch", "Skill frontmatter name must match directory name.", sourcePath, name));
+        }
+        if (!description || description.length < 40) {
+            diagnostics.push(diagnostic("skills.description_missing", "Skill description must be specific.", sourcePath, name || skillName));
+        }
+        if (name && names.has(name)) {
+            diagnostics.push(diagnostic("skills.duplicate_name", `Duplicate skill name '${name}'.`, sourcePath, name));
+        }
+        names.add(name);
+        commandReferences.push(...extractCliCommands(source, sourcePath));
+        checkForbiddenPatterns(source, sourcePath, diagnostics);
+        skills.push({
+            name,
+            path: sourcePath,
+            description,
+            complete: diagnostics.every((item) => item.entity_id !== name && item.source_path !== sourcePath)
+        });
+    }
+    const bootstrapPath = "bootstrap/use-cases.md";
+    const bootstrapFullPath = join(root, bootstrapPath);
+    const bootstrapSections = [];
+    if (!existsSync(bootstrapFullPath)) {
+        diagnostics.push(diagnostic("skills.bootstrap_missing", "Missing use-cases bootstrap.", bootstrapPath));
+    }
+    else {
+        const source = readFileSync(bootstrapFullPath, "utf8");
+        for (const section of BOOTSTRAP_SECTIONS) {
+            if (source.includes(section)) {
+                bootstrapSections.push(section);
+            }
+            else {
+                diagnostics.push(diagnostic("skills.bootstrap_section_missing", `Bootstrap missing '${section}'.`, bootstrapPath));
+            }
+        }
+        for (const phrase of ["repo data", "MCP output", "generated runbooks", "secrets", "private data"]) {
+            if (!source.includes(phrase)) {
+                diagnostics.push(diagnostic("skills.bootstrap_boundary_missing", `Bootstrap missing '${phrase}'.`, bootstrapPath));
+            }
+        }
+        commandReferences.push(...extractCliCommands(source, bootstrapPath));
+        checkForbiddenPatterns(source, bootstrapPath, diagnostics);
+    }
+    const activationPath = "docs/activation.md";
+    const activationFullPath = join(root, activationPath);
+    if (!existsSync(activationFullPath)) {
+        diagnostics.push(diagnostic("skills.activation_missing", "Missing activation docs.", activationPath));
+    }
+    else {
+        const source = readFileSync(activationFullPath, "utf8");
+        for (const marker of ["Decision Tree", "-> use-cases", "-> showcase", "-> walkthrough", "-> migration", "-> do not activate"]) {
+            if (!source.includes(marker)) {
+                diagnostics.push(diagnostic("skills.activation_tree_missing", `Activation docs missing '${marker}'.`, activationPath));
+            }
+        }
+        checkForbiddenPatterns(source, activationPath, diagnostics);
+    }
+    for (const reference of commandReferences) {
+        const bare = reference.command.split(/\s+/)[0];
+        const known = KNOWN_CLI_COMMANDS.has(reference.command) || KNOWN_FLAT_CLI_COMMANDS.has(bare);
+        if (!known) {
+            diagnostics.push(diagnostic("skills.unknown_cli_command", `Unknown CLI command '${reference.command}'.`, reference.source_path, reference.command));
+        }
+    }
+    return {
+        schema_version: 1,
+        complete: diagnostics.every((item) => item.severity !== "error"),
+        skill_count: skills.length,
+        skills,
+        bootstrap: {
+            path: bootstrapPath,
+            complete: BOOTSTRAP_SECTIONS.every((section) => bootstrapSections.includes(section)),
+            sections: bootstrapSections
+        },
+        command_references: commandReferences,
+        diagnostics
+    };
+}
+function parseFrontmatter(source, sourcePath, diagnostics) {
+    const match = source.match(/^---\n([\s\S]*?)\n---\n/);
+    if (!match) {
+        diagnostics.push(diagnostic("skills.frontmatter_missing", "Skill is missing YAML frontmatter.", sourcePath));
+        return null;
+    }
+    const parsed = parseYamlToJson(match[1], sourcePath);
+    if (!parsed.ok) {
+        diagnostics.push(...parsed.diagnostics);
+        return null;
+    }
+    const value = parsed.value;
+    return {
+        name: typeof value.name === "string" ? value.name : "",
+        description: typeof value.description === "string" ? value.description : ""
+    };
+}
+function extractCliCommands(source, sourcePath) {
+    const references = [];
+    for (const match of source.matchAll(/`(?:uc|pnpm cli --)\s+([^`]+?)`/g)) {
+        const tokens = match[1].trim().split(/\s+/);
+        if (tokens.length >= 2) {
+            references.push({ command: `${tokens[0]} ${tokens[1]}`, source_path: sourcePath });
+        }
+    }
+    return references;
+}
+function checkForbiddenPatterns(source, sourcePath, diagnostics) {
+    for (const forbidden of FORBIDDEN_PATTERNS) {
+        if (forbidden.pattern.test(source)) {
+            diagnostics.push(diagnostic(forbidden.code, forbidden.message, sourcePath));
+        }
+    }
+}
+//# sourceMappingURL=validateSkillAssets.js.map

package/packages/core/dist/skills/validateSkillAssets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateSkillAssets.js","sourceRoot":"","sources":["../../src/skills/validateSkillAssets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAChE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,UAAU,EAAE,eAAe,EAAmB,MAAM,oBAAoB,CAAC;AAElF,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,MAAM,kBAAkB,GAAG;IACzB,eAAe;IACf,mBAAmB;IACnB,oBAAoB;IACpB,mBAAmB;IACnB,eAAe;IACf,aAAa;CACL,CAAC;AACX,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC;IACjC,cAAc;IACd,cAAc;IACd,kBAAkB;IAClB,cAAc;IACd,eAAe;IACf,iBAAiB;IACjB,iBAAiB;IACjB,eAAe;IACf,aAAa;IACb,eAAe;IACf,eAAe;IACf,eAAe;IACf,iBAAiB;IACjB,eAAe;IACf,kBAAkB;IAClB,kBAAkB;IAClB,kBAAkB;IAClB,iBAAiB;IACjB,iBAAiB;IACjB,gBAAgB;IAChB,6BAA6B;IAC7B,yBAAyB;IACzB,iBAAiB;IACjB,iBAAiB;IACjB,gBAAgB;IAChB,iBAAiB;IACjB,eAAe;IACf,mBAAmB;CACpB,CAAC,CAAC;AACH,gFAAgF;AAChF,iFAAiF;AACjF,6EAA6E;AAC7E,MAAM,uBAAuB,GAAG,IAAI,GAAG,CAAC;IACtC,MAAM;IACN,MAAM;IACN,MAAM;IACN,QAAQ;IACR,SAAS;IACT,QAAQ;IACR,OAAO;IACP,iBAAiB;CAClB,CAAC,CAAC;AACH,MAAM,kBAAkB,GAA8D;IACpF;QACE,IAAI,EAAE,iCAAiC;QACvC,OAAO,EAAE,mEAAmE;QAC5E,OAAO,EAAE,2DAA2D;KACrE;IACD;QACE,IAAI,EAAE,iCAAiC;QACvC,OAAO,EAAE,8DAA8D;QACvE,OAAO,EAAE,oDAAoD;KAC9D;IACD;QACE,IAAI,EAAE,kCAAkC;QACxC,OAAO,EAAE,iEAAiE;QAC1E,OAAO,EAAE,sDAAsD;KAChE;IACD;QACE,IAAI,EAAE,2BAA2B;QACjC,OAAO,EAAE,qCAAqC;QAC9C,OAAO,EAAE,oDAAoD;KAC9D;CACF,CAAC;AAEF,MAAM,UAAU,mBAAmB,CAAC,OAA8C;IAChF,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,cAAc,CAAC;IAC5C,MAAM,WAAW,GAAiB,EAAE,CAAC;IACrC,MAAM,MAAM,GAAwB,EAAE,CAAC;IACvC,MAAM,iBAAiB,GAA4B,EAAE,CAAC;IACtD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IAElD,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC3B,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,qBAAqB,EAAE,mCAAmC,EAAE,gBAAgB,CAAC,CAAC,CAAC;IAC7G,CAAC;SAAM,CAAC;QACN,MAAM,gBAAgB,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC;QACvD,KAAK,MAAM,QAAQ,IAAI,gBAAgB,EAAE,CAAC;YACxC,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACzC,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,gBAAgB,EAAE,4BAA4B,QAAQ,IAAI,EAAE,kBAAkB,QAAQ,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;YAC5I,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,MAAM,SAAS,IAAI,gBAAgB,EAAE,CAAC;QACzC,MAAM,UAAU,GAAG,kBAAkB,SAAS,WAAW,CAAC;QAC1D,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QACxC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1B,SAAS;QACX,CAAC;QACD,MAAM,MAAM,GAAG,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC9C,MAAM,WAAW,GAAG,gBAAgB,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC;QACtE,MAAM,IAAI,GAAG,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC;QACrC,MAAM,WAAW,GAAG,WAAW,EAAE,WAAW,IAAI,EAAE,CAAC;QACnD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,sBAAsB,EAAE,mDAAmD,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC;QAC9H,CAAC;QACD,IAAI,CAAC,WAAW,IAAI,WAAW,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;YAC5C,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,4BAA4B,EAAE,qCAAqC,EAAE,UAAU,EAAE,IAAI,IAAI,SAAS,CAAC,CAAC,CAAC;QACnI,CAAC;QACD,IAAI,IAAI,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5B,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,uBAAuB,EAAE,yBAAyB,IAAI,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC;QAC7G,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChB,iBAAiB,CAAC,IAAI,CAAC,GAAG,kBAAkB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;QAClE,sBAAsB,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC;QACxD,MAAM,CAAC,IAAI,CAAC;YACV,IAAI;YACJ,IAAI,EAAE,UAAU;YAChB,WAAW;YACX,QAAQ,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,IAAI,IAAI,IAAI,CAAC,WAAW,KAAK,UAAU,CAAC;SAClG,CAAC,CAAC;IACL,CAAC;IAED,MAAM,aAAa,GAAG,wBAAwB,CAAC;IAC/C,MAAM,iBAAiB,GAAG,IAAI,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;IACpD,MAAM,iBAAiB,GAAa,EAAE,CAAC;IACvC,IAAI,CAAC,UAAU,CAAC,iBAAiB,CAAC,EAAE,CAAC;QACnC,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,0BAA0B,EAAE,8BAA8B,EAAE,aAAa,CAAC,CAAC,CAAC;IAC1G,CAAC;SAAM,CAAC;QACN,MAAM,MAAM,GAAG,YAAY,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC;QACvD,KAAK,MAAM,OAAO,IAAI,kBAAkB,EAAE,CAAC;YACzC,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC7B,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAClC,CAAC;iBAAM,CAAC;gBACN,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,kCAAkC,EAAE,sBAAsB,OAAO,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC;YACrH,CAAC;QACH,CAAC;QACD,KAAK,MAAM,MAAM,IAAI,CAAC,WAAW,EAAE,YAAY,EAAE,oBAAoB,EAAE,SAAS,EAAE,cAAc,CAAC,EAAE,CAAC;YAClG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC7B,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,mCAAmC,EAAE,sBAAsB,MAAM,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC;YACrH,CAAC;QACH,CAAC;QACD,iBAAiB,CAAC,IAAI,CAAC,GAAG,kBAAkB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;QACrE,sBAAsB,CAAC,MAAM,EAAE,aAAa,EAAE,WAAW,CAAC,CAAC;IAC7D,CAAC;IAED,MAAM,cAAc,GAAG,oBAAoB,CAAC;IAC5C,MAAM,kBAAkB,GAAG,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;IACtD,IAAI,CAAC,UAAU,CAAC,kBAAkB,CAAC,EAAE,CAAC;QACpC,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,2BAA2B,EAAE,0BAA0B,EAAE,cAAc,CAAC,CAAC,CAAC;IACxG,CAAC;SAAM,CAAC;QACN,MAAM,MAAM,GAAG,YAAY,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC;QACxD,KAAK,MAAM,MAAM,IAAI,CAAC,eAAe,EAAE,cAAc,EAAE,aAAa,EAAE,gBAAgB,EAAE,cAAc,EAAE,oBAAoB,CAAC,EAAE,CAAC;YAC9H,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC7B,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,gCAAgC,EAAE,4BAA4B,MAAM,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC;YACzH,CAAC;QACH,CAAC;QACD,sBAAsB,CAAC,MAAM,EAAE,cAAc,EAAE,WAAW,CAAC,CAAC;IAC9D,CAAC;IAED,KAAK,MAAM,SAAS,IAAI,iBAAiB,EAAE,CAAC;QAC1C,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/C,MAAM,KAAK,GAAG,kBAAkB,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,uBAAuB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC7F,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,WAAW,CAAC,IAAI,CACd,UAAU,CAAC,4BAA4B,EAAE,wBAAwB,SAAS,CAAC,OAAO,IAAI,EAAE,SAAS,CAAC,WAAW,EAAE,SAAS,CAAC,OAAO,CAAC,CAClI,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO;QACL,cAAc,EAAE,CAAC;QACjB,QAAQ,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,KAAK,OAAO,CAAC;QAChE,WAAW,EAAE,MAAM,CAAC,MAAM;QAC1B,MAAM;QACN,SAAS,EAAE;YACT,IAAI,EAAE,aAAa;YACnB,QAAQ,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,iBAAiB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YACpF,QAAQ,EAAE,iBAAiB;SAC5B;QACD,kBAAkB,EAAE,iBAAiB;QACrC,WAAW;KACZ,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CACvB,MAAc,EACd,UAAkB,EAClB,WAAyB;IAEzB,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAC;IACtD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,4BAA4B,EAAE,oCAAoC,EAAE,UAAU,CAAC,CAAC,CAAC;QAC7G,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,MAAM,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;IACrD,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,WAAW,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;QACxC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAkD,CAAC;IACxE,OAAO;QACL,IAAI,EAAE,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE;QACtD,WAAW,EAAE,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE;KAC5E,CAAC;AACJ,CAAC;AAED,SAAS,kBAAkB,CAAC,MAAc,EAAE,UAAkB;IAC5D,MAAM,UAAU,GAA4B,EAAE,CAAC;IAC/C,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,QAAQ,CAAC,kCAAkC,CAAC,EAAE,CAAC;QACxE,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC5C,IAAI,MAAM,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;YACvB,UAAU,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC,CAAC;QACrF,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,SAAS,sBAAsB,CAAC,MAAc,EAAE,UAAkB,EAAE,WAAyB;IAC3F,KAAK,MAAM,SAAS,IAAI,kBAAkB,EAAE,CAAC;QAC3C,IAAI,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACnC,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC;QAC9E,CAAC;IACH,CAAC;AACH,CAAC"}

package/packages/core/dist/useCases/integrity.d.ts

@@ -0,0 +1,11 @@
+import type { Diagnostic } from "../schema/index.js";
+import type { LoadedUseCase, MatrixFileResult, MatrixListResultData, MatrixSnapshot, MatrixValidationResultData } from "./types.js";
+export declare function buildMatrixSnapshot(input: {
+    context: MatrixSnapshot["context"];
+    files: MatrixFileResult[];
+    candidates: LoadedUseCase[];
+    diagnostics: Diagnostic[];
+}): MatrixSnapshot;
+export declare function toMatrixValidationResult(snapshot: MatrixSnapshot): MatrixValidationResultData;
+export declare function toMatrixListResult(snapshot: MatrixSnapshot, useCases: LoadedUseCase[]): MatrixListResultData;
+//# sourceMappingURL=integrity.d.ts.map

package/packages/core/dist/useCases/integrity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrity.d.ts","sourceRoot":"","sources":["../../src/useCases/integrity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAEV,aAAa,EACb,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,EAEd,0BAA0B,EAC3B,MAAM,YAAY,CAAC;AAGpB,wBAAgB,mBAAmB,CAAC,KAAK,EAAE;IACzC,OAAO,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC;IACnC,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B,GAAG,cAAc,CAgHjB;AAGD,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,cAAc,GAAG,0BAA0B,CAmB7F;AAED,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,aAAa,EAAE,GACxB,oBAAoB,CA4BtB"}

package/packages/core/dist/useCases/integrity.js

@@ -0,0 +1,178 @@
+//: @use-case: matrix.product.integrity_degraded_nonfatal
+export function buildMatrixSnapshot(input) {
+    const diagnostics = [...input.context.diagnostics, ...input.diagnostics];
+    const byId = groupByUseCaseId(input.candidates);
+    const ambiguousUseCaseIds = Array.from(byId.entries())
+        .filter(([, items]) => items.length > 1)
+        .map(([id, items]) => ({
+        entity_kind: "use_case",
+        id,
+        source_paths: items.map((item) => item.source.path).sort()
+    }))
+        .sort((left, right) => left.id.localeCompare(right.id));
+    const ambiguousIds = new Set(ambiguousUseCaseIds.map((item) => item.id));
+    const addressableUseCases = input.candidates
+        .filter((item) => !ambiguousIds.has(item.value.id))
+        .sort((left, right) => left.value.id.localeCompare(right.value.id));
+    for (const group of ambiguousUseCaseIds) {
+        diagnostics.push({
+            code: "duplicate_id",
+            severity: "error",
+            message: `Use case '${group.id}' appears in multiple files.`,
+            source_path: group.source_paths[0] ?? null,
+            json_pointer: null,
+            entity_id: group.id,
+            related_ids: group.source_paths
+        });
+    }
+    const brokenSourceIds = new Set();
+    let brokenReferences = 0;
+    for (const useCase of addressableUseCases) {
+        for (const targetId of useCase.value.related_use_cases ?? []) {
+            const target = byId.get(targetId);
+            if (!target) {
+                brokenReferences += 1;
+                brokenSourceIds.add(useCase.value.id);
+                diagnostics.push(referenceDiagnostic("broken_reference", useCase, targetId));
+            }
+            else if (target.length > 1) {
+                brokenReferences += 1;
+                brokenSourceIds.add(useCase.value.id);
+                diagnostics.push(referenceDiagnostic("ambiguous_reference", useCase, targetId));
+            }
+        }
+    }
+    const blockingDiagnosticCount = diagnostics.filter((item) => item.severity === "error").length;
+    const counts = {
+        files_discovered: input.files.length,
+        files_loaded: input.files.filter((file) => file.status === "loaded").length,
+        files_excluded: input.files.filter((file) => file.status !== "loaded").length,
+        use_case_candidates: input.candidates.length,
+        use_cases_addressable: addressableUseCases.length,
+        use_cases_ambiguous: input.candidates.filter((item) => ambiguousIds.has(item.value.id)).length,
+        use_cases_structurally_clean: addressableUseCases.filter((item) => !brokenSourceIds.has(item.value.id)).length,
+        broken_references: brokenReferences
+    };
+    const populated = input.candidates.length > 0;
+    const state = blockingDiagnosticCount === 0
+        ? "clean"
+        : addressableUseCases.length > 0
+            ? "partial"
+            : "unusable";
+    const snapshotBase = {
+        context: input.context,
+        complete: blockingDiagnosticCount === 0,
+        integrity: {
+            state,
+            populated,
+            blockingDiagnosticCount
+        },
+        files: input.files.sort((left, right) => left.path.localeCompare(right.path)),
+        candidates: input.candidates,
+        addressableUseCases,
+        ambiguousUseCaseIds,
+        diagnostics,
+        counts
+    };
+    return {
+        ...snapshotBase,
+        resolveUseCase(id) {
+            const candidates = byId.get(id);
+            if (!candidates) {
+                return { kind: "missing", id };
+            }
+            if (candidates.length > 1) {
+                return { kind: "ambiguous", id, candidates };
+            }
+            return { kind: "resolved", id, useCase: candidates[0] };
+        },
+        resolveScenario(useCaseId, scenarioId) {
+            const resolved = this.resolveUseCase(useCaseId);
+            if (resolved.kind !== "resolved") {
+                return resolved.kind === "ambiguous"
+                    ? { kind: "ambiguous", useCaseId, scenarioId, candidates: resolved.candidates }
+                    : { kind: "missing", useCaseId, scenarioId };
+            }
+            const scenarios = resolved.useCase.value.scenarios ?? [];
+            const matches = scenarios.filter((scenario) => scenario.id === scenarioId);
+            if (matches.length === 0) {
+                return { kind: "missing", useCaseId, scenarioId };
+            }
+            if (matches.length > 1) {
+                return { kind: "ambiguous", useCaseId, scenarioId, candidates: [resolved.useCase] };
+            }
+            return { kind: "resolved", useCaseId, scenarioId, useCase: resolved.useCase };
+        }
+    };
+}
+//: @use-case: end matrix.product.integrity_degraded_nonfatal
+export function toMatrixValidationResult(snapshot) {
+    return {
+        schema_version: 1,
+        complete: snapshot.complete,
+        valid: snapshot.complete,
+        integrity: {
+            state: snapshot.integrity.state,
+            populated: snapshot.integrity.populated,
+            blocking_diagnostic_count: snapshot.integrity.blockingDiagnosticCount
+        },
+        files: snapshot.files.map((file) => ({
+            path: file.path,
+            status: file.status,
+            ...(file.semantic_hash ? { semantic_hash: file.semantic_hash } : {}),
+            ...(file.file_hash ? { file_hash: file.file_hash } : {})
+        })),
+        counts: snapshot.counts,
+        ambiguous_ids: snapshot.ambiguousUseCaseIds
+    };
+}
+export function toMatrixListResult(snapshot, useCases) {
+    return {
+        schema_version: 1,
+        complete: snapshot.complete,
+        integrity: {
+            state: snapshot.integrity.state,
+            populated: snapshot.integrity.populated,
+            blocking_diagnostic_count: snapshot.integrity.blockingDiagnosticCount
+        },
+        use_cases: useCases.map((item) => ({
+            id: item.value.id,
+            title: item.value.title,
+            feature_id: item.feature.id,
+            lifecycle: item.value.lifecycle,
+            value_tier: item.value.value_tier,
+            journey_role: item.value.journey_role,
+            source_path: item.source.path,
+            semantic_hash: item.semanticHash,
+            host_surfaces: (item.value.host_applicability ?? [])
+                .filter((host) => host.supported)
+                .map((host) => host.host_surface),
+            tags: item.value.tags ?? []
+        })),
+        counts: {
+            returned: useCases.length,
+            total_addressable: snapshot.addressableUseCases.length
+        }
+    };
+}
+function groupByUseCaseId(candidates) {
+    const byId = new Map();
+    for (const candidate of candidates) {
+        const current = byId.get(candidate.value.id) ?? [];
+        current.push(candidate);
+        byId.set(candidate.value.id, current);
+    }
+    return byId;
+}
+function referenceDiagnostic(code, useCase, targetId) {
+    return {
+        code,
+        severity: "error",
+        message: `Use case '${useCase.value.id}' references ${code === "broken_reference" ? "missing" : "ambiguous"} use case '${targetId}'.`,
+        source_path: useCase.source.path,
+        json_pointer: `${useCase.source.jsonPointer}/related_use_cases`,
+        entity_id: useCase.value.id,
+        related_ids: [targetId]
+    };
+}
+//# sourceMappingURL=integrity.js.map

package/packages/core/dist/useCases/integrity.js.map

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

package/packages/core/dist/useCases/loadUseCaseMatrix.d.ts

@@ -0,0 +1,7 @@
+import type { ResolvedWorkspaceContext } from "../roots.js";
+import type { MatrixSnapshot } from "./types.js";
+export type MatrixLoadOptions = {
+    context: ResolvedWorkspaceContext;
+};
+export declare function loadUseCaseMatrix(options: MatrixLoadOptions): MatrixSnapshot;
+//# sourceMappingURL=loadUseCaseMatrix.d.ts.map

package/packages/core/dist/useCases/loadUseCaseMatrix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadUseCaseMatrix.d.ts","sourceRoot":"","sources":["../../src/useCases/loadUseCaseMatrix.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAE5D,OAAO,KAAK,EAAmC,cAAc,EAAE,MAAM,YAAY,CAAC;AAGlF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,wBAAwB,CAAC;CACnC,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,GAAG,cAAc,CA6B5E"}

package/packages/core/dist/useCases/loadUseCaseMatrix.js

@@ -0,0 +1,74 @@
+import { existsSync, lstatSync, readdirSync, realpathSync } from "node:fs";
+import { extname, isAbsolute, join, relative, sep } from "node:path";
+import { diagnostic } from "../schema/index.js";
+import { buildMatrixSnapshot } from "./integrity.js";
+import { validateUseCaseFile } from "./validateUseCaseFile.js";
+export function loadUseCaseMatrix(options) {
+    const diagnostics = [];
+    const files = [];
+    const candidates = [];
+    const root = options.context.use_cases_root;
+    if (!existsSync(root)) {
+        return buildMatrixSnapshot({
+            context: options.context,
+            files,
+            candidates,
+            diagnostics
+        });
+    }
+    const rootRealPath = realpathSync(root);
+    for (const entry of listUseCaseEntries(root, root, options.context.data_root, rootRealPath, diagnostics, files)) {
+        const result = validateUseCaseFile(entry.filePath, entry.sourcePath);
+        files.push(result.file);
+        candidates.push(...result.candidates);
+        diagnostics.push(...result.diagnostics);
+    }
+    return buildMatrixSnapshot({
+        context: options.context,
+        files,
+        candidates,
+        diagnostics
+    });
+}
+function listUseCaseEntries(root, current, dataRoot, rootRealPath, diagnostics, files) {
+    const entries = readdirSync(current, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name));
+    const results = [];
+    for (const entry of entries) {
+        const fullPath = join(current, entry.name);
+        const sourcePath = normalizeRelative(dataRoot, fullPath);
+        const stat = lstatSync(fullPath);
+        if (stat.isSymbolicLink()) {
+            files.push({ path: sourcePath, status: "symlink_rejected" });
+            diagnostics.push(diagnostic("symlink_rejected", "Symlinks under use-cases are not followed.", sourcePath));
+            continue;
+        }
+        if (stat.isDirectory()) {
+            results.push(...listUseCaseEntries(root, fullPath, dataRoot, rootRealPath, diagnostics, files));
+            continue;
+        }
+        if (!stat.isFile()) {
+            files.push({ path: sourcePath, status: "io_error" });
+            diagnostics.push(diagnostic("io_error", "Only regular files are supported under use-cases.", sourcePath));
+            continue;
+        }
+        if (![".yml", ".yaml"].includes(extname(fullPath))) {
+            continue;
+        }
+        const realPath = realpathSync(fullPath);
+        if (!isContained(rootRealPath, realPath)) {
+            files.push({ path: sourcePath, status: "path_escape" });
+            diagnostics.push(diagnostic("path_escape", "Use-case file escapes use_cases_root.", sourcePath));
+            continue;
+        }
+        results.push({ filePath: fullPath, sourcePath });
+    }
+    return results;
+}
+function normalizeRelative(root, path) {
+    return relative(root, path).split(sep).join("/");
+}
+function isContained(root, child) {
+    const relativePath = relative(root, child);
+    return relativePath === "" || (!relativePath.startsWith("..") && !isAbsolute(relativePath));
+}
+//# sourceMappingURL=loadUseCaseMatrix.js.map

package/packages/core/dist/useCases/loadUseCaseMatrix.js.map

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

package/packages/core/dist/useCases/mutateUseCaseMatrix.d.ts

@@ -0,0 +1,25 @@
+import type { ResolvedWorkspaceContext } from "../roots.js";
+import { type Diagnostic } from "../schema/index.js";
+export type UseCaseMutationOperation = "upsert" | "remove";
+export type UseCaseMutationOptions = {
+    context: ResolvedWorkspaceContext;
+    operation: UseCaseMutationOperation;
+    targetFile?: string;
+    useCaseId?: string;
+    useCase?: Record<string, unknown>;
+    expectedSemanticHash?: string;
+    reason?: string;
+    actor?: "agent" | "user" | "script" | "system";
+};
+export type UseCaseMutationResult = {
+    schema_version: 1;
+    operation: UseCaseMutationOperation;
+    status: "created" | "updated" | "removed" | "blocked";
+    use_case_id: string | null;
+    file_path: string | null;
+    before_hash: string | null;
+    after_hash: string | null;
+    diagnostics: Diagnostic[];
+};
+export declare function mutateUseCaseMatrix(options: UseCaseMutationOptions): UseCaseMutationResult;
+//# sourceMappingURL=mutateUseCaseMatrix.d.ts.map

package/packages/core/dist/useCases/mutateUseCaseMatrix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutateUseCaseMatrix.d.ts","sourceRoot":"","sources":["../../src/useCases/mutateUseCaseMatrix.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAuD,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAO1G,MAAM,MAAM,wBAAwB,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE3D,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,wBAAwB,CAAC;IAClC,SAAS,EAAE,wBAAwB,CAAC;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;CAChD,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,cAAc,EAAE,CAAC,CAAC;IAClB,SAAS,EAAE,wBAAwB,CAAC;IACpC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IACtD,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B,CAAC;AAUF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CAU1F"}