@itsthelore/proofkeeper 2026.6.0

package/dist/writeback/comment.js

@@ -0,0 +1,150 @@
+/**
+ * Pull-request comment renderers — Proofkeeper Initiative 5.
+ *
+ * Two informational comments, both behind the human-review boundary (ADR-065):
+ * Proofkeeper never merges or approves; it only reports.
+ *
+ *  - {@link renderWriteBackComment}: a confirmation on the write-back PR it
+ *    raises — the linked evidence plus the fidelity result.
+ *  - {@link renderCoverageComment}: a verification-coverage status for a
+ *    developer's feature PR, driven by the coverage read-model.
+ *
+ * Pure string builders (no I/O) so they are unit-testable; the gateway posts.
+ */
+const REVIEW_NOTE = "_Informational — a human reviewer accepts the link (ADR-065). Proofkeeper produces and runs the evidence; it does not merge or approve._";
+/**
+ * Hidden, namespaced markers identifying each Proofkeeper comment kind. Embedded
+ * as invisible HTML comments at the top of a body so a pull request carries one
+ * canonical comment per kind that {@link upsertComment} finds and updates in
+ * place, regardless of how the prose is reformatted.
+ */
+export const SCOPED_QA_MARKER = "<!-- proofkeeper:scoped-qa -->";
+export const WRITE_BACK_MARKER = "<!-- proofkeeper:write-back -->";
+export const COVERAGE_MARKER = "<!-- proofkeeper:coverage -->";
+function linkLine(link) {
+    return `- \`${link.test}\`${link.trace ? ` (trace: \`${link.trace}\`)` : ""}`;
+}
+/** Confirmation comment for the write-back PR Proofkeeper raises. */
+export function renderWriteBackComment(input) {
+    const lines = [
+        WRITE_BACK_MARKER,
+        `Proofkeeper recorded verification for **${input.capabilityId}**.`,
+        "",
+        "Linked evidence:",
+        ...input.links.map(linkLine),
+    ];
+    if (input.plan && input.plan.trim().length > 0) {
+        lines.push("", "Test plan:", "", input.plan.trim());
+    }
+    if (input.steps && input.steps.length > 0) {
+        lines.push("", "Steps exercised:");
+        input.steps.forEach((s, i) => lines.push(`${i + 1}. ${s}`));
+    }
+    const trace = input.links.find((l) => l.trace)?.trace;
+    if (trace) {
+        lines.push("", `Replay the trace locally: \`npx playwright show-trace ${trace}\``);
+    }
+    if (input.fidelity) {
+        const f = input.fidelity;
+        lines.push("", `Fidelity gate: ${f.passed}/${f.attempts} re-runs green — ${f.stable ? "stable, safe to commit" : "unstable, quarantined"}.`);
+    }
+    lines.push("", REVIEW_NOTE);
+    return lines.join("\n");
+}
+/** Verification-coverage status comment for a developer's feature PR. */
+export function renderCoverageComment(report, options = {}) {
+    const heading = options.title ?? "Proofkeeper verification coverage";
+    const src = report.source ? ` for \`${report.source}\`` : "";
+    const lines = [
+        COVERAGE_MARKER,
+        `## ${heading}${src}`,
+        "",
+        `${report.verified.length}/${report.total} capabilities have a verifying test; ${report.unverified.length} unverified.`,
+    ];
+    if (report.verified.length > 0) {
+        lines.push("", "Verified by committed tests:");
+        for (const c of report.verified) {
+            // Bare paths backtick cleanly; only wrap a target that has no backtick of
+            // its own, so a legacy verbose target is shown verbatim rather than nested.
+            const targets = c.verifiedBy.map((t) => (t.includes("`") ? t : `\`${t}\``)).join(", ");
+            lines.push(`- **${c.id}** — ${c.title}: ${targets}`);
+        }
+    }
+    if (report.unverified.length > 0) {
+        lines.push("", "Still unverified:");
+        for (const c of report.unverified) {
+            lines.push(`- ${c.id} — ${c.title}`);
+        }
+    }
+    lines.push("", REVIEW_NOTE);
+    return lines.join("\n");
+}
+/** Scoped-QA evidence comment for the feature PR that triggered the run. */
+export function renderScopedQaComment(input) {
+    const lines = [
+        SCOPED_QA_MARKER,
+        `## Proofkeeper QA — ${input.changedCount} changed file(s)`,
+        "",
+        input.driven.length > 0
+            ? `Drove ${input.driven.length} capability(ies) this change touched:`
+            : "No unverified capabilities were touched by this change.",
+    ];
+    for (const r of input.driven) {
+        if (r.error) {
+            lines.push(`- ⚠️ **${r.id}** — ${r.title}: ${r.error}`);
+        }
+        else if (r.stable) {
+            lines.push(`- ✅ **${r.id}** — ${r.title}: stable${r.writeBackUrl ? ` — proposed ${r.writeBackUrl}` : ""}`);
+        }
+        else {
+            lines.push(`- ❌ **${r.id}** — ${r.title}: unstable (quarantined)`);
+        }
+    }
+    if (input.alreadyVerified.length > 0) {
+        lines.push("", "Already verified, not re-driven:");
+        for (const c of input.alreadyVerified)
+            lines.push(`- ${c.id} — ${c.title}`);
+    }
+    if (input.unknown.length > 0) {
+        lines.push("", `Config ids not found as capabilities in the graph: ${input.unknown.join(", ")}`);
+    }
+    if (input.failureSuggestions && input.failureSuggestions.length > 0) {
+        lines.push("", "Known failure modes:");
+        for (const s of input.failureSuggestions) {
+            lines.push(`- **${s.id}** — ${s.title}:`);
+            for (const reason of s.reasons)
+                lines.push(`  - ${reason}`);
+        }
+    }
+    lines.push("", REVIEW_NOTE);
+    return lines.join("\n");
+}
+/**
+ * Maintain exactly one comment per kind on a pull request: find the existing
+ * comment whose body carries `marker` and update it in place; otherwise create
+ * one (the body itself carries the marker, so it is self-identifying next time).
+ * Keys only on the marker, never on prose.
+ */
+export async function upsertComment(gateway, input) {
+    const existing = await gateway.listComments(input.number);
+    const match = existing.find((c) => c.body.includes(input.marker));
+    if (match) {
+        const updated = await gateway.updateComment(match.id, input.body);
+        return { url: updated.url, updated: true };
+    }
+    const created = await gateway.commentOnPullRequest({ number: input.number, body: input.body });
+    return { url: created.url, updated: false };
+}
+/**
+ * Post (or update in place) a verification-coverage status comment on a feature
+ * pull request. The report comes from the coverage read-model (`computeCoverage`).
+ * Informational only — it never approves or merges.
+ */
+export function commentCoverageStatus(gateway, input) {
+    return upsertComment(gateway, {
+        number: input.prNumber,
+        marker: COVERAGE_MARKER,
+        body: renderCoverageComment(input.report, input.options ?? {}),
+    });
+}
+//# sourceMappingURL=comment.js.map

