@pugi/cli 0.1.0-beta.98 → 1.0.0-alpha.1

package/dist/core/consensus/rubric.js

@@ -1,233 +0,0 @@
-/**
- * Consensus rubric — `pugi review --consensus` .
- *
- * Three independent reviewers (Codex / Claude / DeepSeek) produce findings
- * tagged `[P0]` / `[P1]` / `[P2]` / `[P3]`. The rubric translates the per-
- * reviewer severity vector into one of `PASS` / `WARN` / `BLOCK`.
- *
- * Rubric (verbatim from /triple-review skill + admin-api OES MCP triple_review):
- *
- *  any reviewer reports [P0]             -> BLOCK
- *  two or more reviewers report [P1]     -> BLOCK  (consensus)
- *  exactly one reviewer reports [P1]     -> WARN   (asymmetric)
- *  no reviewer reports [P0] or [P1]      -> PASS   (P2/P3 only)
- *  every reviewer errored                -> BLOCK  (no signal)
- *
- * The rubric never reads model text beyond the severity markers; the
- * reviewer-side narrative is shown to the operator unchanged. Keeping the
- * verdict deterministic + LLM-free is the entire point of the gate (CEO
- * directive): a model that disagrees with the rubric can be
- * audited, a model that produces the verdict cannot.
- */
-/**
- * Regex matches the `[P0]` / `[P1]` / `[P2]` / `[P3]` token at the start
- * of a line OR inline. Accepts surrounding whitespace and lowercase form.
- * The line-anchored `m` flag scans every line; `g` allows `matchAll`.
- *
- * The capture group on the digit lets `parseFindings` reconstruct the
- * severity without a second regex. Square brackets are escaped because
- * the JS regex engine treats `[` as a character class otherwise.
- */
-const SEVERITY_TOKEN = /\[\s*[Pp]([0-3])\s*\]/g;
-/**
- * Parse a raw reviewer text blob into structured findings.
- *
- * Heuristics (intentionally permissive — different models format very
- * differently and a strict parser would drop signal):
- *
- *  1. Split the text on `[Px]` tokens, preserving the marker.
- *  2. Each marker starts a new finding. The summary is the rest of the
- *     same line (and the next line if the first is `:` or empty after
- *     stripping whitespace).
- *  3. Empty / whitespace-only summaries are dropped — a bare `[P1]`
- *     with no context cannot be acted on, and treating it as a finding
- *     would falsely trigger consensus.
- */
-export function parseFindings(raw) {
-    if (typeof raw !== 'string' || raw.length === 0)
-        return [];
-    const findings = [];
-    // Track marker positions so we can slice the summary up to the next
-    // marker without quadratic re-scans.
-    const markers = [];
-    // Reset lastIndex defensively — `matchAll` allocates its own iterator,
-    // but belt-and-braces against a future caller passing a stateful regex.
-    SEVERITY_TOKEN.lastIndex = 0;
-    for (const match of raw.matchAll(SEVERITY_TOKEN)) {
-        const digit = match[1] ?? '';
-        const severity = `P${digit}`;
-        markers.push({ severity, index: match.index ?? 0, matchLength: match[0].length });
-    }
-    for (let i = 0; i < markers.length; i += 1) {
-        const marker = markers[i];
-        const start = marker.index + marker.matchLength;
-        const end = i + 1 < markers.length ? markers[i + 1].index : raw.length;
-        const slice = raw.slice(start, end);
-        const summary = extractSummary(slice);
-        if (summary.length === 0)
-            continue;
-        findings.push({ severity: marker.severity, summary });
-    }
-    return findings;
-}
-/**
- * Extract a single-line summary from the text following a severity
- * marker. Trims leading colon / dash / whitespace; truncates at the
- * first newline so multi-paragraph findings render as one line in the
- * REPL transcript (the full reviewer text stays available in `rawContent`).
- */
-function extractSummary(slice) {
-    let cursor = 0;
-    while (cursor < slice.length && /[\s:\-—–]/.test(slice[cursor]))
-        cursor += 1;
-    const tail = slice.slice(cursor);
-    const newlineIdx = tail.search(/\r?\n/);
-    const oneLine = newlineIdx === -1 ? tail : tail.slice(0, newlineIdx);
-    return oneLine.trim();
-}
-/**
- * Compute the highest BLOCKING severity from a finding list. Returns
- * `null` when the reviewer is clean for gating purposes, i.e. either:
- *  - no findings at all, OR
- *  - only P2 / P3 findings (informational, non-blocking by rubric).
- *
- * `null` is the right contract for downstream tooling that gates on
- * "did this reviewer flag anything that should block ship?" - the
- * rubric in `aggregate` already treats P2/P3 as non-blocking, so an
- * external `topSeverity === null` check matches the gate's semantics
- * exactly without re-parsing the finding list.
- *
- * Per-finding severity is still preserved in `findings[].severity`
- * for callers that want to surface P2/P3 counts in their UX.
- *
- * Returns the priority floor for blocking findings only: P0 > P1.
- */
-export function topSeverityOf(findings) {
-    let best = null;
-    for (const finding of findings) {
-        if (finding.severity === 'P0')
-            return 'P0';
-        if (finding.severity === 'P1')
-            best = 'P1';
-        // P2 / P3 are non-blocking by rubric -> they do NOT contribute to
-        // topSeverity. They remain visible via `findings[].severity` for
-        // operators who want to see the full breakdown.
-    }
-    return best;
-}
-/**
- * Convenience: parse a raw reviewer text blob into a `ReviewerVerdict`.
- * `errored` defaults to false; callers that detected a transport-level
- * failure should set it true and pass an empty raw string.
- */
-export function reviewerVerdictFromRaw(reviewer, raw, errored = false) {
-    if (errored) {
-        return { reviewer, topSeverity: null, findings: [], errored: true };
-    }
-    const findings = parseFindings(raw);
-    return {
-        reviewer,
-        topSeverity: topSeverityOf(findings),
-        findings,
-        errored: false,
-    };
-}
-/**
- * Apply the rubric to 1..N reviewer verdicts. The shape is N-aware so the
- * same function handles the dev `/triple-review` 3-reviewer case AND a
- * customer running with 2 reviewers (e.g. a tier that does not yet include
- * DeepSeek).
- */
-export function aggregate(verdicts) {
-    const totalReviewers = verdicts.length;
-    const erroredReviewers = verdicts.filter((v) => v.errored).length;
-    // Zero reviewers = zero signal. Falling through to the no-P0/no-P1
-    // branch would emit a false PASS — exactly the regression flagged by
-    // Codex during PR review. Treat empty input as BLOCK so the gate
-    // fails closed when the backend returns no events at all (5xx that
-    // somehow drained the SSE, server-side bug, dispatcher misconfig).
-    if (totalReviewers === 0) {
-        return {
-            verdict: 'BLOCK',
-            p0Count: 0,
-            p1Count: 0,
-            p1Reviewers: 0,
-            reasoning: 'No reviewer signal: backend returned 0 events. Fail-closed BLOCK.',
-        };
-    }
-    if (totalReviewers > 0 && erroredReviewers === totalReviewers) {
-        return {
-            verdict: 'BLOCK',
-            p0Count: 0,
-            p1Count: 0,
-            p1Reviewers: 0,
-            reasoning: 'Every reviewer errored: no signal. Treating as BLOCK until at least one reviewer returns.',
-        };
-    }
-    let p0Count = 0;
-    let p1Count = 0;
-    let p1Reviewers = 0;
-    for (const verdict of verdicts) {
-        if (verdict.errored)
-            continue;
-        const p0 = verdict.findings.filter((f) => f.severity === 'P0').length;
-        const p1 = verdict.findings.filter((f) => f.severity === 'P1').length;
-        p0Count += p0;
-        p1Count += p1;
-        if (p1 > 0)
-            p1Reviewers += 1;
-    }
-    if (p0Count > 0) {
-        return {
-            verdict: 'BLOCK',
-            p0Count,
-            p1Count,
-            p1Reviewers,
-            reasoning: `${p0Count}x P0 finding${p0Count === 1 ? '' : 's'}: BLOCK (any P0 fails the gate).`,
-        };
-    }
-    if (p1Reviewers >= 2) {
-        return {
-            verdict: 'BLOCK',
-            p0Count,
-            p1Count,
-            p1Reviewers,
-            reasoning: `${p1Reviewers} reviewers each reported P1: consensus = likely real bug, BLOCK.`,
-        };
-    }
-    if (p1Reviewers === 1) {
-        return {
-            verdict: 'WARN',
-            p0Count,
-            p1Count,
-            p1Reviewers,
-            reasoning: 'One reviewer reported P1: asymmetric signal, examine the disagreement before merging.',
-        };
-    }
-    return {
-        verdict: 'PASS',
-        p0Count,
-        p1Count,
-        p1Reviewers,
-        reasoning: 'No P0 or P1 findings: PASS. P2/P3 findings are non-blocking.',
-    };
-}
-/**
- * Map a rubric verdict to the conventional exit code Pugi CLI uses for
- * gates (spec ):
- *
- *  PASS -> 0
- *  WARN -> 1
- *  BLOCK -> 2
- *
- * The non-zero codes are distinct so a shell script can branch on the
- * exact outcome without re-parsing stdout.
- */
-export function exitCodeFor(verdict) {
-    if (verdict === 'PASS')
-        return 0;
-    if (verdict === 'WARN')
-        return 1;
-    return 2;
-}
-//# sourceMappingURL=rubric.js.map

