@mjasnikovs/pi-task 0.40.50 → 0.42.0

package/dist/task/task-parsers.js

@@ -13,19 +13,18 @@ const FRONT_MATTER_KEYS = [
     'updated_at',
     'title',
     'label',
+    'plan_key',
     'reason'
 ];
+/** Front-matter keys omitted entirely when empty rather than emitted blank. */
+const OPTIONAL_KEYS = new Set(['label', 'plan_key', 'reason']);
 // ─── Front matter ────────────────────────────────────────────────────────────
 export function emitFrontMatter(fm) {
     const lines = ['---'];
     for (const k of FRONT_MATTER_KEYS) {
         const v = fm[k];
-        if (v === undefined || v === '') {
-            // Optional fields are omitted entirely when empty rather than emitted
-            // as a blank `key:` line.
-            if (k === 'reason' || k === 'label')
-                continue;
-        }
+        if ((v === undefined || v === '') && OPTIONAL_KEYS.has(k))
+            continue;
         lines.push(`${k}: ${typeof v === 'string' ? v : String(v)}`);
     }
     lines.push('---');
@@ -59,6 +58,7 @@ export function parseFrontMatter(content) {
         updated_at: obj.updated_at ?? obj.created_at,
         title: obj.title ?? '',
         label: obj.label || undefined,
+        plan_key: obj.plan_key || undefined,
         reason: obj.reason || undefined
     };
 }

package/dist/task/task-types.d.ts

@@ -21,6 +21,13 @@ export interface TaskFrontMatter {
      * of `title` (`titleForDisplay`, parsers.ts). See title-label.ts.
      */
     label?: string;
+    /**
+     * The /task-auto plan entry this task implements (`TaskEntry.key`). It is
+     * what the owned-requirements ledger joins on, and it lives here rather than
+     * in memory because a resumed run reconstructs the task from this file alone.
+     * Absent on a bare /task and on any task planned before keys existed.
+     */
+    plan_key?: string;
     reason?: string;
 }
 export declare const PHASE_ORDER: PhaseName[];

package/dist/task/timings.d.ts

@@ -18,3 +18,14 @@ export interface TimingEntry {
 }
 export declare function formatMs(ms: number): string;
 export declare function formatTimings(entries: ReadonlyArray<TimingEntry>): string;
+/**
+ * The `## phase timings` body once this attempt's phases are added to it.
+ *
+ * A run re-entered for an autofix resumes at `phase: done` and therefore runs no
+ * phases at all, so rendering only what IT timed wrote an empty block over the
+ * five phases the first attempt measured — the timings vanished for exactly the
+ * tasks that took longest. Each attempt gets its own labelled block instead, and
+ * an unlabelled body written before this grammar is adopted as attempt 1 rather
+ * than discarded.
+ */
+export declare function mergeTimings(prev: string | null, next: ReadonlyArray<TimingEntry>): string;

package/dist/task/timings.js

@@ -36,3 +36,24 @@ export function formatTimings(entries) {
     lines.push(`${'total'.padEnd(TOP_LABEL_WIDTH)}${formatMs(total).padStart(MS_COLUMN_WIDTH)}`);
     return lines.join('\n');
 }
+/** Heading of one attempt's block inside the `## phase timings` section. */
+const ATTEMPT_HEADING_RE = /^attempt (\d+)$/gm;
+/**
+ * The `## phase timings` body once this attempt's phases are added to it.
+ *
+ * A run re-entered for an autofix resumes at `phase: done` and therefore runs no
+ * phases at all, so rendering only what IT timed wrote an empty block over the
+ * five phases the first attempt measured — the timings vanished for exactly the
+ * tasks that took longest. Each attempt gets its own labelled block instead, and
+ * an unlabelled body written before this grammar is adopted as attempt 1 rather
+ * than discarded.
+ */
+export function mergeTimings(prev, next) {
+    const before = (prev ?? '').trim();
+    if (before.length === 0)
+        return `attempt 1\n\n${formatTimings(next)}`;
+    const seen = [...before.matchAll(ATTEMPT_HEADING_RE)];
+    const body = seen.length === 0 ? `attempt 1\n\n${before}` : before;
+    const last = seen.length === 0 ? 1 : parseInt(seen[seen.length - 1][1], 10);
+    return `${body}\n\nattempt ${last + 1}\n\n${formatTimings(next)}`;
+}