package/dist/writeback/comment.js.map

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

package/dist/writeback/gateways/github-rest.d.ts

@@ -0,0 +1,66 @@
+/**
+ * A concrete {@link RepoGateway} over the GitHub REST API — Proofkeeper
+ * Initiative 5.
+ *
+ * Dependency-free: it uses the global `fetch` (Node ≥ 20), so wiring the
+ * write-back to GitHub needs no SDK. `fetch` is injectable for testing. A token
+ * with `contents:write` + `pull_requests:write` on the target repo is required.
+ *
+ * It only ever branches, commits to that branch, and opens a pull request — it
+ * never writes the base branch (the proposer relies on that; this gateway
+ * exposes no base-write path either). The trust boundary stays human PR review
+ * (ADR-065).
+ */
+import type { RepoGateway } from "../proposer.js";
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+export interface GitHubRestGatewayOptions {
+    owner: string;
+    repo: string;
+    /** Token with contents:write and pull_requests:write on the repo. */
+    token: string;
+    /** Override for testing or GitHub Enterprise. Defaults to api.github.com. */
+    fetch?: FetchLike;
+    baseUrl?: string;
+}
+export declare class GitHubRestGateway implements RepoGateway {
+    private readonly owner;
+    private readonly repo;
+    private readonly token;
+    private readonly fetchImpl;
+    private readonly baseUrl;
+    constructor(options: GitHubRestGatewayOptions);
+    private request;
+    private repoPath;
+    getFileContent(path: string, ref: string): Promise<string>;
+    createBranch(name: string, fromRef: string): Promise<void>;
+    commitFile(input: {
+        branch: string;
+        path: string;
+        content: string;
+        message: string;
+    }): Promise<void>;
+    openPullRequest(input: {
+        base: string;
+        head: string;
+        title: string;
+        body: string;
+    }): Promise<{
+        url: string;
+        number: number;
+    }>;
+    commentOnPullRequest(input: {
+        number: number;
+        body: string;
+    }): Promise<{
+        url: string;
+    }>;
+    listComments(prNumber: number): Promise<{
+        id: number;
+        body: string;
+    }[]>;
+    updateComment(commentId: number, body: string): Promise<{
+        url: string;
+    }>;
+}
+export {};
+//# sourceMappingURL=github-rest.d.ts.map

