@quickchatai/pi-quickreview 0.0.0-stage → 1.1.0

package/dist/src/round-stage-deadlines.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"round-stage-deadlines.d.ts","sourceRoot":"","sources":["../../src/round-stage-deadlines.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE;IACN,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACpC,EACD,SAAS,EAAE,OAAO,GACjB;IACD,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;CAC5B,CAOA"}

package/dist/src/round-stage-deadlines.js

@@ -0,0 +1,10 @@
+/** Start-derived round deadlines, shared by enforcement and status publication. */
+export function roundStageDeadlines(started, bounds, sweepOwed) {
+    const extra = sweepOwed ? (bounds.follow_up_sweep_extra_min ?? 0) : 0;
+    return {
+        first_pass_start: started + bounds.first_pass_max_min * 60_000,
+        passes_complete: started + (bounds.passes_max_min + extra) * 60_000,
+        running_hard_bound: started + (bounds.running_max_min + extra) * 60_000,
+    };
+}
+//# sourceMappingURL=round-stage-deadlines.js.map

package/dist/src/round-stage-deadlines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"round-stage-deadlines.js","sourceRoot":"","sources":["../../src/round-stage-deadlines.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,MAAM,UAAU,mBAAmB,CACjC,OAAe,EACf,MAKC,EACD,SAAkB;IAMlB,MAAM,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,yBAAyB,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACtE,OAAO;QACL,gBAAgB,EAAE,OAAO,GAAG,MAAM,CAAC,kBAAkB,GAAG,MAAM;QAC9D,eAAe,EAAE,OAAO,GAAG,CAAC,MAAM,CAAC,cAAc,GAAG,KAAK,CAAC,GAAG,MAAM;QACnE,kBAAkB,EAAE,OAAO,GAAG,CAAC,MAAM,CAAC,eAAe,GAAG,KAAK,CAAC,GAAG,MAAM;KACxE,CAAC;AACJ,CAAC"}

package/dist/src/session-command.d.ts

@@ -0,0 +1,19 @@
+/** Stable receipt carried in the Pi user message for one durable command.
+ * It binds the database id to the immutable payload hash, so restart recovery
+ * can reconcile SQLite ownership against session JSONL without trusting a
+ * mutable inject filename. */
+export declare function sessionCommandMarker(id: string, payloadSha256: string): string;
+export declare function parseSessionCommandMarker(text: string): {
+    id: string;
+    payloadSha256: string;
+} | undefined;
+/** The exact reservation whose consumer recovery is allowed to fence. */
+export interface SessionCommandOwnership {
+    id: string;
+    status: string;
+    owner_token: string | null;
+    attempt: number;
+    started_at: string | null;
+}
+export declare function sameSessionCommandOwner(current: SessionCommandOwnership | undefined, expected: SessionCommandOwnership): boolean;
+//# sourceMappingURL=session-command.d.ts.map

package/dist/src/session-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-command.d.ts","sourceRoot":"","sources":["../../src/session-command.ts"],"names":[],"mappings":"AAAA;;;8BAG8B;AAC9B,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAE9E;AAED,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,GACX;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAGnD;AAED,yEAAyE;AACzE,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,uBAAuB,GAAG,SAAS,EAC5C,QAAQ,EAAE,uBAAuB,GAChC,OAAO,CAST"}

package/dist/src/session-command.js

@@ -0,0 +1,20 @@
+/** Stable receipt carried in the Pi user message for one durable command.
+ * It binds the database id to the immutable payload hash, so restart recovery
+ * can reconcile SQLite ownership against session JSONL without trusting a
+ * mutable inject filename. */
+export function sessionCommandMarker(id, payloadSha256) {
+    return `<!-- qcr-command:${id}:${payloadSha256} -->`;
+}
+export function parseSessionCommandMarker(text) {
+    const match = [...text.matchAll(/<!-- qcr-command:([^:\s>]+):([a-f0-9]{64}) -->/g)].at(-1);
+    return match ? { id: match[1], payloadSha256: match[2] } : undefined;
+}
+export function sameSessionCommandOwner(current, expected) {
+    return (current !== undefined &&
+        current.id === expected.id &&
+        current.status === expected.status &&
+        current.owner_token === expected.owner_token &&
+        current.attempt === expected.attempt &&
+        current.started_at === expected.started_at);
+}
+//# sourceMappingURL=session-command.js.map

