agentweaver 0.1.17 → 0.1.19

package/dist/runtime/project-guidance.js

@@ -0,0 +1,339 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { TaskRunnerError } from "../errors.js";
+import { loadProjectPlaybook, PLAYBOOK_DIR, PLAYBOOK_MANIFEST, } from "./playbook.js";
+export const GUIDANCE_PHASES = ["plan", "design-review", "implement", "review", "repair/review-fix"];
+export const DEFAULT_GUIDANCE_BUDGETS = {
+    plan: 1200,
+    "design-review": 1000,
+    implement: 1400,
+    review: 1000,
+    "repair/review-fix": 1000,
+};
+export const DEFAULT_INLINE_THRESHOLD = 300;
+const LANGUAGE_HINTS = ["typescript", "javascript", "node", "go", "golang", "python", "react", "vue", "svelte"];
+const FRAMEWORK_HINTS = ["express", "fastify", "nestjs", "react", "vite", "vitest", "node:test", "jest", "ink"];
+export function normalizeGuidancePhase(value) {
+    const normalized = value.trim().toLowerCase().replace(/_/g, "-");
+    if (normalized === "design_review") {
+        return "design-review";
+    }
+    if (normalized === "repair" || normalized === "review-fix") {
+        return "repair/review-fix";
+    }
+    if (GUIDANCE_PHASES.includes(normalized)) {
+        return normalized;
+    }
+    throw new TaskRunnerError(`Unsupported project guidance phase '${value}'. Supported phases: ${GUIDANCE_PHASES.join(", ")}.`);
+}
+export function toPlaybookPhase(phase) {
+    switch (phase) {
+        case "design-review":
+            return "design_review";
+        case "repair/review-fix":
+            return "repair";
+        default:
+            return phase;
+    }
+}
+export function getDefaultGuidanceBudget(phase) {
+    return { limit: DEFAULT_GUIDANCE_BUDGETS[phase], inlineThreshold: DEFAULT_INLINE_THRESHOLD };
+}
+export function estimateApproxTokens(value) {
+    return Math.ceil(value.length / 4);
+}
+export function extractTaskSignals(taskContext) {
+    const values = [];
+    collectStrings(taskContext, values);
+    const joined = values.join("\n");
+    const keywords = Array.from(new Set(joined.toLowerCase().match(/[a-z][a-z0-9_-]{2,}/g) ?? []))
+        .filter((word) => !STOP_WORDS.has(word))
+        .sort();
+    const referencedPaths = Array.from(new Set(joined.match(/(?:^|\s)([./]?[A-Za-z0-9_.@-]+\/[A-Za-z0-9_./@-]+)/g)?.map((item) => item.trim()) ?? []))
+        .map((item) => item.replace(/^["'`]|["'`,.;:]$/g, ""))
+        .sort();
+    const languages = LANGUAGE_HINTS.filter((hint) => keywords.includes(hint));
+    const frameworks = FRAMEWORK_HINTS.filter((hint) => keywords.includes(hint));
+    const record = isRecord(taskContext) ? taskContext : {};
+    return {
+        title: firstString(record.title, record.summary, record.key) || "Untitled task",
+        source_type: firstString(record.source_type, record.sourceType) || "unknown",
+        keywords,
+        file_globs: referencedPaths,
+        referenced_paths: referencedPaths,
+        languages,
+        frameworks,
+    };
+}
+export function buildProjectGuidance(options) {
+    const phase = normalizeGuidancePhase(options.phase);
+    const playbookRoot = path.join(path.resolve(options.projectRoot), PLAYBOOK_DIR);
+    const manifestPath = path.join(playbookRoot, PLAYBOOK_MANIFEST);
+    const defaults = getDefaultGuidanceBudget(phase);
+    const budget = makeBudget(options.budgetLimit ?? defaults.limit, options.inlineThreshold ?? defaults.inlineThreshold);
+    const taskSignals = extractTaskSignals(options.taskContext);
+    if (!existsSync(manifestPath)) {
+        return {
+            summary: `No project playbook manifest was found for ${phase} guidance.`,
+            status: "missing_playbook",
+            phase,
+            source_playbook: { root_dir: playbookRoot, manifest_path: manifestPath, exists: false, valid: false },
+            task_signals: taskSignals,
+            selected_practices: [],
+            selected_examples: [],
+            always_include: [],
+            phase_sections: [],
+            budget,
+            skipped_items: [],
+            warnings: [{ code: "missing_playbook", message: "Project guidance was not generated because manifest.yaml is absent.", severity: "warning" }],
+        };
+    }
+    let playbook;
+    try {
+        playbook = loadProjectPlaybook(options.projectRoot);
+    }
+    catch (error) {
+        const message = error.message;
+        if ((options.invalidPlaybookPolicy ?? "fail_before_prompt") === "write_diagnostic_artifact") {
+            return {
+                summary: `The project playbook manifest is invalid for ${phase} guidance.`,
+                status: "invalid_playbook",
+                phase,
+                source_playbook: { root_dir: playbookRoot, manifest_path: manifestPath, exists: true, valid: false, error: message },
+                task_signals: taskSignals,
+                selected_practices: [],
+                selected_examples: [],
+                always_include: [],
+                phase_sections: [],
+                budget,
+                skipped_items: [],
+                warnings: [{ code: "invalid_playbook", message, severity: "error" }],
+            };
+        }
+        throw new TaskRunnerError(`Invalid project playbook ${manifestPath}: ${message}`);
+    }
+    const scored = [...playbook.practices, ...playbook.examples]
+        .map((entry) => scoreEntry(entry, playbook, phase, taskSignals))
+        .filter((entry) => entry !== null)
+        .sort(compareScoredEntries);
+    const skipped = [];
+    const selected = [];
+    for (const scoredEntry of scored) {
+        selected.push(materializeEntry(scoredEntry, playbook, budget, skipped));
+    }
+    const selectedPractices = selected.filter((entry) => entry.kind === "practice");
+    const selectedExamples = selected.filter((entry) => entry.kind === "example");
+    const status = selected.length > 0 || playbook.alwaysInclude.length > 0 ? "available" : "empty_selection";
+    return {
+        summary: status === "available"
+            ? `Selected compact ${phase} project guidance from manifest.yaml.`
+            : `No matching project guidance was selected for ${phase}.`,
+        status,
+        phase,
+        source_playbook: { root_dir: playbook.playbookRoot, manifest_path: playbook.manifestPath, exists: true, valid: true },
+        task_signals: taskSignals,
+        selected_practices: selectedPractices,
+        selected_examples: selectedExamples,
+        always_include: playbook.alwaysInclude,
+        phase_sections: selectedPractices.map((entry) => entry.title),
+        budget,
+        skipped_items: skipped,
+        warnings: [],
+    };
+}
+export function renderProjectGuidanceMarkdown(guidance, language = "en") {
+    if (language === "ru") {
+        return renderRussianMarkdown(guidance);
+    }
+    return renderEnglishMarkdown(guidance);
+}
+function scoreEntry(entry, playbook, phase, signals) {
+    const playbookPhase = toPlaybookPhase(phase);
+    const phases = entry.metadata.phases;
+    const always = playbook.alwaysInclude.includes(entry.path);
+    const reasons = [];
+    let score = 0;
+    if (always) {
+        score += 1000;
+        reasons.push("always_include");
+    }
+    if (phases.length === 0 || phases.includes(playbookPhase)) {
+        score += 100;
+        reasons.push("phase_match");
+    }
+    else if (!always) {
+        return null;
+    }
+    const appliesTo = entry.metadata.applies_to;
+    const text = `${entry.id} ${entry.title} ${entry.body}`.toLowerCase();
+    const keywordMatches = (appliesTo?.keywords ?? signals.keywords).filter((keyword) => signals.keywords.includes(keyword.toLowerCase()) || text.includes(keyword.toLowerCase()));
+    if (keywordMatches.length > 0) {
+        score += Math.min(keywordMatches.length, 10) * 8;
+        reasons.push("keyword_match");
+    }
+    if ((appliesTo?.globs ?? []).some((glob) => signals.referenced_paths.some((filePath) => globMatches(glob, filePath)))) {
+        score += 40;
+        reasons.push("glob_match");
+    }
+    if ((appliesTo?.languages ?? []).some((language) => signals.languages.includes(language.toLowerCase()))) {
+        score += 30;
+        reasons.push("language_match");
+    }
+    if ((appliesTo?.frameworks ?? []).some((framework) => signals.frameworks.includes(framework.toLowerCase()))) {
+        score += 30;
+        reasons.push("framework_match");
+    }
+    score += (entry.metadata.priority ?? 0) * 5;
+    if (entry.metadata.priority !== undefined) {
+        reasons.push("priority");
+    }
+    score += severityWeight(entry.metadata.severity);
+    if (entry.metadata.severity) {
+        reasons.push("severity");
+    }
+    if (score <= 0) {
+        return null;
+    }
+    return { entry, score, reasons: Array.from(new Set(reasons)), always };
+}
+function materializeEntry(scored, playbook, budget, skipped) {
+    const safePath = containedPlaybookPath(playbook, scored.entry.path);
+    const tokens = estimateApproxTokens(scored.entry.body);
+    const referenceReason = scored.entry.kind === "example" ? "example_reference_only" : "over_budget";
+    const item = {
+        id: scored.entry.id,
+        title: scored.entry.title,
+        kind: scored.entry.kind,
+        source_path: safePath,
+        selection_reasons: scored.reasons,
+        relevance_score: scored.score,
+        priority: scored.entry.metadata.priority ?? 0,
+        severity: scored.entry.metadata.severity ?? "info",
+        reference_only: true,
+        reference: { source_path: safePath, reason: referenceReason },
+    };
+    if (scored.entry.kind === "practice" && tokens <= budget.inline_threshold && tokens <= budget.remaining) {
+        item.inline_content = scored.entry.body.trim();
+        item.reference_only = false;
+        item.reference.reason = "inlined";
+        budget.used += tokens;
+        budget.remaining = Math.max(0, budget.limit - budget.used);
+    }
+    else if (tokens > budget.inline_threshold || tokens > budget.remaining) {
+        skipped.push({ id: scored.entry.id, kind: scored.entry.kind, source_path: safePath, reason: tokens > budget.inline_threshold ? "inline_threshold_exceeded" : "over_budget" });
+    }
+    return item;
+}
+function containedPlaybookPath(playbook, relativePath) {
+    if (path.isAbsolute(relativePath)) {
+        throw new TaskRunnerError(`Playbook reference must be relative: ${relativePath}`);
+    }
+    const resolved = path.resolve(playbook.playbookRoot, relativePath);
+    const relative = path.relative(playbook.playbookRoot, resolved);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new TaskRunnerError(`Playbook reference escapes ${PLAYBOOK_DIR}: ${relativePath}`);
+    }
+    return relative.split(path.sep).join("/");
+}
+function compareScoredEntries(left, right) {
+    return (Number(right.always) - Number(left.always) ||
+        right.score - left.score ||
+        (right.entry.metadata.priority ?? 0) - (left.entry.metadata.priority ?? 0) ||
+        severityWeight(right.entry.metadata.severity) - severityWeight(left.entry.metadata.severity) ||
+        left.entry.id.localeCompare(right.entry.id));
+}
+function severityWeight(severity) {
+    if (severity === "must") {
+        return 30;
+    }
+    if (severity === "should") {
+        return 10;
+    }
+    return 0;
+}
+function makeBudget(limit, inlineThreshold) {
+    return {
+        limit: Math.max(0, Math.floor(limit)),
+        used: 0,
+        remaining: Math.max(0, Math.floor(limit)),
+        inline_threshold: Math.max(0, Math.floor(inlineThreshold)),
+        unit: "approx_tokens",
+        estimator: "chars_div_4",
+    };
+}
+function renderRussianMarkdown(guidance) {
+    const lines = [`# Проектные рекомендации: ${guidance.phase}`, "", `Статус: ${guidance.status}`, "", "## Обязательные правила"];
+    if (guidance.status === "missing_playbook") {
+        lines.push("- Проектный playbook manifest.yaml не найден; дополнительных проектных рекомендаций нет.");
+    }
+    else if (guidance.selected_practices.length === 0) {
+        lines.push("- Для этой фазы не выбраны дополнительные правила.");
+    }
+    else {
+        for (const item of guidance.selected_practices) {
+            lines.push(`- ${item.title} (${item.source_path}): ${item.selection_reasons.join(", ")}`);
+            if (item.inline_content) {
+                lines.push(`  ${item.inline_content.replace(/\n/g, " ")}`);
+            }
+        }
+    }
+    lines.push("", "## Релевантные примеры и ссылки");
+    const refs = [...guidance.selected_examples, ...guidance.selected_practices.filter((item) => item.reference_only)];
+    lines.push(...(refs.length === 0 ? ["- Нет релевантных ссылок."] : refs.map((item) => `- ${item.title}: ${item.source_path} (${item.reference.reason})`)));
+    lines.push("", "Открывайте полные примеры только когда они напрямую релевантны текущему изменению.");
+    lines.push("", "## Бюджет", `Использовано ${guidance.budget.used} из ${guidance.budget.limit} ${guidance.budget.unit}; осталось ${guidance.budget.remaining}.`);
+    return `${lines.join("\n")}\n`;
+}
+function renderEnglishMarkdown(guidance) {
+    const lines = [`# Project Guidance: ${guidance.phase}`, "", `Status: ${guidance.status}`, "", "## Must-Follow Rules"];
+    if (guidance.status === "missing_playbook") {
+        lines.push("- Project playbook manifest.yaml was not found; no additional project guidance is available.");
+    }
+    else if (guidance.selected_practices.length === 0) {
+        lines.push("- No additional rules were selected for this phase.");
+    }
+    else {
+        for (const item of guidance.selected_practices) {
+            lines.push(`- ${item.title} (${item.source_path}): ${item.selection_reasons.join(", ")}`);
+            if (item.inline_content) {
+                lines.push(`  ${item.inline_content.replace(/\n/g, " ")}`);
+            }
+        }
+    }
+    lines.push("", "## Relevant Examples And References");
+    const refs = [...guidance.selected_examples, ...guidance.selected_practices.filter((item) => item.reference_only)];
+    lines.push(...(refs.length === 0 ? ["- No relevant references."] : refs.map((item) => `- ${item.title}: ${item.source_path} (${item.reference.reason})`)));
+    lines.push("", "Open full examples only when they are directly relevant to the current change.");
+    lines.push("", "## Budget", `Used ${guidance.budget.used} of ${guidance.budget.limit} ${guidance.budget.unit}; remaining ${guidance.budget.remaining}.`);
+    return `${lines.join("\n")}\n`;
+}
+function collectStrings(value, result) {
+    if (typeof value === "string") {
+        result.push(value);
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item) => collectStrings(item, result));
+        return;
+    }
+    if (isRecord(value)) {
+        Object.values(value).forEach((item) => collectStrings(item, result));
+    }
+}
+function firstString(...values) {
+    return values.find((value) => typeof value === "string" && value.trim().length > 0)?.trim() ?? "";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function globMatches(glob, value) {
+    const source = glob
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*\*/g, ".*")
+        .replace(/\*/g, "[^/]*");
+    return new RegExp(`^${source}$`).test(value.replace(/^\.\//, ""));
+}
+const STOP_WORDS = new Set([
+    "and", "the", "with", "for", "from", "into", "that", "this", "when", "then", "must", "should", "will", "are", "was",
+    "как", "для", "что", "это", "или", "при", "над", "под", "если",
+]);

package/dist/structured-artifact-schema-registry.js

@@ -15,7 +15,15 @@ export const STRUCTURED_ARTIFACT_SCHEMA_IDS = [
     "jira-description/v1",
     "mr-description/v1",
     "planning-questions/v1",
+    "playbook-answers/v1",
+    "playbook-draft/v1",
+    "playbook-final/v1",
+    "playbook-questions/v1",
+    "playbook-write-result/v1",
+    "practice-candidates/v1",
+    "project-guidance/v1",
     "qa-plan/v1",
+    "repo-inventory/v1",
     "review-assessment/v1",
     "review-findings/v1",
     "review-fix-report/v1",

package/dist/structured-artifact-schemas.json

@@ -1,4 +1,94 @@
 {
+  "project-guidance/v1": {
+    "type": "object",
+    "properties": {
+      "summary": { "type": "string", "nonEmpty": true },
+      "status": { "type": "string", "enum": ["available", "missing_playbook", "empty_selection", "invalid_playbook"] },
+      "phase": { "type": "string", "enum": ["plan", "design-review", "implement", "review", "repair/review-fix"] },
+      "source_playbook": {
+        "type": "object",
+        "properties": {
+          "root_dir": { "type": "string", "nonEmpty": true },
+          "manifest_path": { "type": "string", "nonEmpty": true },
+          "exists": { "type": "boolean" },
+          "valid": { "type": "boolean" },
+          "error": { "type": "string", "nonEmpty": true }
+        },
+        "required": ["root_dir", "manifest_path", "exists", "valid"]
+      },
+      "task_signals": {
+        "type": "object",
+        "properties": {
+          "title": { "type": "string", "nonEmpty": true },
+          "source_type": { "type": "string", "nonEmpty": true },
+          "keywords": { "type": "array", "items": { "type": "string", "nonEmpty": true } },
+          "file_globs": { "type": "array", "items": { "type": "string", "nonEmpty": true } },
+          "referenced_paths": { "type": "array", "items": { "type": "string", "nonEmpty": true } },
+          "languages": { "type": "array", "items": { "type": "string", "nonEmpty": true } },
+          "frameworks": { "type": "array", "items": { "type": "string", "nonEmpty": true } }
+        },
+        "required": ["title", "source_type", "keywords", "file_globs", "referenced_paths", "languages", "frameworks"]
+      },
+      "selected_practices": { "type": "array", "items": { "type": "object", "properties": {
+        "id": { "type": "string", "nonEmpty": true },
+        "title": { "type": "string", "nonEmpty": true },
+        "kind": { "type": "string", "enum": ["practice"] },
+        "source_path": { "type": "string", "nonEmpty": true },
+        "selection_reasons": { "type": "array", "items": { "type": "string", "nonEmpty": true }, "minItems": 1 },
+        "relevance_score": { "type": "number" },
+        "priority": { "type": "number" },
+        "severity": { "type": "string", "enum": ["must", "should", "info"] },
+        "reference_only": { "type": "boolean" },
+        "reference": { "type": "object", "properties": {
+          "source_path": { "type": "string", "nonEmpty": true },
+          "reason": { "type": "string", "nonEmpty": true }
+        }, "required": ["source_path", "reason"] },
+        "inline_content": { "type": "string", "nonEmpty": true }
+      }, "required": ["id", "title", "kind", "source_path", "selection_reasons", "relevance_score", "priority", "severity", "reference_only", "reference"] } },
+      "selected_examples": { "type": "array", "items": { "type": "object", "properties": {
+        "id": { "type": "string", "nonEmpty": true },
+        "title": { "type": "string", "nonEmpty": true },
+        "kind": { "type": "string", "enum": ["example"] },
+        "source_path": { "type": "string", "nonEmpty": true },
+        "selection_reasons": { "type": "array", "items": { "type": "string", "nonEmpty": true }, "minItems": 1 },
+        "relevance_score": { "type": "number" },
+        "priority": { "type": "number" },
+        "severity": { "type": "string", "enum": ["must", "should", "info"] },
+        "reference_only": { "type": "boolean" },
+        "reference": { "type": "object", "properties": {
+          "source_path": { "type": "string", "nonEmpty": true },
+          "reason": { "type": "string", "nonEmpty": true }
+        }, "required": ["source_path", "reason"] },
+        "inline_content": { "type": "string", "nonEmpty": true }
+      }, "required": ["id", "title", "kind", "source_path", "selection_reasons", "relevance_score", "priority", "severity", "reference_only", "reference"] } },
+      "always_include": { "type": "array", "items": { "type": "string", "nonEmpty": true } },
+      "phase_sections": { "type": "array", "items": { "type": "string", "nonEmpty": true } },
+      "budget": {
+        "type": "object",
+        "properties": {
+          "limit": { "type": "number", "minimum": 0 },
+          "used": { "type": "number", "minimum": 0 },
+          "remaining": { "type": "number", "minimum": 0 },
+          "inline_threshold": { "type": "number", "minimum": 0 },
+          "unit": { "type": "string", "enum": ["approx_tokens"] },
+          "estimator": { "type": "string", "enum": ["chars_div_4"] }
+        },
+        "required": ["limit", "used", "remaining", "inline_threshold", "unit", "estimator"]
+      },
+      "skipped_items": { "type": "array", "items": { "type": "object", "properties": {
+        "id": { "type": "string", "nonEmpty": true },
+        "kind": { "type": "string", "enum": ["practice", "example", "always_include"] },
+        "source_path": { "type": "string", "nonEmpty": true },
+        "reason": { "type": "string", "nonEmpty": true }
+      }, "required": ["id", "kind", "source_path", "reason"] } },
+      "warnings": { "type": "array", "items": { "type": "object", "properties": {
+        "code": { "type": "string", "nonEmpty": true },
+        "message": { "type": "string", "nonEmpty": true },
+        "severity": { "type": "string", "enum": ["info", "warning", "error"] }
+      }, "required": ["code", "message", "severity"] } }
+    },
+    "required": ["summary", "status", "phase", "source_playbook", "task_signals", "selected_practices", "selected_examples", "always_include", "phase_sections", "budget", "skipped_items", "warnings"]
+  },
   "bug-analysis/v1": {
     "type": "object",
     "properties": {
@@ -461,6 +551,151 @@
     },
     "required": ["summary", "questions"]
   },
+  "playbook-answers/v1": {
+    "type": "object",
+    "properties": {
+      "summary": { "type": "string", "nonEmpty": true },
+      "answered_at": { "type": "string", "nonEmpty": true },
+      "answers": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "question_id": { "type": "string", "nonEmpty": true },
+            "answer": { "type": "string" }
+          },
+          "required": ["question_id", "answer"]
+        }
+      },
+      "final_write_accepted": { "type": "boolean" }
+    },
+    "required": ["summary", "answered_at", "answers", "final_write_accepted"]
+  },
+  "playbook-draft/v1": {
+    "type": "object",
+    "properties": {
+      "summary": { "type": "string", "nonEmpty": true },
+      "generated_at": { "type": "string", "nonEmpty": true },
+      "accepted_rules": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "id": { "type": "string", "nonEmpty": true },
+            "title": { "type": "string", "nonEmpty": true },
+            "rule": { "type": "string", "nonEmpty": true },
+            "evidence_paths": { "type": "array", "items": { "type": "string", "nonEmpty": true }, "minItems": 1 }
+          },
+          "required": ["id", "title", "rule", "evidence_paths"]
+        }
+      },
+      "candidate_rules": { "type": "array", "items": { "type": "object" } },
+      "unresolved_questions": { "type": "array", "items": { "type": "string", "nonEmpty": true } },
+      "evidence_paths": { "type": "array", "items": { "type": "string", "nonEmpty": true } },
+      "proposed_files": { "type": "array", "items": { "type": "string", "nonEmpty": true }, "minItems": 2 }
+    },
+    "required": ["summary", "generated_at", "accepted_rules", "candidate_rules", "unresolved_questions", "evidence_paths", "proposed_files"]
+  },
+  "playbook-final/v1": {
+    "type": "object",
+    "properties": {
+      "status": { "type": "string", "nonEmpty": true, "enum": ["accepted"] },
+      "accepted_at": { "type": "string", "nonEmpty": true },
+      "source_draft_artifact": { "type": "string", "nonEmpty": true },
+      "summary": { "type": "string", "nonEmpty": true },
+      "rules": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "id": { "type": "string", "nonEmpty": true },
+            "title": { "type": "string", "nonEmpty": true },
+            "rule": { "type": "string", "nonEmpty": true },
+            "evidence_paths": { "type": "array", "items": { "type": "string", "nonEmpty": true }, "minItems": 1 }
+          },
+          "required": ["id", "title", "rule", "evidence_paths"]
+        }
+      },
+      "evidence_paths": { "type": "array", "items": { "type": "string", "nonEmpty": true } }
+    },
+    "required": ["status", "accepted_at", "source_draft_artifact", "summary", "rules", "evidence_paths"]
+  },
+  "playbook-questions/v1": {
+    "type": "object",
+    "properties": {
+      "summary": { "type": "string", "nonEmpty": true },
+      "questions": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "id": { "type": "string", "nonEmpty": true },
+            "text": { "type": "string", "nonEmpty": true },
+            "rationale": { "type": "string", "nonEmpty": true },
+            "candidate_ids": { "type": "array", "items": { "type": "string", "nonEmpty": true } },
+            "evidence_paths": { "type": "array", "items": { "type": "string", "nonEmpty": true }, "minItems": 1 },
+            "answer_kind": { "type": "string", "nonEmpty": true, "enum": ["text", "boolean", "single_select"] }
+          },
+          "required": ["id", "text", "rationale", "candidate_ids", "evidence_paths", "answer_kind"]
+        }
+      }
+    },
+    "required": ["summary", "questions"]
+  },
+  "playbook-write-result/v1": {
+    "type": "object",
+    "properties": {
+      "status": { "type": "string", "nonEmpty": true, "enum": ["written", "skipped_valid_existing", "blocked", "not_accepted", "dry_run_written", "invalid_manifest", "partial_manifest", "missing_playbook", "failed"] },
+      "message": { "type": "string", "nonEmpty": true },
+      "written_files": { "type": "array", "items": { "type": "string", "nonEmpty": true } },
+      "skipped_files": { "type": "array", "items": { "type": "string", "nonEmpty": true } },
+      "existing_playbook_path": { "type": "string" },
+      "intended_files": { "type": "array", "items": { "type": "string", "nonEmpty": true } },
+      "blocked_paths": { "type": "array", "items": { "type": "string", "nonEmpty": true } }
+    },
+    "required": ["status", "message", "written_files", "skipped_files", "existing_playbook_path", "intended_files", "blocked_paths"]
+  },
+  "practice-candidates/v1": {
+    "type": "object",
+    "properties": {
+      "summary": { "type": "string", "nonEmpty": true },
+      "candidates": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "id": { "type": "string", "nonEmpty": true },
+            "title": { "type": "string", "nonEmpty": true },
+            "proposed_rule_text": { "type": "string", "nonEmpty": true },
+            "confidence": { "type": "string", "nonEmpty": true, "enum": ["low", "medium", "high"] },
+            "evidence_paths": { "type": "array", "items": { "type": "string", "nonEmpty": true }, "minItems": 1 },
+            "rationale": { "type": "string", "nonEmpty": true },
+            "questions_needed": { "type": "array", "items": { "type": "string", "nonEmpty": true } }
+          },
+          "required": ["id", "title", "proposed_rule_text", "confidence", "evidence_paths", "rationale", "questions_needed"]
+        }
+      }
+    },
+    "required": ["summary", "candidates"]
+  },
+  "repo-inventory/v1": {
+    "type": "object",
+    "properties": {
+      "summary": { "type": "string", "nonEmpty": true },
+      "repository_root": { "type": "string", "nonEmpty": true },
+      "generated_at": { "type": "string", "nonEmpty": true },
+      "ignored_directories": { "type": "array", "items": { "type": "string", "nonEmpty": true } },
+      "stack_indicators": { "type": "array", "items": { "type": "object" } },
+      "test_structure": { "type": "array", "items": { "type": "object" } },
+      "architecture_hints": { "type": "array", "items": { "type": "object" } },
+      "quality_tooling": { "type": "array", "items": { "type": "object" } },
+      "specification_files": { "type": "array", "items": { "type": "object" } },
+      "runtime_configs": { "type": "array", "items": { "type": "object" } },
+      "generated_code": { "type": "array", "items": { "type": "object" } },
+      "evidence": { "type": "array", "items": { "type": "string", "nonEmpty": true } }
+    },
+    "required": ["summary", "repository_root", "generated_at", "ignored_directories", "stack_indicators", "test_structure", "architecture_hints", "quality_tooling", "specification_files", "runtime_configs", "generated_code", "evidence"]
+  },
   "qa-plan/v1": {
     "type": "object",
     "properties": {

package/dist/structured-artifacts.js

@@ -75,7 +75,13 @@ function validateNode(value, schema, currentPath) {
         case "json":
             return validateJsonValue(value, currentPath);
         case "number":
-            return typeof value === "number" && !Number.isNaN(value) ? [] : [`${currentPath} must be a number`];
+            if (typeof value !== "number" || Number.isNaN(value)) {
+                return [`${currentPath} must be a number`];
+            }
+            if (schema.minimum !== undefined && value < schema.minimum) {
+                return [`${currentPath} must be at least ${schema.minimum}`];
+            }
+            return [];
         case "null":
             return value === null ? [] : [`${currentPath} must be null`];
         case "array": {