package/dist/writeback/gateways/github-rest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-rest.d.ts","sourceRoot":"","sources":["../../../src/writeback/gateways/github-rest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,KAAK,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAExE,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,iBAAkB,YAAW,WAAW;IACnD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,EAAE,wBAAwB;YAW/B,OAAO;IAiBrB,OAAO,CAAC,QAAQ;IAIV,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAW1D,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU1D,UAAU,CAAC,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBpG,eAAe,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QACjG,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IAUI,oBAAoB,CAAC,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAQvF,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAQvE,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CAM/E"}

package/dist/writeback/gateways/github-rest.js

@@ -0,0 +1,107 @@
+/**
+ * A concrete {@link RepoGateway} over the GitHub REST API — Proofkeeper
+ * Initiative 5.
+ *
+ * Dependency-free: it uses the global `fetch` (Node ≥ 20), so wiring the
+ * write-back to GitHub needs no SDK. `fetch` is injectable for testing. A token
+ * with `contents:write` + `pull_requests:write` on the target repo is required.
+ *
+ * It only ever branches, commits to that branch, and opens a pull request — it
+ * never writes the base branch (the proposer relies on that; this gateway
+ * exposes no base-write path either). The trust boundary stays human PR review
+ * (ADR-065).
+ */
+export class GitHubRestGateway {
+    owner;
+    repo;
+    token;
+    fetchImpl;
+    baseUrl;
+    constructor(options) {
+        this.owner = options.owner;
+        this.repo = options.repo;
+        this.token = options.token;
+        this.fetchImpl = options.fetch ?? globalThis.fetch;
+        this.baseUrl = options.baseUrl ?? "https://api.github.com";
+        if (!this.fetchImpl) {
+            throw new Error("GitHubRestGateway needs a fetch implementation (Node >= 20 or inject one).");
+        }
+    }
+    async request(method, path, body) {
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method,
+            headers: {
+                authorization: `Bearer ${this.token}`,
+                accept: "application/vnd.github+json",
+                "x-github-api-version": "2022-11-28",
+                ...(body ? { "content-type": "application/json" } : {}),
+            },
+            ...(body ? { body: JSON.stringify(body) } : {}),
+        });
+        if (!res.ok) {
+            throw new Error(`GitHub ${method} ${path} failed: ${res.status} ${await res.text()}`);
+        }
+        return res.status === 204 ? undefined : (await res.json());
+    }
+    repoPath(suffix) {
+        return `/repos/${this.owner}/${this.repo}${suffix}`;
+    }
+    async getFileContent(path, ref) {
+        const data = (await this.request("GET", this.repoPath(`/contents/${encodeURIComponent(path).replace(/%2F/g, "/")}?ref=${encodeURIComponent(ref)}`)));
+        if (typeof data.content !== "string") {
+            throw new Error(`no file content at ${path}@${ref}`);
+        }
+        return Buffer.from(data.content, data.encoding ?? "base64").toString("utf8");
+    }
+    async createBranch(name, fromRef) {
+        const ref = (await this.request("GET", this.repoPath(`/git/ref/heads/${fromRef}`)));
+        await this.request("POST", this.repoPath("/git/refs"), {
+            ref: `refs/heads/${name}`,
+            sha: ref.object.sha,
+        });
+    }
+    async commitFile(input) {
+        // Look up the file's blob sha on the branch (required to update an existing file).
+        let sha;
+        try {
+            const existing = (await this.request("GET", this.repoPath(`/contents/${encodeURIComponent(input.path).replace(/%2F/g, "/")}?ref=${encodeURIComponent(input.branch)}`)));
+            sha = existing.sha;
+        }
+        catch {
+            sha = undefined; // new file
+        }
+        await this.request("PUT", this.repoPath(`/contents/${encodeURIComponent(input.path).replace(/%2F/g, "/")}`), {
+            message: input.message,
+            content: Buffer.from(input.content, "utf8").toString("base64"),
+            branch: input.branch,
+            ...(sha ? { sha } : {}),
+        });
+    }
+    async openPullRequest(input) {
+        const pr = (await this.request("POST", this.repoPath("/pulls"), {
+            title: input.title,
+            head: input.head,
+            base: input.base,
+            body: input.body,
+        }));
+        return { url: pr.html_url, number: pr.number };
+    }
+    async commentOnPullRequest(input) {
+        // PR comments are issue comments in the GitHub REST API.
+        const comment = (await this.request("POST", this.repoPath(`/issues/${input.number}/comments`), {
+            body: input.body,
+        }));
+        return { url: comment.html_url };
+    }
+    async listComments(prNumber) {
+        const data = (await this.request("GET", this.repoPath(`/issues/${prNumber}/comments?per_page=100`)));
+        return data.map((c) => ({ id: c.id, body: c.body ?? "" }));
+    }
+    async updateComment(commentId, body) {
+        const comment = (await this.request("PATCH", this.repoPath(`/issues/comments/${commentId}`), {
+            body,
+        }));
+        return { url: comment.html_url };
+    }
+}
+//# sourceMappingURL=github-rest.js.map

