artifact-contracts 0.33.4 → 0.33.6

package/dist/cli/discover.d.ts

@@ -0,0 +1,12 @@
+export interface DiscoverOptions {
+    adapter?: string;
+    model?: string;
+    showPrompt?: boolean;
+    dryRun?: boolean;
+    write?: boolean;
+    output?: string;
+    reportFormat?: string;
+    logFile?: string;
+}
+export declare function handleDiscover(options: DiscoverOptions): Promise<void>;
+//# sourceMappingURL=discover.d.ts.map

package/dist/cli/discover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../src/cli/discover.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAUD,wBAAsB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAkE5E"}

package/dist/cli/discover.js

@@ -0,0 +1,208 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { resolve } from "node:path";
+import { stringify as yamlStringify } from "yaml";
+const EXIT_RUNTIME_MISSING = 11;
+const EXIT_ADAPTER_ERROR = 12;
+export async function handleDiscover(options) {
+    const yamlPath = resolve("artifact-contracts.yaml");
+    const mode = existsSync(yamlPath) ? "update" : "init";
+    let fileTree;
+    try {
+        fileTree = await getFileTree();
+    }
+    catch (err) {
+        process.stderr.write(`Error: ${err.message}\n`);
+        process.exit(3);
+    }
+    let existingContent;
+    if (mode === "update") {
+        try {
+            existingContent = readFileSync(yamlPath, "utf-8");
+        }
+        catch (err) {
+            process.stderr.write(`Error: ${err.message}\n`);
+            process.exit(3);
+        }
+    }
+    const metadata = getProjectMetadata();
+    const context = buildDiscoverContext({ mode, fileTree, existingContent, metadata });
+    if (options.showPrompt || options.dryRun) {
+        console.log(context);
+        return;
+    }
+    const { runAgentTask } = await import("../agents/orchestrator.js");
+    let result;
+    try {
+        result = await runAgentTask(context, "discover-artifact-definitions", {
+            adapter: options.adapter ?? "mock",
+            model: options.model,
+        }, {
+            dryRun: false,
+            failOn: "error",
+            logFile: options.logFile,
+        });
+    }
+    catch (err) {
+        const exitCode = err.exitCode;
+        if (exitCode === EXIT_RUNTIME_MISSING) {
+            process.stderr.write(err.message + "\n");
+            process.exit(EXIT_RUNTIME_MISSING);
+        }
+        if (exitCode === EXIT_ADAPTER_ERROR) {
+            process.stderr.write(`Adapter error: ${err.message}\n`);
+            process.exit(EXIT_ADAPTER_ERROR);
+        }
+        throw err;
+    }
+    const output = extractOutput(result, mode, options.reportFormat ?? "yaml");
+    if (options.write) {
+        writeFileSync(yamlPath, output, "utf-8");
+        process.stderr.write(`Written to ${yamlPath}\n`);
+    }
+    else if (options.output) {
+        writeFileSync(resolve(options.output), output, "utf-8");
+        process.stderr.write(`Written to ${options.output}\n`);
+    }
+    else {
+        console.log(output);
+    }
+}
+async function getFileTree() {
+    const cwd = process.cwd();
+    let filePaths;
+    try {
+        const output = execSync("git ls-files", {
+            encoding: "utf-8",
+            cwd,
+        });
+        filePaths = output.trim().split("\n").filter(Boolean);
+    }
+    catch {
+        try {
+            const { globSync } = await import("glob");
+            filePaths = globSync("**/*", {
+                cwd,
+                dot: true,
+                nodir: true,
+                ignore: ["node_modules/**", ".git/**"],
+            });
+        }
+        catch (err) {
+            throw new Error(`Failed to enumerate repository files: ${err.message}`);
+        }
+    }
+    return organizeFileTree(filePaths);
+}
+function organizeFileTree(filePaths) {
+    const tree = {};
+    for (const filePath of filePaths.sort()) {
+        const parts = filePath.split("/");
+        const dir = parts.length > 1 ? parts.slice(0, -1).join("/") : ".";
+        if (!tree[dir])
+            tree[dir] = [];
+        tree[dir].push(filePath);
+    }
+    const lines = [];
+    for (const dir of Object.keys(tree).sort()) {
+        lines.push(`${dir}/`);
+        for (const file of tree[dir]) {
+            lines.push(`  ${file}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+function getProjectMetadata() {
+    const pkgPath = resolve("package.json");
+    if (!existsSync(pkgPath)) {
+        return "No package.json found.";
+    }
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        const lines = [
+            `name: ${pkg.name ?? "unknown"}`,
+            pkg.description ? `description: ${pkg.description}` : "",
+            pkg.version ? `version: ${pkg.version}` : "",
+            pkg.keywords?.length ? `keywords: ${pkg.keywords.join(", ")}` : "",
+            pkg.repository?.url ? `repository: ${pkg.repository.url}` : "",
+        ];
+        return lines.filter(Boolean).join("\n");
+    }
+    catch {
+        return "package.json exists but could not be parsed.";
+    }
+}
+function buildDiscoverContext(input) {
+    const { mode, fileTree, existingContent, metadata } = input;
+    const lines = [
+        "# Artifact Discovery",
+        "",
+        `## Mode: ${mode}`,
+        mode === "init"
+            ? "Create a new artifact-contracts.yaml from scratch based on the project file structure."
+            : "Update the existing artifact-contracts.yaml by adding definitions for uncovered files. Preserve all existing artifact definitions.",
+        "",
+        "## Project Metadata",
+        "",
+        metadata,
+        "",
+        "## Repository File Tree",
+        "",
+        fileTree,
+    ];
+    if (mode === "update" && existingContent) {
+        lines.push("## Existing artifact-contracts.yaml", "", "```yaml", existingContent, "```", "");
+    }
+    lines.push("## artifact-contracts.yaml Schema Reference", "", "The generated YAML must conform to this schema:", "", "```yaml", "artifact_contracts: \"2026A\"  # or latest schema version", "", "system:", "  id: <kebab-case-system-id>", "  name: <human-readable name>", "", "artifacts:", "  <artifact-id>:  # kebab-case IDs", "    type: <artifact-type>  # e.g. source, config, generated-code, generated-doc", "    description: <optional description>", "    authority: canonical | derived | generated | control", "    manual_edit: allowed | discouraged | forbidden  # optional, defaults by authority", "    change_control: none | approval-required | regeneration-required  # optional", "    visibility: public | internal | private  # optional", "    path_patterns:  # required, at least one pattern", "      - \"glob/pattern/**\"", "    exclude_patterns:  # optional", "      - \"glob/pattern/to/exclude/**\"", "", "trace:", "  links:", "    - id: <kebab-case-link-id>", "      from: <source-artifact-id>", "      to: <target-artifact-id>", "      resolver: operationId | ast | naming | codegen", "      description: <optional description>", "```", "", "### Authority Guidelines", "", "- canonical: hand-written source of truth (source code, configs)", "- derived: generated from canonical sources but may need review (docs)", "- generated: auto-generated, should not be manually edited", "- control: governance/control files (CI, hooks)", "", "### Type Guidelines", "", "- source: application/library source code", "- config: configuration files (YAML, JSON configs)", "- generated-code: auto-generated code", "- generated-doc: auto-generated documentation", "", "### Path Pattern Rules", "", "- Use specific glob patterns, not overly broad ones like \"**/*\"", "- Group logically related files into single artifacts", "- Use exclude_patterns to omit test files, generated subdirs, etc.", "- Artifact IDs must be kebab-case", "", "### Trace Link Guidelines", "", "- Detect relationships between config/DSL artifacts and their generated outputs", "- Use resolver: codegen for build-time generation relationships", "- Use resolver: naming for convention-based relationships", "- Use resolver: ast for code-level references", "- Use resolver: operationId for API operation references", "", "## Instructions", "", "1. Analyze the file tree and group files into logical artifacts", "2. Assign appropriate type, authority, and path_patterns to each artifact", "3. Detect trace link relationships (especially config/DSL → generated code)", "4. In update mode, preserve ALL existing artifact definitions unchanged", "5. Add new artifacts only for files not covered by existing patterns", "6. Generate complete, valid artifact-contracts.yaml content", "", "## Output Format", "", "Respond with a JSON object matching the artifact-discovery-result handoff schema:", "", "```json", "{", "  \"artifact_contracts_yaml\": \"<complete YAML string for artifact-contracts.yaml>\",", "  \"decisions\": [", "    { \"artifact_id\": \"<id>\", \"reasoning\": \"<why this grouping>\" }", "  ],", "  \"trace_decisions\": [", "    { \"link_id\": \"<id>\", \"reasoning\": \"<why this trace link>\" }", "  ],", "  \"uncategorized_files\": [\"<files that could not be categorized>\"],", "  \"suggestions\": [\"<improvement suggestions>\"]", "}", "```", "", "The artifact_contracts_yaml field must contain the complete, valid YAML document.", "");
+    return lines.join("\n");
+}
+function extractOutput(result, mode, reportFormat) {
+    if (result.status === "error") {
+        const msg = result.errorMessage ?? "Unknown error";
+        if (reportFormat === "json")
+            return JSON.stringify({ error: msg }, null, 2);
+        if (reportFormat === "yaml")
+            return yamlStringify({ error: msg });
+        return `Error: ${msg}`;
+    }
+    const data = result.data;
+    if (reportFormat === "json") {
+        const jsonResult = {
+            mode,
+            artifact_contracts_yaml: data?.artifact_contracts_yaml ?? extractYamlFromRaw(result.raw),
+            decisions: data?.decisions ?? [],
+            trace_decisions: data?.trace_decisions ?? [],
+            uncategorized_files: data?.uncategorized_files ?? [],
+            suggestions: data?.suggestions ?? [],
+        };
+        return JSON.stringify(jsonResult, null, 2);
+    }
+    const yamlContent = data?.artifact_contracts_yaml ?? extractYamlFromRaw(result.raw);
+    if (reportFormat === "yaml") {
+        return yamlContent;
+    }
+    return yamlContent;
+}
+function extractYamlFromRaw(raw) {
+    if (!raw)
+        return "";
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed.artifact_contracts_yaml) {
+            return parsed.artifact_contracts_yaml;
+        }
+    }
+    catch {
+        // not JSON, try to extract YAML block
+    }
+    const yamlBlockMatch = raw.match(/```ya?ml\n([\s\S]*?)```/);
+    if (yamlBlockMatch) {
+        return yamlBlockMatch[1].trim();
+    }
+    if (raw.includes("artifact_contracts:")) {
+        return raw.trim();
+    }
+    return raw;
+}
+//# sourceMappingURL=discover.js.map

package/dist/cli/discover.js.map

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

package/dist/cli/index.js

@@ -8,6 +8,7 @@ import { handleResolve } from "./resolve.js";
 import { handleList } from "./list.js";
 import { handleExplain } from "./explain.js";
 import { handleAudit } from "./audit.js";
+import { handleDiscover } from "./discover.js";
 import { resolvedDsl } from "../generated/dsl/index.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(resolve(__dirname, "../../package.json"), "utf-8"));