package/dist/src/session-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-command.js","sourceRoot":"","sources":["../../src/session-command.ts"],"names":[],"mappings":"AAAA;;;8BAG8B;AAC9B,MAAM,UAAU,oBAAoB,CAAC,EAAU,EAAE,aAAqB;IACpE,OAAO,oBAAoB,EAAE,IAAI,aAAa,MAAM,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,IAAY;IAEZ,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,iDAAiD,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3F,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,aAAa,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AACzE,CAAC;AAWD,MAAM,UAAU,uBAAuB,CACrC,OAA4C,EAC5C,QAAiC;IAEjC,OAAO,CACL,OAAO,KAAK,SAAS;QACrB,OAAO,CAAC,EAAE,KAAK,QAAQ,CAAC,EAAE;QAC1B,OAAO,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM;QAClC,OAAO,CAAC,WAAW,KAAK,QAAQ,CAAC,WAAW;QAC5C,OAAO,CAAC,OAAO,KAAK,QAAQ,CAAC,OAAO;QACpC,OAAO,CAAC,UAAU,KAAK,QAAQ,CAAC,UAAU,CAC3C,CAAC;AACJ,CAAC"}

package/dist/src/settledread.d.ts

@@ -0,0 +1,61 @@
+export interface PartialWritePolicy {
+    /** Bytes that moved this recently may still be mid-write. Also the time an
+     * unchanged unparseable file must sit, under our own observation, before it
+     * is called corrupt. */
+    settleMs: number;
+    /** Hard bound from the first look to "unparseable", however the file moves.
+     * 0 disables the tolerance: one read decides (tests). */
+    windowMs: number;
+    /** First re-read delay; doubles up to `maxDelayMs`. */
+    initialDelayMs: number;
+    maxDelayMs: number;
+}
+/** 3 s of stillness is two orders of magnitude above a healthy write and well
+ * above a CFS-throttled one; 30 s bounds the worst case. A truly corrupt file
+ * is declared after ~3–4 s instead of 120 ms, which costs nothing: the round
+ * is over either way and nothing else is waiting on the answer. */
+export declare const DEFAULT_PARTIAL_WRITE_POLICY: PartialWritePolicy;
+export type SettledRead = {
+    kind: "parsed";
+    value: unknown;
+    reads: number;
+    waited_ms: number;
+}
+/** The file is not there (ENOENT) — never there, or gone mid-wait. Only
+ * ENOENT: any other stat or read failure is evidence about a file that is
+ * there, and is reported as `unparseable` below. */
+ | {
+    kind: "missing";
+    reads: number;
+} | {
+    /** The bytes never parsed as JSON — or could not be read at all (EISDIR,
+     * EACCES, EIO, …; `error` then says "could not be read"): either way
+     * nothing usable is there, and the caller's malformed path decides. */
+    kind: "unparseable";
+    error: string;
+    reads: number;
+    waited_ms: number;
+    /** `settled`: it sat still and stayed broken. `window`: the hard bound.
+     * `no_tolerance`: the policy's window is 0. */
+    why: "settled" | "window" | "no_tolerance";
+};
+export interface SettledReadIo {
+    /** Monotonic ms — the wait's own clock. Default `performance.now()`. */
+    monotonicMs?: () => number;
+    /** Wall ms, compared with the file's mtime. Default `Date.now()`. */
+    wallMs?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    stat?: (path: string) => {
+        size: number;
+        mtimeMs: number;
+        ino: number;
+    };
+    read?: (path: string) => string;
+}
+export declare function resolvePartialWritePolicy(over: Partial<PartialWritePolicy> | undefined): PartialWritePolicy;
+/**
+ * Read `path` as JSON, tolerating a writer that has not finished. Total: never
+ * throws. The caller still owns shape validation of `value`.
+ */
+export declare function readSettledJson(path: string, policy: PartialWritePolicy, io?: SettledReadIo): Promise<SettledRead>;
+//# sourceMappingURL=settledread.d.ts.map