package/dist/writeback/gateways/github-rest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-rest.js","sourceRoot":"","sources":["../../../src/writeback/gateways/github-rest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAgBH,MAAM,OAAO,iBAAiB;IACX,KAAK,CAAS;IACd,IAAI,CAAS;IACb,KAAK,CAAS;IACd,SAAS,CAAY;IACrB,OAAO,CAAS;IAEjC,YAAY,OAAiC;QAC3C,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,KAAK,IAAK,UAAU,CAAC,KAAmB,CAAC;QAClE,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,wBAAwB,CAAC;QAC3D,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CAAC,4EAA4E,CAAC,CAAC;QAChG,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,OAAO,CAAC,MAAc,EAAE,IAAY,EAAE,IAAc;QAChE,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,EAAE;YACzD,MAAM;YACN,OAAO,EAAE;gBACP,aAAa,EAAE,UAAU,IAAI,CAAC,KAAK,EAAE;gBACrC,MAAM,EAAE,6BAA6B;gBACrC,sBAAsB,EAAE,YAAY;gBACpC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACxD;YACD,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChD,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,UAAU,MAAM,IAAI,IAAI,YAAY,GAAG,CAAC,MAAM,IAAI,MAAM,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACxF,CAAC;QACD,OAAO,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAE,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAa,CAAC;IAC1E,CAAC;IAEO,QAAQ,CAAC,MAAc;QAC7B,OAAO,UAAU,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,GAAG,MAAM,EAAE,CAAC;IACtD,CAAC;IAED,KAAK,CAAC,cAAc,CAAC,IAAY,EAAE,GAAW;QAC5C,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,OAAO,CAC9B,KAAK,EACL,IAAI,CAAC,QAAQ,CAAC,aAAa,kBAAkB,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,QAAQ,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC,CAC3G,CAA4C,CAAC;QAC9C,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,sBAAsB,IAAI,IAAI,GAAG,EAAE,CAAC,CAAC;QACvD,CAAC;QACD,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAG,IAAI,CAAC,QAA2B,IAAI,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACnG,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,IAAY,EAAE,OAAe;QAC9C,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,kBAAkB,OAAO,EAAE,CAAC,CAAC,CAEjF,CAAC;QACF,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE;YACrD,GAAG,EAAE,cAAc,IAAI,EAAE;YACzB,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG;SACpB,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,KAAyE;QACxF,mFAAmF;QACnF,IAAI,GAAuB,CAAC;QAC5B,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,CAAC,MAAM,IAAI,CAAC,OAAO,CAClC,KAAK,EACL,IAAI,CAAC,QAAQ,CAAC,aAAa,kBAAkB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,QAAQ,kBAAkB,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAC1H,CAAqB,CAAC;YACvB,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC;QACrB,CAAC;QAAC,MAAM,CAAC;YACP,GAAG,GAAG,SAAS,CAAC,CAAC,WAAW;QAC9B,CAAC;QACD,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,aAAa,kBAAkB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC,EAAE;YAC3G,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC;YAC9D,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACxB,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,eAAe,CAAC,KAAkE;QAItF,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE;YAC9D,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,IAAI,EAAE,KAAK,CAAC,IAAI;SACjB,CAAC,CAAyC,CAAC;QAC5C,OAAO,EAAE,GAAG,EAAE,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC;IACjD,CAAC;IAED,KAAK,CAAC,oBAAoB,CAAC,KAAuC;QAChE,yDAAyD;QACzD,MAAM,OAAO,GAAG,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,WAAW,KAAK,CAAC,MAAM,WAAW,CAAC,EAAE;YAC7F,IAAI,EAAE,KAAK,CAAC,IAAI;SACjB,CAAC,CAAyB,CAAC;QAC5B,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,QAAgB;QACjC,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,OAAO,CAC9B,KAAK,EACL,IAAI,CAAC,QAAQ,CAAC,WAAW,QAAQ,wBAAwB,CAAC,CAC3D,CAAoC,CAAC;QACtC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;IAC7D,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,SAAiB,EAAE,IAAY;QACjD,MAAM,OAAO,GAAG,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,oBAAoB,SAAS,EAAE,CAAC,EAAE;YAC3F,IAAI;SACL,CAAC,CAAyB,CAAC;QAC5B,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;IACnC,CAAC;CACF"}