package/dist/core/context/builder.js

@@ -1,114 +0,0 @@
-/**
- * Context builder — separates static and dynamic blocks so the model's
- * prompt cache stays warm across turns.
- *
- * Per `docs/research/pugi-cli-corpus/patterns/context-compaction.md` §6,
- * static and dynamic context live in different sections:
- *
- *  STATIC                       DYNAMIC
- *  - system instructions        - transcript turns (recent)
- *  - tool schemas (sorted)      - session memory ref
- *  - safety rules               - open task graph snapshot
- *  - PUGI.md + AGENTS.md
- *
- * Static blocks hash deterministically; identical session starts emit
- * identical static prefixes, hitting the model provider's prompt cache.
- * Dynamic blocks rebuild every turn — compaction touches dynamic only.
- *
- * This module is pure: no fs, no network. Markdown loading happens in
- * `markdown-loader.ts` and is passed in. Hash inputs are sorted to keep
- * the static hash stable under map-iteration-order changes.
- */
-import { createHash } from 'node:crypto';
-/**
- * Build a `BuiltContext` from input. Pure function: same input always
- * produces byte-identical static blocks (and therefore byte-identical
- * static hashes). Dynamic blocks are returned as-is in transcript order;
- * compaction reshuffles dynamic only.
- *
- * Marked async to match the codebase convention even though the body is
- * fully sync. Callers chain `await buildContext(...)` so a future move
- * to async markdown reloading or RAG injection does not break callers.
- */
-export async function buildContext(input) {
-    const blocks = [];
-    // 1. Tools first — alphabetically sorted by name, per pattern card §6.
-    const sortedTools = [...input.tools].sort((a, b) => a.name.localeCompare(b.name));
-    const toolBundle = sortedTools.map((t) => `${t.name}:${t.schema}`).join('\n');
-    blocks.push({
-        kind: 'tool_schema',
-        name: 'tools',
-        content: toolBundle,
-        bytes: Buffer.byteLength(toolBundle, 'utf8'),
-    });
-    // 2. Instructions — single deterministic block.
-    const instructionsContent = normalizeNewlines(input.instructions);
-    blocks.push({
-        kind: 'instructions',
-        name: 'instructions',
-        content: instructionsContent,
-        bytes: Buffer.byteLength(instructionsContent, 'utf8'),
-    });
-    // 3. Safety rules — optional, hashed into the instructions block via
-    //   concatenation when present so consumers can read both as one.
-    if (input.safetyRules) {
-        const safety = normalizeNewlines(input.safetyRules);
-        blocks.push({
-            kind: 'safety_rules',
-            name: 'safety',
-            content: safety,
-            bytes: Buffer.byteLength(safety, 'utf8'),
-        });
-    }
-    // 4. PUGI.md / AGENTS.md — loaded markdown in workspace-root order.
-    for (const md of input.markdown) {
-        blocks.push({
-            kind: md.source === 'PUGI.md' ? 'pugi_md' : 'agents_md',
-            name: md.source,
-            content: md.content,
-            bytes: Buffer.byteLength(md.content, 'utf8'),
-        });
-    }
-    const staticBytes = blocks.reduce((sum, b) => sum + b.bytes, 0);
-    const instructionsBlock = blocks.find((b) => b.kind === 'instructions');
-    const toolBlock = blocks.find((b) => b.kind === 'tool_schema');
-    const mdBlocks = blocks.filter((b) => b.kind === 'pugi_md' || b.kind === 'agents_md');
-    const instructionsHash = sha256(instructionsBlock?.content ?? '');
-    const toolSchemaHash = sha256(toolBundle);
-    const pugiMdHash = mdBlocks.length > 0 ? sha256(mdBlocks.map((b) => b.content).join('\n---\n')) : undefined;
-    const dynamicBytes = input.transcript.reduce((sum, t) => sum + Buffer.byteLength(t.content, 'utf8'), 0) +
-        (input.sessionMemory?.bytes ?? 0) +
-        estimateTaskGraphBytes(input.openTaskGraph);
-    const totalBytes = staticBytes + dynamicBytes;
-    return {
-        static: {
-            instructionsHash,
-            toolSchemaHash,
-            pugiMdHash,
-            blocks,
-            bytes: staticBytes,
-        },
-        dynamic: {
-            transcriptTurns: input.transcript,
-            sessionMemory: input.sessionMemory,
-            openTaskGraph: input.openTaskGraph,
-            bytes: dynamicBytes,
-        },
-        totalBytes,
-        estimatedTokens: Math.ceil(totalBytes / 4),
-    };
-}
-function sha256(input) {
-    return createHash('sha256').update(input, 'utf8').digest('hex');
-}
-function normalizeNewlines(input) {
-    // CRLF normalization plus trailing-newline strip so identical source
-    // emitted by different OS shells hashes identically.
-    return input.replace(/\r\n/g, '\n').replace(/\n+$/, '');
-}
-function estimateTaskGraphBytes(graph) {
-    if (!graph)
-        return 0;
-    return Buffer.byteLength(JSON.stringify(graph), 'utf8');
-}
-//# sourceMappingURL=builder.js.map