package/dist/src/settledread.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settledread.d.ts","sourceRoot":"","sources":["../../src/settledread.ts"],"names":[],"mappings":"AAyBA,MAAM,WAAW,kBAAkB;IACjC;;4BAEwB;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB;6DACyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;mEAGmE;AACnE,eAAO,MAAM,4BAA4B,EAAE,kBAK1C,CAAC;AAQF,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE;AACtE;;oDAEoD;GAClD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAClC;IACE;;2EAEuE;IACvE,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB;mDAC+C;IAC/C,GAAG,EAAE,SAAS,GAAG,QAAQ,GAAG,cAAc,CAAC;CAC5C,CAAC;AAEN,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,MAAM,CAAC;IAC3B,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACxE,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CACjC;AAED,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,SAAS,GAC5C,kBAAkB,CAEpB;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,kBAAkB,EAC1B,EAAE,GAAE,aAAkB,GACrB,OAAO,CAAC,WAAW,CAAC,CAmDtB"}

package/dist/src/settledread.js

@@ -0,0 +1,135 @@
+// Reading a JSON file another process may still be writing.
+//
+// A session writes its verdict (and its recheck outcome) with pi's `write`
+// tool, which is Node's `fs.promises.writeFile`: open with O_TRUNC, then the
+// bytes, then close, each step a separate turn of pi's event loop. `fs.watch`
+// fires on the open. Between the two steps the file is empty or short, and on
+// a CPU-starved container that gap can outlast a short burst of re-reads.
+//
+// So an unparseable read is not evidence of a malformed file while the file
+// is still plausibly being written: while its bytes moved within the last
+// `settleMs` — by its own mtime, or between two of our own looks. The reader
+// re-reads with backoff until the JSON parses, or until the file has sat
+// unchanged for `settleMs` across several looks (it really is corrupt), or
+// until `windowMs` has passed since the first look (a hard bound, so a file
+// rewritten forever is still declared). Only unparseable bytes wait: a file
+// that parses is complete, whatever its shape, and shape checking is the
+// caller's. A file that is there but cannot be read (EISDIR, EACCES, EIO, …)
+// waits the same way and is then reported as unparseable — never as missing,
+// which would leave it in place, unconsumed and unannounced. Only ENOENT is
+// "missing".
+//
+// The wait is an ordinary async sleep, never a busy loop: nothing here holds
+// the event loop.
+import { readFileSync, statSync } from "node:fs";
+/** 3 s of stillness is two orders of magnitude above a healthy write and well
+ * above a CFS-throttled one; 30 s bounds the worst case. A truly corrupt file
+ * is declared after ~3–4 s instead of 120 ms, which costs nothing: the round
+ * is over either way and nothing else is waiting on the answer. */
+export const DEFAULT_PARTIAL_WRITE_POLICY = {
+    settleMs: 3_000,
+    windowMs: 30_000,
+    initialDelayMs: 50,
+    maxDelayMs: 1_000,
+};
+/** Unchanged looks required before stillness counts — at least two re-reads
+ * after the signature was first seen, so a look that lands right after a
+ * daemon stall (when the writer, in the same throttled cgroup, has not run
+ * yet either) can never decide alone. */
+const MIN_STABLE_LOOKS = 3;
+export function resolvePartialWritePolicy(over) {
+    return { ...DEFAULT_PARTIAL_WRITE_POLICY, ...(over ?? {}) };
+}
+/**
+ * Read `path` as JSON, tolerating a writer that has not finished. Total: never
+ * throws. The caller still owns shape validation of `value`.
+ */
+export async function readSettledJson(path, policy, io = {}) {
+    const mono = io.monotonicMs ?? (() => performance.now());
+    const wall = io.wallMs ?? (() => Date.now());
+    const sleep = io.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const stat = io.stat ?? ((p) => statSync(p));
+    const read = io.read ?? ((p) => readFileSync(p, "utf8"));
+    const start = mono();
+    let delay = Math.max(1, policy.initialDelayMs);
+    let reads = 0;
+    let lastSig = null;
+    let stableSince = start;
+    let stableLooks = 0;
+    for (;;) {
+        const look = lookAt(path, stat, read, wall);
+        if (look.kind === "missing")
+            return { kind: "missing", reads };
+        reads++;
+        let error;
+        if (look.kind === "bytes") {
+            try {
+                return { kind: "parsed", value: JSON.parse(look.raw), reads, waited_ms: mono() - start };
+            }
+            catch (err) {
+                error = String(err);
+            }
+        }
+        else {
+            error = `the file could not be read: ${look.error}`;
+        }
+        const now = mono();
+        const waited = now - start;
+        if (policy.windowMs <= 0)
+            return { kind: "unparseable", error, reads, waited_ms: waited, why: "no_tolerance" };
+        const { sig, mtimeAge } = look;
+        if (sig !== lastSig) {
+            lastSig = sig;
+            stableSince = now;
+            stableLooks = 1;
+        }
+        else {
+            stableLooks++;
+        }
+        const stillFor = now - stableSince;
+        if (stableLooks >= MIN_STABLE_LOOKS &&
+            stillFor >= policy.settleMs &&
+            mtimeAge >= policy.settleMs)
+            return { kind: "unparseable", error, reads, waited_ms: waited, why: "settled" };
+        if (waited >= policy.windowMs)
+            return { kind: "unparseable", error, reads, waited_ms: waited, why: "window" };
+        await sleep(Math.min(delay, Math.max(1, policy.windowMs - waited)));
+        delay = Math.min(delay * 2, Math.max(1, policy.maxDelayMs));
+    }
+}
+/** ENOENT is the one failure that means "no file here". */
+function isMissing(err) {
+    return err?.code === "ENOENT";
+}
+/** One look: the file's signature and its bytes, or why they could not be had.
+ * A read that fails on a file that is there (EISDIR, EACCES, EIO, …) is not
+ * "missing" — a verdict path the watcher silently never consumes would wedge
+ * its round with nothing ever said — so it is reported as an error and waited
+ * out like unparseable bytes: transient ones clear, persistent ones are
+ * declared at the same bounds. */
+function lookAt(path, stat, read, wall) {
+    let st;
+    try {
+        st = stat(path);
+    }
+    catch (err) {
+        if (isMissing(err))
+            return { kind: "missing" };
+        // No mtime to age: stillness under our own looks decides alone.
+        const code = err?.code ?? "unknown";
+        return { kind: "error", error: String(err), sig: `stat-error:${code}`, mtimeAge: Infinity };
+    }
+    // Size alone misses a same-length rewrite; mtime alone misses a coarse
+    // clock; the inode catches a rename onto the name.
+    const sig = `${st.size}:${st.mtimeMs}:${st.ino}`;
+    const mtimeAge = wall() - st.mtimeMs;
+    try {
+        return { kind: "bytes", raw: read(path), sig, mtimeAge };
+    }
+    catch (err) {
+        if (isMissing(err))
+            return { kind: "missing" };
+        return { kind: "error", error: String(err), sig, mtimeAge };
+    }
+}
+//# sourceMappingURL=settledread.js.map

