@deftai/directive-core 0.95.0 → 0.97.0

package/dist/parent-turn-shape/evaluate.js

@@ -0,0 +1,353 @@
+/**
+ * Parent turn-shape hard-stop for text-repetition hang (FC14 / #3131).
+ *
+ * Soft skill prose (#2943) alone is insufficient: parents still burn the full
+ * output budget on identical progress sentences with zero tool_use after leaf
+ * announce. This pure library is the Directive-side machine-checkable gate.
+ *
+ * Hosts (OpenClaw, swarm parents, review monitors) SHOULD evaluate the parent
+ * turn stream mid-generation and hard-stop when `ok` is false.
+ *
+ * Illegal shape (MUST NOT):
+ *   N > maxIdenticalWithoutTool (default 2) near-identical assistant sentences
+ *   (or streaming text chunks) in one turn with no tool_use and no yield.
+ *
+ * Legal post-announce shapes:
+ *   1. Tool batch (ground-truth) then one consolidate
+ *   2. sessions_yield / wait without filler
+ *   3. One short user answer that is NOT a repeated progress line
+ */
+/** Canonical fail class for the hang (#3131 / soft FC14 recurrence of #2943). */
+export const PARENT_TURN_FAIL_FC14 = "FC14";
+/** Default max identical text units without tool/yield (N>2 is illegal). */
+export const DEFAULT_MAX_IDENTICAL_WITHOUT_TOOL = 2;
+/** Minimum length (chars) for a text unit to count toward repetition. */
+const MIN_UNIT_LEN = 12;
+/** Word Jaccard threshold for near-identical (after normalize). */
+const JACCARD_NEAR = 0.9;
+/** Progress-ish tokens that mark filler narration after announce. */
+const PROGRESS_HINT_RE = /\b(checking|checking\s+worktrees|open\s+prs?|next|unfinished|implementing|looking\s+at|will\s+(check|inspect|verify|spawn)|status\s+next|monitor(?:ing)?)\b/i;
+/**
+ * Normalize assistant text for identity comparison.
+ * Collapses whitespace, lowercases, strips common trailing punctuation.
+ */
+export function normalizeTurnText(text) {
+    return text
+        .normalize("NFKC")
+        .toLowerCase()
+        .replace(/\s+/g, " ")
+        .replace(/^[\s"'`]+|[\s"'`]+$/g, "")
+        .replace(/[.!?…,:;]+$/g, "")
+        .trim();
+}
+/** Split a blob into sentence-like units (periods, newlines, ellipsis). */
+export function splitTextUnits(text) {
+    const raw = text.replace(/\r\n/g, "\n");
+    // Include single newlines so block-formatted repeated progress lines still
+    // unitize (FC14 hang class often streams one line per newline, no period).
+    // Optional closing quotes after terminal punctuation, with or without space:
+    // `"Hello." "Hello."` and `"Hello.""Hello."`.
+    const parts = raw
+        .split(/(?:\n+|(?<=[.!?…])["']+\s*|(?<=[.!?…])\s+|(?<=\.\.\.)\s+)/)
+        .map((p) => p.trim())
+        .filter((p) => p.length > 0);
+    if (parts.length === 0 && raw.trim().length > 0) {
+        return [raw.trim()];
+    }
+    return parts;
+}
+function wordSet(normalized) {
+    const words = normalized.split(/[^a-z0-9_]+/).filter((w) => w.length > 0);
+    return new Set(words);
+}
+/**
+ * True when two normalized strings are near-identical (exact, containment with
+ * high length ratio, or high word Jaccard). Short units never match.
+ */
+export function isNearIdentical(a, b) {
+    const na = normalizeTurnText(a);
+    const nb = normalizeTurnText(b);
+    if (na.length < MIN_UNIT_LEN || nb.length < MIN_UNIT_LEN)
+        return false;
+    if (na === nb)
+        return true;
+    const shorter = na.length <= nb.length ? na : nb;
+    const longer = na.length <= nb.length ? nb : na;
+    if (longer.includes(shorter) && shorter.length / longer.length >= 0.85) {
+        return true;
+    }
+    const sa = wordSet(na);
+    const sb = wordSet(nb);
+    if (sa.size === 0 || sb.size === 0)
+        return false;
+    let inter = 0;
+    for (const w of sa) {
+        if (sb.has(w))
+            inter += 1;
+    }
+    const union = sa.size + sb.size - inter;
+    if (union === 0)
+        return false;
+    return inter / union >= JACCARD_NEAR;
+}
+/**
+ * Collect assistant text units from turn events.
+ *
+ * Streaming hosts often emit word/chunk deltas as separate `assistant_text`
+ * events. Coalesce consecutive text events into one blob so fragmented
+ * progress sentences reconstruct before split/identity checks (P1 / #3131).
+ * Non-text events (tool_use / yield) flush the coalesce buffer.
+ */
+function collectAssistantUnits(events) {
+    const units = [];
+    const pushUnitsFrom = (text) => {
+        for (const u of splitTextUnits(text)) {
+            const t = u.trim();
+            if (t.length >= MIN_UNIT_LEN)
+                units.push(t);
+        }
+    };
+    let run = "";
+    for (const ev of events) {
+        if (ev.kind === "assistant_text") {
+            const text = typeof ev.text === "string" ? ev.text : "";
+            if (!text)
+                continue;
+            // Sentence-boundary deltas often omit whitespace after `.!?` before the
+            // next capital letter. Insert space only at sentence ends — never between
+            // arbitrary alnum chunks (subword streams like workt+rees must not gain
+            // a false space).
+            if (run.length > 0 && /[.!?…]["']?\s*$/.test(run) && !/^\s/.test(text) && !/\s$/.test(run)) {
+                run += " ";
+            }
+            run += text;
+            continue;
+        }
+        // Non-text event ends the coalesce run (tool/yield boundaries).
+        if (run.trim().length > 0)
+            pushUnitsFrom(run);
+        run = "";
+    }
+    if (run.trim().length > 0)
+        pushUnitsFrom(run);
+    return units;
+}
+/**
+ * Max connected-component size under near-identity edges (union-find).
+ * Captures non-transitive chains of incrementally varied progress lines
+ * (A≈B≈C even when A≉C) so FC14 cannot be bypassed by wording drift.
+ */
+function maxNearIdentityComponent(units) {
+    const n = units.length;
+    if (n === 0)
+        return 0;
+    // Precompute normalize + word sets once (avoid O(n²) re-normalize/Set alloc).
+    const norms = units.map((u) => normalizeTurnText(u));
+    const sets = norms.map((n) => wordSet(n));
+    const near = (i, j) => {
+        const na = norms[i] ?? "";
+        const nb = norms[j] ?? "";
+        if (na.length < MIN_UNIT_LEN || nb.length < MIN_UNIT_LEN)
+            return false;
+        if (na === nb)
+            return true;
+        const shorter = na.length <= nb.length ? na : nb;
+        const longer = na.length <= nb.length ? nb : na;
+        if (longer.includes(shorter) && shorter.length / longer.length >= 0.85)
+            return true;
+        const sa = sets[i] ?? new Set();
+        const sb = sets[j] ?? new Set();
+        if (sa.size === 0 || sb.size === 0)
+            return false;
+        let inter = 0;
+        for (const w of sa) {
+            if (sb.has(w))
+                inter += 1;
+        }
+        const union = sa.size + sb.size - inter;
+        return union > 0 && inter / union >= JACCARD_NEAR;
+    };
+    const parent = Array.from({ length: n }, (_, i) => i);
+    const find = (i) => {
+        let x = i;
+        while (parent[x] !== x) {
+            parent[x] = parent[parent[x] ?? x] ?? x;
+            x = parent[x] ?? x;
+        }
+        return x;
+    };
+    const unite = (a, b) => {
+        const ra = find(a);
+        const rb = find(b);
+        if (ra !== rb)
+            parent[ra] = rb;
+    };
+    for (let i = 0; i < n; i++) {
+        for (let j = i + 1; j < n; j++) {
+            if (near(i, j))
+                unite(i, j);
+        }
+    }
+    const sizes = new Map();
+    let max = 1;
+    for (let i = 0; i < n; i++) {
+        const r = find(i);
+        const next = (sizes.get(r) ?? 0) + 1;
+        sizes.set(r, next);
+        if (next > max)
+            max = next;
+    }
+    return max;
+}
+/**
+ * Max count of any single near-identical cluster among units.
+ * Consecutive runs + exact-normalized frequency (O(n)); for small unit counts
+ * also union-find near-identity components so non-consecutive / chain variants
+ * cannot bypass FC14 (P1 / #3131).
+ */
+function maxIdenticalCluster(units) {
+    if (units.length === 0)
+        return 0;
+    const norms = units.map((u) => normalizeTurnText(u));
+    let maxRun = 1;
+    let run = 1;
+    for (let i = 1; i < units.length; i++) {
+        if (isNearIdentical(units[i] ?? "", units[i - 1] ?? "")) {
+            run += 1;
+            if (run > maxRun)
+                maxRun = run;
+        }
+        else {
+            run = 1;
+        }
+    }
+    // Frequency by exact normalized form (O(n)).
+    const freq = new Map();
+    let maxFreq = 1;
+    for (const n of norms) {
+        if (n.length < MIN_UNIT_LEN)
+            continue;
+        const next = (freq.get(n) ?? 0) + 1;
+        freq.set(n, next);
+        if (next > maxFreq)
+            maxFreq = next;
+    }
+    // Always cluster near-identity components. Input size is bounded by the
+    // zero-tool character hard-stop above, so O(n²) stays finite.
+    const maxComponent = maxNearIdentityComponent(units);
+    return Math.max(maxRun, maxFreq, maxComponent);
+}
+/**
+ * Detect when a single blob itself embeds the same sentence many times
+ * (model streams one giant assistant message of repeated lines).
+ */
+export function countRepeatedUnitsInBlob(text) {
+    const units = splitTextUnits(text).filter((u) => u.trim().length >= MIN_UNIT_LEN);
+    return maxIdenticalCluster(units);
+}
+function looksLikeProgressOnly(units) {
+    if (units.length < 2)
+        return false;
+    let progressHits = 0;
+    for (const u of units) {
+        if (PROGRESS_HINT_RE.test(u))
+            progressHits += 1;
+    }
+    // Majority of multi-sentence text is progress narration.
+    return progressHits >= Math.ceil(units.length / 2);
+}
+/**
+ * Evaluate whether a parent turn shape is legal under the FC14 hard-stop.
+ * Pure / side-effect free — safe for mid-stream host gates and unit tests.
+ */
+export function evaluateParentTurnShape(input) {
+    const events = input.events ?? [];
+    const maxAllowed = input.maxIdenticalWithoutTool ?? DEFAULT_MAX_IDENTICAL_WITHOUT_TOOL;
+    let hasToolUse = false;
+    let hasYield = false;
+    for (const ev of events) {
+        if (ev.kind === "tool_use")
+            hasToolUse = true;
+        if (ev.kind === "yield")
+            hasYield = true;
+    }
+    // Tool or yield greases the turn: repetition hard-stop does not fire.
+    if (hasToolUse || hasYield) {
+        return {
+            ok: true,
+            failClass: "none",
+            reasons: [],
+            maxIdenticalCount: 0,
+            hasToolUse,
+            hasYield,
+        };
+    }
+    // Fail closed on unbounded zero-tool text (output-budget burn / DoS class).
+    const ZERO_TOOL_CHAR_CAP = 50_000;
+    let zeroToolChars = 0;
+    for (const ev of events) {
+        if (ev.kind === "assistant_text" && typeof ev.text === "string") {
+            zeroToolChars += ev.text.length;
+        }
+    }
+    if (zeroToolChars > ZERO_TOOL_CHAR_CAP) {
+        return {
+            ok: false,
+            failClass: "FC14",
+            reasons: [
+                `FC14 text-repetition-hang: zero-tool assistant text exceeds ${ZERO_TOOL_CHAR_CAP} chars ` +
+                    `(${zeroToolChars}) without tool_use/yield — hard-stop budget burn. Refs #3131 / #2943.`,
+            ],
+            maxIdenticalCount: Math.ceil(zeroToolChars / MIN_UNIT_LEN),
+            hasToolUse,
+            hasYield,
+        };
+    }
+    const units = collectAssistantUnits(events);
+    // Also fold in whole-blob repetition for single giant text events.
+    let maxIdenticalCount = maxIdenticalCluster(units);
+    for (const ev of events) {
+        if (ev.kind === "assistant_text" && typeof ev.text === "string") {
+            maxIdenticalCount = Math.max(maxIdenticalCount, countRepeatedUnitsInBlob(ev.text));
+        }
+    }
+    const reasons = [];
+    let failClass = "none";
+    if (maxIdenticalCount > maxAllowed) {
+        failClass = "FC14";
+        reasons.push(`FC14 text-repetition-hang: ${maxIdenticalCount} near-identical assistant text units ` +
+            `with zero tool_use/yield (max allowed ${maxAllowed}; N>${maxAllowed} is illegal). ` +
+            `After subagent announce, emit a tool-first ground-truth batch, sessions_yield, ` +
+            `or one short non-repeated answer — not repeated progress lines. Refs #3131 / #2943.`);
+    }
+    // Post-announce: multi-sentence progress-only with zero tools is also illegal
+    // even when sentences are not exact clones (soft-only #2943 recurrence class).
+    // Threshold is >=2 units (N>1 multi-sentence) — exactly two progress lines
+    // must not bypass the gate.
+    if (input.afterSubagentAnnounce &&
+        units.length >= 2 &&
+        looksLikeProgressOnly(units) &&
+        failClass === "none") {
+        failClass = "progress-only-no-tool";
+        reasons.push(`progress-only-no-tool: post-subagent-announce turn has ${units.length} assistant ` +
+            `text units with progress narration and zero tool_use/yield. MUST tool-first or yield. Refs #3131 / #2943.`);
+    }
+    // Alias surface: FC14 and text-repetition-hang name the same hang class.
+    if (failClass === "FC14") {
+        // Keep failClass as FC14; callers may also match text-repetition-hang via reasons.
+    }
+    return {
+        ok: failClass === "none",
+        failClass,
+        reasons,
+        maxIdenticalCount,
+        hasToolUse,
+        hasYield,
+    };
+}
+/** Convenience: true when the turn is an illegal text-repetition hang. */
+export function isTextRepetitionHang(input) {
+    const r = evaluateParentTurnShape(input);
+    return r.failClass === "FC14" || r.failClass === "text-repetition-hang";
+}
+//# sourceMappingURL=evaluate.js.map

package/dist/parent-turn-shape/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Parent turn-shape hard-stop (FC14 / #3131).
+ *
+ * Machine-checkable gate so soft skill prose is not the sole mitigation for
+ * the OpenClaw parent text-repetition hang after leaf announce.
+ */
+export { countRepeatedUnitsInBlob, DEFAULT_MAX_IDENTICAL_WITHOUT_TOOL, evaluateParentTurnShape, isNearIdentical, isTextRepetitionHang, normalizeTurnText, PARENT_TURN_FAIL_FC14, type ParentTurnEvent, type ParentTurnFailClass, type ParentTurnShapeInput, type ParentTurnShapeResult, splitTextUnits, } from "./evaluate.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/parent-turn-shape/index.js

@@ -0,0 +1,8 @@
+/**
+ * Parent turn-shape hard-stop (FC14 / #3131).
+ *
+ * Machine-checkable gate so soft skill prose is not the sole mitigation for
+ * the OpenClaw parent text-repetition hang after leaf announce.
+ */
+export { countRepeatedUnitsInBlob, DEFAULT_MAX_IDENTICAL_WITHOUT_TOOL, evaluateParentTurnShape, isNearIdentical, isTextRepetitionHang, normalizeTurnText, PARENT_TURN_FAIL_FC14, splitTextUnits, } from "./evaluate.js";
+//# sourceMappingURL=index.js.map

package/dist/pr-merge-readiness/ci-gate.d.ts

@@ -1,5 +1,21 @@
 import type { CheckRunRecord } from "./gh.js";
-export type CiReadyState = "ready" | "blocked" | "not_ready_yet" | "runner_capacity_stall" | "skipped";
+/**
+ * Bot-reviewer check-runs are not CI workflow jobs. Presence of only these
+ * (or empty check-runs) is the `ci_never_scheduled` weather signal (#3167).
+ */
+export declare function isBotReviewCheck(name: string): boolean;
+/**
+ * Suite family for cancelled↔green sibling matching (#3167 / Greptile P1).
+ * Unrelated greens (CodeQL, Socket, …) must not clear a cancelled TypeScript/Go lane.
+ * Returns null when the check is not a TS/Go CI suite job.
+ */
+export declare function suiteFamilyOf(name: string): "typescript" | "go" | null;
+/**
+ * Branch-protection SoT aggregators only (#3168 map). Primary/failover lanes are
+ * not authoritative: a green primary must not clear a cancelled aggregator.
+ */
+export declare function isAuthoritativeSuiteAggregator(name: string): boolean;
+export type CiReadyState = "ready" | "blocked" | "ci_failures" | "not_ready_yet" | "runner_capacity_stall" | "ci_never_scheduled" | "ci_cancelled_no_failover" | "skipped";
 export interface CiGateOptions {
     readonly skipCi?: boolean;
     readonly ignoreCheckNames?: readonly string[];
@@ -23,6 +39,8 @@ export interface CiGateSummary {
     readonly pending_required: readonly string[];
     /** Required checks classified as capacity-stalled (#2672). */
     readonly capacity_stalled_required: readonly string[];
+    /** Required checks cancelled without a green failover sibling (#3167). */
+    readonly cancelled_required: readonly string[];
     readonly conclusions: readonly CiCheckConclusion[];
 }
 export interface CiGateResult {
@@ -30,5 +48,15 @@ export interface CiGateResult {
     readonly summary: CiGateSummary;
 }
 export declare function buildCiSummaryLine(summary: CiGateSummary): string;
+/**
+ * Classify required CI weather for a HEAD check-run list (#2169 / #2672 / #3167).
+ *
+ * Distinct ready_state codes:
+ * - `ci_never_scheduled` — no CI workflow check-runs (bots alone / empty)
+ * - `runner_capacity_stall` — queued past budget, no runner claimed
+ * - `ci_failures` — completed failure / timed_out with product evidence
+ * - `ci_cancelled_no_failover` — only cancelled failures; no green failover
+ * - `not_ready_yet` / `ready` / `blocked` / `skipped` — legacy + residual
+ */
 export declare function evaluateCiGate(checkRuns: readonly CheckRunRecord[], options?: CiGateOptions): CiGateResult;
 //# sourceMappingURL=ci-gate.d.ts.map