package/dist/writeback/merge.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Merge a `## Verified By` section into a requirement artifact's Markdown —
+ * Proofkeeper Initiative 5 (the write-back transform).
+ *
+ * Pure and idempotent: given the artifact's current content and a set of
+ * {@link VerificationLink}s, return the updated content with the links recorded
+ * under `## Verified By`. Re-running with the same links is a no-op (the diff is
+ * empty), which is what lets the proposer skip opening an empty pull request.
+ *
+ * Placement follows the engine's relationship-section ordering (ADR-084):
+ * `## Verified By` is the last relationship section, so it is inserted directly
+ * after the trailing `## Related *` block (or `## Supersedes`), and otherwise
+ * appended. An existing section is merged in place, preserving its lines.
+ *
+ * This is a pure transform. It never writes a file or touches a corpus — the
+ * proposer carries the result into a human-reviewed pull request (ADR-065).
+ */
+import { type VerificationLink } from "./verified-by.js";
+/**
+ * Merge `links` into the `## Verified By` section of `content`. Each link
+ * contributes its bare test reference and, when present, its bare trace
+ * reference (both are external-target references, ADR-084).
+ *
+ * @throws {Error} when `links` is empty — an empty section is never written.
+ */
+export declare function mergeVerifiedBy(content: string, links: VerificationLink[]): string;
+//# sourceMappingURL=merge.d.ts.map