package/dist/task/tree-hash.d.ts

@@ -0,0 +1,8 @@
+import type { GitRunner } from '../shared/git-runner.js';
+/**
+ * Snapshot the worktree content into a tree object. Returns null when git cannot
+ * build the tree (an unborn HEAD, a non-repo cwd, a missing binary).
+ */
+export declare function worktreeTreeHash(git: GitRunner): Promise<string | null>;
+/** The tree object a commit-ish points at — the committed twin of the above. */
+export declare function commitTreeHash(git: GitRunner, revision: string): Promise<string | null>;

package/dist/task/tree-hash.js

@@ -0,0 +1,55 @@
+/**
+ * tree-hash — the content identity of the working tree, computed without touching
+ * the real index or the working tree.
+ *
+ * `git add -A` against a THROWAWAY `GIT_INDEX_FILE` is the whole technique: the
+ * staged state a user (or a half-finished gate) left in the real index survives,
+ * nothing is stashed, and no file moves. Every consumer that asks "is this the
+ * same tree as before?" — the git-state guard's reconcile, the health baseline,
+ * and the evidence cache when it lands — must ask it the same way, or two answers
+ * disagree about the same tree.
+ *
+ * `.pi-tasks` is excluded because the gate machinery writes its own trail there
+ * DURING the work being hashed; including it would make every hash differ from
+ * every other one for reasons that have nothing to do with the code.
+ *
+ * Null means "git could not tell us", never "empty tree": a caller that treats an
+ * unreadable tree as a match would call two different trees identical.
+ */
+import * as fsp from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+/** Keep the gate machinery's own artifacts out of the hash. */
+const EXCLUDE_TASKS_DIR = ':(exclude).pi-tasks';
+function throwawayIndexPath() {
+    return path.join(os.tmpdir(), `pi-task-index-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+}
+/**
+ * Snapshot the worktree content into a tree object. Returns null when git cannot
+ * build the tree (an unborn HEAD, a non-repo cwd, a missing binary).
+ */
+export async function worktreeTreeHash(git) {
+    const tmpIndex = throwawayIndexPath();
+    const env = { GIT_INDEX_FILE: tmpIndex };
+    try {
+        const empty = await git(['read-tree', '--empty'], env);
+        if (empty.exitCode !== 0)
+            return null;
+        const add = await git(['add', '-A', '--', '.', EXCLUDE_TASKS_DIR], env);
+        if (add.exitCode !== 0)
+            return null;
+        const tree = await git(['write-tree'], env);
+        return tree.exitCode === 0 ? tree.stdout.trim() : null;
+    }
+    finally {
+        await fsp.rm(tmpIndex, { force: true }).catch(() => { });
+    }
+}
+/** The tree object a commit-ish points at — the committed twin of the above. */
+export async function commitTreeHash(git, revision) {
+    const r = await git(['rev-parse', `${revision}^{tree}`]);
+    if (r.exitCode !== 0)
+        return null;
+    const sha = r.stdout.trim();
+    return sha.length > 0 ? sha : null;
+}

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

@@ -35,7 +35,8 @@ export declare function findAbsenceConflicts(spec: string, ctx: AbsenceConflictC
  *  each conflict, why it is one, and the reconciliation to apply. */
 export declare function absenceProbeText(conflicts: AbsenceConflict[]): string;
 /** Parse SIBLING titles out of `buildScopeFence`'s listing, whose rows read
- *  `[N] head` and `[N] (THIS STEP) head`. The "(THIS STEP)" row is dropped — a
- *  task may legitimately assert about its own deliverables. '' and undefined
- *  (a bare /task with no plan) yield none. */
+ *  `[N] [done|this|later] head`. The `[this]` row is dropped — a task may
+ *  legitimately assert about its own deliverables; a `[done]` sibling is kept,
+ *  since its deliverable is in the tree and asserting its ABSENCE is the very
+ *  defect this feeds. '' and undefined (a bare /task with no plan) yield none. */
 export declare function siblingTitlesFromPlanContext(planContext: string | undefined): string[];

package/dist/task/verify-reconcile.js

@@ -184,20 +184,19 @@ export function absenceProbeText(conflicts) {
     ].join('\n');
 }
 /** Parse SIBLING titles out of `buildScopeFence`'s listing, whose rows read
- *  `[N] head` and `[N] (THIS STEP) head`. The "(THIS STEP)" row is dropped — a
- *  task may legitimately assert about its own deliverables. '' and undefined
- *  (a bare /task with no plan) yield none. */
+ *  `[N] [done|this|later] head`. The `[this]` row is dropped — a task may
+ *  legitimately assert about its own deliverables; a `[done]` sibling is kept,
+ *  since its deliverable is in the tree and asserting its ABSENCE is the very
+ *  defect this feeds. '' and undefined (a bare /task with no plan) yield none. */
 export function siblingTitlesFromPlanContext(planContext) {
     if (!planContext)
         return [];
     const out = [];
     for (const line of planContext.split('\n')) {
-        const m = /^\[\d+\](.*)$/.exec(line.trim());
-        if (!m)
+        const m = /^\[\d+\] \[(done|this|later)\] (.*)$/.exec(line.trim());
+        if (!m || m[1] === 'this')
             continue;
-        if (m[1].startsWith(' (THIS STEP)'))
-            continue;
-        const title = m[1].trim();
+        const title = m[2].trim();
         if (title.length > 0)
             out.push(title);
     }

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

@@ -1,30 +1,50 @@
+import type { SpecContradiction } from './gate-resolution.js';
 /** The observe-only contract handed to the child. The same string as
  *  verify-work's VERIFY_TOOLS, so both passes are told the same thing. */
 declare const RESOLUTION_TOOLS = "read,bash";
 /** Which card the picker tints RECOMMENDED. */
 export type ResolutionRecommendation = 'autofix' | 'accept';
+/**
+ * The marker a judge emits INSTEAD of a recommendation when it finds the two
+ * gates contradict each other: the acceptance criterion can only be met by
+ * editing a path the same spec freezes.
+ *
+ * It exists because the judge was previously offered AUTOFIX or ACCEPT and
+ * nothing else, so a contradiction it had already diagnosed came back as
+ * "AUTOFIX" and the loop spent its whole budget re-deriving it (0053).
+ */
+export declare const BLOCKED_BY_FROZEN = "BLOCKED-BY-FROZEN";
 export interface ResolutionOutcome {
     /** The card to recommend. Defaults to 'autofix' (conservative: re-do, don't
      *  bless) when the research could not run or emitted no verdict. */
     recommend: ResolutionRecommendation;
     /** Short, human-readable rationale shown under the picker. Always set. */
     rationale: string;
+    /** Set only by the BLOCKED-BY-FROZEN marker: the criterion the spec's own
+     *  freeze makes unreachable. Outranks `recommend` in the gate's decision
+     *  table — no re-run and no picker answer can resolve a contradiction. */
+    contradiction?: SpecContradiction;
 }
 /**
  * Build the resolution research child's prompt. Pure, so the wording is
  * unit-tested without spawning pi. The contract it states: investigate the real
  * workspace and end on exactly one `VERIFY-RESOLUTION:` line.
  */
-export declare function buildResolutionPrompt(spec: string, failReason: string): string;
+export declare function buildResolutionPrompt(spec: string, failReason: string, qaRecord?: string): string;
 /**
- * Parse the child's recommendation out of the LAST
- * `VERIFY-RESOLUTION: AUTOFIX|ACCEPT` marker, case-insensitively. Last match
- * wins: the model reasons before concluding, and a bash command it runs can
- * print the token back, so an earlier occurrence is not the verdict.
+ * Parse the child's verdict out of the LAST `VERIFY-RESOLUTION:` marker,
+ * case-insensitively. Last match wins: the model reasons before concluding, and a
+ * bash command it runs can print the token back, so an earlier occurrence is not
+ * the verdict.
  *
  * No marker → AUTOFIX (re-do rather than bless), with a rationale saying the
  * research was inconclusive. A marker with no trailing sentence gets a stock
  * rationale, so `rationale` is never empty.
+ *
+ * A BLOCKED-BY-FROZEN marker yields a CONTRADICTION plus an `accept`
+ * recommendation, which is what the gate does with it once the contradiction is
+ * recorded as debt. A marker that names no path is not a usable contradiction and
+ * degrades to that recommendation alone.
  */
 export declare function parseResolutionVerdict(text: string): ResolutionOutcome;
 export declare const ACCEPT_VALUE = "accept";
@@ -44,7 +64,10 @@ export interface ResolutionChoice {
  * `recommended: i === 0`). Values are the bare tokens; remote buttons carry the
  * labels — {@link classifyResolutionAnswer} accepts both.
  */
-export declare function resolutionOptions(recommend: ResolutionRecommendation): {
+export declare function resolutionOptions(recommend: ResolutionRecommendation, 
+/** What ACCEPT queues besides keeping the artifact — the repair a red health
+ *  check earns — so the picker shows the whole consequence of the choice. */
+acceptQueues?: string): {
     label: string;
     value: string;
     recommended: boolean;
@@ -62,6 +85,9 @@ export interface ResolutionDeps {
     signal?: AbortSignal;
     /** The composed spec the task was verified against. */
     spec: string;
+    /** The task's rendered Q&A, which resolves each constraint's provenance tag —
+     *  the same input the verify child got, so both weigh the spec alike. */
+    qaRecord?: string;
     /** The verify gate's FAIL reason (VerifyOutcome.reason). */
     failReason: string;
     /** Runs the research child and returns its assistant text. Injected so the

package/dist/task/verify-resolution.js

@@ -14,10 +14,9 @@
  * INVESTIGATE the real workspace: a genuine defect in the work (→ AUTOFIX), or
  * an artifact the gate misjudged (→ ACCEPT).
  *
- * The recommendation also decides whether a human is asked at all. In
- * task-gates.ts an AUTOFIX recommendation is applied UNATTENDED, bounded by
- * MAX_AUTO_AUTOFIX; the picker is reached on an ACCEPT recommendation, once that
- * bound is spent, or when the FAIL is UNOBSERVED or frozen-blocked.
+ * The recommendation is one input to gate-resolution.ts's decision table, which
+ * alone decides whether a human is asked. This module never overrides itself: an
+ * ACCEPT reached here stands.
  *
  * Tools: `read` + `bash`, the same string as verify-work's VERIFY_TOOLS. That is
  * a CONTRACT, not a capability — `bash` can write. gate-child.ts marks the
@@ -28,15 +27,28 @@
  * rather than blessing it.
  */
 import { USER_CANCELLED } from './child-runner.js';
+import { annotateConstraints, renderConstraintPolicy } from './constraint-policy.js';
+import { specValue } from './verify-work.js';
 /** The observe-only contract handed to the child. The same string as
  *  verify-work's VERIFY_TOOLS, so both passes are told the same thing. */
 const RESOLUTION_TOOLS = 'read,bash';
+/**
+ * The marker a judge emits INSTEAD of a recommendation when it finds the two
+ * gates contradict each other: the acceptance criterion can only be met by
+ * editing a path the same spec freezes.
+ *
+ * It exists because the judge was previously offered AUTOFIX or ACCEPT and
+ * nothing else, so a contradiction it had already diagnosed came back as
+ * "AUTOFIX" and the loop spent its whole budget re-deriving it (0053).
+ */
+export const BLOCKED_BY_FROZEN = 'BLOCKED-BY-FROZEN';
 /**
  * Build the resolution research child's prompt. Pure, so the wording is
  * unit-tested without spawning pi. The contract it states: investigate the real
  * workspace and end on exactly one `VERIFY-RESOLUTION:` line.
  */
-export function buildResolutionPrompt(spec, failReason) {
+export function buildResolutionPrompt(spec, failReason, qaRecord) {
+    const weights = annotateConstraints(specValue(spec, qaRecord).constraints);
     return [
         "A strict verification gate just FAILED an AI coding agent's task and the",
         'run paused. You are the reviewer who decides what to recommend next. The',
@@ -49,6 +61,13 @@ export function buildResolutionPrompt(spec, failReason) {
         'THE TASK SPEC (its ACCEPTANCE criteria and VERIFY block were the contract):',
         spec.trim(),
         '',
+        ...(weights === null ?
+            []
+            : [
+                "THE SPEC'S CONSTRAINTS, BY WEIGHT (rule 5 below says what each weight is worth):",
+                weights,
+                ''
+            ]),
         "THE GATE'S FAILURE REASON:",
         failReason.trim(),
         '',
@@ -86,25 +105,46 @@ export function buildResolutionPrompt(spec, failReason) {
         '   when you run it — that is AUTOFIX. When you cannot positively confirm the',
         '   artifact works, recommend AUTOFIX: re-doing the work is the safe default;',
         '   blessing broken work is the failure mode this whole gate exists to stop.',
+        '4. If the ONLY edit that could satisfy the failing criterion is to a file the',
+        "   spec's CONSTRAINTS forbid this task from modifying, neither verdict above",
+        '   is true: a re-run happens under the same freeze and cannot converge. Report',
+        '   the contradiction instead, naming the frozen path and the criterion.',
+        // The SAME policy the verify child was held to (constraint-policy.ts). Two
+        // children reading one spec must not weigh its constraints differently —
+        // that disagreement is what made a grill-invented constraint unwaivable.
+        ...renderConstraintPolicy('5.'),
         '',
         'When done, output EXACTLY ONE of these as the final line:',
         '  VERIFY-RESOLUTION: AUTOFIX <one sentence why the work must be re-done>',
         '  VERIFY-RESOLUTION: ACCEPT <one sentence why the artifact is good as-is>',
+        `  VERIFY-RESOLUTION: ${BLOCKED_BY_FROZEN} <frozen path> — <the criterion it blocks>`,
         'Output the verdict line verbatim — it is parsed mechanically.'
     ].join('\n');
 }
 /**
- * Parse the child's recommendation out of the LAST
- * `VERIFY-RESOLUTION: AUTOFIX|ACCEPT` marker, case-insensitively. Last match
- * wins: the model reasons before concluding, and a bash command it runs can
- * print the token back, so an earlier occurrence is not the verdict.
+ * The path/criterion separator the marker's contract states. An em dash is what
+ * the prompt shows; a model that retypes it as an en dash or a spaced hyphen
+ * means the same thing, and losing a contradiction over a dash costs the whole
+ * autofix budget.
+ */
+const CONTRADICTION_SEP = /\s+[—–]\s+|\s+-{1,2}\s+/;
+/**
+ * Parse the child's verdict out of the LAST `VERIFY-RESOLUTION:` marker,
+ * case-insensitively. Last match wins: the model reasons before concluding, and a
+ * bash command it runs can print the token back, so an earlier occurrence is not
+ * the verdict.
  *
  * No marker → AUTOFIX (re-do rather than bless), with a rationale saying the
  * research was inconclusive. A marker with no trailing sentence gets a stock
  * rationale, so `rationale` is never empty.
+ *
+ * A BLOCKED-BY-FROZEN marker yields a CONTRADICTION plus an `accept`
+ * recommendation, which is what the gate does with it once the contradiction is
+ * recorded as debt. A marker that names no path is not a usable contradiction and
+ * degrades to that recommendation alone.
  */
 export function parseResolutionVerdict(text) {
-    const re = /VERIFY-RESOLUTION:\s*(AUTOFIX|ACCEPT)\b[ \t]*(.*)/gi;
+    const re = new RegExp(`VERIFY-RESOLUTION:\\s*(AUTOFIX|ACCEPT|${BLOCKED_BY_FROZEN})\\b[ \\t]*(.*)`, 'gi');
     let last = null;
     for (let m = re.exec(text); m !== null; m = re.exec(text))
         last = m;
@@ -114,11 +154,28 @@ export function parseResolutionVerdict(text) {
             rationale: 'research inconclusive — defaulting to re-doing the work'
         };
     }
-    const recommend = last[1].toUpperCase() === 'ACCEPT' ? 'accept' : 'autofix';
-    const rationale = last[2].trim()
+    const verdict = last[1].toUpperCase();
+    const tail = last[2].trim();
+    if (verdict === BLOCKED_BY_FROZEN)
+        return blockedVerdict(tail);
+    const recommend = verdict === 'ACCEPT' ? 'accept' : 'autofix';
+    const rationale = tail
         || (recommend === 'accept' ? 'artifact judged acceptable' : 'work judged to need fixing');
     return { recommend, rationale };
 }
+function blockedVerdict(tail) {
+    const sep = CONTRADICTION_SEP.exec(tail);
+    const frozenPath = (sep ? tail.slice(0, sep.index) : (tail.split(/\s+/)[0] ?? '')).trim();
+    const criterion = sep ? tail.slice(sep.index + sep[0].length).trim() : '';
+    const rationale = frozenPath.length > 0 ?
+        `blocked by spec-frozen \`${frozenPath}\`${criterion ? `: ${criterion}` : ''}`
+        : 'judged blocked by a spec-frozen path, but the marker named none';
+    return {
+        recommend: 'accept',
+        rationale,
+        ...(frozenPath.length > 0 ? { contradiction: { criterion, frozenPath } } : {})
+    };
+}
 // ─── Picker plumbing ─────────────────────────────────────────────────────────
 //
 // These pure helpers shape the boxed two-choice picker (task-gates.ts
@@ -136,8 +193,14 @@ export const AUTOFIX_LABEL = 'Autofix — re-run the task to fix it, then verify
  * `recommended: i === 0`). Values are the bare tokens; remote buttons carry the
  * labels — {@link classifyResolutionAnswer} accepts both.
  */
-export function resolutionOptions(recommend) {
-    const accept = { label: ACCEPT_LABEL, value: ACCEPT_VALUE };
+export function resolutionOptions(recommend, 
+/** What ACCEPT queues besides keeping the artifact — the repair a red health
+ *  check earns — so the picker shows the whole consequence of the choice. */
+acceptQueues) {
+    const accept = {
+        label: acceptQueues ? `${ACCEPT_LABEL}; queues ${acceptQueues}` : ACCEPT_LABEL,
+        value: ACCEPT_VALUE
+    };
     const autofix = { label: AUTOFIX_LABEL, value: AUTOFIX_VALUE };
     return recommend === 'accept' ?
         [
@@ -179,7 +242,7 @@ export function classifyResolutionAnswer(answer) {
 export async function researchResolution(deps) {
     let text;
     try {
-        text = await deps.runChild(RESOLUTION_TOOLS, buildResolutionPrompt(deps.spec, deps.failReason), deps.signal);
+        text = await deps.runChild(RESOLUTION_TOOLS, buildResolutionPrompt(deps.spec, deps.failReason, deps.qaRecord), deps.signal);
     }
     catch (err) {
         if (err instanceof Error && err.message === USER_CANCELLED)