agentera 3.0.0-dev.4 → 3.0.0-dev.46

package/dist/registries/capabilityContract.js

@@ -11,6 +11,7 @@ export const BOOTSTRAP_RULE_SECTIONS = [
     "FIELD_RULES",
     "PRIMITIVE_REFERENCE_FIELDS",
     "ROUTE_ALIASES",
+    "TRIGGER_ENRICHMENT",
 ];
 export class ContractBootstrapError extends Error {
     errors;
@@ -26,7 +27,7 @@ function isMapping(value) {
 export function loadCapabilitySchemaContract(contractPath) {
     let data;
     try {
-        data = loadYamlMapping(fs.readFileSync(contractPath, "utf8"));
+        data = loadYamlMapping(fs.readFileSync(contractPath, "utf8")); // cast: YAML parse IO boundary
     }
     catch (exc) {
         throw new ContractBootstrapError([
@@ -73,7 +74,8 @@ export function buildCapabilitySchemaContract(data, contractPath) {
         path: contractPath,
         requiredGroups: [...data.REQUIRED_GROUPS],
         directoryRules: {
-            instructionPath: directory.instruction_file.path,
+            instructionPath: directory.instruction_module.path,
+            instructionModulePath: directory.instruction_module.path,
             schemasPath: directory.schemas_directory.path,
             schemaGlob: schemaFiles.glob,
             minimumSchemaFiles: schemaFiles.minimum_count,
@@ -99,8 +101,47 @@ export function buildCapabilitySchemaContract(data, contractPath) {
                 capability: entry.capability,
             })),
         },
+        triggerEnrichment: buildTriggerEnrichmentRules(data),
     };
 }
+function buildTriggerEnrichmentRules(data) {
+    const enrichment = data.TRIGGER_ENRICHMENT;
+    const fields = enrichment.fields;
+    const primaryAliases = data.ROUTE_ALIASES.primary_aliases;
+    const allowedCapabilityIds = primaryAliases.map((entry) => entry.capability);
+    return {
+        spec: enrichment.spec,
+        fields: Object.fromEntries(Object.entries(fields).map(([name, raw]) => [name, buildEnrichmentFieldRule(raw)])),
+        allowedCapabilityIds,
+    };
+}
+function buildEnrichmentFieldRule(raw) {
+    const rule = {
+        type: raw.type,
+        required: Boolean(raw.required),
+        default: raw.default,
+    };
+    if (typeof raw.min === "number")
+        rule.min = raw.min;
+    if (typeof raw.max === "number")
+        rule.max = raw.max;
+    if (raw.each_must_be_valid_regex === true)
+        rule.eachMustBeValidRegex = true;
+    if (isMapping(raw.entries)) {
+        const entries = {};
+        for (const [entryName, entryRaw] of Object.entries(raw.entries)) {
+            const e = entryRaw;
+            entries[entryName] = {
+                type: e.type,
+                required: Boolean(e.required),
+                nonEmpty: e.non_empty === true,
+                enumSource: typeof e.enum_source === "string" ? e.enum_source : "",
+            };
+        }
+        rule.entries = entries;
+    }
+    return rule;
+}
 function requiredGroupsOf(data, sourceLabel, errors) {
     const groups = data.REQUIRED_GROUPS;
     if (!Array.isArray(groups) ||
@@ -153,30 +194,31 @@ function checkRuleSections(data, sourceLabel, errors) {
     checkTriggerPriorityRules(data, sourceLabel, errors);
     checkPrimitiveReferenceRules(data, sourceLabel, errors);
     checkRouteAliasRules(data, sourceLabel, errors);
+    checkTriggerEnrichmentRules(data, sourceLabel, errors);
 }
 function checkDirectoryRules(data, sourceLabel, errors) {
     const directory = data.DIRECTORY_REQUIREMENTS;
     if (!isMapping(directory)) {
         return;
     }
-    for (const section of ["instruction_file", "schemas_directory", "schema_files"]) {
+    for (const section of ["instruction_module", "schemas_directory", "schema_files"]) {
         if (!isMapping(directory[section])) {
             errors.push(`bootstrap [error]: DIRECTORY_REQUIREMENTS.${section} in ${sourceLabel} must be a mapping`);
         }
     }
     if ("required_files" in directory) {
-        errors.push(`bootstrap [error]: DIRECTORY_REQUIREMENTS.required_files in ${sourceLabel} duplicates instruction_file and schemas_directory authority`);
+        errors.push(`bootstrap [error]: DIRECTORY_REQUIREMENTS.required_files in ${sourceLabel} duplicates instruction_module and schemas_directory authority`);
     }
-    const instructionFile = directory.instruction_file;
-    if (isMapping(instructionFile)) {
-        if (instructionFile.path !== "instructions.md") {
-            errors.push(`bootstrap [error]: DIRECTORY_REQUIREMENTS.instruction_file.path in ${sourceLabel} must be instructions.md`);
+    const instructionModule = directory.instruction_module;
+    if (isMapping(instructionModule)) {
+        if (instructionModule.path !== "packages/cli/src/capabilities/<name>/instructions.ts") {
+            errors.push(`bootstrap [error]: DIRECTORY_REQUIREMENTS.instruction_module.path in ${sourceLabel} must be packages/cli/src/capabilities/<name>/instructions.ts`);
         }
-        if (instructionFile.type !== "file") {
-            errors.push(`bootstrap [error]: DIRECTORY_REQUIREMENTS.instruction_file.type in ${sourceLabel} must be file`);
+        if (instructionModule.type !== "file") {
+            errors.push(`bootstrap [error]: DIRECTORY_REQUIREMENTS.instruction_module.type in ${sourceLabel} must be file`);
         }
-        if (instructionFile.required !== true) {
-            errors.push(`bootstrap [error]: DIRECTORY_REQUIREMENTS.instruction_file.required in ${sourceLabel} must be true`);
+        if (instructionModule.required !== true) {
+            errors.push(`bootstrap [error]: DIRECTORY_REQUIREMENTS.instruction_module.required in ${sourceLabel} must be true`);
         }
     }
     const schemaFiles = directory.schema_files;
@@ -307,4 +349,90 @@ function checkSelfGroups(data, sourceLabel, requiredGroups, errors) {
         }
     }
 }
-//# sourceMappingURL=capabilityContract.js.map
+/**
+ * Required integer range field inside TRIGGER_ENRICHMENT compatibility rules.
+ */
+function checkEnrichmentIntegerField(value, label, sourceLabel, errors) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > 100) {
+        errors.push(`bootstrap [error]: ${label} in ${sourceLabel} must be an integer in range 0..100`);
+    }
+}
+function checkTriggerEnrichmentRules(data, sourceLabel, errors) {
+    const enrichment = data.TRIGGER_ENRICHMENT;
+    if (!isMapping(enrichment)) {
+        errors.push(`bootstrap [error]: TRIGGER_ENRICHMENT in ${sourceLabel} must be present as a mapping`);
+        return;
+    }
+    if (typeof enrichment.spec !== "string" || !enrichment.spec) {
+        errors.push(`bootstrap [error]: TRIGGER_ENRICHMENT.spec in ${sourceLabel} must be a non-empty string`);
+    }
+    const fields = enrichment.fields;
+    if (!isMapping(fields)) {
+        errors.push(`bootstrap [error]: TRIGGER_ENRICHMENT.fields in ${sourceLabel} must be a mapping`);
+        return;
+    }
+    // Legacy fields remain shape-validated for compatibility, but are not
+    // carried into the active semantic trigger model.
+    const expected = {
+        patterns: "list_of_strings",
+        confidence_threshold: "integer",
+        borderline_band: "integer",
+        patterns_regex: "list_of_strings",
+        disambiguates_against: "list_of_mappings",
+    };
+    for (const [fieldName, expectedType] of Object.entries(expected)) {
+        if (!isMapping(fields[fieldName])) {
+            errors.push(`bootstrap [error]: TRIGGER_ENRICHMENT.fields.${fieldName} in ${sourceLabel} must be a mapping`);
+            continue;
+        }
+        if (fields[fieldName].type !== expectedType) {
+            errors.push(`bootstrap [error]: TRIGGER_ENRICHMENT.fields.${fieldName}.type in ${sourceLabel} must be ${expectedType}`);
+        }
+        if (fields[fieldName].required !== false) {
+            errors.push(`bootstrap [error]: TRIGGER_ENRICHMENT.fields.${fieldName}.required in ${sourceLabel} must be false (enrichment is opt-in)`);
+        }
+        const min = fields[fieldName].min;
+        const max = fields[fieldName].max;
+        if (expectedType === "integer") {
+            if (typeof min !== "number" || min !== 0) {
+                errors.push(`bootstrap [error]: TRIGGER_ENRICHMENT.fields.${fieldName}.min in ${sourceLabel} must be 0`);
+            }
+            if (typeof max !== "number" || max !== 100) {
+                errors.push(`bootstrap [error]: TRIGGER_ENRICHMENT.fields.${fieldName}.max in ${sourceLabel} must be 100`);
+            }
+        }
+        if (fieldName === "patterns_regex" && fields[fieldName].each_must_be_valid_regex !== true) {
+            errors.push(`bootstrap [error]: TRIGGER_ENRICHMENT.fields.${fieldName}.each_must_be_valid_regex in ${sourceLabel} must be true`);
+        }
+    }
+    // disambiguates_against.entries capability/hint shape
+    const disambig = isMapping(fields.disambiguates_against) ? fields.disambiguates_against : null;
+    const entriesList = disambig && isMapping(disambig.entries) ? disambig.entries : null;
+    if (disambig && !entriesList) {
+        errors.push(`bootstrap [error]: TRIGGER_ENRICHMENT.fields.disambiguates_against.entries in ${sourceLabel} must be a mapping`);
+    }
+    if (entriesList) {
+        if (!isMapping(entriesList.capability)) {
+            errors.push(`bootstrap [error]: TRIGGER_ENRICHMENT.fields.disambiguates_against.entries.capability in ${sourceLabel} must be a mapping`);
+        }
+        else {
+            if (entriesList.capability.required !== true) {
+                errors.push(`bootstrap [error]: TRIGGER_ENRICHMENT.fields.disambiguates_against.entries.capability.required in ${sourceLabel} must be true`);
+            }
+            if (entriesList.capability.enum_source !== "ROUTE_ALIASES.primary_aliases.capability") {
+                errors.push(`bootstrap [error]: TRIGGER_ENRICHMENT.fields.disambiguates_against.entries.capability.enum_source in ${sourceLabel} must be ROUTE_ALIASES.primary_aliases.capability`);
+            }
+        }
+        if (!isMapping(entriesList.hint)) {
+            errors.push(`bootstrap [error]: TRIGGER_ENRICHMENT.fields.disambiguates_against.entries.hint in ${sourceLabel} must be a mapping`);
+        }
+        else {
+            if (entriesList.hint.required !== true) {
+                errors.push(`bootstrap [error]: TRIGGER_ENRICHMENT.fields.disambiguates_against.entries.hint.required in ${sourceLabel} must be true`);
+            }
+            if (entriesList.hint.non_empty !== true) {
+                errors.push(`bootstrap [error]: TRIGGER_ENRICHMENT.fields.disambiguates_against.entries.hint.non_empty in ${sourceLabel} must be true`);
+            }
+        }
+    }
+}

package/dist/registries/evaluatorHandoffContract.js

@@ -0,0 +1,170 @@
+import fs from "node:fs";
+import { execSync } from "node:child_process";
+import path from "node:path";
+import { loadYamlMapping } from "../core/yaml.js";
+/**
+ * Evaluator-handoff contract loader and audit evaluation report validator.
+ * Authority: references/cli/capability-instruction-contract.yaml#evaluator_handoff
+ */
+export const EVALUATOR_HANDOFF_REPORT_SCHEMA_VERSION = "agentera.inspekteraEvaluationReport.v1";
+function isMapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function asString(value) {
+    return value === null || value === undefined ? "" : String(value).trim();
+}
+export function defaultEvaluatorHandoffContractPath(repoRoot) {
+    return path.join(repoRoot, "references", "cli", "capability-instruction-contract.yaml");
+}
+export function loadEvaluatorHandoffContract(contractPath) {
+    const data = loadYamlMapping(fs.readFileSync(contractPath, "utf8")); // cast: YAML parse IO boundary
+    const handoff = data.evaluator_handoff;
+    if (!isMapping(handoff)) {
+        throw new Error(`evaluator_handoff section missing in ${contractPath}`);
+    }
+    const rowSchema = isMapping(handoff.row_schema) ? handoff.row_schema : {};
+    const citationFormats = isMapping(rowSchema.citation_formats) ? rowSchema.citation_formats : {};
+    const fileLine = isMapping(citationFormats.file_line) ? citationFormats.file_line : {};
+    const notApplicable = isMapping(citationFormats.not_applicable) ? citationFormats.not_applicable : {};
+    const warnVerify = isMapping(rowSchema.warn_verify_command) ? rowSchema.warn_verify_command : {};
+    const patternSource = asString(fileLine.pattern) || "^[^:\\s]+:\\d+$";
+    return {
+        path: contractPath,
+        status: asString(handoff.status) || "unknown",
+        reportSchemaVersion: asString(handoff.report_schema_version) || EVALUATOR_HANDOFF_REPORT_SCHEMA_VERSION,
+        citationRequiredFor: Array.isArray(rowSchema.citation_required_for)
+            ? rowSchema.citation_required_for.map((v) => String(v))
+            : ["WARN", "FAIL"],
+        fileLinePattern: new RegExp(patternSource),
+        notApplicablePrefix: asString(notApplicable.prefix) || "not-applicable:",
+        minNotApplicableReasonLength: Number(notApplicable.min_reason_length) || 8,
+        warnVerifyCommandRequired: warnVerify.required_when === "file_line_citation",
+        warnVerifyCommandPrefixes: Array.isArray(warnVerify.allowed_prefixes)
+            ? warnVerify.allowed_prefixes.map((v) => String(v))
+            : ["grep", "git show"],
+    };
+}
+export function isFileLineCitation(citation, contract) {
+    return contract.fileLinePattern.test(citation);
+}
+export function isNotApplicableCitation(citation, contract) {
+    if (!citation.startsWith(contract.notApplicablePrefix))
+        return false;
+    const reason = citation.slice(contract.notApplicablePrefix.length).trim();
+    return reason.length >= contract.minNotApplicableReasonLength;
+}
+export function isValidCitation(citation, contract) {
+    const trimmed = citation.trim();
+    if (!trimmed)
+        return false;
+    return isFileLineCitation(trimmed, contract) || isNotApplicableCitation(trimmed, contract);
+}
+export function parseFileLineCitation(citation) {
+    const match = /^([^:\s]+):(\d+)$/.exec(citation.trim());
+    if (!match)
+        return null;
+    return { file: match[1], line: Number(match[2]) };
+}
+export function isAllowedVerifyCommand(command, contract) {
+    const trimmed = command.trim();
+    return contract.warnVerifyCommandPrefixes.some((prefix) => trimmed.startsWith(prefix));
+}
+export function validateEvaluationReportRow(row, index, contract) {
+    const errors = [];
+    const label = `rows[${index}]`;
+    const status = asString(row.status).toUpperCase();
+    const criterion = asString(row.criterion);
+    const evidence = asString(row.evidence);
+    if (!criterion)
+        errors.push(`${label}: missing criterion`);
+    if (!status)
+        errors.push(`${label}: missing status`);
+    if (!evidence)
+        errors.push(`${label}: missing evidence`);
+    if (!contract.citationRequiredFor.includes(status))
+        return errors;
+    const citation = asString(row.citation);
+    if (!citation) {
+        errors.push(`${label}: WARN/FAIL row missing citation`);
+        return errors;
+    }
+    if (!isValidCitation(citation, contract)) {
+        errors.push(`${label}: citation must be file:line (e.g. TODO.md:15) or not-applicable: <reason> (min ${contract.minNotApplicableReasonLength} chars)`);
+        return errors;
+    }
+    if (status === "WARN" && contract.warnVerifyCommandRequired && isFileLineCitation(citation, contract)) {
+        const verifyCommand = asString(row.verify_command);
+        if (!verifyCommand) {
+            errors.push(`${label}: WARN row with file:line citation missing verify_command`);
+        }
+        else if (!isAllowedVerifyCommand(verifyCommand, contract)) {
+            errors.push(`${label}: verify_command must start with grep or git show`);
+        }
+    }
+    return errors;
+}
+export function validateEvaluationReport(report, contract) {
+    const errors = [];
+    const schemaVersion = asString(report.schemaVersion);
+    if (schemaVersion && schemaVersion !== contract.reportSchemaVersion) {
+        errors.push(`schemaVersion must be ${contract.reportSchemaVersion}`);
+    }
+    const rows = Array.isArray(report.rows) ? report.rows : null;
+    if (!rows || rows.length === 0) {
+        errors.push("rows must be a non-empty array");
+        return errors;
+    }
+    rows.forEach((row, index) => {
+        errors.push(...validateEvaluationReportRow(row, index, contract));
+    });
+    return errors;
+}
+function readCitedLine(repoRoot, file, line) {
+    const absPath = path.isAbsolute(file) ? file : path.join(repoRoot, file);
+    if (!fs.existsSync(absPath))
+        return "";
+    const lines = fs.readFileSync(absPath, "utf8").split(/\r?\n/);
+    return (lines[line - 1] ?? "").trim();
+}
+export function verifyWarnCitationAtLine(row, repoRoot) {
+    const citation = asString(row.citation);
+    const verifyCommand = asString(row.verify_command);
+    const parsed = parseFileLineCitation(citation);
+    if (!parsed) {
+        return { ok: true, message: "not-applicable citation skips line verification" };
+    }
+    const citedLine = readCitedLine(repoRoot, parsed.file, parsed.line);
+    if (!citedLine) {
+        return { ok: false, message: `cited line ${parsed.line} is missing or empty in ${parsed.file}` };
+    }
+    if (!verifyCommand) {
+        return { ok: false, message: "missing verify_command for file:line citation" };
+    }
+    try {
+        const output = execSync(verifyCommand, { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })
+            .trim();
+        if (output.includes(citedLine)) {
+            return { ok: true, message: "verify_command output includes cited line text" };
+        }
+        return {
+            ok: false,
+            message: `verify_command output does not reproduce cited line ${parsed.line} in ${parsed.file}`,
+        };
+    }
+    catch (exc) {
+        return { ok: false, message: `verify_command failed: ${exc.message}` };
+    }
+}
+export function evaluatorHandoffOutputRequirements(contract) {
+    return {
+        citation_required_for: contract.citationRequiredFor,
+        warn_verify_command_required: contract.warnVerifyCommandRequired,
+        citation_formats: {
+            file_line: "path/to/file:line",
+            not_applicable: `${contract.notApplicablePrefix}<reason>`,
+        },
+        verify_command_prefixes: contract.warnVerifyCommandPrefixes,
+        report_schema_version: contract.reportSchemaVersion,
+        schema_authority: "references/cli/capability-instruction-contract.yaml#evaluator_handoff",
+    };
+}