package/dist/writeback/merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../src/writeback/merge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,kBAAkB,CAAC;AA4B1B;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,EAAE,GAAG,MAAM,CAkDlF"}

package/dist/writeback/merge.js

@@ -0,0 +1,89 @@
+/**
+ * Merge a `## Verified By` section into a requirement artifact's Markdown —
+ * Proofkeeper Initiative 5 (the write-back transform).
+ *
+ * Pure and idempotent: given the artifact's current content and a set of
+ * {@link VerificationLink}s, return the updated content with the links recorded
+ * under `## Verified By`. Re-running with the same links is a no-op (the diff is
+ * empty), which is what lets the proposer skip opening an empty pull request.
+ *
+ * Placement follows the engine's relationship-section ordering (ADR-084):
+ * `## Verified By` is the last relationship section, so it is inserted directly
+ * after the trailing `## Related *` block (or `## Supersedes`), and otherwise
+ * appended. An existing section is merged in place, preserving its lines.
+ *
+ * This is a pure transform. It never writes a file or touches a corpus — the
+ * proposer carries the result into a human-reviewed pull request (ADR-065).
+ */
+import { renderVerifiedByItem, verificationRefs, VERIFIED_BY_HEADING, } from "./verified-by.js";
+const SECTION_TITLE = "verified by";
+/** Level-2 (`## `) headings only — `### ` subsections belong to their parent. */
+function level2Headings(lines) {
+    const headings = [];
+    lines.forEach((line, index) => {
+        const match = /^##\s+(.+?)\s*$/.exec(line);
+        if (match && !line.startsWith("###")) {
+            headings.push({ line: index, title: match[1].toLowerCase() });
+        }
+    });
+    return headings;
+}
+/** The first backtick-quoted token on a list item — its reference path. */
+function itemRef(item) {
+    return /`([^`]+)`/.exec(item)?.[1];
+}
+/**
+ * Merge `links` into the `## Verified By` section of `content`. Each link
+ * contributes its bare test reference and, when present, its bare trace
+ * reference (both are external-target references, ADR-084).
+ *
+ * @throws {Error} when `links` is empty — an empty section is never written.
+ */
+export function mergeVerifiedBy(content, links) {
+    if (links.length === 0) {
+        throw new Error("refusing to merge an empty `## Verified By` section");
+    }
+    const wanted = verificationRefs(links);
+    const lines = content.split("\n");
+    const headings = level2Headings(lines);
+    const existing = headings.find((h) => h.title === SECTION_TITLE);
+    if (existing) {
+        // Merge into the existing section: keep its lines, append only new refs.
+        const next = headings.find((h) => h.line > existing.line);
+        const end = next ? next.line : lines.length;
+        const sectionLines = lines.slice(existing.line, end);
+        const presentRefs = new Set(sectionLines.filter((l) => l.startsWith("- ")).map(itemRef).filter(Boolean));
+        const additions = wanted.filter((ref) => !presentRefs.has(ref)).map(renderVerifiedByItem);
+        if (additions.length === 0)
+            return content; // idempotent: nothing new
+        // Insert new items after the last existing list item (or after the heading).
+        let lastItem = existing.line;
+        for (let i = existing.line; i < end; i++) {
+            if (lines[i].startsWith("- "))
+                lastItem = i;
+        }
+        const merged = [...lines.slice(0, lastItem + 1), ...additions, ...lines.slice(lastItem + 1)];
+        return merged.join("\n");
+    }
+    // No existing section — build one and place it after the relationship block.
+    const section = [VERIFIED_BY_HEADING, "", ...wanted.map(renderVerifiedByItem)];
+    const anchor = [...headings].reverse().find((h) => h.title.startsWith("related ")) ??
+        headings.find((h) => h.title === "supersedes");
+    if (anchor) {
+        const next = headings.find((h) => h.line > anchor.line);
+        const insertAt = next ? next.line : lines.length;
+        const before = lines.slice(0, insertAt);
+        const after = lines.slice(insertAt);
+        // Ensure a blank line separates the new section from its neighbours.
+        while (before.length > 0 && before[before.length - 1] === "")
+            before.pop();
+        const block = ["", ...section, ...(after.length > 0 ? [""] : [])];
+        return [...before, ...block, ...after].join("\n");
+    }
+    // Append at end of document.
+    const trimmed = [...lines];
+    while (trimmed.length > 0 && trimmed[trimmed.length - 1] === "")
+        trimmed.pop();
+    return [...trimmed, "", ...section, ""].join("\n");
+}
+//# sourceMappingURL=merge.js.map

