@ztothez/design-engineering 2.0.0

package/dist/src/comparison/loader.js

@@ -0,0 +1,26 @@
+import { readFile, stat } from "node:fs/promises";
+import { extname, resolve } from "node:path";
+import { parse } from "yaml";
+import { comparisonMethodologySchema, comparisonReviewSchema, } from "./schema.js";
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+async function loadStructuredFile(path) {
+    const resolvedPath = resolve(path);
+    if (!/^\.(?:json|ya?ml)$/i.test(extname(resolvedPath))) {
+        throw new Error("Comparison files must end in .json, .yaml, or .yml");
+    }
+    const fileStats = await stat(resolvedPath);
+    if (!fileStats.isFile())
+        throw new Error("Comparison path is not a regular file");
+    if (fileStats.size > MAX_FILE_BYTES) {
+        throw new Error(`Comparison file exceeds ${MAX_FILE_BYTES} bytes`);
+    }
+    const text = await readFile(resolvedPath, "utf8");
+    return resolvedPath.endsWith(".json") ? JSON.parse(text) : parse(text);
+}
+export async function loadComparisonMethodology(path) {
+    return comparisonMethodologySchema.parse(await loadStructuredFile(path));
+}
+export async function loadComparisonReview(path) {
+    return comparisonReviewSchema.parse(await loadStructuredFile(path));
+}
+//# sourceMappingURL=loader.js.map

package/dist/src/comparison/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../../src/comparison/loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE7C,OAAO,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC;AAE7B,OAAO,EACL,2BAA2B,EAC3B,sBAAsB,GAGvB,MAAM,aAAa,CAAC;AAErB,MAAM,cAAc,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAEvC,KAAK,UAAU,kBAAkB,CAAC,IAAY;IAC5C,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACxE,CAAC;IACD,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,CAAC;IAC3C,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAClF,IAAI,SAAS,CAAC,IAAI,GAAG,cAAc,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,2BAA2B,cAAc,QAAQ,CAAC,CAAC;IACrE,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IAClD,OAAO,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AACzE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,IAAY;IAC1D,OAAO,2BAA2B,CAAC,KAAK,CAAC,MAAM,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC;AAC3E,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,IAAY;IACrD,OAAO,sBAAsB,CAAC,KAAK,CAAC,MAAM,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC;AACtE,CAAC"}

