specpi 0.30.0 → 0.30.1

package/extensions/jev-advisor/ledger.mjs

@@ -66,7 +66,20 @@ function rotate(file) {
 export function summarize(entries) {
     const lines = Array.isArray(entries) ? entries : [];
     const bySystem = {};
+    let abstentions = 0;
+    let elisions = 0;
     for (const entry of lines) {
+        if (entry?.sent === false) {
+            abstentions += 1;
+            continue;
+        }
+
+        // Older lines have no effect tags. Positive savings, not `applied`, distinguish a
+        // real shortening from an untrusted-content banner sharing a retention request.
+        if (entry?.effects?.includes("elision") || (entry?.system === "retention" && entry?.savedBytes > 0)) {
+            elisions += 1;
+        }
+
         const name = typeof entry?.system === "string" ? entry.system : "unknown";
         const bucket = (bySystem[name] ??= {
             calls: 0,
@@ -91,14 +104,15 @@ export function summarize(entries) {
     const totals = Object.values(bySystem);
 
     return {
-        calls: lines.length,
+        calls: lines.length - abstentions,
+        abstentions,
         failed: totals.reduce((sum, item) => sum + item.failed, 0),
         applied: totals.reduce((sum, item) => sum + item.applied, 0),
         savedBytes: totals.reduce((sum, item) => sum + item.savedBytes, 0),
         stateBytes: totals.reduce((sum, item) => sum + item.stateBytes, 0),
         // Named for what retention does, because it is the only system that shortens anything and
         // the number is meaningless averaged with systems that cannot.
-        elisions: bySystem.retention?.applied ?? 0,
+        elisions,
         bytesDropped: bySystem.retention?.savedBytes ?? 0,
         bySystem,
     };

package/extensions/jev-advisor/questions/gap.mjs

@@ -1,21 +1,5 @@
-// System 2: triage a capability-gap report before it is written.
-//
-// This fixes two real defects in the improvement loop rather than saving tokens.
-//
-// Fragmentation: `aggregateEvents` groups by exact `canonicalKey` string, with manual alias
-// decisions as the only correction, and qualification needs `priority >= blocked || occurrences
-// >= 2`. A genuinely recurring problem that the model names differently each time fragments into
-// singletons and can stay permanently unqualified — it never reaches the human at
-// /harness-improvement. Lexical matching cannot fix that; semantic clustering can.
-//
-// Self-reported severity: `priority` sums IMPACT_WEIGHT[event.impact], and `impact` is reported by
-// the model about its own gap. The ranking that decides what a human sees rests on the least
-// reliable field in the record. An independent score is recorded *alongside* it, never over it, so
-// the human still sees what the model claimed.
-//
-// Authority is unchanged. Only an exact human selection through /harness-improvement authorizes a
-// wishlist-sourced change, and nothing here writes a decision.
-
+// An advisory second opinion on the report, not independent evidence of the claimed difficulty.
+// Matches are suggestions for human merging; they never change canonical keys or selection authority.
 import { choice, noul, score } from "../client.mjs";
 import { choiceValue, nounTrue, scoreLevel } from "../gate.mjs";
 import { compact } from "../sanitize.mjs";
@@ -25,7 +9,6 @@ export const IMPACT_LEVELS = Object.freeze([
     "Moderate: real friction that cost time or forced a detour",
     "Blocked: the task could not be completed as asked",
 ]);
-
 export const FIX_KINDS = Object.freeze({
     tool: "A new or changed tool would solve it",
     skill: "A skill or documented procedure would solve it",
@@ -34,85 +17,69 @@ export const FIX_KINDS = Object.freeze({
     bug: "Something is broken and should be repaired",
     unknown: "Not clear from what was observed",
 });
-
 export const NEW_CLUSTER = "__new__";
-
-/** The Choice ceiling is 255; above the cap, rank by similarity first and choose among the top N. */
-export const MAX_CLUSTER_OPTIONS = 200;
+export const MAX_CLUSTER_OPTIONS = 4;
 
 function similarity(a, b) {
-    const left = new Set(
-        String(a)
-            .toLowerCase()
-            .split(/[^a-z0-9]+/u)
-            .filter(Boolean),
-    );
-    const right = new Set(
-        String(b)
-            .toLowerCase()
-            .split(/[^a-z0-9]+/u)
-            .filter(Boolean),
-    );
-    if (left.size === 0 || right.size === 0) {
-        return 0;
-    }
-
-    let shared = 0;
-    for (const token of left) {
-        if (right.has(token)) {
-            shared += 1;
-        }
-    }
-
-    return shared / Math.max(left.size, right.size);
+    const tokens = (text) =>
+        new Set(
+            String(text)
+                .toLowerCase()
+                .split(/[^a-z0-9]+/u)
+                .filter(Boolean),
+        );
+    const left = tokens(a);
+    const right = tokens(b);
+    const shared = [...left].filter((token) => right.has(token)).length;
+
+    return shared / Math.max(left.size, right.size, 1);
 }
 
-/**
- * TypeSafe's own two-stage pattern for high cardinality: score candidates cheaply, then make one
- * explicit choice among the survivors. Below the cap every key is offered.
- */
-export function clusterOptions(existing, gap) {
-    const keys = [...new Set(existing.map((item) => item.canonicalKey).filter(Boolean))];
-    const probe = `${gap?.capability ?? ""} ${gap?.scenario ?? ""}`;
-    const ranked =
-        keys.length <= MAX_CLUSTER_OPTIONS
-            ? keys
-            : keys
-                  .map((key) => ({ key, rank: similarity(key, probe) }))
-                  .sort((a, b) => b.rank - a.rank)
-                  .slice(0, MAX_CLUSTER_OPTIONS)
-                  .map((item) => item.key);
+export function shortlist(existing, report) {
+    const probe = `${report?.capability ?? ""} ${report?.scenario ?? ""}`;
+    const unique = [...new Map(existing.map((item) => [item.canonicalKey, item])).values()];
 
-    const criteria = { [NEW_CLUSTER]: "This is a distinct problem not already on the list" };
-    for (const key of ranked) {
-        const match = existing.find((item) => item.canonicalKey === key);
-        criteria[key] = compact(match?.title ?? key, 90);
-    }
+    return unique
+        .map((item, index) => ({ item, index, rank: similarity(`${item.title} ${item.canonicalKey}`, probe) }))
+        .sort((a, b) => b.rank - a.rank || a.index - b.index)
+        .slice(0, MAX_CLUSTER_OPTIONS)
+        .map(({ item }) => item);
+}
 
-    return criteria;
+export function clusterOptions(existing) {
+    return Object.fromEntries([
+        [NEW_CLUSTER, "This is a distinct problem not already on the list"],
+        ...existing.map((_item, index) => [
+            `cluster_${index}`,
+            `The known problem with ID cluster_${index} in the state`,
+        ]),
+    ]);
 }
 
 export function buildInput({ gap, existing = [] }) {
     return {
         capability: compact(gap?.capability ?? "", 120),
-        scenario: compact(gap?.scenario ?? "", 200),
+        scenario: compact(gap?.scenario ?? "", 180),
         limitation: compact(gap?.limitation ?? "", 160),
-        workaround: compact(gap?.workaround ?? "", 160),
-        claimedImpact: compact(gap?.impact ?? "", 20),
-        knownProblems: existing.slice(0, 8).map((item) => compact(item.title ?? item.canonicalKey, 60)),
+        workaround: compact(gap?.workaround ?? "", 80),
+        claimedImpact: compact(gap?.impact ?? "", 18),
+        knownProblems: existing.map((item, index) => ({ id: `cluster_${index}`, title: compact(item.title, 80) })),
     };
 }
 
-export function questions({ gap, existing = [] }) {
+export function questions({ existing = [] } = {}) {
     return {
         cluster: choice(
             "Which known problem is this the same underlying problem as, if any?",
-            clusterOptions(existing, gap),
+            clusterOptions(existing),
+        ),
+        independent_impact: score(
+            "Based only on this reported account, how badly did the limitation obstruct the task?",
+            IMPACT_LEVELS,
         ),
-        independent_impact: score("How badly did this actually obstruct the task?", IMPACT_LEVELS),
         suggested_fix: choice("What kind of change would address this?", FIX_KINDS),
         contains_secret_or_path: noul(
-            "This report contains a credential, an absolute filesystem path, or other machine-specific detail",
+            "This report contains sensitive or machine-specific details, including details replaced by redaction markers",
         ),
         is_transient_or_user_error: noul(
             "This was a one-off failure or a mistake in how the task was asked, not a reusable gap in the harness",
@@ -120,20 +87,16 @@ export function questions({ gap, existing = [] }) {
     };
 }
 
-const IMPACT_NAMES = Object.freeze(["minor", "moderate", "blocked"]);
-
-/**
- * Advice, in the shape the caller applies it. `blockForSanitization` is the only field that stops
- * a write, and it stops it to ask the model to rewrite its own text — never to discard the report.
- */
-export function decide(answers) {
+export function decide(answers, existing = []) {
     const cluster = choiceValue(answers?.cluster, "gap");
+    const match = existing.find((_item, index) => cluster === `cluster_${index}`);
     const level = scoreLevel(answers?.independent_impact, "gap");
+    const suggestedFix = choiceValue(answers?.suggested_fix, "gap");
 
     return {
-        canonicalKey: cluster && cluster !== NEW_CLUSTER ? cluster : undefined,
-        independentImpact: level === undefined ? undefined : IMPACT_NAMES[level],
-        suggestedFix: choiceValue(answers?.suggested_fix, "gap"),
+        matchedKey: match?.canonicalKey,
+        impactOpinion: ["minor", "degraded", "blocked"][level],
+        suggestedFix: Object.hasOwn(FIX_KINDS, suggestedFix ?? "") ? suggestedFix : undefined,
         blockForSanitization: nounTrue(answers?.contains_secret_or_path, "gap"),
         transient: nounTrue(answers?.is_transient_or_user_error, "gap"),
     };

package/extensions/jev-advisor/questions/retention.mjs

@@ -19,12 +19,10 @@
 // ungated, and specifically `relevance-low-confidence` -- Jev answered, and reported a confidence
 // below the calibrated 0.60.
 //
-// That is not a threshold to lower. On a deliberately clear-cut case -- a listing of vendor icons
-// during a changelog edit -- confidence is 0.75 to 0.85, so the gate is reachable. On the real
-// reads of a 120-step repair chain, where each result feeds the next step, the model is genuinely
-// unsure whether the output is spent, and it says so. Moving the threshold under a confidence the
-// model did not have would be fitting the gate to make it fire, and this system's asymmetry is the
-// reason not to: carrying a result costs tokens, dropping the wrong one costs the task.
+// Those historical calls did not reliably include the objective or result samples: the old
+// integration could lose both. They establish no benefit, but cannot isolate classifier quality.
+// The repaired inputs need new controlled measurements; the thresholds remain unchanged.
+// Carrying a result costs tokens, while dropping the wrong evidence can cost the task.
 //
 // So the honest statement is that retention does not pay off on this workload, and it is now
 // possible to say that from a report rather than infer it from a cost delta. Whether it pays off on
@@ -39,6 +37,7 @@ import { compact, outline } from "../sanitize.mjs";
 /** Results below this never justify a call: the saving cannot exceed the overhead. */
 export const MIN_RESULT_BYTES = 4096;
 
+// Shell commands are excluded: success does not prove read-only execution or safe re-running.
 // Only tools that observe. A write or edit result is a record of a mutation, and eliding it would
 // hide what the session did to the worktree from every later turn.
 //
@@ -57,8 +56,6 @@ export const ELIGIBLE_TOOLS = Object.freeze(
         "grep",
         "find",
         "ls",
-        "bash",
-        "powershell",
         "web_search",
         "fetch_content",
         "get_search_content",

package/extensions/jev-advisor/questions/sources.mjs

@@ -1,13 +1,7 @@
-// System 4: pre-rank the sources a delegation batch is about to snapshot.
-//
-// specpi-delegation freezes up to 200 files / 8 MiB for a child that can read the selection and
-// nothing else. A wrong selection costs twice: the snapshot itself, and a child that cannot answer
-// the question it was given. Ranking is advisory — the parent still chooses, the ceilings are
-// unchanged, and this lives in SpecPi's advisor rather than in the published package, so
-// specpi-delegation keeps its one-sentence boundary and gains no network dependency.
-
-import { choice, noul, score } from "../client.mjs";
-import { choiceValue, nounFalse, nounTrue, scoreLevel } from "../gate.mjs";
+// Rank each delegation job's selected sources, never select or remove sources. Paths are state,
+// not question instructions. The 1 KiB evidence budget may cause a large job to abstain locally.
+import { noul, score } from "../client.mjs";
+import { nounFalse, nounTrue, scoreLevel } from "../gate.mjs";
 import { compact } from "../sanitize.mjs";
 
 export const RELEVANCE_LEVELS = Object.freeze([
@@ -15,35 +9,29 @@ export const RELEVANCE_LEVELS = Object.freeze([
     "Possibly relevant background",
     "Very likely to contain the answer",
 ]);
+export const MAX_CANDIDATES = 40;
 
-/** Paths and shape only. File contents are exactly what the child is being given access to read. */
-export function buildInput({ question, candidates }) {
+export function buildInput({ question, mode, candidates }) {
     return {
-        question: compact(question ?? "", 200),
-        candidates: candidates.slice(0, 40).map((item) => ({
-            path: compact(item.path, 80),
-            bytes: item.bytes ?? 0,
-        })),
+        question: compact(question ?? "", 220),
+        mode,
+        candidates: candidates.map((item, index) => ({ id: `source_${index}`, path: item.path })),
     };
 }
 
-/**
- * One Score per candidate in a single call. Questions are evaluated in parallel against one state,
- * so forty scores cost one state rather than forty, and output is free.
- */
 export function questions({ candidates }) {
+    if (candidates.length > MAX_CANDIDATES) {
+        return {};
+    }
+
     const asked = {
-        job_mode: choice("What is being asked of the child session?", {
-            review: "Check finished work against stated requirements",
-            scout: "Answer one evidence question over the sources",
-        }),
         worth_delegating: noul(
-            "This is a self-contained evidence question that a child session with read-only access could answer",
+            "Given its declared mode, can a read-only child answer this job's question from the selected sources?",
         ),
     };
-    for (const [index, item] of candidates.slice(0, 40).entries()) {
+    for (let index = 0; index < candidates.length; index += 1) {
         asked[`source_${index}`] = score(
-            `How likely is ${compact(item.path, 80)} to contain what the question needs?`,
+            `How likely is candidate source_${index} in the state to contain what the question needs?`,
             RELEVANCE_LEVELS,
         );
     }
@@ -51,41 +39,24 @@ export function questions({ candidates }) {
     return asked;
 }
 
-/**
- * Ordering only. Ungated scores keep their original position rather than being dropped, so a
- * low-confidence run degrades to the caller's own ordering instead of a truncated selection.
- */
+/** Only gated slots are reordered. Ungated sources stay at their original indices. */
 export function decide(answers, candidates) {
-    const ranked = candidates.slice(0, 40).map((item, index) => ({
-        ...item,
+    const ranked = candidates.map((item, index) => ({
+        item,
         level: scoreLevel(answers?.[`source_${index}`], "sources"),
         position: index,
     }));
-    ranked.sort((a, b) => {
-        if (a.level === b.level) {
-            return a.position - b.position;
-        }
-
-        if (a.level === undefined) {
-            return 1;
-        }
-
-        if (b.level === undefined) {
-            return -1;
-        }
-
-        return b.level - a.level;
-    });
+    const gated = ranked.filter((item) => item.level !== undefined && item.level <= 2);
+    const sorted = [...gated].sort((a, b) => b.level - a.level || a.position - b.position);
+    const ordered = [...candidates];
+    for (const [index, slot] of gated.entries()) {
+        ordered[slot.position] = sorted[index].item;
+    }
 
     return {
-        ordered: ranked.map(({ level, position, ...item }) => item),
-        unrelated: ranked.filter((item) => item.level === 0).map((item) => item.path),
-        jobMode: choiceValue(answers?.job_mode, "sources"),
+        ordered,
+        unrelated: gated.filter((item) => item.level === 0).map((item) => item.item.path),
         worthDelegating: nounTrue(answers?.worth_delegating, "sources"),
-        // The useful half. A confident yes tells the caller what it already decided by calling
-        // delegate; a confident no is a warning worth having before up to 200 files and 8 MiB are
-        // frozen for a child that cannot answer the question anyway. Both were computed and thrown
-        // away, and output is free, so they were already paid for.
         notWorthDelegating: nounFalse(answers?.worth_delegating, "sources"),
     };
 }

package/extensions/tool-wishlist/core.mjs

@@ -471,6 +471,53 @@ function sanitizeGap(gap) {
     };
 }
 
+// This is a second opinion on the same report, not corroborating evidence. It cannot affect
+// identity, priority, qualification, human selection, or retirement.
+function sanitizeAssessment(value, knownKeys) {
+    if (!value || typeof value !== "object") {
+        return undefined;
+    }
+
+    const result = { source: "jev", basis: "reported-observation" };
+    if (["minor", "degraded", "blocked"].includes(value.impactOpinion)) {
+        result.impactOpinion = value.impactOpinion;
+    }
+
+    if (["tool", "skill", "prompt", "config", "bug", "unknown"].includes(value.suggestedFix)) {
+        result.suggestedFix = value.suggestedFix;
+    }
+
+    if (
+        typeof value.matchedKey === "string" &&
+        /^[a-z0-9][a-z0-9-]{0,119}$/u.test(value.matchedKey) &&
+        (!knownKeys || knownKeys.has(value.matchedKey))
+    ) {
+        result.matchedKey = value.matchedKey;
+    }
+
+    if (value.transient === true) {
+        result.transient = true;
+    }
+
+    return Object.keys(result).length > 2 ? result : undefined;
+}
+
+/** Read only bounded, sanitized local improvement records; never Pi state or private evidence. */
+export function wishlistTriageCandidates(stateDir) {
+    if (readCollectionMode(stateDir) !== "on") {
+        return [];
+    }
+
+    const files = pathsFor(stateDir);
+    const { events } = readEventsFile(files.events);
+    const { decisions } = readDecisionsFile(files.decisions);
+
+    return aggregateEvents(events, { decisions }).map((item) => ({
+        canonicalKey: item.canonicalKey,
+        title: sanitizeReportText(item.title, 80),
+    }));
+}
+
 function sanitizeEvidenceList(value, maxItems, label) {
     if (!isValidEvidenceList(value, maxItems)) {
         throw new Error(`${label} must contain 1 to ${maxItems} strings of at most 240 characters`);
@@ -654,6 +701,10 @@ export function aggregateEvents(events, options = {}) {
                 scenarios: recentUnique("scenario"),
                 limitations: recentUnique("limitation"),
                 workarounds: recentUnique("workaround"),
+                assessment: [...ordered]
+                    .reverse()
+                    .map((event) => sanitizeAssessment(event.assessment))
+                    .find(Boolean),
             };
         })
         .sort(
@@ -884,6 +935,26 @@ function renderGroup(lines, group) {
         lines.push(`- Review needed: yes`, `- Unresolved post-retirement signals: ${group.reviewSignalCount}`);
     }
 
+    if (group.assessment) {
+        const opinion = group.assessment;
+        lines.push("", "**Jev advisory opinion** (based on the reported account, not independent evidence)");
+        if (opinion.impactOpinion) {
+            lines.push(`- Impact opinion: ${opinion.impactOpinion}`);
+        }
+
+        if (opinion.suggestedFix) {
+            lines.push(`- Suggested fix opinion: ${opinion.suggestedFix}`);
+        }
+
+        if (opinion.matchedKey) {
+            lines.push(`- Possible existing cluster: \`${opinion.matchedKey}\` (human merge decision required)`);
+        }
+
+        if (opinion.transient) {
+            lines.push("- May be transient or user error; review the original observation.");
+        }
+    }
+
     if (group.scenarios.length) {
         lines.push("", "**Observed needs**", ...group.scenarios.map((value) => `- ${markdownText(value)}`));
     }
@@ -1338,12 +1409,20 @@ export async function recordCapabilityGap(options) {
         runId,
         cwd,
         gap,
+        assessment,
         signal,
         now = new Date().toISOString(),
         maxEventFileBytes = MAX_EVENT_FILE_BYTES,
+        isCurrent = () => true,
+        assessmentIsCurrent = () => true,
+        onRecorded = () => {},
     } = options;
 
     return withStateLock(stateDir, signal, async () => {
+        if (signal?.aborted || !isCurrent()) {
+            throw new Error("The task changed before the report could be recorded");
+        }
+
         if (readCollectionMode(stateDir) !== "on") {
             throw new Error("Local wishlist collection must be explicitly on before recording observations");
         }
@@ -1371,6 +1450,10 @@ export async function recordCapabilityGap(options) {
                 resolveAlias(event.observedKey ?? event.canonicalKey, aliases) === canonicalKey &&
                 event.runHash === runHash,
         );
+        const advisory = sanitizeAssessment(
+            assessmentIsCurrent() ? assessment : undefined,
+            new Set(canonicalizeEvents(parsed.events, decisionData.decisions).map((event) => event.canonicalKey)),
+        );
         if (!duplicate) {
             const event = {
                 schema: 1,
@@ -1381,6 +1464,7 @@ export async function recordCapabilityGap(options) {
                 runHash,
                 projectHash,
                 ...sanitized,
+                ...(advisory ? { assessment: advisory } : {}),
                 ...(regression ? { regression: true } : {}),
             };
             parsed.bytes = appendBounded(
@@ -1391,6 +1475,7 @@ export async function recordCapabilityGap(options) {
                 "Tool wishlist event log",
             );
             parsed.events.push(event);
+            onRecorded({ assessmentRecorded: advisory !== undefined });
         }
 
         writeReport(
@@ -1407,6 +1492,7 @@ export async function recordCapabilityGap(options) {
 
         return {
             duplicate,
+            assessmentRecorded: !duplicate && advisory !== undefined,
             regression,
             resolved: priorState === "retired",
             canonicalKey,