package/dist/core/context/compaction-events.js

@@ -1,99 +0,0 @@
-/**
- * Compaction event emitter — appends `compaction.*` events to the
- * session's events.jsonl using the shared AuditEvent discriminated union
- * in `@pugi/sdk/audit-trace.ts`.
- *
- * Until PR these events were written with the ad-hoc shape
- * `{ id, ts, sessionId, ... }` and the comment in this header claimed
- * "we keep `session.ts` untouched and write our events through a
- * dedicated helper that bypasses the AuditEvent schema". The downside,
- * caught by Claude review on PR, is that every consumer that
- * calls `auditEventSchema.parse(line)` (cabinet UI, replay tooling,
- * `core/index-store.ts`) would throw on every compaction event, and
- * `safeParse` consumers would silently drop them.
- *
- * Fix: extend the discriminated union with four compaction event
- * shapes and emit using the `timestamp` (full word) field name to
- * match every other event already in the schema. The events now
- * round-trip through `auditEventSchema.parse` without loss.
- *
- * Events emitted:
- *
- *  compaction.started           { sessionId, tier, trigger }
- *  compaction.completed         { sessionId, tier, bytesReclaimed,
- *                                  newContextSize, artifactsCreated }
- *  compaction.skipped           { sessionId, tier, reason }
- *  compaction.invariant_violated { sessionId, invariant, evidence,
- *                                  artifactRef? }
- *
- * All four are appended in mode 0o600 and respect the
- * `session.enabled` flag (no-op when `.pugi/` is absent).
- */
-import { appendFileSync } from 'node:fs';
-import { randomUUID } from 'node:crypto';
-export function emitCompactionStarted(session, tier, trigger) {
-    if (!session.enabled)
-        return;
-    appendCompactionEvent(session, {
-        type: 'compaction.started',
-        id: randomUUID(),
-        timestamp: nowIso(),
-        sessionId: session.id,
-        tier,
-        trigger,
-    });
-}
-export function emitCompactionCompleted(session, tier, bytesReclaimed, newContextSize, artifactsCreated) {
-    if (!session.enabled)
-        return;
-    appendCompactionEvent(session, {
-        type: 'compaction.completed',
-        id: randomUUID(),
-        timestamp: nowIso(),
-        sessionId: session.id,
-        tier,
-        bytesReclaimed,
-        newContextSize,
-        artifactsCreated: artifactsCreated.map((a) => ({
-            sha256: a.sha256,
-            size: a.size,
-            producedBy: a.producedBy,
-        })),
-    });
-}
-export function emitCompactionSkipped(session, tier, reason) {
-    if (!session.enabled)
-        return;
-    appendCompactionEvent(session, {
-        type: 'compaction.skipped',
-        id: randomUUID(),
-        timestamp: nowIso(),
-        sessionId: session.id,
-        tier,
-        reason,
-    });
-}
-export function emitCompactionInvariantViolated(session, violation) {
-    if (!session.enabled)
-        return;
-    const event = {
-        type: 'compaction.invariant_violated',
-        id: randomUUID(),
-        timestamp: nowIso(),
-        sessionId: session.id,
-        invariant: violation.invariant,
-        evidence: violation.evidence,
-        ...(violation.artifactRef !== undefined ? { artifactRef: violation.artifactRef } : {}),
-    };
-    appendCompactionEvent(session, event);
-}
-function appendCompactionEvent(session, event) {
-    appendFileSync(session.eventsPath, `${JSON.stringify(event)}\n`, {
-        encoding: 'utf8',
-        mode: 0o600,
-    });
-}
-function nowIso() {
-    return new Date().toISOString();
-}
-//# sourceMappingURL=compaction-events.js.map