@@ -31,6 +32,9 @@ const handlers = {
     audit: async (opts) => {
         await handleAudit(opts);
     },
+    discover: async (opts) => {
+        await handleDiscover(opts);
+    },
     agents: async (opts) => {
         const YAML = await import("yaml");
         const format = opts.format ?? "yaml";

package/dist/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAwB,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAExD,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CACpB,YAAY,CAAC,OAAO,CAAC,SAAS,EAAE,oBAAoB,CAAC,EAAE,OAAO,CAAC,CACzC,CAAC;AAEzB,MAAM,QAAQ,GAAoB;IAChC,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QACvB,MAAM,cAAc,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QACtB,MAAM,aAAa,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAED,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QACnB,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;QAC5B,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;YACpD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,MAAM,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAClC,CAAC;IAED,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QACpB,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QACrB,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC;QAClC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC;QACrC,IAAI,CAAC;YACH,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;gBACtB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;YACpD,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;YAC/D,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,yBAA0B,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;YACjE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;CACF,CAAC;AAEF,aAAa,CAAC,QAAQ,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAwB,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAExD,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CACpB,YAAY,CAAC,OAAO,CAAC,SAAS,EAAE,oBAAoB,CAAC,EAAE,OAAO,CAAC,CACzC,CAAC;AAEzB,MAAM,QAAQ,GAAoB;IAChC,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QACvB,MAAM,cAAc,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QACtB,MAAM,aAAa,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAED,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QACnB,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;QAC5B,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;YACpD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,MAAM,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAClC,CAAC;IAED,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QACpB,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QACvB,MAAM,cAAc,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QACrB,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC;QAClC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC;QACrC,IAAI,CAAC;YACH,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;gBACtB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;YACpD,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;YAC/D,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,yBAA0B,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;YACjE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;CACF,CAAC;AAEF,aAAa,CAAC,QAAQ,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC"}

package/dist/generated/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/generated/contract.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,aAAa,EAAE,MAAmklB,CAAC;AAEhmlB,eAAO,MAAM,iBAAiB,EAAE,MAAmk3B,CAAC"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/generated/contract.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,aAAa,EAAE,MAAk5tB,CAAC;AAE/6tB,eAAO,MAAM,iBAAiB,EAAE,MAAkukC,CAAC"}

package/dist/generated/contract.js

@@ -1,5 +1,5 @@
 // Auto-generated by cli-contracts. Do not edit.
 // Embedded contract for the extract subcommand.
-export const CONTRACT_YAML = "# yaml-language-server: $schema=./node_modules/cli-contracts/schemas/cli-contract.schema.json\ncli_contracts: 0.1.0\n\ninfo:\n  title: artifact-contracts CLI\n  version: 0.1.1\n  description: >-\n    Declarative artifact registry — define file properties, resolve\n    paths to artifact IDs, and detect definition overlaps.\n    stdout is reserved for primary output (JSON/YAML/text result);\n    all diagnostics and progress messages go to stderr.\n  license:\n    name: MIT\n  contact:\n    name: foo-log-inc\n    url: https://github.com/foo-log-inc/artifact-contracts\n\nartifact_slots:\n  artifact-definitions:\n    description: artifact-contracts.yaml definitions and config files\n    direction: read\n  repository-files:\n    description: Repository files scanned for path pattern matching and overlap detection\n    direction: read\n  audit-report:\n    description: LLM audit result output files\n    direction: write\n\ncommand_sets:\n  artifact-contracts:\n    summary: >-\n      Artifact registry CLI — validate definitions, resolve artifacts,\n      list registered entries, and explain file properties.\n    executable: artifact-contracts\n\n    global_options:\n      - name: version\n        aliases: [V]\n        description: Output the version number\n        schema:\n          type: boolean\n      - name: help\n        aliases: [h]\n        description: Display help for command\n        schema:\n          type: boolean\n\n    commands:\n      validate:\n        summary: Validate artifact-contracts definitions\n        description: >-\n          Validates artifact-contracts.yaml against the schema, checks\n          artifact ID naming conventions, ensures path_patterns are\n          non-empty, and optionally detects overlapping definitions\n          against real repository files.\n        options:\n          - name: config\n            description: Path to artifact-contracts.config.yaml\n            value_name: path\n          - name: check-files\n            description: >-\n              Scan repository files to detect path_patterns overlaps\n              that static glob analysis cannot fully determine.\n              When enabled, reads all files from git ls-files or glob.\n            schema:\n              type: boolean\n        effects:\n          risk_level: low\n          reads:\n            - artifact-definitions\n            - repository-files\n          execution_mode: normal\n        x-agent:\n          expected_duration_ms: 5000\n          retryable_exit_codes: []\n        stdout:\n          schema:\n            $ref: \"#/components/schemas/ValidationResult\"\n          description: >-\n            Validation diagnostics. On exit 0 stdout is empty (diagnostics\n            go to stderr). On exit 1/2 with --format json, structured\n            diagnostics are written to stdout.\n        exits:\n          \"0\":\n            description: Validation passed with no errors\n          \"1\":\n            description: Schema or naming convention errors detected\n          \"2\":\n            description: Overlap detected — same path matches multiple artifacts\n          \"3\":\n            description: Config or input file not found / parse error\n\n      resolve:\n        summary: Output fully-resolved artifact definitions\n        description: >-\n          Expands config variables, applies authority-based defaults\n          for manual_edit and change_control, and outputs the complete\n          resolved DSL. Default format is yaml.\n        options:\n          - name: config\n            description: Path to artifact-contracts.config.yaml\n            value_name: path\n          - name: format\n            description: \"Output format (default: yaml)\"\n            schema:\n              type: string\n              enum: [yaml, json]\n        effects:\n          risk_level: low\n          reads:\n            - artifact-definitions\n          execution_mode: normal\n        x-agent:\n          expected_duration_ms: 2000\n          retryable_exit_codes: []\n        stdout:\n          schema:\n            $ref: \"#/components/schemas/ResolvedDefinitions\"\n          description: >-\n            Fully resolved artifact definitions with authority-based\n            defaults applied. Format varies by --format (yaml default, json).\n        exits:\n          \"0\":\n            description: Successfully output resolved definitions\n          \"1\":\n            description: Error resolving definitions\n          \"3\":\n            description: Config or input file not found / parse error\n\n      list:\n        summary: List registered artifacts\n        description: >-\n          Displays all registered artifacts with optional filtering\n          by authority. Use --path for simple ID lookup; use explain\n          for full governance metadata. Default format is text.\n        options:\n          - name: config\n            description: Path to artifact-contracts.config.yaml\n            value_name: path\n          - name: authority\n            description: Filter by authority type\n            schema:\n              type: string\n              enum: [canonical, derived, generated, control]\n          - name: path\n            description: >-\n              Reverse-lookup — show artifact IDs matching this file\n              path. For full governance details, use the explain command.\n            value_name: file\n          - name: format\n            description: \"Output format (default: text)\"\n            schema:\n              type: string\n              enum: [text, json, yaml]\n        effects:\n          risk_level: low\n          reads:\n            - artifact-definitions\n          execution_mode: normal\n        x-agent:\n          expected_duration_ms: 2000\n          retryable_exit_codes: []\n        stdout:\n          schema:\n            $ref: \"#/components/schemas/ArtifactList\"\n          description: >-\n            List of matching artifacts. Schema applies to --format json\n            and --format yaml. Text format is human-readable only.\n        exits:\n          \"0\":\n            description: Successfully listed artifacts\n          \"1\":\n            description: Error reading definitions\n          \"3\":\n            description: Config or input file not found / parse error\n\n      explain:\n        summary: Explain artifact properties for a file path\n        description: >-\n          Given a file path, resolves the matching artifact and displays\n          its full governance properties — artifact ID, authority,\n          manual_edit policy, change_control, and other metadata.\n          Useful for humans and LLM agents to understand file\n          governance. Default format is text.\n        arguments:\n          - name: path\n            description: File path to explain\n            required: true\n        options:\n          - name: config\n            description: Path to artifact-contracts.config.yaml\n            value_name: path\n          - name: format\n            description: \"Output format (default: text)\"\n            schema:\n              type: string\n              enum: [text, json, yaml]\n        effects:\n          risk_level: low\n          reads:\n            - artifact-definitions\n          execution_mode: normal\n        x-agent:\n          expected_duration_ms: 2000\n          retryable_exit_codes: []\n        stdout:\n          schema:\n            $ref: \"#/components/schemas/ArtifactExplanation\"\n          description: >-\n            Artifact governance metadata for the resolved path.\n            Schema applies to --format json and --format yaml.\n            Text format is human-readable only.\n        exits:\n          \"0\":\n            description: Path resolved to an artifact\n          \"2\":\n            description: Overlap — path matches multiple artifacts\n          \"3\":\n            description: Config or input file not found / parse error\n          \"4\":\n            description: Path does not match any registered artifact\n\n      audit:\n        summary: LLM-based semantic audit of artifact definitions\n        description: >-\n          Performs semantic analysis of artifact definitions using LLM\n          to identify quality issues that static validation cannot\n          detect — naming inconsistencies, missing coverage for common\n          file types, authority mismatches, and structural improvements.\n        options:\n          - name: config\n            description: Path to artifact-contracts.config.yaml\n            value_name: path\n          - name: adapter\n            description: LLM adapter to use\n            schema:\n              type: string\n              enum: [mock, openai, claude, gemini]\n          - name: model\n            description: Model name to pass to the adapter\n          - name: show-prompt\n            description: Output the constructed prompt without calling the LLM API\n            schema:\n              type: boolean\n          - name: dry-run\n            aliases: [n]\n            description: Alias for --show-prompt (output prompt without LLM call)\n            schema:\n              type: boolean\n          - name: fail-on\n            description: >-\n              Minimum severity that causes exit 10. Ordering:\n              critical > error > warning > info. For example,\n              --fail-on warning exits 10 on warning, error, or critical.\n            schema:\n              type: string\n              enum: [info, warning, error, critical]\n          - name: output\n            aliases: [o]\n            description: Write result to a file instead of stdout\n            value_name: file\n          - name: report-format\n            description: >-\n              Output format for the report (default: text).\n              LLM commands use --report-format; deterministic\n              commands use --format.\n            schema:\n              type: string\n              enum: [text, json, yaml]\n          - name: log-file\n            aliases: [l]\n            description: Write agent progress log to this file path.\n            schema:\n              type: string\n        effects:\n          risk_level: medium\n          reads:\n            - artifact-definitions\n          writes:\n            - audit-report\n          network:\n            description: LLM API calls to configured provider\n            idempotent: false\n          execution_mode: normal\n        stdout:\n          schema:\n            $ref: \"#/components/schemas/AgentAuditResult\"\n          description: >-\n            Structured audit result conforming to the AgentAuditResult\n            schema. Format varies by --report-format (json, yaml, text).\n        x-agent:\n          dslTask: audit-artifact-definitions\n          riskLevel: low\n          requiresConfirmation: false\n          idempotent: true\n          sideEffects: [network]\n          sideEffectNote: >-\n            Makes network calls to the configured LLM provider when adapter is\n            not mock. Filesystem write only when --output is specified.\n          safeDryRunOption: show-prompt\n          expectedDurationMs: 120000\n          retryableExitCodes: [1, 12]\n          recommendedBeforeUse:\n            - \"Run with --show-prompt first to preview the prompt\"\n        exits:\n          \"0\":\n            description: Audit completed — no findings above threshold\n          \"1\":\n            description: General / transient error\n          \"3\":\n            description: Config or input file not found / parse error\n          \"10\":\n            description: Findings detected above --fail-on threshold\n          \"11\":\n            description: agent-contracts-runtime is not installed\n          \"12\":\n            description: Adapter initialization error (missing API key, etc.)\n\n      # ── agents ──────────────────────────────────────────\n      agents:\n        summary: Output the full resolved agent DSL as structured data.\n        description: >-\n          Outputs the complete resolved agent-contracts DSL (agents, tasks,\n          workflows, handoff_types) embedded in this CLI binary.\n          Useful for debugging, external tooling integration, and DSL\n          inspection.\n        options:\n          - name: format\n            aliases: [F]\n            description: Output format.\n            schema:\n              type: string\n              enum: [yaml, json]\n              default: yaml\n\n        exits:\n          '0':\n            description: DSL output successfully.\n            stdout:\n              format: text\n          '1':\n            description: Failed to load embedded DSL.\n            stderr:\n              format: text\n\n        x-agent:\n          riskLevel: low\n          requiresConfirmation: false\n          idempotent: true\n          sideEffects: []\n\n    env:\n      OPENAI_API_KEY:\n        description: >-\n          OpenAI API key. Required when --adapter openai is selected.\n        required: false\n      ANTHROPIC_API_KEY:\n        description: >-\n          Anthropic API key. Required when --adapter claude is selected.\n        required: false\n      GEMINI_API_KEY:\n        description: >-\n          Google Gemini API key. Required when --adapter gemini is selected.\n        required: false\n\ncomponents:\n  schemas:\n    AgentFinding:\n      type: object\n      properties:\n        id:\n          type: string\n        severity:\n          type: string\n          enum: [critical, error, warning, info]\n        category:\n          type: string\n        title:\n          type: string\n        description:\n          type: string\n        location:\n          type: string\n        target:\n          type: string\n        recommendation:\n          type: string\n        evidence:\n          type: array\n          items:\n            $ref: \"#/components/schemas/AgentEvidence\"\n      required: [id, severity, category, title, description]\n\n    AgentAuditResult:\n      type: object\n      properties:\n        summary:\n          type: string\n        risk_level:\n          type: string\n          enum: [none, low, medium, high, critical]\n        findings:\n          type: array\n          items:\n            $ref: \"#/components/schemas/AgentFinding\"\n        recommended_actions:\n          type: array\n          items:\n            $ref: \"#/components/schemas/AgentRecommendedAction\"\n        metadata:\n          type: object\n          properties:\n            total_artifacts:\n              type: integer\n            analyzed_artifacts:\n              type: integer\n            analysis_scope:\n              type: string\n      required: [summary, risk_level, findings, recommended_actions]\n\n    AgentEvidence:\n      type: object\n      properties:\n        kind:\n          type: string\n          enum: [schema, code, config, runtime, doc]\n        target:\n          type: string\n        location:\n          type: string\n        excerpt:\n          type: string\n        reasoning:\n          type: string\n      required: [kind]\n\n    AgentRecommendedAction:\n      type: object\n      properties:\n        action:\n          type: string\n        priority:\n          type: string\n          enum: [high, medium, low]\n        description:\n          type: string\n      required: [action, priority]\n\n    ResolvedDefinitions:\n      type: object\n      description: Output of the resolve command\n      properties:\n        artifact_contracts:\n          type: string\n        system:\n          type: object\n          properties:\n            id:\n              type: string\n            name:\n              type: string\n          required: [id]\n        artifacts:\n          type: object\n          description: Map of artifact ID to resolved artifact definition\n          additionalProperties:\n            $ref: \"#/components/schemas/ArtifactDefinition\"\n      required: [artifact_contracts, system, artifacts]\n\n    ArtifactExplanation:\n      type: object\n      description: Output of the explain command (json/yaml format)\n      properties:\n        id:\n          type: string\n        type:\n          type: string\n        authority:\n          type: string\n        manual_edit:\n          type: string\n        change_control:\n          type: string\n        visibility:\n          type: string\n        description:\n          type: string\n        path_patterns:\n          type: array\n          items:\n            type: string\n        exclude_patterns:\n          type: array\n          items:\n            type: string\n      required: [id, type, authority, manual_edit, change_control]\n\n    ArtifactDefinition:\n      type: object\n      description: A single resolved artifact definition\n      properties:\n        type:\n          type: string\n        authority:\n          type: string\n          enum: [canonical, derived, generated, control]\n        manual_edit:\n          type: string\n          enum: [allowed, discouraged, forbidden]\n        change_control:\n          type: string\n          enum: [none, approval-required, regeneration-required]\n        visibility:\n          type: string\n          enum: [public, internal, private]\n        description:\n          type: string\n        path_patterns:\n          type: array\n          items:\n            type: string\n        exclude_patterns:\n          type: array\n          items:\n            type: string\n        states:\n          type: array\n          items:\n            type: string\n      required: [type, authority, manual_edit, change_control, visibility, path_patterns]\n\n    ArtifactList:\n      type: object\n      description: Output of the list command (json/yaml format)\n      properties:\n        artifacts:\n          type: object\n          description: Map of artifact ID to resolved artifact definition\n          additionalProperties:\n            $ref: \"#/components/schemas/ArtifactDefinition\"\n\n    ValidationResult:\n      type: object\n      description: Output of the validate command (json format, on error)\n      properties:\n        valid:\n          type: boolean\n        diagnostics:\n          type: array\n          items:\n            type: object\n            properties:\n              path:\n                type: string\n              message:\n                type: string\n              severity:\n                type: string\n                enum: [error, warning]\n            required: [message, severity]\n        overlaps:\n          type: array\n          items:\n            type: object\n            properties:\n              path:\n                type: string\n              matching_artifacts:\n                type: array\n                items:\n                  type: string\n            required: [path, matching_artifacts]\n      required: [valid, diagnostics, overlaps]\n";
-export const CONTRACT_JSON_STR = "{\n  \"cli_contracts\": \"0.1.0\",\n  \"info\": {\n    \"title\": \"artifact-contracts CLI\",\n    \"version\": \"0.1.1\",\n    \"description\": \"Declarative artifact registry — define file properties, resolve paths to artifact IDs, and detect definition overlaps. stdout is reserved for primary output (JSON/YAML/text result); all diagnostics and progress messages go to stderr.\",\n    \"license\": {\n      \"name\": \"MIT\"\n    },\n    \"contact\": {\n      \"name\": \"foo-log-inc\",\n      \"url\": \"https://github.com/foo-log-inc/artifact-contracts\"\n    }\n  },\n  \"artifact_slots\": {\n    \"artifact-definitions\": {\n      \"description\": \"artifact-contracts.yaml definitions and config files\",\n      \"direction\": \"read\"\n    },\n    \"repository-files\": {\n      \"description\": \"Repository files scanned for path pattern matching and overlap detection\",\n      \"direction\": \"read\"\n    },\n    \"audit-report\": {\n      \"description\": \"LLM audit result output files\",\n      \"direction\": \"write\"\n    }\n  },\n  \"command_sets\": {\n    \"artifact-contracts\": {\n      \"summary\": \"Artifact registry CLI — validate definitions, resolve artifacts, list registered entries, and explain file properties.\",\n      \"executable\": \"artifact-contracts\",\n      \"global_options\": [\n        {\n          \"name\": \"version\",\n          \"aliases\": [\n            \"V\"\n          ],\n          \"description\": \"Output the version number\",\n          \"schema\": {\n            \"type\": \"boolean\"\n          }\n        },\n        {\n          \"name\": \"help\",\n          \"aliases\": [\n            \"h\"\n          ],\n          \"description\": \"Display help for command\",\n          \"schema\": {\n            \"type\": \"boolean\"\n          }\n        }\n      ],\n      \"commands\": {\n        \"validate\": {\n          \"summary\": \"Validate artifact-contracts definitions\",\n          \"description\": \"Validates artifact-contracts.yaml against the schema, checks artifact ID naming conventions, ensures path_patterns are non-empty, and optionally detects overlapping definitions against real repository files.\",\n          \"options\": [\n            {\n              \"name\": \"config\",\n              \"description\": \"Path to artifact-contracts.config.yaml\",\n              \"value_name\": \"path\"\n            },\n            {\n              \"name\": \"check-files\",\n              \"description\": \"Scan repository files to detect path_patterns overlaps that static glob analysis cannot fully determine. When enabled, reads all files from git ls-files or glob.\",\n              \"schema\": {\n                \"type\": \"boolean\"\n              }\n            }\n          ],\n          \"effects\": {\n            \"risk_level\": \"low\",\n            \"reads\": [\n              \"artifact-definitions\",\n              \"repository-files\"\n            ],\n            \"execution_mode\": \"normal\"\n          },\n          \"x-agent\": {\n            \"expected_duration_ms\": 5000,\n            \"retryable_exit_codes\": []\n          },\n          \"stdout\": {\n            \"schema\": {\n              \"$ref\": \"#/components/schemas/ValidationResult\"\n            },\n            \"description\": \"Validation diagnostics. On exit 0 stdout is empty (diagnostics go to stderr). On exit 1/2 with --format json, structured diagnostics are written to stdout.\"\n          },\n          \"exits\": {\n            \"0\": {\n              \"description\": \"Validation passed with no errors\"\n            },\n            \"1\": {\n              \"description\": \"Schema or naming convention errors detected\"\n            },\n            \"2\": {\n              \"description\": \"Overlap detected — same path matches multiple artifacts\"\n            },\n            \"3\": {\n              \"description\": \"Config or input file not found / parse error\"\n            }\n          }\n        },\n        \"resolve\": {\n          \"summary\": \"Output fully-resolved artifact definitions\",\n          \"description\": \"Expands config variables, applies authority-based defaults for manual_edit and change_control, and outputs the complete resolved DSL. Default format is yaml.\",\n          \"options\": [\n            {\n              \"name\": \"config\",\n              \"description\": \"Path to artifact-contracts.config.yaml\",\n              \"value_name\": \"path\"\n            },\n            {\n              \"name\": \"format\",\n              \"description\": \"Output format (default: yaml)\",\n              \"schema\": {\n                \"type\": \"string\",\n                \"enum\": [\n                  \"yaml\",\n                  \"json\"\n                ]\n              }\n            }\n          ],\n          \"effects\": {\n            \"risk_level\": \"low\",\n            \"reads\": [\n              \"artifact-definitions\"\n            ],\n            \"execution_mode\": \"normal\"\n          },\n          \"x-agent\": {\n            \"expected_duration_ms\": 2000,\n            \"retryable_exit_codes\": []\n          },\n          \"stdout\": {\n            \"schema\": {\n              \"$ref\": \"#/components/schemas/ResolvedDefinitions\"\n            },\n            \"description\": \"Fully resolved artifact definitions with authority-based defaults applied. Format varies by --format (yaml default, json).\"\n          },\n          \"exits\": {\n            \"0\": {\n              \"description\": \"Successfully output resolved definitions\"\n            },\n            \"1\": {\n              \"description\": \"Error resolving definitions\"\n            },\n            \"3\": {\n              \"description\": \"Config or input file not found / parse error\"\n            }\n          }\n        },\n        \"list\": {\n          \"summary\": \"List registered artifacts\",\n          \"description\": \"Displays all registered artifacts with optional filtering by authority. Use --path for simple ID lookup; use explain for full governance metadata. Default format is text.\",\n          \"options\": [\n            {\n              \"name\": \"config\",\n              \"description\": \"Path to artifact-contracts.config.yaml\",\n              \"value_name\": \"path\"\n            },\n            {\n              \"name\": \"authority\",\n              \"description\": \"Filter by authority type\",\n              \"schema\": {\n                \"type\": \"string\",\n                \"enum\": [\n                  \"canonical\",\n                  \"derived\",\n                  \"generated\",\n                  \"control\"\n                ]\n              }\n            },\n            {\n              \"name\": \"path\",\n              \"description\": \"Reverse-lookup — show artifact IDs matching this file path. For full governance details, use the explain command.\",\n              \"value_name\": \"file\"\n            },\n            {\n              \"name\": \"format\",\n              \"description\": \"Output format (default: text)\",\n              \"schema\": {\n                \"type\": \"string\",\n                \"enum\": [\n                  \"text\",\n                  \"json\",\n                  \"yaml\"\n                ]\n              }\n            }\n          ],\n          \"effects\": {\n            \"risk_level\": \"low\",\n            \"reads\": [\n              \"artifact-definitions\"\n            ],\n            \"execution_mode\": \"normal\"\n          },\n          \"x-agent\": {\n            \"expected_duration_ms\": 2000,\n            \"retryable_exit_codes\": []\n          },\n          \"stdout\": {\n            \"schema\": {\n              \"$ref\": \"#/components/schemas/ArtifactList\"\n            },\n            \"description\": \"List of matching artifacts. Schema applies to --format json and --format yaml. Text format is human-readable only.\"\n          },\n          \"exits\": {\n            \"0\": {\n              \"description\": \"Successfully listed artifacts\"\n            },\n            \"1\": {\n              \"description\": \"Error reading definitions\"\n            },\n            \"3\": {\n              \"description\": \"Config or input file not found / parse error\"\n            }\n          }\n        },\n        \"explain\": {\n          \"summary\": \"Explain artifact properties for a file path\",\n          \"description\": \"Given a file path, resolves the matching artifact and displays its full governance properties — artifact ID, authority, manual_edit policy, change_control, and other metadata. Useful for humans and LLM agents to understand file governance. Default format is text.\",\n          \"arguments\": [\n            {\n              \"name\": \"path\",\n              \"description\": \"File path to explain\",\n              \"required\": true\n            }\n          ],\n          \"options\": [\n            {\n              \"name\": \"config\",\n              \"description\": \"Path to artifact-contracts.config.yaml\",\n              \"value_name\": \"path\"\n            },\n            {\n              \"name\": \"format\",\n              \"description\": \"Output format (default: text)\",\n              \"schema\": {\n                \"type\": \"string\",\n                \"enum\": [\n                  \"text\",\n                  \"json\",\n                  \"yaml\"\n                ]\n              }\n            }\n          ],\n          \"effects\": {\n            \"risk_level\": \"low\",\n            \"reads\": [\n              \"artifact-definitions\"\n            ],\n            \"execution_mode\": \"normal\"\n          },\n          \"x-agent\": {\n            \"expected_duration_ms\": 2000,\n            \"retryable_exit_codes\": []\n          },\n          \"stdout\": {\n            \"schema\": {\n              \"$ref\": \"#/components/schemas/ArtifactExplanation\"\n            },\n            \"description\": \"Artifact governance metadata for the resolved path. Schema applies to --format json and --format yaml. Text format is human-readable only.\"\n          },\n          \"exits\": {\n            \"0\": {\n              \"description\": \"Path resolved to an artifact\"\n            },\n            \"2\": {\n              \"description\": \"Overlap — path matches multiple artifacts\"\n            },\n            \"3\": {\n              \"description\": \"Config or input file not found / parse error\"\n            },\n            \"4\": {\n              \"description\": \"Path does not match any registered artifact\"\n            }\n          }\n        },\n        \"audit\": {\n          \"summary\": \"LLM-based semantic audit of artifact definitions\",\n          \"description\": \"Performs semantic analysis of artifact definitions using LLM to identify quality issues that static validation cannot detect — naming inconsistencies, missing coverage for common file types, authority mismatches, and structural improvements.\",\n          \"options\": [\n            {\n              \"name\": \"config\",\n              \"description\": \"Path to artifact-contracts.config.yaml\",\n              \"value_name\": \"path\"\n            },\n            {\n              \"name\": \"adapter\",\n              \"description\": \"LLM adapter to use\",\n              \"schema\": {\n                \"type\": \"string\",\n                \"enum\": [\n                  \"mock\",\n                  \"openai\",\n                  \"claude\",\n                  \"gemini\"\n                ]\n              }\n            },\n            {\n              \"name\": \"model\",\n              \"description\": \"Model name to pass to the adapter\"\n            },\n            {\n              \"name\": \"show-prompt\",\n              \"description\": \"Output the constructed prompt without calling the LLM API\",\n              \"schema\": {\n                \"type\": \"boolean\"\n              }\n            },\n            {\n              \"name\": \"dry-run\",\n              \"aliases\": [\n                \"n\"\n              ],\n              \"description\": \"Alias for --show-prompt (output prompt without LLM call)\",\n              \"schema\": {\n                \"type\": \"boolean\"\n              }\n            },\n            {\n              \"name\": \"fail-on\",\n              \"description\": \"Minimum severity that causes exit 10. Ordering: critical > error > warning > info. For example, --fail-on warning exits 10 on warning, error, or critical.\",\n              \"schema\": {\n                \"type\": \"string\",\n                \"enum\": [\n                  \"info\",\n                  \"warning\",\n                  \"error\",\n                  \"critical\"\n                ]\n              }\n            },\n            {\n              \"name\": \"output\",\n              \"aliases\": [\n                \"o\"\n              ],\n              \"description\": \"Write result to a file instead of stdout\",\n              \"value_name\": \"file\"\n            },\n            {\n              \"name\": \"report-format\",\n              \"description\": \"Output format for the report (default: text). LLM commands use --report-format; deterministic commands use --format.\",\n              \"schema\": {\n                \"type\": \"string\",\n                \"enum\": [\n                  \"text\",\n                  \"json\",\n                  \"yaml\"\n                ]\n              }\n            },\n            {\n              \"name\": \"log-file\",\n              \"aliases\": [\n                \"l\"\n              ],\n              \"description\": \"Write agent progress log to this file path.\",\n              \"schema\": {\n                \"type\": \"string\"\n              }\n            }\n          ],\n          \"effects\": {\n            \"risk_level\": \"medium\",\n            \"reads\": [\n              \"artifact-definitions\"\n            ],\n            \"writes\": [\n              \"audit-report\"\n            ],\n            \"network\": {\n              \"description\": \"LLM API calls to configured provider\",\n              \"idempotent\": false\n            },\n            \"execution_mode\": \"normal\"\n          },\n          \"stdout\": {\n            \"schema\": {\n              \"$ref\": \"#/components/schemas/AgentAuditResult\"\n            },\n            \"description\": \"Structured audit result conforming to the AgentAuditResult schema. Format varies by --report-format (json, yaml, text).\"\n          },\n          \"x-agent\": {\n            \"dslTask\": \"audit-artifact-definitions\",\n            \"riskLevel\": \"low\",\n            \"requiresConfirmation\": false,\n            \"idempotent\": true,\n            \"sideEffects\": [\n              \"network\"\n            ],\n            \"sideEffectNote\": \"Makes network calls to the configured LLM provider when adapter is not mock. Filesystem write only when --output is specified.\",\n            \"safeDryRunOption\": \"show-prompt\",\n            \"expectedDurationMs\": 120000,\n            \"retryableExitCodes\": [\n              1,\n              12\n            ],\n            \"recommendedBeforeUse\": [\n              \"Run with --show-prompt first to preview the prompt\"\n            ]\n          },\n          \"exits\": {\n            \"0\": {\n              \"description\": \"Audit completed — no findings above threshold\"\n            },\n            \"1\": {\n              \"description\": \"General / transient error\"\n            },\n            \"3\": {\n              \"description\": \"Config or input file not found / parse error\"\n            },\n            \"10\": {\n              \"description\": \"Findings detected above --fail-on threshold\"\n            },\n            \"11\": {\n              \"description\": \"agent-contracts-runtime is not installed\"\n            },\n            \"12\": {\n              \"description\": \"Adapter initialization error (missing API key, etc.)\"\n            }\n          }\n        },\n        \"agents\": {\n          \"summary\": \"Output the full resolved agent DSL as structured data.\",\n          \"description\": \"Outputs the complete resolved agent-contracts DSL (agents, tasks, workflows, handoff_types) embedded in this CLI binary. Useful for debugging, external tooling integration, and DSL inspection.\",\n          \"options\": [\n            {\n              \"name\": \"format\",\n              \"aliases\": [\n                \"F\"\n              ],\n              \"description\": \"Output format.\",\n              \"schema\": {\n                \"type\": \"string\",\n                \"enum\": [\n                  \"yaml\",\n                  \"json\"\n                ],\n                \"default\": \"yaml\"\n              }\n            }\n          ],\n          \"exits\": {\n            \"0\": {\n              \"description\": \"DSL output successfully.\",\n              \"stdout\": {\n                \"format\": \"text\"\n              }\n            },\n            \"1\": {\n              \"description\": \"Failed to load embedded DSL.\",\n              \"stderr\": {\n                \"format\": \"text\"\n              }\n            }\n          },\n          \"x-agent\": {\n            \"riskLevel\": \"low\",\n            \"requiresConfirmation\": false,\n            \"idempotent\": true,\n            \"sideEffects\": []\n          }\n        }\n      },\n      \"env\": {\n        \"OPENAI_API_KEY\": {\n          \"description\": \"OpenAI API key. Required when --adapter openai is selected.\",\n          \"required\": false\n        },\n        \"ANTHROPIC_API_KEY\": {\n          \"description\": \"Anthropic API key. Required when --adapter claude is selected.\",\n          \"required\": false\n        },\n        \"GEMINI_API_KEY\": {\n          \"description\": \"Google Gemini API key. Required when --adapter gemini is selected.\",\n          \"required\": false\n        }\n      }\n    }\n  },\n  \"components\": {\n    \"schemas\": {\n      \"AgentFinding\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"id\": {\n            \"type\": \"string\"\n          },\n          \"severity\": {\n            \"type\": \"string\",\n            \"enum\": [\n              \"critical\",\n              \"error\",\n              \"warning\",\n              \"info\"\n            ]\n          },\n          \"category\": {\n            \"type\": \"string\"\n          },\n          \"title\": {\n            \"type\": \"string\"\n          },\n          \"description\": {\n            \"type\": \"string\"\n          },\n          \"location\": {\n            \"type\": \"string\"\n          },\n          \"target\": {\n            \"type\": \"string\"\n          },\n          \"recommendation\": {\n            \"type\": \"string\"\n          },\n          \"evidence\": {\n            \"type\": \"array\",\n            \"items\": {\n              \"$ref\": \"#/components/schemas/AgentEvidence\"\n            }\n          }\n        },\n        \"required\": [\n          \"id\",\n          \"severity\",\n          \"category\",\n          \"title\",\n          \"description\"\n        ]\n      },\n      \"AgentAuditResult\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"summary\": {\n            \"type\": \"string\"\n          },\n          \"risk_level\": {\n            \"type\": \"string\",\n            \"enum\": [\n              \"none\",\n              \"low\",\n              \"medium\",\n              \"high\",\n              \"critical\"\n            ]\n          },\n          \"findings\": {\n            \"type\": \"array\",\n            \"items\": {\n              \"$ref\": \"#/components/schemas/AgentFinding\"\n            }\n          },\n          \"recommended_actions\": {\n            \"type\": \"array\",\n            \"items\": {\n              \"$ref\": \"#/components/schemas/AgentRecommendedAction\"\n            }\n          },\n          \"metadata\": {\n            \"type\": \"object\",\n            \"properties\": {\n              \"total_artifacts\": {\n                \"type\": \"integer\"\n              },\n              \"analyzed_artifacts\": {\n                \"type\": \"integer\"\n              },\n              \"analysis_scope\": {\n                \"type\": \"string\"\n              }\n            }\n          }\n        },\n        \"required\": [\n          \"summary\",\n          \"risk_level\",\n          \"findings\",\n          \"recommended_actions\"\n        ]\n      },\n      \"AgentEvidence\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"kind\": {\n            \"type\": \"string\",\n            \"enum\": [\n              \"schema\",\n              \"code\",\n              \"config\",\n              \"runtime\",\n              \"doc\"\n            ]\n          },\n          \"target\": {\n            \"type\": \"string\"\n          },\n          \"location\": {\n            \"type\": \"string\"\n          },\n          \"excerpt\": {\n            \"type\": \"string\"\n          },\n          \"reasoning\": {\n            \"type\": \"string\"\n          }\n        },\n        \"required\": [\n          \"kind\"\n        ]\n      },\n      \"AgentRecommendedAction\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"action\": {\n            \"type\": \"string\"\n          },\n          \"priority\": {\n            \"type\": \"string\",\n            \"enum\": [\n              \"high\",\n              \"medium\",\n              \"low\"\n            ]\n          },\n          \"description\": {\n            \"type\": \"string\"\n          }\n        },\n        \"required\": [\n          \"action\",\n          \"priority\"\n        ]\n      },\n      \"ResolvedDefinitions\": {\n        \"type\": \"object\",\n        \"description\": \"Output of the resolve command\",\n        \"properties\": {\n          \"artifact_contracts\": {\n            \"type\": \"string\"\n          },\n          \"system\": {\n            \"type\": \"object\",\n            \"properties\": {\n              \"id\": {\n                \"type\": \"string\"\n              },\n              \"name\": {\n                \"type\": \"string\"\n              }\n            },\n            \"required\": [\n              \"id\"\n            ]\n          },\n          \"artifacts\": {\n            \"type\": \"object\",\n            \"description\": \"Map of artifact ID to resolved artifact definition\",\n            \"additionalProperties\": {\n              \"$ref\": \"#/components/schemas/ArtifactDefinition\"\n            }\n          }\n        },\n        \"required\": [\n          \"artifact_contracts\",\n          \"system\",\n          \"artifacts\"\n        ]\n      },\n      \"ArtifactExplanation\": {\n        \"type\": \"object\",\n        \"description\": \"Output of the explain command (json/yaml format)\",\n        \"properties\": {\n          \"id\": {\n            \"type\": \"string\"\n          },\n          \"type\": {\n            \"type\": \"string\"\n          },\n          \"authority\": {\n            \"type\": \"string\"\n          },\n          \"manual_edit\": {\n            \"type\": \"string\"\n          },\n          \"change_control\": {\n            \"type\": \"string\"\n          },\n          \"visibility\": {\n            \"type\": \"string\"\n          },\n          \"description\": {\n            \"type\": \"string\"\n          },\n          \"path_patterns\": {\n            \"type\": \"array\",\n            \"items\": {\n              \"type\": \"string\"\n            }\n          },\n          \"exclude_patterns\": {\n            \"type\": \"array\",\n            \"items\": {\n              \"type\": \"string\"\n            }\n          }\n        },\n        \"required\": [\n          \"id\",\n          \"type\",\n          \"authority\",\n          \"manual_edit\",\n          \"change_control\"\n        ]\n      },\n      \"ArtifactDefinition\": {\n        \"type\": \"object\",\n        \"description\": \"A single resolved artifact definition\",\n        \"properties\": {\n          \"type\": {\n            \"type\": \"string\"\n          },\n          \"authority\": {\n            \"type\": \"string\",\n            \"enum\": [\n              \"canonical\",\n              \"derived\",\n              \"generated\",\n              \"control\"\n            ]\n          },\n          \"manual_edit\": {\n            \"type\": \"string\",\n            \"enum\": [\n              \"allowed\",\n              \"discouraged\",\n              \"forbidden\"\n            ]\n          },\n          \"change_control\": {\n            \"type\": \"string\",\n            \"enum\": [\n              \"none\",\n              \"approval-required\",\n              \"regeneration-required\"\n            ]\n          },\n          \"visibility\": {\n            \"type\": \"string\",\n            \"enum\": [\n              \"public\",\n              \"internal\",\n              \"private\"\n            ]\n          },\n          \"description\": {\n            \"type\": \"string\"\n          },\n          \"path_patterns\": {\n            \"type\": \"array\",\n            \"items\": {\n              \"type\": \"string\"\n            }\n          },\n          \"exclude_patterns\": {\n            \"type\": \"array\",\n            \"items\": {\n              \"type\": \"string\"\n            }\n          },\n          \"states\": {\n            \"type\": \"array\",\n            \"items\": {\n              \"type\": \"string\"\n            }\n          }\n        },\n        \"required\": [\n          \"type\",\n          \"authority\",\n          \"manual_edit\",\n          \"change_control\",\n          \"visibility\",\n          \"path_patterns\"\n        ]\n      },\n      \"ArtifactList\": {\n        \"type\": \"object\",\n        \"description\": \"Output of the list command (json/yaml format)\",\n        \"properties\": {\n          \"artifacts\": {\n            \"type\": \"object\",\n            \"description\": \"Map of artifact ID to resolved artifact definition\",\n            \"additionalProperties\": {\n              \"$ref\": \"#/components/schemas/ArtifactDefinition\"\n            }\n          }\n        }\n      },\n      \"ValidationResult\": {\n        \"type\": \"object\",\n        \"description\": \"Output of the validate command (json format, on error)\",\n        \"properties\": {\n          \"valid\": {\n            \"type\": \"boolean\"\n          },\n          \"diagnostics\": {\n            \"type\": \"array\",\n            \"items\": {\n              \"type\": \"object\",\n              \"properties\": {\n                \"path\": {\n                  \"type\": \"string\"\n                },\n                \"message\": {\n                  \"type\": \"string\"\n                },\n                \"severity\": {\n                  \"type\": \"string\",\n                  \"enum\": [\n                    \"error\",\n                    \"warning\"\n                  ]\n                }\n              },\n              \"required\": [\n                \"message\",\n                \"severity\"\n              ]\n            }\n          },\n          \"overlaps\": {\n            \"type\": \"array\",\n            \"items\": {\n              \"type\": \"object\",\n              \"properties\": {\n                \"path\": {\n                  \"type\": \"string\"\n                },\n                \"matching_artifacts\": {\n                  \"type\": \"array\",\n                  \"items\": {\n                    \"type\": \"string\"\n                  }\n                }\n              },\n              \"required\": [\n                \"path\",\n                \"matching_artifacts\"\n              ]\n            }\n          }\n        },\n        \"required\": [\n          \"valid\",\n          \"diagnostics\",\n          \"overlaps\"\n        ]\n      }\n    }\n  }\n}";
+export const CONTRACT_YAML = "# yaml-language-server: $schema=./node_modules/cli-contracts/schemas/cli-contract.schema.json\ncli_contracts: 0.1.0\n\ninfo:\n  title: artifact-contracts CLI\n  version: 0.1.1\n  description: >-\n    Declarative artifact registry — define file properties, resolve\n    paths to artifact IDs, and detect definition overlaps.\n    stdout is reserved for primary output (JSON/YAML/text result);\n    all diagnostics and progress messages go to stderr.\n  license:\n    name: MIT\n  contact:\n    name: foo-log-inc\n    url: https://github.com/foo-log-inc/artifact-contracts\n\nartifact_slots:\n  artifact-definitions:\n    description: artifact-contracts.yaml definitions and config files\n    direction: read\n  repository-files:\n    description: Repository files scanned for path pattern matching and overlap detection\n    direction: read\n  audit-report:\n    description: LLM audit result output files\n    direction: write\n\ncommand_sets:\n  artifact-contracts:\n    summary: >-\n      Artifact registry CLI — validate definitions, resolve artifacts,\n      list registered entries, and explain file properties.\n    executable: artifact-contracts\n\n    global_options:\n      - name: version\n        aliases: [V]\n        description: Output the version number\n        schema:\n          type: boolean\n      - name: help\n        aliases: [h]\n        description: Display help for command\n        schema:\n          type: boolean\n\n    commands:\n      validate:\n        summary: Validate artifact-contracts definitions\n        description: >-\n          Validates artifact-contracts.yaml against the schema, checks\n          artifact ID naming conventions, ensures path_patterns are\n          non-empty, and optionally detects overlapping definitions\n          against real repository files.\n        options:\n          - name: config\n            description: Path to artifact-contracts.config.yaml\n            value_name: path\n          - name: check-files\n            description: >-\n              Scan repository files to detect path_patterns overlaps\n              that static glob analysis cannot fully determine.\n              When enabled, reads all files from git ls-files or glob.\n            schema:\n              type: boolean\n        effects:\n          risk_level: low\n          reads:\n            - artifact-definitions\n            - repository-files\n          execution_mode: normal\n        x-agent:\n          expected_duration_ms: 5000\n          retryable_exit_codes: []\n        stdout:\n          schema:\n            $ref: \"#/components/schemas/ValidationResult\"\n          description: >-\n            Validation diagnostics. On exit 0 stdout is empty (diagnostics\n            go to stderr). On exit 1/2 with --format json, structured\n            diagnostics are written to stdout.\n        exits:\n          \"0\":\n            description: Validation passed with no errors\n          \"1\":\n            description: Schema or naming convention errors detected\n          \"2\":\n            description: Overlap detected — same path matches multiple artifacts\n          \"3\":\n            description: Config or input file not found / parse error\n\n      resolve:\n        summary: Output fully-resolved artifact definitions\n        description: >-\n          Expands config variables, applies authority-based defaults\n          for manual_edit and change_control, and outputs the complete\n          resolved DSL. Default format is yaml.\n        options:\n          - name: config\n            description: Path to artifact-contracts.config.yaml\n            value_name: path\n          - name: format\n            description: \"Output format (default: yaml)\"\n            schema:\n              type: string\n              enum: [yaml, json]\n        effects:\n          risk_level: low\n          reads:\n            - artifact-definitions\n          execution_mode: normal\n        x-agent:\n          expected_duration_ms: 2000\n          retryable_exit_codes: []\n        stdout:\n          schema:\n            $ref: \"#/components/schemas/ResolvedDefinitions\"\n          description: >-\n            Fully resolved artifact definitions with authority-based\n            defaults applied. Format varies by --format (yaml default, json).\n        exits:\n          \"0\":\n            description: Successfully output resolved definitions\n          \"1\":\n            description: Error resolving definitions\n          \"3\":\n            description: Config or input file not found / parse error\n\n      list:\n        summary: List registered artifacts\n        description: >-\n          Displays all registered artifacts with optional filtering\n          by authority. Use --path for simple ID lookup; use explain\n          for full governance metadata. Default format is text.\n        options:\n          - name: config\n            description: Path to artifact-contracts.config.yaml\n            value_name: path\n          - name: authority\n            description: Filter by authority type\n            schema:\n              type: string\n              enum: [canonical, derived, generated, control]\n          - name: path\n            description: >-\n              Reverse-lookup — show artifact IDs matching this file\n              path. For full governance details, use the explain command.\n            value_name: file\n          - name: format\n            description: \"Output format (default: text)\"\n            schema:\n              type: string\n              enum: [text, json, yaml]\n        effects:\n          risk_level: low\n          reads:\n            - artifact-definitions\n          execution_mode: normal\n        x-agent:\n          expected_duration_ms: 2000\n          retryable_exit_codes: []\n        stdout:\n          schema:\n            $ref: \"#/components/schemas/ArtifactList\"\n          description: >-\n            List of matching artifacts. Schema applies to --format json\n            and --format yaml. Text format is human-readable only.\n        exits:\n          \"0\":\n            description: Successfully listed artifacts\n          \"1\":\n            description: Error reading definitions\n          \"3\":\n            description: Config or input file not found / parse error\n\n      explain:\n        summary: Explain artifact properties for a file path\n        description: >-\n          Given a file path, resolves the matching artifact and displays\n          its full governance properties — artifact ID, authority,\n          manual_edit policy, change_control, and other metadata.\n          Useful for humans and LLM agents to understand file\n          governance. Default format is text.\n        arguments:\n          - name: path\n            description: File path to explain\n            required: true\n        options:\n          - name: config\n            description: Path to artifact-contracts.config.yaml\n            value_name: path\n          - name: format\n            description: \"Output format (default: text)\"\n            schema:\n              type: string\n              enum: [text, json, yaml]\n        effects:\n          risk_level: low\n          reads:\n            - artifact-definitions\n          execution_mode: normal\n        x-agent:\n          expected_duration_ms: 2000\n          retryable_exit_codes: []\n        stdout:\n          schema:\n            $ref: \"#/components/schemas/ArtifactExplanation\"\n          description: >-\n            Artifact governance metadata for the resolved path.\n            Schema applies to --format json and --format yaml.\n            Text format is human-readable only.\n        exits:\n          \"0\":\n            description: Path resolved to an artifact\n          \"2\":\n            description: Overlap — path matches multiple artifacts\n          \"3\":\n            description: Config or input file not found / parse error\n          \"4\":\n            description: Path does not match any registered artifact\n\n      audit:\n        summary: LLM-based semantic audit of artifact definitions\n        description: >-\n          Performs semantic analysis of artifact definitions using LLM\n          to identify quality issues that static validation cannot\n          detect — naming inconsistencies, missing coverage for common\n          file types, authority mismatches, and structural improvements.\n        options:\n          - name: config\n            description: Path to artifact-contracts.config.yaml\n            value_name: path\n          - name: adapter\n            description: LLM adapter to use\n            schema:\n              type: string\n              enum: [mock, openai, claude, gemini]\n          - name: model\n            description: Model name to pass to the adapter\n          - name: show-prompt\n            description: Output the constructed prompt without calling the LLM API\n            schema:\n              type: boolean\n          - name: dry-run\n            aliases: [n]\n            description: Alias for --show-prompt (output prompt without LLM call)\n            schema:\n              type: boolean\n          - name: fail-on\n            description: >-\n              Minimum severity that causes exit 10. Ordering:\n              critical > error > warning > info. For example,\n              --fail-on warning exits 10 on warning, error, or critical.\n            schema:\n              type: string\n              enum: [info, warning, error, critical]\n          - name: output\n            aliases: [o]\n            description: Write result to a file instead of stdout\n            value_name: file\n          - name: report-format\n            description: >-\n              Output format for the report (default: text).\n              LLM commands use --report-format; deterministic\n              commands use --format.\n            schema:\n              type: string\n              enum: [text, json, yaml]\n          - name: log-file\n            aliases: [l]\n            description: Write agent progress log to this file path.\n            schema:\n              type: string\n        effects:\n          risk_level: medium\n          reads:\n            - artifact-definitions\n          writes:\n            - audit-report\n          network:\n            description: LLM API calls to configured provider\n            idempotent: false\n          execution_mode: normal\n        stdout:\n          schema:\n            $ref: \"#/components/schemas/AgentAuditResult\"\n          description: >-\n            Structured audit result conforming to the AgentAuditResult\n            schema. Format varies by --report-format (json, yaml, text).\n        x-agent:\n          dslTask: audit-artifact-definitions\n          riskLevel: low\n          requiresConfirmation: false\n          idempotent: true\n          sideEffects: [network]\n          sideEffectNote: >-\n            Makes network calls to the configured LLM provider when adapter is\n            not mock. Filesystem write only when --output is specified.\n          safeDryRunOption: show-prompt\n          expectedDurationMs: 120000\n          retryableExitCodes: [1, 12]\n          recommendedBeforeUse:\n            - \"Run with --show-prompt first to preview the prompt\"\n        exits:\n          \"0\":\n            description: Audit completed — no findings above threshold\n          \"1\":\n            description: General / transient error\n          \"3\":\n            description: Config or input file not found / parse error\n          \"10\":\n            description: Findings detected above --fail-on threshold\n          \"11\":\n            description: agent-contracts-runtime is not installed\n          \"12\":\n            description: Adapter initialization error (missing API key, etc.)\n\n      discover:\n        summary: LLM-based artifact discovery from project file structure\n        description: >-\n          Analyzes the project file structure using LLM to generate or update\n          artifact-contracts.yaml definitions. In init mode (no existing file),\n          creates a new registry from scratch. In update mode (existing file),\n          proposes additional artifact definitions and trace link rules for\n          uncovered files.\n        options:\n          - name: adapter\n            description: LLM adapter to use\n            schema:\n              type: string\n              enum: [mock, openai, claude, gemini]\n          - name: model\n            description: Model name to pass to the adapter\n          - name: show-prompt\n            description: Output the constructed prompt without calling the LLM API\n            schema:\n              type: boolean\n          - name: dry-run\n            aliases: [n]\n            description: Alias for --show-prompt (output prompt without LLM call)\n            schema:\n              type: boolean\n          - name: write\n            aliases: [w]\n            description: Write the generated YAML directly to artifact-contracts.yaml\n            schema:\n              type: boolean\n          - name: output\n            aliases: [o]\n            description: Write result to a specific file path instead of stdout\n            value_name: file\n          - name: report-format\n            description: \"Output format (default: yaml)\"\n            schema:\n              type: string\n              enum: [yaml, json]\n          - name: log-file\n            aliases: [l]\n            description: Write agent progress log to this file path.\n            schema:\n              type: string\n        effects:\n          risk_level: medium\n          reads:\n            - artifact-definitions\n            - repository-files\n          writes:\n            - artifact-definitions\n          network:\n            description: LLM API calls to configured provider\n            idempotent: false\n          execution_mode: normal\n        stdout:\n          schema:\n            $ref: \"#/components/schemas/DiscoverResult\"\n          description: >-\n            Generated artifact-contracts.yaml content or structured discovery result.\n        x-agent:\n          dslTask: discover-artifact-definitions\n          riskLevel: low\n          requiresConfirmation: false\n          idempotent: true\n          sideEffects: [network]\n          sideEffectNote: >-\n            Makes network calls to the configured LLM provider when adapter is\n            not mock. Filesystem write only when --write or --output is specified.\n          safeDryRunOption: show-prompt\n          expectedDurationMs: 120000\n          retryableExitCodes: [1, 12]\n          recommendedBeforeUse:\n            - \"Run with --show-prompt first to preview the prompt\"\n        exits:\n          \"0\":\n            description: Discovery completed successfully\n          \"1\":\n            description: General / transient error\n          \"3\":\n            description: File system read error\n          \"11\":\n            description: agent-contracts-runtime is not installed\n          \"12\":\n            description: Adapter initialization error (missing API key, etc.)\n\n      # ── agents ──────────────────────────────────────────\n      agents:\n        summary: Output the full resolved agent DSL as structured data.\n        description: >-\n          Outputs the complete resolved agent-contracts DSL (agents, tasks,\n          workflows, handoff_types) embedded in this CLI binary.\n          Useful for debugging, external tooling integration, and DSL\n          inspection.\n        options:\n          - name: format\n            aliases: [F]\n            description: Output format.\n            schema:\n              type: string\n              enum: [yaml, json]\n              default: yaml\n\n        exits:\n          '0':\n            description: DSL output successfully.\n            stdout:\n              format: text\n          '1':\n            description: Failed to load embedded DSL.\n            stderr:\n              format: text\n\n        x-agent:\n          riskLevel: low\n          requiresConfirmation: false\n          idempotent: true\n          sideEffects: []\n\n    env:\n      OPENAI_API_KEY:\n        description: >-\n          OpenAI API key. Required when --adapter openai is selected.\n        required: false\n      ANTHROPIC_API_KEY:\n        description: >-\n          Anthropic API key. Required when --adapter claude is selected.\n        required: false\n      GEMINI_API_KEY:\n        description: >-\n          Google Gemini API key. Required when --adapter gemini is selected.\n        required: false\n\ncomponents:\n  schemas:\n    AgentFinding:\n      type: object\n      properties:\n        id:\n          type: string\n        severity:\n          type: string\n          enum: [critical, error, warning, info]\n        category:\n          type: string\n        title:\n          type: string\n        description:\n          type: string\n        location:\n          type: string\n        target:\n          type: string\n        recommendation:\n          type: string\n        evidence:\n          type: array\n          items:\n            $ref: \"#/components/schemas/AgentEvidence\"\n      required: [id, severity, category, title, description]\n\n    AgentAuditResult:\n      type: object\n      properties:\n        summary:\n          type: string\n        risk_level:\n          type: string\n          enum: [none, low, medium, high, critical]\n        findings:\n          type: array\n          items:\n            $ref: \"#/components/schemas/AgentFinding\"\n        recommended_actions:\n          type: array\n          items:\n            $ref: \"#/components/schemas/AgentRecommendedAction\"\n        metadata:\n          type: object\n          properties:\n            total_artifacts:\n              type: integer\n            analyzed_artifacts:\n              type: integer\n            analysis_scope:\n              type: string\n      required: [summary, risk_level, findings, recommended_actions]\n\n    AgentEvidence:\n      type: object\n      properties:\n        kind:\n          type: string\n          enum: [schema, code, config, runtime, doc]\n        target:\n          type: string\n        location:\n          type: string\n        excerpt:\n          type: string\n        reasoning:\n          type: string\n      required: [kind]\n\n    AgentRecommendedAction:\n      type: object\n      properties:\n        action:\n          type: string\n        priority:\n          type: string\n          enum: [high, medium, low]\n        description:\n          type: string\n      required: [action, priority]\n\n    ResolvedDefinitions:\n      type: object\n      description: Output of the resolve command\n      properties:\n        artifact_contracts:\n          type: string\n        system:\n          type: object\n          properties:\n            id:\n              type: string\n            name:\n              type: string\n          required: [id]\n        artifacts:\n          type: object\n          description: Map of artifact ID to resolved artifact definition\n          additionalProperties:\n            $ref: \"#/components/schemas/ArtifactDefinition\"\n      required: [artifact_contracts, system, artifacts]\n\n    ArtifactExplanation:\n      type: object\n      description: Output of the explain command (json/yaml format)\n      properties:\n        id:\n          type: string\n        type:\n          type: string\n        authority:\n          type: string\n        manual_edit:\n          type: string\n        change_control:\n          type: string\n        visibility:\n          type: string\n        description:\n          type: string\n        path_patterns:\n          type: array\n          items:\n            type: string\n        exclude_patterns:\n          type: array\n          items:\n            type: string\n      required: [id, type, authority, manual_edit, change_control]\n\n    ArtifactDefinition:\n      type: object\n      description: A single resolved artifact definition\n      properties:\n        type:\n          type: string\n        authority:\n          type: string\n          enum: [canonical, derived, generated, control]\n        manual_edit:\n          type: string\n          enum: [allowed, discouraged, forbidden]\n        change_control:\n          type: string\n          enum: [none, approval-required, regeneration-required]\n        visibility:\n          type: string\n          enum: [public, internal, private]\n        description:\n          type: string\n        path_patterns:\n          type: array\n          items:\n            type: string\n        exclude_patterns:\n          type: array\n          items:\n            type: string\n        states:\n          type: array\n          items:\n            type: string\n      required: [type, authority, manual_edit, change_control, visibility, path_patterns]\n\n    ArtifactList:\n      type: object\n      description: Output of the list command (json/yaml format)\n      properties:\n        artifacts:\n          type: object\n          description: Map of artifact ID to resolved artifact definition\n          additionalProperties:\n            $ref: \"#/components/schemas/ArtifactDefinition\"\n\n    DiscoverResult:\n      type: object\n      description: Output of the discover command\n      properties:\n        mode:\n          type: string\n          enum: [init, update]\n        artifact_contracts_yaml:\n          type: string\n          description: Generated YAML content\n        decisions:\n          type: array\n          items:\n            type: object\n            properties:\n              artifact_id:\n                type: string\n              reasoning:\n                type: string\n            required: [artifact_id, reasoning]\n        trace_decisions:\n          type: array\n          items:\n            type: object\n            properties:\n              link_id:\n                type: string\n              reasoning:\n                type: string\n            required: [link_id, reasoning]\n        uncategorized_files:\n          type: array\n          items:\n            type: string\n        suggestions:\n          type: array\n          items:\n            type: string\n      required: [mode, artifact_contracts_yaml]\n\n    ValidationResult:\n      type: object\n      description: Output of the validate command (json format, on error)\n      properties:\n        valid:\n          type: boolean\n        diagnostics:\n          type: array\n          items:\n            type: object\n            properties:\n              path:\n                type: string\n              message:\n                type: string\n              severity:\n                type: string\n                enum: [error, warning]\n            required: [message, severity]\n        overlaps:\n          type: array\n          items:\n            type: object\n            properties:\n              path:\n                type: string\n              matching_artifacts:\n                type: array\n                items:\n                  type: string\n            required: [path, matching_artifacts]\n      required: [valid, diagnostics, overlaps]\n";
+export const CONTRACT_JSON_STR = "{\n  \"cli_contracts\": \"0.1.0\",\n  \"info\": {\n    \"title\": \"artifact-contracts CLI\",\n    \"version\": \"0.1.1\",\n    \"description\": \"Declarative artifact registry — define file properties, resolve paths to artifact IDs, and detect definition overlaps. stdout is reserved for primary output (JSON/YAML/text result); all diagnostics and progress messages go to stderr.\",\n    \"license\": {\n      \"name\": \"MIT\"\n    },\n    \"contact\": {\n      \"name\": \"foo-log-inc\",\n      \"url\": \"https://github.com/foo-log-inc/artifact-contracts\"\n    }\n  },\n  \"artifact_slots\": {\n    \"artifact-definitions\": {\n      \"description\": \"artifact-contracts.yaml definitions and config files\",\n      \"direction\": \"read\"\n    },\n    \"repository-files\": {\n      \"description\": \"Repository files scanned for path pattern matching and overlap detection\",\n      \"direction\": \"read\"\n    },\n    \"audit-report\": {\n      \"description\": \"LLM audit result output files\",\n      \"direction\": \"write\"\n    }\n  },\n  \"command_sets\": {\n    \"artifact-contracts\": {\n      \"summary\": \"Artifact registry CLI — validate definitions, resolve artifacts, list registered entries, and explain file properties.\",\n      \"executable\": \"artifact-contracts\",\n      \"global_options\": [\n        {\n          \"name\": \"version\",\n          \"aliases\": [\n            \"V\"\n          ],\n          \"description\": \"Output the version number\",\n          \"schema\": {\n            \"type\": \"boolean\"\n          }\n        },\n        {\n          \"name\": \"help\",\n          \"aliases\": [\n            \"h\"\n          ],\n          \"description\": \"Display help for command\",\n          \"schema\": {\n            \"type\": \"boolean\"\n          }\n        }\n      ],\n      \"commands\": {\n        \"validate\": {\n          \"summary\": \"Validate artifact-contracts definitions\",\n          \"description\": \"Validates artifact-contracts.yaml against the schema, checks artifact ID naming conventions, ensures path_patterns are non-empty, and optionally detects overlapping definitions against real repository files.\",\n          \"options\": [\n            {\n              \"name\": \"config\",\n              \"description\": \"Path to artifact-contracts.config.yaml\",\n              \"value_name\": \"path\"\n            },\n            {\n              \"name\": \"check-files\",\n              \"description\": \"Scan repository files to detect path_patterns overlaps that static glob analysis cannot fully determine. When enabled, reads all files from git ls-files or glob.\",\n              \"schema\": {\n                \"type\": \"boolean\"\n              }\n            }\n          ],\n          \"effects\": {\n            \"risk_level\": \"low\",\n            \"reads\": [\n              \"artifact-definitions\",\n              \"repository-files\"\n            ],\n            \"execution_mode\": \"normal\"\n          },\n          \"x-agent\": {\n            \"expected_duration_ms\": 5000,\n            \"retryable_exit_codes\": []\n          },\n          \"stdout\": {\n            \"schema\": {\n              \"$ref\": \"#/components/schemas/ValidationResult\"\n            },\n            \"description\": \"Validation diagnostics. On exit 0 stdout is empty (diagnostics go to stderr). On exit 1/2 with --format json, structured diagnostics are written to stdout.\"\n          },\n          \"exits\": {\n            \"0\": {\n              \"description\": \"Validation passed with no errors\"\n            },\n            \"1\": {\n              \"description\": \"Schema or naming convention errors detected\"\n            },\n            \"2\": {\n              \"description\": \"Overlap detected — same path matches multiple artifacts\"\n            },\n            \"3\": {\n              \"description\": \"Config or input file not found / parse error\"\n            }\n          }\n        },\n        \"resolve\": {\n          \"summary\": \"Output fully-resolved artifact definitions\",\n          \"description\": \"Expands config variables, applies authority-based defaults for manual_edit and change_control, and outputs the complete resolved DSL. Default format is yaml.\",\n          \"options\": [\n            {\n              \"name\": \"config\",\n              \"description\": \"Path to artifact-contracts.config.yaml\",\n              \"value_name\": \"path\"\n            },\n            {\n              \"name\": \"format\",\n              \"description\": \"Output format (default: yaml)\",\n              \"schema\": {\n                \"type\": \"string\",\n                \"enum\": [\n                  \"yaml\",\n                  \"json\"\n                ]\n              }\n            }\n          ],\n          \"effects\": {\n            \"risk_level\": \"low\",\n            \"reads\": [\n              \"artifact-definitions\"\n            ],\n            \"execution_mode\": \"normal\"\n          },\n          \"x-agent\": {\n            \"expected_duration_ms\": 2000,\n            \"retryable_exit_codes\": []\n          },\n          \"stdout\": {\n            \"schema\": {\n              \"$ref\": \"#/components/schemas/ResolvedDefinitions\"\n            },\n            \"description\": \"Fully resolved artifact definitions with authority-based defaults applied. Format varies by --format (yaml default, json).\"\n          },\n          \"exits\": {\n            \"0\": {\n              \"description\": \"Successfully output resolved definitions\"\n            },\n            \"1\": {\n              \"description\": \"Error resolving definitions\"\n            },\n            \"3\": {\n              \"description\": \"Config or input file not found / parse error\"\n            }\n          }\n        },\n        \"list\": {\n          \"summary\": \"List registered artifacts\",\n          \"description\": \"Displays all registered artifacts with optional filtering by authority. Use --path for simple ID lookup; use explain for full governance metadata. Default format is text.\",\n          \"options\": [\n            {\n              \"name\": \"config\",\n              \"description\": \"Path to artifact-contracts.config.yaml\",\n              \"value_name\": \"path\"\n            },\n            {\n              \"name\": \"authority\",\n              \"description\": \"Filter by authority type\",\n              \"schema\": {\n                \"type\": \"string\",\n                \"enum\": [\n                  \"canonical\",\n                  \"derived\",\n                  \"generated\",\n                  \"control\"\n                ]\n              }\n            },\n            {\n              \"name\": \"path\",\n              \"description\": \"Reverse-lookup — show artifact IDs matching this file path. For full governance details, use the explain command.\",\n              \"value_name\": \"file\"\n            },\n            {\n              \"name\": \"format\",\n              \"description\": \"Output format (default: text)\",\n              \"schema\": {\n                \"type\": \"string\",\n                \"enum\": [\n                  \"text\",\n                  \"json\",\n                  \"yaml\"\n                ]\n              }\n            }\n          ],\n          \"effects\": {\n            \"risk_level\": \"low\",\n            \"reads\": [\n              \"artifact-definitions\"\n            ],\n            \"execution_mode\": \"normal\"\n          },\n          \"x-agent\": {\n            \"expected_duration_ms\": 2000,\n            \"retryable_exit_codes\": []\n          },\n          \"stdout\": {\n            \"schema\": {\n              \"$ref\": \"#/components/schemas/ArtifactList\"\n            },\n            \"description\": \"List of matching artifacts. Schema applies to --format json and --format yaml. Text format is human-readable only.\"\n          },\n          \"exits\": {\n            \"0\": {\n              \"description\": \"Successfully listed artifacts\"\n            },\n            \"1\": {\n              \"description\": \"Error reading definitions\"\n            },\n            \"3\": {\n              \"description\": \"Config or input file not found / parse error\"\n            }\n          }\n        },\n        \"explain\": {\n          \"summary\": \"Explain artifact properties for a file path\",\n          \"description\": \"Given a file path, resolves the matching artifact and displays its full governance properties — artifact ID, authority, manual_edit policy, change_control, and other metadata. Useful for humans and LLM agents to understand file governance. Default format is text.\",\n          \"arguments\": [\n            {\n              \"name\": \"path\",\n              \"description\": \"File path to explain\",\n              \"required\": true\n            }\n          ],\n          \"options\": [\n            {\n              \"name\": \"config\",\n              \"description\": \"Path to artifact-contracts.config.yaml\",\n              \"value_name\": \"path\"\n            },\n            {\n              \"name\": \"format\",\n              \"description\": \"Output format (default: text)\",\n              \"schema\": {\n                \"type\": \"string\",\n                \"enum\": [\n                  \"text\",\n                  \"json\",\n                  \"yaml\"\n                ]\n              }\n            }\n          ],\n          \"effects\": {\n            \"risk_level\": \"low\",\n            \"reads\": [\n              \"artifact-definitions\"\n            ],\n            \"execution_mode\": \"normal\"\n          },\n          \"x-agent\": {\n            \"expected_duration_ms\": 2000,\n            \"retryable_exit_codes\": []\n          },\n          \"stdout\": {\n            \"schema\": {\n              \"$ref\": \"#/components/schemas/ArtifactExplanation\"\n            },\n            \"description\": \"Artifact governance metadata for the resolved path. Schema applies to --format json and --format yaml. Text format is human-readable only.\"\n          },\n          \"exits\": {\n            \"0\": {\n              \"description\": \"Path resolved to an artifact\"\n            },\n            \"2\": {\n              \"description\": \"Overlap — path matches multiple artifacts\"\n            },\n            \"3\": {\n              \"description\": \"Config or input file not found / parse error\"\n            },\n            \"4\": {\n              \"description\": \"Path does not match any registered artifact\"\n            }\n          }\n        },\n        \"audit\": {\n          \"summary\": \"LLM-based semantic audit of artifact definitions\",\n          \"description\": \"Performs semantic analysis of artifact definitions using LLM to identify quality issues that static validation cannot detect — naming inconsistencies, missing coverage for common file types, authority mismatches, and structural improvements.\",\n          \"options\": [\n            {\n              \"name\": \"config\",\n              \"description\": \"Path to artifact-contracts.config.yaml\",\n              \"value_name\": \"path\"\n            },\n            {\n              \"name\": \"adapter\",\n              \"description\": \"LLM adapter to use\",\n              \"schema\": {\n                \"type\": \"string\",\n                \"enum\": [\n                  \"mock\",\n                  \"openai\",\n                  \"claude\",\n                  \"gemini\"\n                ]\n              }\n            },\n            {\n              \"name\": \"model\",\n              \"description\": \"Model name to pass to the adapter\"\n            },\n            {\n              \"name\": \"show-prompt\",\n              \"description\": \"Output the constructed prompt without calling the LLM API\",\n              \"schema\": {\n                \"type\": \"boolean\"\n              }\n            },\n            {\n              \"name\": \"dry-run\",\n              \"aliases\": [\n                \"n\"\n              ],\n              \"description\": \"Alias for --show-prompt (output prompt without LLM call)\",\n              \"schema\": {\n                \"type\": \"boolean\"\n              }\n            },\n            {\n              \"name\": \"fail-on\",\n              \"description\": \"Minimum severity that causes exit 10. Ordering: critical > error > warning > info. For example, --fail-on warning exits 10 on warning, error, or critical.\",\n              \"schema\": {\n                \"type\": \"string\",\n                \"enum\": [\n                  \"info\",\n                  \"warning\",\n                  \"error\",\n                  \"critical\"\n                ]\n              }\n            },\n            {\n              \"name\": \"output\",\n              \"aliases\": [\n                \"o\"\n              ],\n              \"description\": \"Write result to a file instead of stdout\",\n              \"value_name\": \"file\"\n            },\n            {\n              \"name\": \"report-format\",\n              \"description\": \"Output format for the report (default: text). LLM commands use --report-format; deterministic commands use --format.\",\n              \"schema\": {\n                \"type\": \"string\",\n                \"enum\": [\n                  \"text\",\n                  \"json\",\n                  \"yaml\"\n                ]\n              }\n            },\n            {\n              \"name\": \"log-file\",\n              \"aliases\": [\n                \"l\"\n              ],\n              \"description\": \"Write agent progress log to this file path.\",\n              \"schema\": {\n                \"type\": \"string\"\n              }\n            }\n          ],\n          \"effects\": {\n            \"risk_level\": \"medium\",\n            \"reads\": [\n              \"artifact-definitions\"\n            ],\n            \"writes\": [\n              \"audit-report\"\n            ],\n            \"network\": {\n              \"description\": \"LLM API calls to configured provider\",\n              \"idempotent\": false\n            },\n            \"execution_mode\": \"normal\"\n          },\n          \"stdout\": {\n            \"schema\": {\n              \"$ref\": \"#/components/schemas/AgentAuditResult\"\n            },\n            \"description\": \"Structured audit result conforming to the AgentAuditResult schema. Format varies by --report-format (json, yaml, text).\"\n          },\n          \"x-agent\": {\n            \"dslTask\": \"audit-artifact-definitions\",\n            \"riskLevel\": \"low\",\n            \"requiresConfirmation\": false,\n            \"idempotent\": true,\n            \"sideEffects\": [\n              \"network\"\n            ],\n            \"sideEffectNote\": \"Makes network calls to the configured LLM provider when adapter is not mock. Filesystem write only when --output is specified.\",\n            \"safeDryRunOption\": \"show-prompt\",\n            \"expectedDurationMs\": 120000,\n            \"retryableExitCodes\": [\n              1,\n              12\n            ],\n            \"recommendedBeforeUse\": [\n              \"Run with --show-prompt first to preview the prompt\"\n            ]\n          },\n          \"exits\": {\n            \"0\": {\n              \"description\": \"Audit completed — no findings above threshold\"\n            },\n            \"1\": {\n              \"description\": \"General / transient error\"\n            },\n            \"3\": {\n              \"description\": \"Config or input file not found / parse error\"\n            },\n            \"10\": {\n              \"description\": \"Findings detected above --fail-on threshold\"\n            },\n            \"11\": {\n              \"description\": \"agent-contracts-runtime is not installed\"\n            },\n            \"12\": {\n              \"description\": \"Adapter initialization error (missing API key, etc.)\"\n            }\n          }\n        },\n        \"discover\": {\n          \"summary\": \"LLM-based artifact discovery from project file structure\",\n          \"description\": \"Analyzes the project file structure using LLM to generate or update artifact-contracts.yaml definitions. In init mode (no existing file), creates a new registry from scratch. In update mode (existing file), proposes additional artifact definitions and trace link rules for uncovered files.\",\n          \"options\": [\n            {\n              \"name\": \"adapter\",\n              \"description\": \"LLM adapter to use\",\n              \"schema\": {\n                \"type\": \"string\",\n                \"enum\": [\n                  \"mock\",\n                  \"openai\",\n                  \"claude\",\n                  \"gemini\"\n                ]\n              }\n            },\n            {\n              \"name\": \"model\",\n              \"description\": \"Model name to pass to the adapter\"\n            },\n            {\n              \"name\": \"show-prompt\",\n              \"description\": \"Output the constructed prompt without calling the LLM API\",\n              \"schema\": {\n                \"type\": \"boolean\"\n              }\n            },\n            {\n              \"name\": \"dry-run\",\n              \"aliases\": [\n                \"n\"\n              ],\n              \"description\": \"Alias for --show-prompt (output prompt without LLM call)\",\n              \"schema\": {\n                \"type\": \"boolean\"\n              }\n            },\n            {\n              \"name\": \"write\",\n              \"aliases\": [\n                \"w\"\n              ],\n              \"description\": \"Write the generated YAML directly to artifact-contracts.yaml\",\n              \"schema\": {\n                \"type\": \"boolean\"\n              }\n            },\n            {\n              \"name\": \"output\",\n              \"aliases\": [\n                \"o\"\n              ],\n              \"description\": \"Write result to a specific file path instead of stdout\",\n              \"value_name\": \"file\"\n            },\n            {\n              \"name\": \"report-format\",\n              \"description\": \"Output format (default: yaml)\",\n              \"schema\": {\n                \"type\": \"string\",\n                \"enum\": [\n                  \"yaml\",\n                  \"json\"\n                ]\n              }\n            },\n            {\n              \"name\": \"log-file\",\n              \"aliases\": [\n                \"l\"\n              ],\n              \"description\": \"Write agent progress log to this file path.\",\n              \"schema\": {\n                \"type\": \"string\"\n              }\n            }\n          ],\n          \"effects\": {\n            \"risk_level\": \"medium\",\n            \"reads\": [\n              \"artifact-definitions\",\n              \"repository-files\"\n            ],\n            \"writes\": [\n              \"artifact-definitions\"\n            ],\n            \"network\": {\n              \"description\": \"LLM API calls to configured provider\",\n              \"idempotent\": false\n            },\n            \"execution_mode\": \"normal\"\n          },\n          \"stdout\": {\n            \"schema\": {\n              \"$ref\": \"#/components/schemas/DiscoverResult\"\n            },\n            \"description\": \"Generated artifact-contracts.yaml content or structured discovery result.\"\n          },\n          \"x-agent\": {\n            \"dslTask\": \"discover-artifact-definitions\",\n            \"riskLevel\": \"low\",\n            \"requiresConfirmation\": false,\n            \"idempotent\": true,\n            \"sideEffects\": [\n              \"network\"\n            ],\n            \"sideEffectNote\": \"Makes network calls to the configured LLM provider when adapter is not mock. Filesystem write only when --write or --output is specified.\",\n            \"safeDryRunOption\": \"show-prompt\",\n            \"expectedDurationMs\": 120000,\n            \"retryableExitCodes\": [\n              1,\n              12\n            ],\n            \"recommendedBeforeUse\": [\n              \"Run with --show-prompt first to preview the prompt\"\n            ]\n          },\n          \"exits\": {\n            \"0\": {\n              \"description\": \"Discovery completed successfully\"\n            },\n            \"1\": {\n              \"description\": \"General / transient error\"\n            },\n            \"3\": {\n              \"description\": \"File system read error\"\n            },\n            \"11\": {\n              \"description\": \"agent-contracts-runtime is not installed\"\n            },\n            \"12\": {\n              \"description\": \"Adapter initialization error (missing API key, etc.)\"\n            }\n          }\n        },\n        \"agents\": {\n          \"summary\": \"Output the full resolved agent DSL as structured data.\",\n          \"description\": \"Outputs the complete resolved agent-contracts DSL (agents, tasks, workflows, handoff_types) embedded in this CLI binary. Useful for debugging, external tooling integration, and DSL inspection.\",\n          \"options\": [\n            {\n              \"name\": \"format\",\n              \"aliases\": [\n                \"F\"\n              ],\n              \"description\": \"Output format.\",\n              \"schema\": {\n                \"type\": \"string\",\n                \"enum\": [\n                  \"yaml\",\n                  \"json\"\n                ],\n                \"default\": \"yaml\"\n              }\n            }\n          ],\n          \"exits\": {\n            \"0\": {\n              \"description\": \"DSL output successfully.\",\n              \"stdout\": {\n                \"format\": \"text\"\n              }\n            },\n            \"1\": {\n              \"description\": \"Failed to load embedded DSL.\",\n              \"stderr\": {\n                \"format\": \"text\"\n              }\n            }\n          },\n          \"x-agent\": {\n            \"riskLevel\": \"low\",\n            \"requiresConfirmation\": false,\n            \"idempotent\": true,\n            \"sideEffects\": []\n          }\n        }\n      },\n      \"env\": {\n        \"OPENAI_API_KEY\": {\n          \"description\": \"OpenAI API key. Required when --adapter openai is selected.\",\n          \"required\": false\n        },\n        \"ANTHROPIC_API_KEY\": {\n          \"description\": \"Anthropic API key. Required when --adapter claude is selected.\",\n          \"required\": false\n        },\n        \"GEMINI_API_KEY\": {\n          \"description\": \"Google Gemini API key. Required when --adapter gemini is selected.\",\n          \"required\": false\n        }\n      }\n    }\n  },\n  \"components\": {\n    \"schemas\": {\n      \"AgentFinding\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"id\": {\n            \"type\": \"string\"\n          },\n          \"severity\": {\n            \"type\": \"string\",\n            \"enum\": [\n              \"critical\",\n              \"error\",\n              \"warning\",\n              \"info\"\n            ]\n          },\n          \"category\": {\n            \"type\": \"string\"\n          },\n          \"title\": {\n            \"type\": \"string\"\n          },\n          \"description\": {\n            \"type\": \"string\"\n          },\n          \"location\": {\n            \"type\": \"string\"\n          },\n          \"target\": {\n            \"type\": \"string\"\n          },\n          \"recommendation\": {\n            \"type\": \"string\"\n          },\n          \"evidence\": {\n            \"type\": \"array\",\n            \"items\": {\n              \"$ref\": \"#/components/schemas/AgentEvidence\"\n            }\n          }\n        },\n        \"required\": [\n          \"id\",\n          \"severity\",\n          \"category\",\n          \"title\",\n          \"description\"\n        ]\n      },\n      \"AgentAuditResult\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"summary\": {\n            \"type\": \"string\"\n          },\n          \"risk_level\": {\n            \"type\": \"string\",\n            \"enum\": [\n              \"none\",\n              \"low\",\n              \"medium\",\n              \"high\",\n              \"critical\"\n            ]\n          },\n          \"findings\": {\n            \"type\": \"array\",\n            \"items\": {\n              \"$ref\": \"#/components/schemas/AgentFinding\"\n            }\n          },\n          \"recommended_actions\": {\n            \"type\": \"array\",\n            \"items\": {\n              \"$ref\": \"#/components/schemas/AgentRecommendedAction\"\n            }\n          },\n          \"metadata\": {\n            \"type\": \"object\",\n            \"properties\": {\n              \"total_artifacts\": {\n                \"type\": \"integer\"\n              },\n              \"analyzed_artifacts\": {\n                \"type\": \"integer\"\n              },\n              \"analysis_scope\": {\n                \"type\": \"string\"\n              }\n            }\n          }\n        },\n        \"required\": [\n          \"summary\",\n          \"risk_level\",\n          \"findings\",\n          \"recommended_actions\"\n        ]\n      },\n      \"AgentEvidence\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"kind\": {\n            \"type\": \"string\",\n            \"enum\": [\n              \"schema\",\n              \"code\",\n              \"config\",\n              \"runtime\",\n              \"doc\"\n            ]\n          },\n          \"target\": {\n            \"type\": \"string\"\n          },\n          \"location\": {\n            \"type\": \"string\"\n          },\n          \"excerpt\": {\n            \"type\": \"string\"\n          },\n          \"reasoning\": {\n            \"type\": \"string\"\n          }\n        },\n        \"required\": [\n          \"kind\"\n        ]\n      },\n      \"AgentRecommendedAction\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"action\": {\n            \"type\": \"string\"\n          },\n          \"priority\": {\n            \"type\": \"string\",\n            \"enum\": [\n              \"high\",\n              \"medium\",\n              \"low\"\n            ]\n          },\n          \"description\": {\n            \"type\": \"string\"\n          }\n        },\n        \"required\": [\n          \"action\",\n          \"priority\"\n        ]\n      },\n      \"ResolvedDefinitions\": {\n        \"type\": \"object\",\n        \"description\": \"Output of the resolve command\",\n        \"properties\": {\n          \"artifact_contracts\": {\n            \"type\": \"string\"\n          },\n          \"system\": {\n            \"type\": \"object\",\n            \"properties\": {\n              \"id\": {\n                \"type\": \"string\"\n              },\n              \"name\": {\n                \"type\": \"string\"\n              }\n            },\n            \"required\": [\n              \"id\"\n            ]\n          },\n          \"artifacts\": {\n            \"type\": \"object\",\n            \"description\": \"Map of artifact ID to resolved artifact definition\",\n            \"additionalProperties\": {\n              \"$ref\": \"#/components/schemas/ArtifactDefinition\"\n            }\n          }\n        },\n        \"required\": [\n          \"artifact_contracts\",\n          \"system\",\n          \"artifacts\"\n        ]\n      },\n      \"ArtifactExplanation\": {\n        \"type\": \"object\",\n        \"description\": \"Output of the explain command (json/yaml format)\",\n        \"properties\": {\n          \"id\": {\n            \"type\": \"string\"\n          },\n          \"type\": {\n            \"type\": \"string\"\n          },\n          \"authority\": {\n            \"type\": \"string\"\n          },\n          \"manual_edit\": {\n            \"type\": \"string\"\n          },\n          \"change_control\": {\n            \"type\": \"string\"\n          },\n          \"visibility\": {\n            \"type\": \"string\"\n          },\n          \"description\": {\n            \"type\": \"string\"\n          },\n          \"path_patterns\": {\n            \"type\": \"array\",\n            \"items\": {\n              \"type\": \"string\"\n            }\n          },\n          \"exclude_patterns\": {\n            \"type\": \"array\",\n            \"items\": {\n              \"type\": \"string\"\n            }\n          }\n        },\n        \"required\": [\n          \"id\",\n          \"type\",\n          \"authority\",\n          \"manual_edit\",\n          \"change_control\"\n        ]\n      },\n      \"ArtifactDefinition\": {\n        \"type\": \"object\",\n        \"description\": \"A single resolved artifact definition\",\n        \"properties\": {\n          \"type\": {\n            \"type\": \"string\"\n          },\n          \"authority\": {\n            \"type\": \"string\",\n            \"enum\": [\n              \"canonical\",\n              \"derived\",\n              \"generated\",\n              \"control\"\n            ]\n          },\n          \"manual_edit\": {\n            \"type\": \"string\",\n            \"enum\": [\n              \"allowed\",\n              \"discouraged\",\n              \"forbidden\"\n            ]\n          },\n          \"change_control\": {\n            \"type\": \"string\",\n            \"enum\": [\n              \"none\",\n              \"approval-required\",\n              \"regeneration-required\"\n            ]\n          },\n          \"visibility\": {\n            \"type\": \"string\",\n            \"enum\": [\n              \"public\",\n              \"internal\",\n              \"private\"\n            ]\n          },\n          \"description\": {\n            \"type\": \"string\"\n          },\n          \"path_patterns\": {\n            \"type\": \"array\",\n            \"items\": {\n              \"type\": \"string\"\n            }\n          },\n          \"exclude_patterns\": {\n            \"type\": \"array\",\n            \"items\": {\n              \"type\": \"string\"\n            }\n          },\n          \"states\": {\n            \"type\": \"array\",\n            \"items\": {\n              \"type\": \"string\"\n            }\n          }\n        },\n        \"required\": [\n          \"type\",\n          \"authority\",\n          \"manual_edit\",\n          \"change_control\",\n          \"visibility\",\n          \"path_patterns\"\n        ]\n      },\n      \"ArtifactList\": {\n        \"type\": \"object\",\n        \"description\": \"Output of the list command (json/yaml format)\",\n        \"properties\": {\n          \"artifacts\": {\n            \"type\": \"object\",\n            \"description\": \"Map of artifact ID to resolved artifact definition\",\n            \"additionalProperties\": {\n              \"$ref\": \"#/components/schemas/ArtifactDefinition\"\n            }\n          }\n        }\n      },\n      \"DiscoverResult\": {\n        \"type\": \"object\",\n        \"description\": \"Output of the discover command\",\n        \"properties\": {\n          \"mode\": {\n            \"type\": \"string\",\n            \"enum\": [\n              \"init\",\n              \"update\"\n            ]\n          },\n          \"artifact_contracts_yaml\": {\n            \"type\": \"string\",\n            \"description\": \"Generated YAML content\"\n          },\n          \"decisions\": {\n            \"type\": \"array\",\n            \"items\": {\n              \"type\": \"object\",\n              \"properties\": {\n                \"artifact_id\": {\n                  \"type\": \"string\"\n                },\n                \"reasoning\": {\n                  \"type\": \"string\"\n                }\n              },\n              \"required\": [\n                \"artifact_id\",\n                \"reasoning\"\n              ]\n            }\n          },\n          \"trace_decisions\": {\n            \"type\": \"array\",\n            \"items\": {\n              \"type\": \"object\",\n              \"properties\": {\n                \"link_id\": {\n                  \"type\": \"string\"\n                },\n                \"reasoning\": {\n                  \"type\": \"string\"\n                }\n              },\n              \"required\": [\n                \"link_id\",\n                \"reasoning\"\n              ]\n            }\n          },\n          \"uncategorized_files\": {\n            \"type\": \"array\",\n            \"items\": {\n              \"type\": \"string\"\n            }\n          },\n          \"suggestions\": {\n            \"type\": \"array\",\n            \"items\": {\n              \"type\": \"string\"\n            }\n          }\n        },\n        \"required\": [\n          \"mode\",\n          \"artifact_contracts_yaml\"\n        ]\n      },\n      \"ValidationResult\": {\n        \"type\": \"object\",\n        \"description\": \"Output of the validate command (json format, on error)\",\n        \"properties\": {\n          \"valid\": {\n            \"type\": \"boolean\"\n          },\n          \"diagnostics\": {\n            \"type\": \"array\",\n            \"items\": {\n              \"type\": \"object\",\n              \"properties\": {\n                \"path\": {\n                  \"type\": \"string\"\n                },\n                \"message\": {\n                  \"type\": \"string\"\n                },\n                \"severity\": {\n                  \"type\": \"string\",\n                  \"enum\": [\n                    \"error\",\n                    \"warning\"\n                  ]\n                }\n              },\n              \"required\": [\n                \"message\",\n                \"severity\"\n              ]\n            }\n          },\n          \"overlaps\": {\n            \"type\": \"array\",\n            \"items\": {\n              \"type\": \"object\",\n              \"properties\": {\n                \"path\": {\n                  \"type\": \"string\"\n                },\n                \"matching_artifacts\": {\n                  \"type\": \"array\",\n                  \"items\": {\n                    \"type\": \"string\"\n                  }\n                }\n              },\n              \"required\": [\n                \"path\",\n                \"matching_artifacts\"\n              ]\n            }\n          }\n        },\n        \"required\": [\n          \"valid\",\n          \"diagnostics\",\n          \"overlaps\"\n        ]\n      }\n    }\n  }\n}";
 //# sourceMappingURL=contract.js.map

package/dist/generated/contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/generated/contract.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,gDAAgD;AAEhD,MAAM,CAAC,MAAM,aAAa,GAAW,0jlBAA0jlB,CAAC;AAEhmlB,MAAM,CAAC,MAAM,iBAAiB,GAAW,0j3BAA0j3B,CAAC"}
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/generated/contract.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,gDAAgD;AAEhD,MAAM,CAAC,MAAM,aAAa,GAAW,y4tBAAy4tB,CAAC;AAE/6tB,MAAM,CAAC,MAAM,iBAAiB,GAAW,ytkCAAytkC,CAAC"}

package/dist/generated/dsl/agents.d.ts

@@ -28,6 +28,7 @@ export interface AgentContract {
     readonly rules: readonly AgentRule[];
     readonly escalation_criteria: readonly EscalationCriterion[];
 }
+export declare const artifactDiscoveryAgent: AgentContract;
 export declare const artifactQualityReviewer: AgentContract;
 export declare const agentRegistry: Record<string, AgentContract>;
 export type AgentId = keyof typeof agentRegistry;

package/dist/generated/dsl/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../../src/generated/dsl/agents.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,aAAa,GAAG,UAAU,CAAC;CAC7D;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,qBAAqB,GAAG,mBAAmB,CAAC;CAClF;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,WAAW,CAAC;IAC1C,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;IACrC,QAAQ,CAAC,mBAAmB,EAAE,SAAS,mBAAmB,EAAE,CAAC;CAC9D;AAED,eAAO,MAAM,uBAAuB,EAAE,aAgC5B,CAAC;AAEX,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAE9C,CAAC;AAEX,MAAM,MAAM,OAAO,GAAG,MAAM,OAAO,aAAa,CAAC"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../../src/generated/dsl/agents.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,aAAa,GAAG,UAAU,CAAC;CAC7D;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,qBAAqB,GAAG,mBAAmB,CAAC;CAClF;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,WAAW,CAAC;IAC1C,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;IACrC,QAAQ,CAAC,mBAAmB,EAAE,SAAS,mBAAmB,EAAE,CAAC;CAC9D;AAED,eAAO,MAAM,sBAAsB,EAAE,aAiC3B,CAAC;AAEX,eAAO,MAAM,uBAAuB,EAAE,aAgC5B,CAAC;AAEX,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAG9C,CAAC;AAEX,MAAM,MAAM,OAAO,GAAG,MAAM,OAAO,aAAa,CAAC"}