package/dist/writeback/merge.js.map

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

package/dist/writeback/proposal.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Assemble a `## Verified By` write-back proposal — Proofkeeper Initiative 5.
+ *
+ * Pure and deterministic (no timestamps): given a target artifact's current
+ * content and the verification links, produce the updated content plus the
+ * branch name, PR title, and PR body for a human-reviewed pull request. The
+ * proposal carries `changed: false` when every link is already present, so the
+ * proposer can decline to open an empty PR.
+ */
+import type { CandidateTest } from "../compiler/types.js";
+import type { RunResult } from "../runner/types.js";
+import type { VerificationLink } from "./verified-by.js";
+export interface BuildProposalInput {
+    /** The capability (requirement id) being verified. */
+    capabilityId: string;
+    /** Path to the requirement artifact within the target corpus. */
+    targetPath: string;
+    /** Current content of the target artifact. */
+    originalContent: string;
+    /** The verification links to record. */
+    links: VerificationLink[];
+    /** Base branch the PR targets. Defaults to `main`. */
+    baseBranch?: string;
+    /** Prefix for the generated head branch. Defaults to `proofkeeper/verified-by`. */
+    branchPrefix?: string;
+    /** Readable step summary of the driven flow, shown in the PR body. */
+    steps?: string[];
+    /** The Markdown test plan the model wrote before driving, shown in the PR body. */
+    plan?: string;
+}
+export interface WriteBackProposal {
+    capabilityId: string;
+    targetPath: string;
+    baseBranch: string;
+    headBranch: string;
+    title: string;
+    body: string;
+    originalContent: string;
+    updatedContent: string;
+    links: VerificationLink[];
+    /** False when the merge produced no change (all links already present). */
+    changed: boolean;
+}
+/** Build a write-back proposal (does not touch any repo). */
+export declare function buildProposal(input: BuildProposalInput): WriteBackProposal;
+/**
+ * Derive verification links from a compiled test and its run results: the
+ * committed spec (the corpus verifier) plus the first replayable trace produced
+ * for it (surfaced in the PR).
+ */
+export declare function linksFromResults(candidate: CandidateTest, results: RunResult[]): VerificationLink[];
+//# sourceMappingURL=proposal.d.ts.map

package/dist/writeback/proposal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proposal.d.ts","sourceRoot":"","sources":["../../src/writeback/proposal.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAKzD,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,YAAY,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,eAAe,EAAE,MAAM,CAAC;IACxB,wCAAwC;IACxC,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,mFAAmF;IACnF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,2EAA2E;IAC3E,OAAO,EAAE,OAAO,CAAC;CAClB;AAmDD,6DAA6D;AAC7D,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,iBAAiB,CAgB1E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,aAAa,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,gBAAgB,EAAE,CAKnG"}

