@akagilnc/pi-workflow-roles 0.1.3565 → 0.1.3621

package/dist/diarist-mechanical.js

@@ -0,0 +1,411 @@
+/**
+ * 起居郎 mechanical safeguard band — ADR 0075 / #582.
+ * Deterministic: source enum helpers, candidate anchors, dedup, notification
+ * filter, and verbatim quote reverse-verify. Never a production relevance gate.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { pathContainedIn, physicallyContainedIn, } from "./activation-ledger-topology.js";
+export const DEFAULT_QUOTE_MIN = 6;
+export class DiaristSourceReadError extends Error {
+    code = "diarist-source-read";
+    reason;
+    sourcePath;
+    constructor(reason, sourcePath, message, options) {
+        super(message, options);
+        this.name = "DiaristSourceReadError";
+        this.reason = reason;
+        this.sourcePath = sourcePath;
+    }
+}
+/**
+ * Extract 「」 quotes from ticket face text for mechanical anchors.
+ * Only quotes meeting min length are kept.
+ */
+export function extractCornerQuotes(text, minLength = DEFAULT_QUOTE_MIN) {
+    const out = [];
+    const re = /「([^」]+)」/g;
+    let match;
+    while ((match = re.exec(text)) !== null) {
+        const q = match[1].trim();
+        if (q.length >= minLength)
+            out.push(q);
+    }
+    return out;
+}
+/** Build the mechanical anchor set from ticket number + face body. */
+export function buildDiaristAnchors(input) {
+    const fromBody = input.ticketBody === undefined ? [] : extractCornerQuotes(input.ticketBody);
+    const quotes = [...fromBody, ...(input.extraQuotes ?? [])];
+    const seen = new Set();
+    const uniqueQuotes = [];
+    for (const q of quotes) {
+        if (seen.has(q))
+            continue;
+        seen.add(q);
+        uniqueQuotes.push(q);
+    }
+    return {
+        ticketNumber: input.ticketNumber,
+        quotes: uniqueQuotes,
+    };
+}
+/** Drop notification/system noise blocks (typed flags only — no prose match). */
+export function filterNotifications(blocks) {
+    return blocks.filter((b) => !b.isNotification);
+}
+function blockKey(block) {
+    const r = block.sourceRef;
+    return [
+        block.sourceKind,
+        r.sessionFile ?? "",
+        r.entryId === undefined ? "" : String(r.entryId),
+        r.path ?? "",
+        r.url ?? "",
+        createHash("sha256").update(block.transcript, "utf8").digest("hex").slice(0, 16),
+    ].join("|");
+}
+/** Dedup by source pointer + transcript digest (compression replay ×N). */
+export function dedupeSourceBlocks(blocks) {
+    const seen = new Set();
+    const out = [];
+    for (const block of blocks) {
+        const key = blockKey(block);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(block);
+    }
+    return out;
+}
+export function verifyQuotesVerbatim(sourceText, quotes) {
+    const failed = [];
+    for (const q of quotes) {
+        if (q.length === 0)
+            continue;
+        if (!sourceText.includes(q))
+            failed.push(q);
+    }
+    if (failed.length === 0)
+        return { ok: true };
+    return { ok: false, failedQuotes: failed };
+}
+/**
+ * Mechanical safeguard only — never a relevance gate (ADR 0075 / 锚定宪法).
+ * filter notifications (typed) → dedupe. Semantic selection is LLM-only.
+ */
+export function mechanicalSafeguardPipeline(blocks) {
+    return dedupeSourceBlocks(filterNotifications(blocks));
+}
+/** Claude Code project-dir encoding: abs path with / → -. */
+export function encodeClaudeProjectDir(cwd) {
+    const abs = cwd.startsWith("/") ? cwd : `/${cwd}`;
+    return abs.replace(/\//g, "-");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function messageText(message) {
+    if (typeof message === "string")
+        return message;
+    if (!isRecord(message))
+        return "";
+    const content = message.content;
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    const parts = [];
+    for (const part of content) {
+        if (typeof part === "string") {
+            parts.push(part);
+            continue;
+        }
+        if (!isRecord(part))
+            continue;
+        if (typeof part.text === "string")
+            parts.push(part.text);
+        else if (typeof part.content === "string")
+            parts.push(part.content);
+    }
+    return parts.join("\n");
+}
+function isNotificationRow(type, text) {
+    if (type === "queue-operation" || type === "system" || type === "progress") {
+        return true;
+    }
+    if (type === "user") {
+        // Local command / meta noise common in cc transcripts.
+        if (text.startsWith("<command-name>") || text.startsWith("<local-command-")) {
+            return true;
+        }
+        if (text.startsWith("<command-message>") || text.startsWith("<command-args>")) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Enumerate cc session user/assistant turns and human queued-command attachments under Claude projects roots.
+ * cc-sessions-first source family (ADR 0075).
+ * Directory/file/non-empty JSONL line failures throw DiaristSourceReadError
+ * (失败诚实：不得把未读懂洗成没有来源块).
+ */
+export function readCcSessionBlocks(options) {
+    const root = options.projectsRoot ?? join(homedir(), ".claude", "projects");
+    if (!existsSync(root))
+        return [];
+    const blocks = [];
+    const dirs = new Set();
+    for (const cwd of options.cwds) {
+        dirs.add(join(root, encodeClaudeProjectDir(cwd)));
+    }
+    // Also accept already-encoded folder names passed as cwd (test convenience).
+    for (const cwd of options.cwds) {
+        if (cwd.includes("projects"))
+            continue;
+        const direct = join(root, cwd);
+        if (existsSync(direct))
+            dirs.add(direct);
+    }
+    for (const dir of dirs) {
+        if (!existsSync(dir))
+            continue;
+        let dirStat;
+        try {
+            dirStat = statSync(dir);
+        }
+        catch (error) {
+            throw new DiaristSourceReadError("readdir-failed", dir, `diarist cc session dir unstatable (${dir})`, { cause: error });
+        }
+        if (!dirStat.isDirectory())
+            continue;
+        let files;
+        try {
+            files = readdirSync(dir).filter((name) => name.endsWith(".jsonl"));
+        }
+        catch (error) {
+            throw new DiaristSourceReadError("readdir-failed", dir, `diarist cc session dir unreadable (${dir})`, { cause: error });
+        }
+        for (const name of files) {
+            const sessionFile = join(dir, name);
+            let text;
+            try {
+                text = readFileSync(sessionFile, "utf8");
+            }
+            catch (error) {
+                throw new DiaristSourceReadError("file-unreadable", sessionFile, `diarist cc session file unreadable (${sessionFile})`, { cause: error });
+            }
+            const lines = text.split("\n");
+            for (let lineNo = 0; lineNo < lines.length; lineNo += 1) {
+                const line = lines[lineNo];
+                if (!line.trim())
+                    continue;
+                let parsed;
+                try {
+                    parsed = JSON.parse(line);
+                }
+                catch (error) {
+                    throw new DiaristSourceReadError("jsonl-line-unparseable", sessionFile, `diarist cc session JSONL line ${lineNo + 1} unparseable (${sessionFile})`, { cause: error });
+                }
+                // Unknown row shape (not user/assistant or a human queued-command attachment) is ignored — not a read failure.
+                if (!isRecord(parsed))
+                    continue;
+                const type = typeof parsed.type === "string" ? parsed.type : "";
+                const queuedCommand = type === "attachment" &&
+                    isRecord(parsed.attachment) &&
+                    parsed.attachment.type === "queued_command" &&
+                    isRecord(parsed.attachment.origin) &&
+                    parsed.attachment.origin.kind === "human" &&
+                    typeof parsed.attachment.prompt === "string"
+                    ? parsed.attachment.prompt
+                    : undefined;
+                if (type !== "user" && type !== "assistant" && queuedCommand === undefined) {
+                    continue;
+                }
+                const transcript = queuedCommand ?? messageText(parsed.message ?? parsed);
+                if (transcript.trim() === "")
+                    continue;
+                const entryId = typeof parsed.uuid === "string"
+                    ? parsed.uuid
+                    : typeof parsed.id === "string"
+                        ? parsed.id
+                        : `${basename(sessionFile)}:${lineNo + 1}`;
+                const timestamp = typeof parsed.timestamp === "string"
+                    ? parsed.timestamp
+                    : new Date(0).toISOString();
+                const notification = isNotificationRow(type, transcript);
+                blocks.push({
+                    sourceKind: "cc-session",
+                    sourceRef: { sessionFile, entryId },
+                    transcript,
+                    timestamp,
+                    isUserTurn: type === "user" || queuedCommand !== undefined,
+                    isNotification: notification,
+                });
+            }
+        }
+    }
+    return blocks;
+}
+/**
+ * Issue body + comments + 「」 decree spans as typed source blocks.
+ * Each block keeps its own sourceRef (url / comment id) — never merge attachments here.
+ */
+export function readIssueFaceBlocks(input) {
+    const fallbackTs = input.timestamp ?? new Date(0).toISOString();
+    const blocks = [];
+    const body = input.face.body;
+    if (body.trim() !== "") {
+        blocks.push({
+            sourceKind: "issue-body-comment",
+            sourceRef: { url: input.face.bodyUrl, entryId: "body" },
+            transcript: body,
+            timestamp: fallbackTs,
+            isUserTurn: true,
+            isNotification: false,
+        });
+        const quotes = extractCornerQuotes(body);
+        for (let i = 0; i < quotes.length; i += 1) {
+            const q = quotes[i];
+            blocks.push({
+                sourceKind: "ticket-decree-block",
+                sourceRef: { url: input.face.bodyUrl, entryId: `decree-${i + 1}` },
+                transcript: q,
+                timestamp: fallbackTs,
+                isUserTurn: true,
+                isNotification: false,
+            });
+        }
+    }
+    for (const comment of input.face.comments) {
+        if (comment.body.trim() === "")
+            continue;
+        blocks.push({
+            sourceKind: "issue-body-comment",
+            sourceRef: {
+                url: comment.htmlUrl,
+                entryId: comment.id,
+            },
+            transcript: comment.body,
+            timestamp: comment.createdAt || fallbackTs,
+            isUserTurn: true,
+            isNotification: false,
+        });
+    }
+    return blocks;
+}
+/** Relative root every ADR decision-key read must stay under (ADR 0038). */
+export const DIARIST_ADR_ROOT_REL = "docs/adr";
+/**
+ * Read applicable ADR files as decision-key source blocks.
+ * Real IO seam owns lexical + physical containment under cwd/docs/adr (ADR 0038).
+ * Missing / unreadable / escape → typed DiaristSourceReadError (失败诚实).
+ */
+export function readAdrDecisionKeyBlocks(input) {
+    const timestamp = input.timestamp ?? new Date(0).toISOString();
+    const blocks = [];
+    const cwdAbs = resolve(input.cwd);
+    const adrRootAbs = resolve(cwdAbs, DIARIST_ADR_ROOT_REL);
+    let adrRootReal;
+    try {
+        // Prefer the real ADR root when it exists; otherwise fall back to cwd real
+        // so physical checks still have a stable anchor before the first ADR file.
+        adrRootReal = existsSync(adrRootAbs)
+            ? realpathSync(adrRootAbs)
+            : resolve(realpathSync(cwdAbs), DIARIST_ADR_ROOT_REL);
+    }
+    catch (error) {
+        throw new DiaristSourceReadError("adr-unreadable", cwdAbs, `diarist ADR root is not resolvable (${adrRootAbs})`, { cause: error });
+    }
+    for (const rel of input.adrPaths) {
+        const segments = rel.split(/[/\\]/);
+        // Claimed path must sit under docs/adr/ with no traversal segments.
+        if (segments[0] !== "docs" ||
+            segments[1] !== "adr" ||
+            segments.length < 3 ||
+            segments.some((part) => part === "" || part === "." || part === "..")) {
+            throw new DiaristSourceReadError("adr-escape", resolve(cwdAbs, rel), `diarist referenced ADR escapes docs/adr (${rel})`);
+        }
+        const abs = resolve(cwdAbs, rel);
+        // Lexical containment under docs/adr before any read (ADR 0038).
+        if (abs !== adrRootAbs && !pathContainedIn(adrRootAbs, abs)) {
+            throw new DiaristSourceReadError("adr-escape", abs, `diarist referenced ADR escapes docs/adr (${rel})`);
+        }
+        if (!existsSync(abs)) {
+            throw new DiaristSourceReadError("adr-missing", abs, `diarist referenced ADR missing (${rel})`);
+        }
+        let realAbs;
+        try {
+            realAbs = realpathSync(abs);
+        }
+        catch (error) {
+            throw new DiaristSourceReadError("adr-unreadable", abs, `diarist ADR path is not resolvable (${abs})`, { cause: error });
+        }
+        if (realAbs !== adrRootReal && !physicallyContainedIn(adrRootReal, realAbs)) {
+            throw new DiaristSourceReadError("adr-escape", abs, `diarist referenced ADR escapes docs/adr physically (${rel})`);
+        }
+        let text;
+        try {
+            text = readFileSync(realAbs, "utf8");
+        }
+        catch (error) {
+            throw new DiaristSourceReadError("adr-unreadable", realAbs, `diarist ADR file unreadable (${realAbs})`, { cause: error });
+        }
+        if (text.trim() === "")
+            continue;
+        blocks.push({
+            sourceKind: "adr-decision-key",
+            sourceRef: { path: rel },
+            transcript: text,
+            timestamp,
+            isUserTurn: true,
+            isNotification: false,
+        });
+    }
+    return blocks;
+}
+/**
+ * Build an llm-semantic entry after reverse-verify succeeds.
+ * `quotes` are the LLM-claimed quotes that must be verbatim in transcript.
+ * basis.anchors record ticket # + mechanical/claimed quotes for audit only.
+ * Failure returns failedQuotes only — caller records a single diagnostic (not a
+ * disguised diary entry / dead basis.method).
+ */
+export function blockToLlmEntry(block, input) {
+    const verify = verifyQuotesVerbatim(block.transcript, input.quotes);
+    if (!verify.ok) {
+        return {
+            ok: false,
+            failedQuotes: verify.failedQuotes,
+            cause: `verbatim verify failed: ${verify.failedQuotes.join(" | ")}`,
+        };
+    }
+    // Ticket + mechanical face quotes + claimed quotes — reference/反验 only.
+    const anchorNotes = [`#${input.anchors.ticketNumber}`];
+    const seen = new Set(anchorNotes);
+    for (const q of [...input.anchors.quotes, ...input.quotes]) {
+        if (seen.has(q))
+            continue;
+        seen.add(q);
+        anchorNotes.push(q);
+        if (anchorNotes.length >= 12)
+            break;
+    }
+    return {
+        ok: true,
+        entry: {
+            basis: {
+                method: "llm-semantic",
+                anchors: anchorNotes,
+                ...(input.note === undefined ? {} : { note: input.note }),
+            },
+            sourceKind: block.sourceKind,
+            sourceRef: block.sourceRef,
+            transcript: block.transcript,
+            timestamp: block.timestamp,
+        },
+    };
+}

package/dist/diarist-ticket-resolution.js

@@ -0,0 +1,177 @@
+/**
+ * 起居郎 pre-court ticket resolution (#582 / diarist-resolves-ticket-llm-layer).
+ * Unbound countersign: LLM typed assertion over accepted instruction, then two
+ * mechanical checks on N (complete decimal number in instruction; live GitHub issue).
+ * Verification failure is controlled failure — never washed to true-unbound.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createGhApiRunner, projectGhIssueBody, } from "./collector-github.js";
+import { ENGINE_DETOUR_STAGED_PROMPT_TOKEN, runEngineDetourOnce, } from "./engine-detour.js";
+export const DIARIST_RESOLVE_TICKET_METHOD_RELATIVE = "resources/diarist-resolve-ticket.md";
+export class DiaristTicketResolutionError extends Error {
+    code = "diarist-ticket-resolution";
+    reason;
+    constructor(reason, message, options) {
+        super(message, options);
+        this.name = "DiaristTicketResolutionError";
+        this.reason = reason;
+    }
+}
+export function resolveDiaristResolveTicketMethodPath(packageRoot = fileURLToPath(new URL("..", import.meta.url))) {
+    return join(packageRoot, DIARIST_RESOLVE_TICKET_METHOD_RELATIVE);
+}
+/**
+ * Decision-key exact identity: complete decimal number N appears in instruction.
+ * A longer number's digit substring (e.g. 82 inside #582) is not N.
+ */
+export function instructionContainsTicketNumber(instruction, ticketNumber) {
+    if (!Number.isSafeInteger(ticketNumber) || ticketNumber < 1)
+        return false;
+    // Complete number token: not preceded or followed by another digit.
+    return new RegExp(`(?<!\\d)${String(ticketNumber)}(?!\\d)`).test(instruction);
+}
+/** Sole stdout shapes: {assertion:"ticket",ticketNumber:N} | {assertion:"true-unbound"}. */
+export function parseDiaristTicketResolverStdout(stdout) {
+    const trimmed = stdout.trim();
+    if (trimmed.length === 0) {
+        throw new DiaristTicketResolutionError("empty-stdout", "diarist ticket resolver stdout is empty");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch (error) {
+        throw new DiaristTicketResolutionError("unparseable-json", "diarist ticket resolver stdout is not JSON", { cause: error });
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new DiaristTicketResolutionError("not-object", "diarist ticket resolver stdout must be one JSON object");
+    }
+    const record = parsed;
+    if (!Object.prototype.hasOwnProperty.call(record, "assertion")) {
+        throw new DiaristTicketResolutionError("assertion-missing", "diarist ticket resolver stdout missing assertion");
+    }
+    if (record.assertion === "true-unbound")
+        return { kind: "true-unbound" };
+    const n = record.ticketNumber;
+    if (record.assertion === "ticket" &&
+        typeof n === "number" &&
+        Number.isSafeInteger(n) &&
+        n >= 1) {
+        return { kind: "ticket", ticketNumber: n };
+    }
+    throw new DiaristTicketResolutionError("assertion-uninterpretable", "diarist ticket resolver assertion is not ticket|true-unbound with safe ticketNumber");
+}
+const HERMES_RESOLVER_TOOLSET = "context_engine";
+/** Hermes resolver: method bytes + instruction only; empty toolset; staged prompt. */
+export function createHermesDiaristTicketResolver(options = {}) {
+    const methodPath = resolveDiaristResolveTicketMethodPath(options.packageRoot);
+    if (!existsSync(methodPath)) {
+        throw new Error(`diarist resolve-ticket method material missing (${methodPath})`);
+    }
+    const method = readFileSync(methodPath, "utf8");
+    if (method.trim().length === 0) {
+        throw new Error(`diarist resolve-ticket method material is empty (${methodPath})`);
+    }
+    const executable = options.executable ?? "hermes";
+    return async (input) => {
+        const argv = [
+            executable,
+            "chat",
+            "--query-file",
+            ENGINE_DETOUR_STAGED_PROMPT_TOKEN,
+            "-Q",
+            "--no-restore-cwd",
+            "--ignore-rules",
+            "-t",
+            HERMES_RESOLVER_TOOLSET,
+        ];
+        let result;
+        try {
+            result = await runEngineDetourOnce({
+                argv,
+                stagedPrompt: JSON.stringify({ method, instruction: input.instruction }),
+                cwd: options.cwd ?? process.cwd(),
+                ...(options.env === undefined ? {} : { env: options.env }),
+                ...(input.signal === undefined ? {} : { signal: input.signal }),
+            });
+        }
+        catch (error) {
+            throw new DiaristTicketResolutionError("engine-failed", "diarist ticket resolver engine failed to launch", { cause: error });
+        }
+        if (result.code !== 0) {
+            throw new DiaristTicketResolutionError("engine-failed", `diarist ticket resolver engine exited ${result.code}: ${result.stderr.slice(0, 500)}`);
+        }
+        return parseDiaristTicketResolverStdout(result.stdout);
+    };
+}
+/** Live ticket check over shared gh issue-body projection. */
+export function createGhTicketExistenceChecker(options) {
+    const runner = options?.runner ?? createGhApiRunner();
+    return async (input) => {
+        const projected = await projectGhIssueBody(runner, {
+            owner: input.owner,
+            repo: input.repo,
+            ticketNumber: input.ticketNumber,
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+        });
+        if (projected.status === "available")
+            return true;
+        if (projected.status === "unavailable"
+            && projected.reason === "http-non-2xx"
+            && projected.httpStatus === 404) {
+            return false;
+        }
+        if (projected.status === "unavailable" && projected.reason === "pull-request") {
+            throw new DiaristTicketResolutionError("ticket-is-pull-request", `ticket #${input.ticketNumber} resolves to a pull request, not an issue`, { cause: projected });
+        }
+        if (projected.status === "unavailable") {
+            throw new DiaristTicketResolutionError("ticket-unavailable", `ticket verification unavailable for ${input.owner}/${input.repo}#${input.ticketNumber}`, { cause: projected });
+        }
+        throw new DiaristTicketResolutionError("ticket-invalid", `ticket verification returned an invalid issue payload for ${input.owner}/${input.repo}#${input.ticketNumber}`, { cause: projected });
+    };
+}
+/** Mechanical verify after LLM assertion. true-unbound passes; ticket needs both checks. */
+export async function verifyDiaristTicketAssertion(input) {
+    if (input.assertion.kind === "true-unbound")
+        return input.assertion;
+    const n = input.assertion.ticketNumber;
+    if (!instructionContainsTicketNumber(input.instruction, n)) {
+        throw new DiaristTicketResolutionError("number-not-in-instruction", `diarist ticket assertion #${n} complete decimal number does not appear in accepted instruction`);
+    }
+    if (input.origin === undefined) {
+        throw new DiaristTicketResolutionError("origin-unresolved", `diarist ticket assertion #${n} requires a resolvable github.com origin remote`);
+    }
+    let exists;
+    try {
+        exists = await input.checkExistence({
+            owner: input.origin.owner,
+            repo: input.origin.repo,
+            ticketNumber: n,
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+        });
+    }
+    catch (error) {
+        if (error instanceof DiaristTicketResolutionError)
+            throw error;
+        throw new DiaristTicketResolutionError("ticket-unavailable", `diarist ticket assertion #${n} live verification failed`, { cause: error });
+    }
+    if (!exists) {
+        throw new DiaristTicketResolutionError("ticket-missing", `diarist ticket assertion #${n} does not exist as a live issue on ${input.origin.owner}/${input.origin.repo}`);
+    }
+    return input.assertion;
+}
+export async function resolveDiaristTicketFromInstruction(input) {
+    const assertion = await input.resolver({
+        instruction: input.instruction,
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+    });
+    return verifyDiaristTicketAssertion({
+        assertion,
+        instruction: input.instruction,
+        origin: input.origin,
+        checkExistence: input.checkExistence,
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+    });
+}