@phamvuhoang/otto-core 0.29.0 → 0.31.0

package/dist/verification-matrix.js

@@ -0,0 +1,337 @@
+/**
+ * Verification matrix (issue #181 P24, slice 1 — "make verification provable").
+ *
+ * A pure data model + scorer for the roadmap's verification-artifact matrix:
+ * each requirement (a plan task / acceptance criterion) paired with HOW it was
+ * checked, the concrete artifact that proves it (a `file:line`, a commit SHA, a
+ * command transcript, a screenshot path), the result, and a confidence. Today
+ * the `verify` stage emits this as free-form DONE/GAP/DEFERRED prose; P24 turns
+ * it into a structured matrix a maintainer can scan, and a "verification
+ * gallery" a non-engineer can accept/reject from.
+ *
+ * This slice is the substrate — the type, a summary scorer (counts, artifact
+ * coverage, an overall verdict), and a formatter that renders the matrix and
+ * surfaces failures / unproven requirements as explicit risks rather than
+ * burying them in logs. INERT on the loop: nothing here runs a stage or changes
+ * behavior; later P24 slices populate it from the verify stage and fold it into
+ * run reports + `otto-inspect`. Mirrors how the plan/context/report rubrics
+ * shipped pure-then-wired.
+ */
+const METHODS = new Set([
+    "test",
+    "command",
+    "visual",
+    "inspection",
+    "manual",
+]);
+const RESULTS = new Set([
+    "pass",
+    "fail",
+    "partial",
+    "deferred",
+]);
+const CONFIDENCES = new Set(["high", "medium", "low"]);
+/**
+ * Whether a string is a *typed*, durable artifact reference that actually proves
+ * something — a `file:line` (or `file:line-range`), a path with a separator or a
+ * file extension (a transcript / screenshot / source file), or a 7–40 char commit
+ * SHA. A bare command (`node --test`), prose (`read the code`), or a placeholder
+ * (`TODO`) is NOT proof and returns false, so the coverage signal can't be earned
+ * by an unverifiable string (#181 review). Pure.
+ */
+export function isValidArtifactReference(ref) {
+    const r = ref.trim();
+    if (!r)
+        return false;
+    if (/\s/.test(r))
+        return false; // commands / prose carry whitespace
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(r))
+        return false; // URLs (scheme://)
+    if (/(?:^|[\\/])\.\.(?:[\\/]|$)/.test(r))
+        return false; // path traversal
+    if (/^[0-9a-f]{7,40}$/i.test(r))
+        return true; // commit SHA
+    if (/^[\w./\\-]+:\d+(?:-\d+)?$/.test(r))
+        return true; // file:line or file:line-range
+    return /[/\\]/.test(r) || /\.[A-Za-z0-9]{1,8}$/.test(r); // a path, or a file with an extension
+}
+/**
+ * Whether an entry carries a *valid, typed* proving artifact. Syntactically valid
+ * (see {@link isValidArtifactReference}) AND not marked non-existent by the loop's
+ * filesystem/git validation (`artifactExists === false`). When `artifactExists` is
+ * undefined the syntax check stands alone — the pure scorer cannot touch the
+ * filesystem, so the loop sets `artifactExists` before this matters at runtime.
+ */
+function hasArtifact(e) {
+    return (Boolean(e.artifactPath) &&
+        isValidArtifactReference(e.artifactPath) &&
+        e.artifactExists !== false);
+}
+/**
+ * Parse an agent-emitted verification matrix (a JSON `VerificationEntry[]`,
+ * e.g. the `.otto-tmp/verify-matrix.json` the verify stage writes), keeping the
+ * parse diagnostics so a malformed/partial matrix is reported, not silently
+ * dropped (#181 review). Tolerant: never throws, drops any entry missing a
+ * non-empty `requirement` or carrying an unknown `method`/`result`, defaults an
+ * absent/invalid `confidence` to `medium`, and counts each dropped row. Non-array
+ * / malformed JSON ⇒ `{ entries: [], dropped: 0, parsed: false }`. Pure.
+ */
+export function parseVerificationMatrixWithDiagnostics(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { entries: [], dropped: 0, parsed: false };
+    }
+    if (!Array.isArray(parsed))
+        return { entries: [], dropped: 0, parsed: false };
+    const entries = [];
+    let dropped = 0;
+    for (const item of parsed) {
+        const entry = coerceEntry(item);
+        if (entry)
+            entries.push(entry);
+        else
+            dropped += 1;
+    }
+    return { entries, dropped, parsed: true };
+}
+function coerceEntry(item) {
+    if (!item || typeof item !== "object")
+        return null;
+    const r = item;
+    const requirement = typeof r.requirement === "string" ? r.requirement.trim() : "";
+    if (!requirement)
+        return null;
+    if (typeof r.method !== "string" || !METHODS.has(r.method))
+        return null;
+    if (typeof r.result !== "string" || !RESULTS.has(r.result))
+        return null;
+    const confidence = typeof r.confidence === "string" && CONFIDENCES.has(r.confidence)
+        ? r.confidence
+        : "medium";
+    return {
+        requirement,
+        method: r.method,
+        check: typeof r.check === "string" ? r.check : "",
+        ...(typeof r.artifactPath === "string" && r.artifactPath
+            ? { artifactPath: r.artifactPath }
+            : {}),
+        ...(typeof r.beforePath === "string" && r.beforePath
+            ? { beforePath: r.beforePath }
+            : {}),
+        result: r.result,
+        confidence,
+        ...(typeof r.note === "string" && r.note ? { note: r.note } : {}),
+    };
+}
+/** Parse a verification matrix into valid entries (diagnostics discarded). Pure. */
+export function parseVerificationMatrix(raw) {
+    return parseVerificationMatrixWithDiagnostics(raw).entries;
+}
+/** Whether a requirement is one we expect a concrete artifact for (i.e. not deferred). */
+function isVerifiable(e) {
+    return e.result !== "deferred";
+}
+/** Tally a verification matrix into counts, artifact coverage, and a verdict. Pure. */
+export function summarizeVerification(entries) {
+    const total = entries.length;
+    const pass = entries.filter((e) => e.result === "pass").length;
+    const fail = entries.filter((e) => e.result === "fail").length;
+    const partial = entries.filter((e) => e.result === "partial").length;
+    const deferred = entries.filter((e) => e.result === "deferred").length;
+    const verifiable = entries.filter(isVerifiable);
+    const withArtifact = entries.filter(hasArtifact).length;
+    const verifiableProven = verifiable.filter(hasArtifact).length;
+    // Vacuous truth: an all-deferred matrix (entries, but none verifiable) is fully
+    // covered — there is nothing left to prove (#181 review). An empty matrix has
+    // nothing measured, so coverage is 0.
+    const coverage = total === 0
+        ? 0
+        : verifiable.length > 0
+            ? verifiableProven / verifiable.length
+            : 1;
+    let verdict;
+    if (total === 0)
+        verdict = "empty";
+    else if (fail > 0)
+        verdict = "gaps";
+    else if (verifiable.length > 0 && verifiableProven === 0)
+        verdict = "unproven";
+    else if (coverage >= 1 && partial === 0)
+        verdict = "verified";
+    else
+        verdict = "partial";
+    return {
+        total,
+        pass,
+        fail,
+        partial,
+        deferred,
+        withArtifact,
+        coverage,
+        verdict,
+    };
+}
+/**
+ * Score a verification matrix against the roadmap's coverage bar (P24): every
+ * verifiable requirement must carry a valid artifact, none may fail, none may be
+ * left partial, and no rows may have been dropped during parsing. `dropped` rows
+ * are unknown requirements that cannot be assumed proven, so any drop FAILs the
+ * gate (#181 re-review). The `unproven`/`failed`/`incomplete` lists + `dropped`
+ * are exactly why the gate did not pass. Pure.
+ */
+export function scoreVerificationCoverage(entries, dropped = 0) {
+    const summary = summarizeVerification(entries);
+    return {
+        passed: summary.verdict === "verified" && dropped === 0,
+        coverage: summary.coverage,
+        unproven: entries
+            .filter((e) => isVerifiable(e) && !hasArtifact(e))
+            .map((e) => e.requirement),
+        failed: entries
+            .filter((e) => e.result === "fail")
+            .map((e) => e.requirement),
+        incomplete: entries
+            .filter((e) => e.result === "partial")
+            .map((e) => e.requirement),
+        dropped,
+    };
+}
+/**
+ * Render the verification-coverage gate as a report block (mirrors the emit-time
+ * legibility gate): a PASS/FAIL verdict, the artifact-backed coverage, and — on
+ * FAIL — the unproven/failed requirements plus how to clear them. Empty string
+ * for an empty matrix, so a run with no verification adds no gate. Pure.
+ */
+export function formatVerificationCoverageGate(entries, dropped = 0) {
+    if (entries.length === 0 && dropped === 0)
+        return "";
+    const g = scoreVerificationCoverage(entries, dropped);
+    const lines = [
+        "## Verification Coverage Gate",
+        "",
+        `Gate: **${g.passed ? "PASS" : "FAIL"}** — ${pct.format(g.coverage * 100)}% of verifiable requirements are artifact-backed.`,
+    ];
+    if (!g.passed) {
+        if (g.dropped > 0) {
+            lines.push("", `Dropped ${g.dropped} malformed matrix row(s) — those requirements are unknown and unverified; fix the matrix.`);
+        }
+        if (g.failed.length > 0) {
+            lines.push("", `Failed: ${g.failed.join(", ")}.`);
+        }
+        if (g.incomplete.length > 0) {
+            lines.push("", `Incomplete (partial — finish or split): ${g.incomplete.join(", ")}.`);
+        }
+        if (g.unproven.length > 0) {
+            lines.push("", `Unproven (cite a valid artifact — \`file:line\`, a commit SHA, a transcript/screenshot path — or mark the requirement \`deferred\`): ${g.unproven.join(", ")}.`);
+        }
+        // A FAIL with no failed/incomplete/unproven items would be unexplained; make
+        // the residual reason explicit rather than leaving an empty gate (#181 review).
+        if (g.dropped === 0 &&
+            g.failed.length === 0 &&
+            g.incomplete.length === 0 &&
+            g.unproven.length === 0) {
+            lines.push("", "No requirement is fully proven, yet none is individually failed/partial/unproven — review the matrix.");
+        }
+    }
+    return lines.join("\n");
+}
+/** Path prefix of artifacts relocated into the run bundle (see
+ *  `verification-evidence.ts`); only these resolve relative to report.md. */
+export const BUNDLE_ARTIFACT_PREFIX = "verification/";
+const IMAGE_RE = /\.(?:png|jpe?g|gif|webp|svg|avif)$/i;
+/**
+ * A path safe to embed as a markdown image: it was actually copied into the
+ * physical run bundle by the impure layer (`bundled === true` — not a string
+ * prefix the agent could spoof) and has an image extension. So a rejected URL, an
+ * un-relocated path, or an agent-supplied `verification/…` masquerade is never
+ * emitted as an image (#181 boundary review).
+ */
+function embeddableImage(p, bundled) {
+    return (bundled === true &&
+        typeof p === "string" &&
+        !p.includes("..") &&
+        IMAGE_RE.test(p));
+}
+/**
+ * Render the visual evidence (P24 visual half) as a markdown "Screenshot
+ * Evidence" section that *embeds* each `visual` entry's captured screenshot —
+ * a single image, or a before → after pair — so a non-engineer reading the run
+ * report sees the proof, not just a path. Only artifacts the impure layer actually
+ * **copied into the bundle** (`artifactBundled`/`beforeBundled`) and that are
+ * images are embedded; a visual check the environment could not render, or any
+ * unbundled/spoofed path, is left to the coverage gate to flag, never emitted as
+ * an image. Empty string when no embeddable visual evidence exists. Pure.
+ */
+export function formatVisualEvidence(entries) {
+    const visuals = entries.filter((e) => e.method === "visual" &&
+        embeddableImage(e.artifactPath, e.artifactBundled));
+    if (visuals.length === 0)
+        return "";
+    const lines = ["## Screenshot Evidence", ""];
+    for (const e of visuals) {
+        lines.push(`### ${e.requirement}`, "");
+        if (embeddableImage(e.beforePath, e.beforeBundled)) {
+            lines.push(`- Before: ![before](${e.beforePath})`);
+            lines.push(`- After: ![after](${e.artifactPath})`);
+        }
+        else {
+            lines.push(`![${e.requirement}](${e.artifactPath})`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n").trimEnd();
+}
+const RESULT_MARK = {
+    pass: "✓",
+    fail: "✗",
+    partial: "~",
+    deferred: "·",
+};
+const pct = new Intl.NumberFormat("en-US", { maximumFractionDigits: 0 });
+/** Collapse a (possibly multi-line) check to one bounded, fence-safe line. */
+function oneLine(s, max = 80) {
+    const flat = s.replace(/\s+/g, " ").trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+/**
+ * Render a verification matrix as a scannable report: a header verdict line, one
+ * row per requirement (mark · method · requirement · artifact), and an explicit
+ * **Risks** section listing every failed or unproven requirement so a reader
+ * cannot miss them. Pure.
+ */
+export function formatVerificationMatrix(entries) {
+    if (entries.length === 0) {
+        return "Verification: no verification recorded for this run.";
+    }
+    const s = summarizeVerification(entries);
+    const lines = [
+        `Verification: ${s.verdict} — ${s.pass}/${s.total} pass` +
+            (s.fail > 0 ? `, ${s.fail} fail` : "") +
+            (s.partial > 0 ? `, ${s.partial} partial` : "") +
+            (s.deferred > 0 ? `, ${s.deferred} deferred` : "") +
+            ` · ${pct.format(s.coverage * 100)}% artifact-backed`,
+    ];
+    for (const e of entries) {
+        const artifact = hasArtifact(e)
+            ? ` → ${e.artifactPath}`
+            : e.artifactPath
+                ? ` → ${e.artifactPath} (not a valid artifact)`
+                : " → (no artifact)";
+        const conf = e.confidence !== "high" ? ` [${e.confidence}]` : "";
+        const check = e.check ? `  · check: ${oneLine(e.check)}` : "";
+        lines.push(`  ${RESULT_MARK[e.result]} ${e.method}: ${e.requirement}${conf}${artifact}${check}`);
+    }
+    const risks = entries.filter((e) => e.result === "fail" || (isVerifiable(e) && !hasArtifact(e)));
+    if (risks.length > 0) {
+        lines.push("", `Risks (${risks.length}):`);
+        for (const e of risks) {
+            const why = e.result === "fail" ? "failed" : "unproven (no valid artifact)";
+            lines.push(`  - ${e.requirement} — ${why}`);
+        }
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=verification-matrix.js.map

package/dist/verification-matrix.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phamvuhoang/otto-core",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "description": "Claude Code AFK orchestration: iteration loop, native-sandbox runner, template renderer.",
   "type": "module",
   "license": "MIT",

package/templates/plan.md

@@ -18,6 +18,8 @@
 
 </inputs>
 
+{{ SHARPENING }}
+
 # PLAN (AUTHOR THE SPEC + PLAN — DO NOT IMPLEMENT)
 
 You are PLANNING, not implementing. Turn the thin task in `<inputs>` into a

package/templates/verify.md

@@ -22,7 +22,7 @@
 
 You are VERIFYING, not implementing. The `<inputs>` block names a plan and PRD (conventionally file paths). `Read` them.
 
-**Make NO commits and NO source edits.** You may read files and run the test/type suites. The only file you may write is the report named at the end.
+**Make NO commits and NO source edits.** You may read files and run the test/type suites. The only files you may write are the verification report and matrix named below and any verification artifacts they cite (e.g. screenshots), all under the gitignored `.otto-tmp/` scratch dir — nothing else.
 
 # RECONCILE
 
@@ -49,6 +49,46 @@ Write your report to `.otto-tmp/verify-report.md` using the `Write` tool (this p
 
 @include:quality-report.md
 
+# VERIFICATION MATRIX (MACHINE-READABLE)
+
+Also write a structured verification matrix to `.otto-tmp/verify-matrix.json`
+using the `Write` tool (gitignored scratch — this, the report above, and any
+screenshot artifacts cited below are the only writes you may make). It is a JSON
+array, one entry per plan task /
+acceptance criterion you reconciled, so a maintainer (or a non-engineer) can scan
+exactly what was proven and how:
+
+```json
+[
+  {
+    "requirement": "<the task / acceptance criterion>",
+    "method": "test | command | visual | inspection | manual",
+    "check": "<the exact command run, the assertion, or the visual checked>",
+    "artifactPath": "<proof: file:line, a commit SHA, a transcript/screenshot path; omit if none>",
+    "result": "pass | fail | partial | deferred",
+    "confidence": "high | medium | low"
+  }
+]
+```
+
+Rules: one entry per task; `result` mirrors your DONE/GAP/DEFERRED classification
+(`pass` = DONE, `fail`/`partial` = GAP, `deferred` = DEFERRED); always cite an
+`artifactPath` when one exists (a `file:line`, the commit SHA that implements it,
+or the suite command) — an entry with no artifact is an unproven claim and should
+say so via `"confidence": "low"`. Use the real commands you ran; do not invent
+proof. A malformed file is ignored, so prefer omitting a field to guessing.
+
+**Visual evidence (opportunistic).** For a UI/web requirement, if a screenshot
+tool and a renderable target (a running dev server or a static built artifact)
+are actually available to you, capture a screenshot, save it under the gitignored
+`.otto-tmp/` scratch dir, and emit a `"method": "visual"` entry whose
+`artifactPath` is that screenshot path; for a before/after change set `beforePath`
+to the prior-state screenshot and `artifactPath` to the new one. **Never fabricate
+a screenshot or a path.** If you cannot render or capture the UI in this
+environment, still emit the `visual` entry but **omit `artifactPath`** and set
+`"confidence": "low"` — the coverage gate then reports the gap honestly instead of
+claiming unproven visual proof.
+
 # CROSS-RUN QUALITY SUMMARY (READ-ONLY)
 
 Beyond _this_ run, give the maintainer a quality rollup **across** runs so they can