package/dist/src/comparison/maintainer.d.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import type { ComparisonMethodology, ComparisonReport, ComparisonReview } from "./schema.js";
+export declare const maintainerAssessmentSchema: z.ZodObject<{
+    version: z.ZodLiteral<"1.0.0">;
+    track: z.ZodLiteral<"solo-maintainer">;
+    generatedAt: z.ZodString;
+    methodologyId: z.ZodString;
+    reviewId: z.ZodString;
+    targetCandidate: z.ZodString;
+    engineeringReady: z.ZodBoolean;
+    externalReleaseReady: z.ZodBoolean;
+    externalValidationPending: z.ZodBoolean;
+    claimScope: z.ZodLiteral<"engineering-continuation-only">;
+    maintainerSessions: z.ZodObject<{
+        supplied: z.ZodNumber;
+        eligible: z.ZodNumber;
+        sessionIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    targetStages: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodString;
+        passed: z.ZodBoolean;
+    }, z.core.$strict>>;
+    categories: z.ZodArray<z.ZodObject<{
+        category: z.ZodString;
+        targetScore: z.ZodNullable<z.ZodNumber>;
+        minimumScore: z.ZodNumber;
+        comparatorScores: z.ZodArray<z.ZodObject<{
+            candidate: z.ZodString;
+            score: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strict>>;
+        passed: z.ZodBoolean;
+    }, z.core.$strict>>;
+    findings: z.ZodArray<z.ZodObject<{
+        ruleId: z.ZodString;
+        severity: z.ZodEnum<{
+            warning: "warning";
+            info: "info";
+            blocker: "blocker";
+        }>;
+        message: z.ZodString;
+    }, z.core.$strict>>;
+    limitations: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type MaintainerAssessment = z.infer<typeof maintainerAssessmentSchema>;
+export declare function assessSoloMaintainerTrack(methodology: ComparisonMethodology, review: ComparisonReview, comparisonReport: ComparisonReport): MaintainerAssessment;
+export declare function formatMaintainerAssessment(assessment: MaintainerAssessment): string;

package/dist/src/comparison/maintainer.js

@@ -0,0 +1,218 @@
+import { z } from "zod";
+const scoreSchema = z
+    .object({
+    candidate: z.string(),
+    score: z.number().min(0).max(4).nullable(),
+})
+    .strict();
+const categoryAssessmentSchema = z
+    .object({
+    category: z.string(),
+    targetScore: z.number().min(0).max(4).nullable(),
+    minimumScore: z.number().min(0).max(4),
+    comparatorScores: z.array(scoreSchema),
+    passed: z.boolean(),
+})
+    .strict();
+const maintainerFindingSchema = z
+    .object({
+    ruleId: z.string(),
+    severity: z.enum(["blocker", "warning", "info"]),
+    message: z.string(),
+})
+    .strict();
+export const maintainerAssessmentSchema = z
+    .object({
+    version: z.literal("1.0.0"),
+    track: z.literal("solo-maintainer"),
+    generatedAt: z.string(),
+    methodologyId: z.string(),
+    reviewId: z.string(),
+    targetCandidate: z.string(),
+    engineeringReady: z.boolean(),
+    externalReleaseReady: z.boolean(),
+    externalValidationPending: z.boolean(),
+    claimScope: z.literal("engineering-continuation-only"),
+    maintainerSessions: z
+        .object({
+        supplied: z.number().int().nonnegative(),
+        eligible: z.number().int().nonnegative(),
+        sessionIds: z.array(z.string()),
+    })
+        .strict(),
+    targetStages: z.array(z
+        .object({
+        id: z.string(),
+        status: z.string(),
+        passed: z.boolean(),
+    })
+        .strict()),
+    categories: z.array(categoryAssessmentSchema),
+    findings: z.array(maintainerFindingSchema),
+    limitations: z.array(z.string()),
+})
+    .strict();
+function mean(values) {
+    if (values.length === 0)
+        return null;
+    return values.reduce((total, value) => total + value, 0) / values.length;
+}
+function isDisclosedMaintainerSession(session) {
+    return session.level === "human-expert"
+        && session.origin === "reviewer-supplied"
+        && Boolean(session.contributor)
+        && Boolean(session.recordedAt)
+        && Boolean(session.blinding)
+        && (session.blinding.priorCandidateExposure
+            || !session.blinding.candidateIdentitiesWithheld
+            || session.blinding.conflicts.length > 0);
+}
+function hasCompleteExpertMatrix(session, methodology) {
+    const expertCriteria = methodology.rubric.categories.flatMap((category) => category.criteria
+        .filter((criterion) => criterion.evidenceLevel === "human-expert")
+        .map((criterion) => criterion.id));
+    const actual = new Set(session.ratings.map((rating) => `${rating.candidate}:${rating.criterion}`));
+    return methodology.candidates.every((candidate) => expertCriteria.every((criterion) => actual.has(`${candidate.id}:${criterion}`)));
+}
+function scoreCategory(sessions, methodology, categoryId, candidateId) {
+    const category = methodology.rubric.categories.find((entry) => entry.id === categoryId);
+    if (!category)
+        return null;
+    const expertCriteria = new Set(category.criteria
+        .filter((criterion) => criterion.evidenceLevel === "human-expert")
+        .map((criterion) => criterion.id));
+    return mean(sessions.flatMap((session) => session.ratings
+        .filter((rating) => rating.candidate === candidateId && expertCriteria.has(rating.criterion))
+        .map((rating) => rating.score)));
+}
+export function assessSoloMaintainerTrack(methodology, review, comparisonReport) {
+    const findings = [];
+    const benchmark = methodology.decision.benchmark;
+    const targetCandidate = benchmark?.targetCandidate
+        ?? methodology.decision.requiredStageCandidates?.[0]
+        ?? methodology.candidates[0].id;
+    const comparatorCandidates = benchmark?.comparatorCandidates ?? [];
+    const requiredCategories = benchmark?.requiredCategoryIds
+        ?? methodology.rubric.categories.map((category) => category.id);
+    const suppliedMaintainerSessions = review.sessions.filter(isDisclosedMaintainerSession);
+    const eligibleMaintainerSessions = suppliedMaintainerSessions.filter((session) => hasCompleteExpertMatrix(session, methodology));
+    if (suppliedMaintainerSessions.length === 0) {
+        findings.push({
+            ruleId: "ZTDE-MNT-001",
+            severity: "blocker",
+            message: "No attributed human-expert session explicitly discloses maintainer exposure or conflicts.",
+        });
+    }
+    else if (eligibleMaintainerSessions.length === 0) {
+        findings.push({
+            ruleId: "ZTDE-MNT-002",
+            severity: "blocker",
+            message: "The disclosed maintainer review does not score every human-expert criterion for every candidate.",
+        });
+    }
+    if (!comparisonReport.passed) {
+        findings.push({
+            ruleId: "ZTDE-MNT-003",
+            severity: "blocker",
+            message: "The underlying comparison contains integrity errors.",
+        });
+    }
+    const targetStages = comparisonReport.stageResults
+        .filter((stage) => stage.candidate === targetCandidate && stage.required)
+        .map((stage) => ({ id: stage.id, status: stage.status, passed: stage.status === "pass" }));
+    if (targetStages.length === 0 || targetStages.some((stage) => !stage.passed)) {
+        findings.push({
+            ruleId: "ZTDE-MNT-004",
+            severity: "blocker",
+            message: "One or more required automated target stages are missing or not passing.",
+        });
+    }
+    const categories = requiredCategories.map((category) => {
+        const targetScore = scoreCategory(eligibleMaintainerSessions, methodology, category, targetCandidate);
+        const comparatorScores = comparatorCandidates.map((candidate) => ({
+            candidate,
+            score: scoreCategory(eligibleMaintainerSessions, methodology, category, candidate),
+        }));
+        const passed = targetScore !== null
+            && targetScore >= methodology.decision.minimumCategoryScore
+            && comparatorScores.every((entry) => entry.score !== null && targetScore >= entry.score);
+        if (!passed) {
+            findings.push({
+                ruleId: "ZTDE-MNT-005",
+                severity: "blocker",
+                message: `Maintainer-scored category ${category} is missing, below the configured floor, or below a comparator.`,
+            });
+        }
+        return {
+            category,
+            targetScore,
+            minimumScore: methodology.decision.minimumCategoryScore,
+            comparatorScores,
+            passed,
+        };
+    });
+    if (!comparisonReport.releaseReady) {
+        findings.push({
+            ruleId: "ZTDE-MNT-101",
+            severity: "warning",
+            message: "Independent human-expert and representative-user validation remains incomplete.",
+        });
+    }
+    findings.push({
+        ruleId: "ZTDE-MNT-102",
+        severity: "info",
+        message: "Maintainer evidence may authorize continued engineering but cannot establish independent preference, representative-user comprehension, or external release approval.",
+    });
+    const engineeringReady = findings.every((finding) => finding.severity !== "blocker");
+    return maintainerAssessmentSchema.parse({
+        version: "1.0.0",
+        track: "solo-maintainer",
+        generatedAt: new Date().toISOString(),
+        methodologyId: methodology.id,
+        reviewId: review.id,
+        targetCandidate,
+        engineeringReady,
+        externalReleaseReady: comparisonReport.releaseReady,
+        externalValidationPending: !comparisonReport.releaseReady,
+        claimScope: "engineering-continuation-only",
+        maintainerSessions: {
+            supplied: suppliedMaintainerSessions.length,
+            eligible: eligibleMaintainerSessions.length,
+            sessionIds: eligibleMaintainerSessions.map((session) => session.id),
+        },
+        targetStages,
+        categories,
+        findings,
+        limitations: [
+            "The maintainer knows candidate identities and has prior exposure to the target implementation.",
+            "This track contains no representative-user task evidence.",
+            "Engineering readiness is not external release readiness and must not be described as independent validation.",
+        ],
+    });
+}
+export function formatMaintainerAssessment(assessment) {
+    const lines = [
+        "# Solo-Maintainer Assessment",
+        "",
+        `- Engineering ready: ${assessment.engineeringReady ? "YES" : "NO"}`,
+        `- External release ready: ${assessment.externalReleaseReady ? "YES" : "NO"}`,
+        `- External validation pending: ${assessment.externalValidationPending ? "YES" : "NO"}`,
+        `- Claim scope: \`${assessment.claimScope}\``,
+        `- Eligible maintainer sessions: ${assessment.maintainerSessions.eligible}`,
+        "",
+        "## Category Checks",
+        "",
+        ...assessment.categories.map((category) => {
+            const comparators = category.comparatorScores
+                .map((entry) => `${entry.candidate}=${entry.score === null ? "missing" : entry.score.toFixed(2)}`)
+                .join(", ");
+            return `- \`${category.category}\`: target=${category.targetScore === null ? "missing" : category.targetScore.toFixed(2)}, minimum=${category.minimumScore.toFixed(2)}, comparators=${comparators || "none"}, ${category.passed ? "PASS" : "BLOCK"}`;
+        }),
+        "",
+        "## Evidence Boundary",
+        "",
+        ...assessment.limitations.map((limitation) => `- ${limitation}`),
+    ];
+    return lines.join("\n");
+}
+//# sourceMappingURL=maintainer.js.map

package/dist/src/comparison/maintainer.js.map

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

package/dist/src/comparison/report.d.ts

@@ -0,0 +1,2 @@
+import type { ComparisonReport } from "./schema.js";
+export declare function formatComparisonReport(report: ComparisonReport): string;

package/dist/src/comparison/report.js

@@ -0,0 +1,48 @@
+export function formatComparisonReport(report) {
+    const lines = [
+        "# ZtotheZ Design Engineering Interface Comparison",
+        "",
+        `- Methodology: \`${report.methodologyId}\``,
+        `- Review: \`${report.reviewId}\``,
+        `- Validation: ${report.passed ? "PASS" : "FAIL"}`,
+        `- Release ready: ${report.releaseReady ? "YES" : "NO"}`,
+        `- Required stages: ${report.summary.passedRequiredStages}/${report.summary.requiredStages} passed`,
+        `- Findings: ${report.summary.errors} errors, ${report.summary.warnings} warnings, ${report.summary.info} info`,
+        `- Claims: ${report.summary.verifiedClaims}/${report.summary.claims} verified`,
+        `- Human-expert sessions: ${report.humanReview.completeHumanExpertSessions}/${report.humanReview.minimumHumanExpertSessions} required complete (${report.humanReview.humanExpertSessions} supplied)`,
+        `- Representative-user sessions: ${report.humanReview.completeRepresentativeUserSessions}/${report.humanReview.minimumRepresentativeUserSessions} required complete (${report.humanReview.representativeUserSessions} supplied)`,
+        `- Counterbalanced orders: ${report.humanReview.distinctCandidateOrders}/${report.humanReview.minimumCounterbalancedOrders} required`,
+        `- Blinded reviewer sessions: ${report.humanReview.blindedReviewerSessions}`,
+        `- Target benchmark: ${report.benchmarkDecision.configured ? (report.benchmarkDecision.passed ? "PASS" : "INCOMPLETE OR FAIL") : "not configured"}`,
+        "",
+        "Evidence levels remain distinct. Validation does not convert AI inspection into human-expert or representative-user evidence.",
+    ];
+    if (report.stageResults.length > 0) {
+        lines.push("", "## Required Stages", "");
+        for (const stage of report.stageResults) {
+            lines.push(`- \`${stage.candidate}:${stage.id}\`: ${stage.status}${stage.required ? " (required)" : ""}`);
+        }
+    }
+    if (report.candidateResults.length > 0) {
+        lines.push("", "## Candidate Results", "");
+        for (const candidate of report.candidateResults) {
+            const categories = candidate.categories
+                .map((category) => `${category.category}=${category.score === null ? "missing" : category.score.toFixed(2)} (${category.samples})`)
+                .join(", ");
+            lines.push(`- \`${candidate.candidate}\`: ${categories}; completion=${candidate.tasks.completionRate === null ? "missing" : candidate.tasks.completionRate.toFixed(2)}, comprehension=${candidate.tasks.comprehensionAccuracy === null ? "missing" : candidate.tasks.comprehensionAccuracy.toFixed(2)}, confidence=${candidate.tasks.meanConfidence === null ? "missing" : candidate.tasks.meanConfidence.toFixed(2)}, duration=${candidate.tasks.meanDurationSeconds === null ? "missing" : `${candidate.tasks.meanDurationSeconds.toFixed(2)}s`}`);
+        }
+    }
+    if (report.benchmarkDecision.issues.length > 0) {
+        lines.push("", "## Benchmark Decision Gaps", "");
+        for (const issue of report.benchmarkDecision.issues)
+            lines.push(`- ${issue}`);
+    }
+    if (report.findings.length > 0) {
+        lines.push("", "## Findings");
+        for (const finding of report.findings) {
+            lines.push("", `### ${finding.severity.toUpperCase()} ${finding.ruleId}`, "", `- Path: \`${finding.path}\``, `- Problem: ${finding.message}`, `- Remediation: ${finding.remediation}`);
+        }
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=report.js.map

package/dist/src/comparison/report.js.map

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