package/dist/src/settledread.js.map

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

package/dist/src/severity.d.ts

@@ -0,0 +1,167 @@
+import type { Verdict as VerdictType } from "./types.js";
+import { SEVERITIES } from "./severityrank.js";
+export { SEVERITIES };
+export type Severity = (typeof SEVERITIES)[number];
+/** How often the state a finding depends on actually arises. */
+export type Reachability = "routine" | "plausible" | "contrived";
+export declare const REACHABILITY_VALUES: readonly Reachability[];
+/** Findings that omit the axis are read as `routine`, so a pass that does not
+ * emit it can never accidentally soften a blocker. */
+export declare function normalizeReachability(value: string | undefined | null): Reachability;
+/** The directive-path vocabulary the predicate below walks. Config can only
+ * EXTEND it: `[review.directives]` `extra_*` keys add entries and nothing can
+ * remove the built-ins. Replacement is deliberately not offered — dropping,
+ * say, `CLAUDE.md` from the vocabulary would let a config typo silently
+ * change how first-party directive edits are treated. A repo whose tree
+ * genuinely uses one of these names for something else loses at most an
+ * escalation comment; the reverse mistake loses a guarantee. */
+export interface DirectiveVocabulary {
+    /** Path segments that mark VENDORED/third-party content: a directive file
+     * under one of these keeps the injection bright line — it was not authored
+     * in-repo through the PR flow. Matched lowercased. */
+    vendoredSegments: Set<string>;
+    /** Basenames that are agent-directive files wherever they sit in the tree. */
+    basenames: Set<string>;
+    /** Directory segments whose whole subtree is agent-directive content. */
+    dirSegments: Set<string>;
+    /** Root-level directory names whose subtree is directive content AT THE
+     * REPO ROOT ONLY — a nested `foo/prompts/` is an ordinary source dir. */
+    rootDirs: Set<string>;
+    /** Exact repo-relative file paths that are directive files. */
+    files: Set<string>;
+}
+/** Config-shaped EXTENSIONS to the built-in vocabulary (all optional; the
+ * shape [review.directives] parses into — see src/config.ts). */
+export interface DirectiveVocabularyExtras {
+    extra_vendored_segments?: string[];
+    extra_basenames?: string[];
+    extra_dir_segments?: string[];
+    extra_root_dirs?: string[];
+    extra_files?: string[];
+}
+/** The compiled-in vocabulary; the shipped default. */
+export declare const DEFAULT_DIRECTIVE_VOCABULARY: DirectiveVocabulary;
+/** The filenames among `files` that are first-party agent-directive paths
+ * under `extras` (the configured extension of the built-in vocabulary). */
+export declare function firstPartyDirectiveFiles(files: readonly {
+    filename: string;
+}[], extras?: DirectiveVocabularyExtras): string[];
+/** Built-ins ∪ the configured extras — EXTEND-only by construction. */
+export declare function directiveVocabulary(extras?: DirectiveVocabularyExtras): DirectiveVocabulary;
+/**
+ * Is `path` a FIRST-PARTY agent-directive file of the reviewed repo —
+ * `.claude/**`, top-level `prompts/**`, an `AGENTS.md`/`CLAUDE.md` (and kin)
+ * at any depth — and NOT under a vendored tree? The predicate is deliberately
+ * path-shaped and shared: dispatch uses it to pick the escalation mention,
+ * and posting.ts (through `isFirstPartyDirectiveInjection`) to name the files
+ * the escalation comment cites. `vocab` defaults to the compiled-in
+ * vocabulary for callers without config in reach.
+ */
+export declare function isFirstPartyDirectivePath(path: string | undefined | null, vocab?: DirectiveVocabulary): boolean;
+/** An injection-kind finding anchored on a first-party directive path.
+ * Findings without a `kind` never match. */
+export declare function isFirstPartyDirectiveInjection(kind: string | undefined | null, path: string | undefined | null, vocab?: DirectiveVocabulary): boolean;
+export interface PostTagContext {
+    /** The finding's `kind` field, when the pass emitted one. */
+    kind?: string | null;
+    /** The finding's anchored path. */
+    path?: string | null;
+}
+export declare function postTag(severity: Severity, confidence: number, reachability?: Reachability | null, ctx?: PostTagContext): PostTag;
+/**
+ * `postTag`'s reachability gate expressed as a SEVERITY, for a surface with
+ * no posting map (the whole-repo scan): the severity whose ROUTINE tag equals
+ * the original's reachability-gated tag. `contrived` P0–P2 → `P3` (a
+ * question, never a blocker), `plausible` P2 → `P3`; everything else — and an
+ * absent axis, read as `routine` — is unchanged. Pinned against `postTag` at
+ * every severity × reachability × confidence by tests/severity.test.ts.
+ */
+export declare function reachabilityCappedSeverity(severity: Severity, reachability?: Reachability | null): Severity;
+export type { Verdict } from "./types.js";
+export interface VerdictInput {
+    hasBlockers: boolean;
+    /** Legacy input: the session's own "I cannot decide this" call. A
+     * NEEDS_HUMAN verdict is still accepted (older prompts and containers emit
+     * it; `normalizeVerdict` folds ESCALATE into it) and the daemon lands it as
+     * `tracked`: review posted, no approval, the AI keeps driving. There is no
+     * park. No daemon-side criteria feed it. */
+    needsHuman: boolean;
+    /** Legacy input retained for older callers/containers; it has no verdict
+     * effect: routine first-party instructions produce no finding, while a
+     * surviving malicious/path-proven injection follows the ordinary blocker
+     * map. */
+    firstPartyDirectiveInjection?: boolean;
+}
+/** Verdict logic: any [blocker] ⇒ REQUEST_CHANGES; an explicit legacy
+ * cannot-decide call ⇒ NEEDS_HUMAN; else APPROVE. Directive location alone
+ * never changes the merits verdict. */
+export declare function deriveVerdict(v: VerdictInput): VerdictType;
+/**
+ * The "[check this]" inline-comment grammar: every "For a human to
+ * double-check" item is ALSO posted as an inline review comment whose first
+ * line starts with this tag. The repo's
+ * merge rule requires every conversation resolved, so each item opens a
+ * thread a person must touch — and the reviewer never resolves one:
+ * github.ts resolveOwnReviewThread refuses on this marker, so only the author
+ * or another human can clear it.
+ */
+export declare const CHECK_THIS_TAG = "[check this]";
+export declare const CHECK_THIS_RE: RegExp;
+export declare const ASK_HUMAN_TAG = "[ask your human]";
+export declare const ASK_HUMAN_RE: RegExp;
+/** The lens that mints the tag (dispatch.ts ALL_PASSES; agents/pass-ask-human.md). */
+export declare const ASK_HUMAN_LENS = "pass-ask-human";
+/**
+ * Is this finding an ask-your-human question? Keyed on the lens tag (the
+ * merge step concatenates lens tags, so a substring test is the honest one)
+ * or on an explicit `kind: ask-human`.
+ */
+export declare function isAskHumanFinding(kind?: string | null, lens?: string | null): boolean;
+export declare const DEFERRED_TAG = "[deferred]";
+export declare const DEFERRED_RE: RegExp;
+/** Is this finding a conscious deferral? Keyed on an explicit `kind`, the one
+ * signal a session sets deliberately — there is no lens that mints deferrals
+ * (the DECISION to defer belongs to the PR's session, after validation). */
+export declare function isDeferredFinding(kind?: string | null): boolean;
+/** The three posting tags, bare (no brackets) — `postTag`'s whole range. */
+export declare const POSTING_TAG_WORDS: readonly ["blocker", "question", "nit"];
+export type PostTag = (typeof POSTING_TAG_WORDS)[number];
+/** Every sanctioned tag, bracketed, in one list: the three posting tags plus
+ * the marker prefixes. This is THE grammar — a tag not on it is not one. */
+declare const MARKER_TAGS: readonly ["[check this]", "[ask your human]", "[deferred]"];
+type BareMarker<T> = T extends `[${infer Word}]` ? Word : never;
+export type SanctionedTagWord = PostTag | BareMarker<(typeof MARKER_TAGS)[number]>;
+export declare const SANCTIONED_TAGS: readonly string[];
+/** Remove only sanctioned posting and marker tags from a title. */
+export declare function stripSanctionedTags(title: string): string;
+/** The ordinary posting tag a findings-record tag word (bare, lower case) is
+ * counted, posted and ranked under: a posting tag is itself; `check this` is a
+ * question; `ask your human` and `deferred` take the tag their severity maps
+ * to (a question without one). Null for a word outside the grammar. */
+export declare function ordinaryPostTag(tag: string, severity: string | null, confidence: number | null, reachability: string | null): PostTag | null;
+/** A tag's bare word as every reader compares it: no brackets, lowercase,
+ * internal whitespace collapsed (`"[Ask  your human]"` → `"ask your human"`).
+ * "" for null or empty. */
+export declare function bareTag(raw: string | null | undefined): string;
+/** Is `raw` — with or without brackets, in any case, with internal whitespace
+ * collapsed — one of the sanctioned tags? */
+export declare function isSanctionedTag(raw: string | null | undefined): boolean;
+/**
+ * Strip a leading tag from a finding TITLE when that tag is outside the
+ * grammar.
+ *
+ * A title is not where a tag belongs — `inlineBody` mints the real one — so a
+ * bracketed prefix on a title is either a duplicate of the sanctioned tag or an
+ * invented one. Both are removed; the invented one is REPORTED, so the escape
+ * shows up in telemetry instead of going out on the PR. A sanctioned marker
+ * (`[check this]`, `[ask your human]`) is left alone: those are minted from the
+ * finding's own fields and carry meaning.
+ *
+ * Only the tag is stripped. Not one word of the finding's reasoning is touched
+ * — this cuts a wrong label, never a justification.
+ */
+export declare function stripUngrammaticalTag(title: string): {
+    title: string;
+    stripped: string | null;
+};
+//# sourceMappingURL=severity.d.ts.map

package/dist/src/severity.d.ts.map

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