package/dist/writeback/proposal.js

@@ -0,0 +1,79 @@
+/**
+ * Assemble a `## Verified By` write-back proposal — Proofkeeper Initiative 5.
+ *
+ * Pure and deterministic (no timestamps): given a target artifact's current
+ * content and the verification links, produce the updated content plus the
+ * branch name, PR title, and PR body for a human-reviewed pull request. The
+ * proposal carries `changed: false` when every link is already present, so the
+ * proposer can decline to open an empty PR.
+ */
+import { mergeVerifiedBy } from "./merge.js";
+const DEFAULT_BASE_BRANCH = "main";
+const DEFAULT_BRANCH_PREFIX = "proofkeeper/verified-by";
+/** Deterministic, filesystem/branch-safe slug. */
+function slug(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "capability";
+}
+function proposalBody(input) {
+    const items = input.links
+        .map((l) => `- \`${l.test}\`${l.trace ? ` (trace: \`${l.trace}\`)` : ""}`)
+        .join("\n");
+    const lines = [
+        `Proofkeeper proposes recording verification for **${input.capabilityId}**.`,
+        "",
+        `It adds a \`## Verified By\` section to \`${input.targetPath}\` linking the`,
+        "committed test(s) and replayable trace(s) that exercise this capability, as",
+        "bare reference paths.",
+        "",
+        "These are external-target links (ADR-084): the engine emits them with",
+        "`resolved: false` and the literal reference as target — that is expected, not",
+        "an error.",
+        "",
+        "Proposed links:",
+        items,
+    ];
+    if (input.plan && input.plan.trim().length > 0) {
+        lines.push("", "Test plan:", "", input.plan.trim());
+    }
+    if (input.steps && input.steps.length > 0) {
+        lines.push("", "Steps exercised:");
+        input.steps.forEach((s, i) => lines.push(`${i + 1}. ${s}`));
+    }
+    const trace = input.links.find((l) => l.trace)?.trace;
+    if (trace) {
+        lines.push("", `Replay the trace locally: \`npx playwright show-trace ${trace}\``);
+    }
+    lines.push("", "This is a proposal for human review (ADR-065). Proofkeeper produces and runs", "the evidence; a reviewer accepts the link. Merge only after confirming the", "referenced test and trace.");
+    return lines.join("\n");
+}
+/** Build a write-back proposal (does not touch any repo). */
+export function buildProposal(input) {
+    const baseBranch = input.baseBranch ?? DEFAULT_BASE_BRANCH;
+    const branchPrefix = input.branchPrefix ?? DEFAULT_BRANCH_PREFIX;
+    const updatedContent = mergeVerifiedBy(input.originalContent, input.links);
+    return {
+        capabilityId: input.capabilityId,
+        targetPath: input.targetPath,
+        baseBranch,
+        headBranch: `${branchPrefix}/${slug(input.capabilityId)}`,
+        title: `docs(verify): record Verified By for ${input.capabilityId}`,
+        body: proposalBody(input),
+        originalContent: input.originalContent,
+        updatedContent,
+        links: input.links,
+        changed: updatedContent !== input.originalContent,
+    };
+}
+/**
+ * Derive verification links from a compiled test and its run results: the
+ * committed spec (the corpus verifier) plus the first replayable trace produced
+ * for it (surfaced in the PR).
+ */
+export function linksFromResults(candidate, results) {
+    const trace = results.find((r) => r.testId === candidate.id && r.tracePath)?.tracePath;
+    const link = { test: candidate.specPath };
+    if (trace)
+        link.trace = trace;
+    return [link];
+}
+//# sourceMappingURL=proposal.js.map

package/dist/writeback/proposal.js.map

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