@mjasnikovs/pi-task 0.40.50 → 0.42.0

package/dist/task/verify-work.d.ts

@@ -1,4 +1,8 @@
+import { type EmittedNote } from './env-notes.js';
 import { type CrossTaskDeletion } from './task-provenance.js';
+import { type HealthBaseline, type HealthSignal } from './health-baseline.js';
+import { type Spec } from './spec-model.js';
+import { type SuppressionHit } from './suppression-probe.js';
 /**
  * The verification child gets exactly two tools: `read` and `bash`.
  *
@@ -14,19 +18,44 @@ import { type CrossTaskDeletion } from './task-provenance.js';
  *    mutated tree. The enforce pass, whose job IS editing, runs `read,edit`.
  */
 declare const VERIFY_TOOLS = "read,bash";
-export interface VerifyOutcome {
-    /** true → the work verified (or verification disabled / nothing to verify).
-     *  false → the child reported the work does NOT satisfy its spec, or the pass
-     *  could not run / produced no verdict. */
-    ok: boolean;
-    /** Short, human-readable reason. Always set when ok === false; on the pass
-     *  path set to the no-op cause ('disabled', 'no spec to verify'). */
+/**
+ * The work verified, or there was nothing to verify.
+ *
+ * The FAIL-only fields are declared `?: undefined` rather than omitted: a pass may
+ * not carry them (`{ok: true, failClass: …}` is still a compile error), but a
+ * caller holding the bare union can still READ them without narrowing first, which
+ * is how every consumer asks "was this unobserved?" in one expression.
+ */
+export interface VerifyPass {
+    ok: true;
+    /** The NO-OP cause ('disabled', 'no spec to verify'). Absent on a genuine
+     *  pass, which is the only signal the enforce pass may edit against. */
     reason?: string;
-    /** True when the FAIL is specifically an UNOBSERVED outcome (rule 5c): a
-     *  spec-required behavioral check could not run because its tooling is absent.
-     *  The gate routes this straight to the human picker instead of an unattended
-     *  AUTOFIX re-run, which cannot provision a missing tool. Only meaningful when
-     *  ok === false. */
+    failClass?: undefined;
+    unobserved?: undefined;
+    crossTaskDeletions?: undefined;
+    inheritedHealth?: string;
+    health?: undefined;
+    probes?: ProbeFindings;
+}
+/**
+ * The work did NOT satisfy its spec, or the pass could not run.
+ *
+ * `failClass` is REQUIRED. Optional, it travelled as the prefix of `reason` and
+ * every downstream classifier recovered it by re-typing that literal, so a reword
+ * of the mint disarmed them with no compile error — and one site (the
+ * mutation-guard FAIL) simply never set it, which left the decision table with no
+ * class to route on. `VERIFY_FAIL_PREFIX` owns the display strings so mint and
+ * match cannot drift.
+ */
+export interface VerifyFail {
+    ok: false;
+    failClass: VerifyFailClass;
+    /** Short, human-readable reason, minted under the class's prefix. */
+    reason: string;
+    /** Rule 5c: a spec-required behavioral check could not run because its tooling
+     *  is absent. Sets the AUTOFIX budget to zero on any class — an unattended
+     *  re-run cannot provision a missing tool. */
     unobserved?: boolean;
     /** The deterministic cross-task deletion findings (see task-provenance.ts) that
      *  were live when this verdict was produced: sibling tasks' committed
@@ -34,17 +63,25 @@ export interface VerifyOutcome {
      *  can record each as a durable debt if the user ACCEPTs anyway — the deletion
      *  then ships in the next commit and the final gate must re-check it. */
     crossTaskDeletions?: CrossTaskDeletion[];
-    /**
-     * WHICH KIND of FAIL this is, as data. Only meaningful when ok === false.
-     *
-     * Without it the class travels only as the PREFIX of `reason`, and every
-     * downstream classifier has to recover it by re-typing that literal — a
-     * reword of the mint would then disarm them with no compile error.
-     * `VERIFY_FAIL_PREFIX` owns the strings so mint and match cannot drift, and
-     * `verifyFailClass` prefers this field over the prefix.
-     */
-    failClass?: VerifyFailClass;
+    inheritedHealth?: string;
+    /** The health result behind a `repo-health` FAIL: which command, and what its
+     *  output named. What an ACCEPT of this FAIL hands to the repair channel. */
+    health?: HealthSignal & {
+        output?: string;
+    };
+    /** What the deterministic probes found for THIS verdict, carried out so an
+     *  AUTOFIX re-run is told what the gate already knows (see fix-context.ts)
+     *  instead of re-deriving it from the one-line reason. */
+    probes?: ProbeFindings;
 }
+/**
+ * `inheritedHealth` is declared on BOTH halves: the repo's own static checks that
+ * were already failing the same way before this task ran (health-baseline.ts).
+ * A task can verify perfectly in a repo that arrived red, so a PASS carries it
+ * too — dropping it on the pass path is where a sibling's defect disappears until
+ * the run-end gate rediscovers it with nobody's name on it.
+ */
+export type VerifyOutcome = VerifyPass | VerifyFail;
 /**
  * The kinds of verify FAIL. `VERIFY_FAIL_PREFIX` below is a
  * `Record<VerifyFailClass, string>`, so a new member here is a compile error
@@ -72,18 +109,18 @@ export declare const VERIFY_FAIL_PREFIX: Record<VerifyFailClass, string>;
  * mints its `static checks:` line through a different path entirely. This is the
  * only place in src/ that tests a reason against a prefix.
  */
-export declare function verifyFailClass(o: Pick<VerifyOutcome, 'failClass' | 'reason'>): VerifyFailClass | undefined;
+export declare function verifyFailClass(o: {
+    failClass?: VerifyFailClass;
+    reason?: string;
+}): VerifyFailClass | undefined;
 /** The class a recorded reason STRING belongs to, by its minted prefix. */
 export declare function failClassOfReason(reason: string): VerifyFailClass | undefined;
 /** Does this class name a deterministic whole-repo static check, at either altitude? */
 export declare function isStaticClass(cls: VerifyFailClass | undefined): boolean;
 /**
- * Slice the delivered spec (GOAL / CONSTRAINTS / ACCEPTANCE / VERIFY) out of a
- * task file body. The compose and critique phases write the section named `spec`,
- * so the composed spec lives under `## spec` and runs to the next line matching
- * `## ` plus non-space (`## phase timings`); a `### ` subheading stays inside.
- * Returns null when there is no spec section or it is blank (a task that never
- * reached compose), which the caller treats as a pass — nothing to verify against.
+ * The delivered spec's TEXT, for the children that must read its prose verbatim.
+ * The slicing itself lives in spec-model.ts beside the parser, so "the spec
+ * section" is one definition rather than one per consumer.
  */
 export declare function extractSpecForVerification(taskBody: string): string | null;
 /**
@@ -115,6 +152,7 @@ export declare function extractSpecForVerification(taskBody: string): string | n
  * 'VerifyProbes'").
  */
 export interface ProbeRaw {
+    evidence: string[];
     substitution: string[];
     prohibition: string[];
     crossTaskDeletion: CrossTaskDeletion[];
@@ -124,15 +162,19 @@ export interface ProbeRaw {
     scriptEscape: string[];
     runnerGlob: string[];
     testAssembly: string[];
+    repoHealth: string[];
+    suppressionWidening: SuppressionHit[];
 }
 /** Stable identity of one probe channel: table row ↔ findings-bag key. */
 export type ProbeKey = keyof ProbeRaw;
 /**
- * The channels a CALLER binds — every key but `skipEscape`, which is pure text
- * analysis of `deps.spec` and is sourced inside its own table row, so it is never
- * absent and never bound from outside.
+ * The channels a CALLER binds. Two keys are not among them: `skipEscape`, which is
+ * pure text analysis of `deps.spec` and is sourced inside its own table row, and
+ * `repoHealth`, whose findings are the classified DELTA of a check
+ * `runWorkVerification` has already run — only that function holds both the
+ * baseline and the result, so only it can source the row.
  */
-export type BoundProbeKey = Exclude<ProbeKey, 'skipEscape'>;
+export type BoundProbeKey = Exclude<ProbeKey, 'skipEscape' | 'repoHealth'>;
 /**
  * The bound probes: one optional thunk per channel, typed to that channel's raw
  * shape. Built in ONE place (gate-deps' `buildVerifyProbes`); an absent key means
@@ -150,6 +192,12 @@ export type ProbeFindings = Partial<Record<ProbeKey, string[]>>;
  * checked against the table rather than against a hand-kept list.
  */
 export declare const BOUND_PROBE_KEYS: readonly BoundProbeKey[];
+/**
+ * The spec as a VALUE, with each constraint's `[from:]` tag resolved against the
+ * task's own Q&A record. Shared by the verify prompt and the resolution judge, so
+ * one constraint cannot carry two weights.
+ */
+export declare function specValue(spec: string, qaRecord?: string): Spec;
 /**
  * Build the verification child's prompt. Kept pure so the wording is unit-tested
  * without spawning pi. The contract: run the spec's own verification in the real
@@ -162,8 +210,14 @@ export declare const BOUND_PROBE_KEYS: readonly BoundProbeKey[];
 export declare function buildVerifyPrompt(spec: string, findings?: ProbeFindings, context?: {
     /** Environment facts earlier gate children discovered — see env-notes.ts. */
     envNotes?: string;
+    /** This run's id: the notes it recorded lead, older runs' follow. */
+    envRunId?: string;
     /** Cross-slice interface facts the design pins — see contracts.ts. */
     contracts?: string;
+    /** The task file's rendered Q&A, which is what resolves a constraint's
+     *  `[from: Q<n>]` tag to the kind of answer that produced it. Absent ⇒
+     *  every tagged constraint reads as `derived`, which is advisory. */
+    qaRecord?: string;
 }): string;
 /**
  * Parse the child's verdict out of the LAST `WORK-VERIFIED: PASS|FAIL|UNOBSERVED`
@@ -206,7 +260,16 @@ export interface VerificationDeps {
     repoHealth?: () => Promise<{
         ok: boolean;
         reason: string;
-    }>;
+        output?: string;
+    } & HealthSignal>;
+    /**
+     * What those same checks said BEFORE this task ran (see health-baseline.ts).
+     * Consulted only when `repoHealth` comes back red, and it is what decides
+     * whose defect that is: a check failing the same way before is `pre-existing`
+     * and becomes a probe row, not a FAIL. ABSENT, or null, → every red check is
+     * this task's, which is the behavior that shipped before the baseline existed.
+     */
+    healthBaseline?: () => Promise<HealthBaseline | null>;
     /**
      * Progress hook for the DETERMINISTIC stage — the repo-health run plus the
      * `probes` below, all of which run BEFORE the child (and therefore before the
@@ -245,7 +308,10 @@ export interface VerificationDeps {
      */
     envNotes?: {
         read: () => Promise<string>;
-        append: (notes: string[]) => Promise<void>;
+        append: (notes: readonly EmittedNote[]) => Promise<void>;
+        /** The run these notes belong to, so the child's prompt can lead with the
+         *  facts measured against the tree it is standing in. */
+        runId?: string;
     };
     /**
      * Per-run cross-slice contract registry (see contracts.ts): `read` supplies the
@@ -255,6 +321,10 @@ export interface VerificationDeps {
      * `/task` runs, or a design pinning no shared boundary).
      */
     contracts?: () => Promise<string>;
+    /** The task file's `## grill Q&A` text, which resolves each constraint's
+     *  provenance tag (see `specValue`). ABSENT ⇒ every tagged constraint is
+     *  advisory, which is the safe reading of a provenance nobody can confirm. */
+    qaRecord?: string;
 }
 /**
  * Run the verification pass for one task. `repoHealth` runs first and can FAIL on