@mjasnikovs/pi-task 0.40.50 → 0.42.0

package/dist/task/decompose-fidelity.js

@@ -12,10 +12,11 @@
  * Mechanism (contracts.ts pattern, applied to decompose itself): the decompose
  * prompt asks each task line to cite its origin as a trailing
  * `[source: "<verbatim spec line>"]`. The host then:
- *   1. GROUNDS the quote — a citation that is not a (whitespace/case-normalised)
- *      substring of the source doc is fabricated and is stripped, never trusted;
+ *   1. GROUNDS the quote in a BLOCK of the parsed spec doc — a citation that is
+ *      not a (whitespace/case-normalised) substring is fabricated and is
+ *      stripped, never trusted — and remembers which block it landed in;
  *   2. deterministically detects DROPPED ADDITIVE FRAGMENTS: the `+`-joined
- *      trailing constraints of the cited line ("… + tests") whose words are
+ *      trailing constraints of the cited block ("… + tests") whose words are
  *      absent from the title;
  *   3. RE-ATTACHES the missing fragments to the title verbatim.
  *
@@ -30,41 +31,9 @@
  * presence is exact word membership (with a singular/plural `s` allowance).
  */
 import { normalise } from './contracts.js';
+import { demark, groundIn, parseSpecDoc, specPlain } from './spec-doc.js';
 /** One trailing `[source: "…"]` clause, anchored so it is the WHOLE remainder. */
 const SOURCE_RE = /^\[source:\s*"([\s\S]*)"\s*\]$/i;
-/**
- * Markdown MARKUP dropped before grounding — emphasis runs, list and heading
- * markers, table pipes and CODE BACKTICKS. Not content: no word, number or
- * punctuation inside a sentence is touched, so this cannot make an invented
- * quote match.
- *
- * WHY. A model copies a spec line as it READS, and what it reads is rendered:
- * `2. **Auth** — sessions, login/logout/me, guards + tests.` comes back as
- * `Auth — sessions, login/logout/me, guards + tests.` That is a verbatim copy of
- * the line's TEXT, and the exact-substring test called it fabricated and threw
- * it away — including, as here, the "+ tests" line that is this module's own
- * worked example.
- *
- * BACKTICKS ARE THE SAME CLASS and were the larger half. A code span renders as
- * bare text, so `3. **Invites** — create/validate/redeem, \`/join/:token\` page.`
- * comes back as `Invites — create/validate/redeem, /join/:token page.` Screening
- * every spec line in its RENDERED form is what makes those quotes match at all.
- *
- * The two directions this has to hold in, both run:
- *   FLOOR   a real spec line with ONE content word altered must NOT be grounded —
- *           changing `sessions` to `tokens`, or `redeem` to `revoke`, drops it.
- *   CEILING a real spec line quoted without its markup MUST be grounded — both the
- *           `2. **Auth** —` numbering-and-bold case and the backticked
- *           `` `/join/:token` `` case still match.
- */
-function demark(s) {
-    return s
-        .replace(/\*\*|__/g, '')
-        .replace(/^\s*(?:[-*+]|\d+\.)\s+/gm, '')
-        .replace(/^#+\s*/gm, '')
-        .replace(/`/g, '')
-        .replace(/\|/g, ' ');
-}
 /**
  * Undo the backslash-escaping a model applies to a quote it is putting INSIDE a
  * double-quoted clause. `[source: "… \`import { sql } from \\"bun\\"\` gotcha …"]`
@@ -99,7 +68,8 @@ function unescapeQuotes(s) {
  * — exactly like keepGroundedContracts rejects a paraphrased quote.
  */
 export function extractTitleSource(title, sourceDoc) {
-    const ref = normalise(demark(sourceDoc));
+    const doc = typeof sourceDoc === 'string' ? parseSpecDoc(sourceDoc) : sourceDoc;
+    const flat = normalise(specPlain(doc));
     let base = title.trim();
     const sources = [];
     for (;;) {
@@ -111,8 +81,16 @@ export function extractTitleSource(title, sourceDoc) {
             break;
         const quote = m[1].trim();
         base = base.slice(0, at).trim();
-        if (quote.length > 0 && ref.includes(normalise(demark(unescapeQuotes(quote)))))
-            sources.unshift(quote);
+        if (quote.length === 0)
+            continue;
+        const unescaped = unescapeQuotes(quote);
+        const block = groundIn(doc, unescaped);
+        if (block !== null)
+            sources.unshift({ quote, block });
+        // A citation that spans two blocks is still a faithful copy of the doc, so
+        // it stays grounded; it just has no single block to restore fragments from.
+        else if (flat.includes(normalise(demark(unescaped))))
+            sources.unshift({ quote, block: null });
     }
     return { base, sources };
 }
@@ -132,7 +110,57 @@ function fragmentPresent(fragment, titleWords) {
     });
 }
 /**
- * The `+`-joined trailing constraint fragments of `sourceLine` whose words are
+ * An additive suffix is a PROSE construct. Inside a table row a `+` joins one
+ * cell's own words while the row's other cells are unrelated columns; inside a
+ * code fence it is code. Live, those two shapes restored `password) | public |`
+ * (a router table's path, guard and its pipes) and `check` (the tail of a DDL
+ * `check (…)` constraint) into task titles as spec obligations.
+ */
+const RESTORABLE_KINDS = new Set(['para', 'list-item']);
+const BRACKET_PAIRS = [
+    ['(', ')'],
+    ['[', ']'],
+    ['{', '}']
+];
+function occurrences(s, ch) {
+    let n = 0;
+    for (const c of s)
+        if (c === ch)
+            n++;
+    return n;
+}
+/** A fragment cut mid-expression: the cut is the defect, not the content. */
+function isBalanced(s) {
+    return BRACKET_PAIRS.every(([open, close]) => occurrences(s, open) === occurrences(s, close));
+}
+/**
+ * Split on the separators that sit at bracket depth ZERO. A `+` or a comma inside
+ * a parenthetical belongs to the parenthetical — splitting there is what cut
+ * `(unused + not expired)` into a fragment with a dangling `)`.
+ *
+ * A stray closer floors the depth at zero rather than driving it negative, so a
+ * line whose brackets are already unbalanced still splits on its later separators.
+ */
+function splitAtDepth(s, separators) {
+    const out = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (BRACKET_PAIRS.some(([open]) => open === c))
+            depth++;
+        else if (BRACKET_PAIRS.some(([, close]) => close === c))
+            depth = Math.max(0, depth - 1);
+        else if (depth === 0 && separators.includes(c)) {
+            out.push(s.slice(start, i));
+            start = i + 1;
+        }
+    }
+    out.push(s.slice(start));
+    return out;
+}
+/**
+ * The `+`-joined trailing constraint fragments of a spec block whose words are
  * absent from `title`. "2. **Auth** — sessions, login/logout/me, guards + tests."
  * yields the fragment "tests"; a title that never mentions tests gets it back.
  * Fragments before the first `+` are the task's body — a title paraphrases those
@@ -140,31 +168,40 @@ function fragmentPresent(fragment, titleWords) {
  * ("+ Tailwind v4 tokens, nav, router" is three constraints), so a title missing
  * one of them gets ONLY that one restored, not the whole phrase (measured live:
  * whole-phrase restoration re-attached text the title already carried).
+ *
+ * A bare string is read as prose — the shape a caller that has no document has.
  */
-export function findDroppedPlusFragments(sourceLine, title) {
-    const parts = sourceLine.split('+');
+export function findDroppedPlusFragments(source, title) {
+    const block = typeof source === 'string' ?
+        { kind: 'para', text: source, plain: demark(source), line: 0 }
+        : source;
+    if (!RESTORABLE_KINDS.has(block.kind))
+        return [];
+    const parts = splitAtDepth(block.plain, '+');
     if (parts.length < 2)
         return [];
     const titleWords = new Set(words(title));
     const missing = [];
     for (const raw of parts.slice(1)) {
-        for (const sub of raw.split(',')) {
-            // A fragment runs to the next `+`/comma; strip trailing sentence
-            // punctuation and markdown emphasis so "tests.**" compares as "tests".
-            const fragment = sub
-                .replace(/[*_`]/g, '')
-                .replace(/[.,;:!?)\]]+\s*$/, '')
-                .trim();
-            if (fragment.length === 0)
-                continue;
+        for (const sub of splitAtDepth(raw, ',')) {
+            // Trailing sentence punctuation is the line's, not the fragment's;
+            // brackets are left alone because they are what the balance test reads.
+            const fragment = sub.replace(/[.,;:!?]+\s*$/, '').trim();
             if (words(fragment).length === 0)
                 continue;
+            if (!isBalanced(fragment))
+                continue;
             if (!fragmentPresent(fragment, titleWords))
                 missing.push(fragment);
         }
     }
     return missing;
 }
+/** Restored fragments as a DELIMITED list. A bare `join(', ')` is ambiguous the
+ *  moment a fragment contains a comma of its own — and they routinely do. */
+export function renderFragments(fragments) {
+    return fragments.map(f => `"${f}"`).join('; ');
+}
 /**
  * Reconcile decompose output against the source doc: ground each citation, strip
  * the clause (its job ends here), and re-attach any dropped `+`-fragments to the
@@ -173,11 +210,12 @@ export function findDroppedPlusFragments(sourceLine, title) {
  * model that never cites degrades to exactly the old behavior.
  */
 export function reconcileTitleSources(titles, sourceDoc) {
+    const doc = parseSpecDoc(sourceDoc);
     const out = [];
     const restored = [];
     let sourced = 0;
     for (let i = 0; i < titles.length; i++) {
-        const { base, sources } = extractTitleSource(titles[i], sourceDoc);
+        const { base, sources } = extractTitleSource(titles[i], doc);
         if (sources.length === 0) {
             out.push(base);
             continue;
@@ -190,7 +228,9 @@ export function reconcileTitleSources(titles, sourceDoc) {
         const seen = new Set();
         const missing = [];
         for (const src of sources) {
-            for (const f of findDroppedPlusFragments(src, base)) {
+            if (src.block === null)
+                continue;
+            for (const f of findDroppedPlusFragments(src.block, base)) {
                 const k = f.toLowerCase();
                 if (seen.has(k))
                     continue;
@@ -202,8 +242,8 @@ export function reconcileTitleSources(titles, sourceDoc) {
             out.push(base);
             continue;
         }
-        restored.push({ index: i, fragments: missing, sources });
-        out.push(`${base} — MUST also cover (restored from its spec line): ${missing.join(', ')}`);
+        restored.push({ index: i, fragments: missing, sources: sources.map(s => s.quote) });
+        out.push(`${base} — MUST also cover (restored from its spec line): ${renderFragments(missing)}`);
     }
     return { titles: out, restored, sourced };
 }

package/dist/task/decompose-granularity.d.ts

@@ -70,6 +70,8 @@ export declare function isTooCoarse(titles: number, floor: number): boolean;
 export declare const MIN_REQUIREMENTS_FOR_PLAN_SHAPE = 5;
 /** Does this feature have enough distinct deliverables for granularity to matter? */
 export declare function planShapeIsHostsToAnswer(ownable: number): boolean;
+/** The clarify dialog's name for this fork — see `QuestionSource.settle`. */
+export declare const PLAN_SHAPE_TOPIC = "plan-shape";
 /**
  * Does this clarify question decide how finely the feature is CUT into tasks?
  *
@@ -78,13 +80,11 @@ export declare function planShapeIsHostsToAnswer(ownable: number): boolean;
  * over-eager classifier would replace a real user decision with the host's.
  * Matched against the plain-text question.
  *
- * BOTH halves must hold — a breakdown phrase AND a plan-unit noun — and the unit
- * list is SINGULAR except for tasks. Measured across the units it names:
- *   milestone / section / step / phase / task / tasks   fire
- *   milestones / sections / steps / phases              do NOT
- * So "one task per milestone, or split smaller?" fires, while the same fork
- * phrased "follow the milestones as-is, or split more granularly?" does not —
- * the breakdown half matches, the plural unit does not.
+ * BOTH halves must hold — a breakdown phrase AND a plan-unit noun, singular or
+ * plural. The plural used to be excluded, which left "follow the milestones
+ * as-is, or split more granularly?" unmatched: the same fork, redrawn in the
+ * plural, went to the user (or the triage) after the host had already settled it.
+ * Number is not a signal about what the question decides.
  */
 export declare function isPlanShapeQuestion(question: string): boolean;
 /**

package/dist/task/decompose-granularity.js

@@ -78,6 +78,8 @@ export const MIN_REQUIREMENTS_FOR_PLAN_SHAPE = 5;
 export function planShapeIsHostsToAnswer(ownable) {
     return ownable >= MIN_REQUIREMENTS_FOR_PLAN_SHAPE;
 }
+/** The clarify dialog's name for this fork — see `QuestionSource.settle`. */
+export const PLAN_SHAPE_TOPIC = 'plan-shape';
 /**
  * Does this clarify question decide how finely the feature is CUT into tasks?
  *
@@ -86,13 +88,11 @@ export function planShapeIsHostsToAnswer(ownable) {
  * over-eager classifier would replace a real user decision with the host's.
  * Matched against the plain-text question.
  *
- * BOTH halves must hold — a breakdown phrase AND a plan-unit noun — and the unit
- * list is SINGULAR except for tasks. Measured across the units it names:
- *   milestone / section / step / phase / task / tasks   fire
- *   milestones / sections / steps / phases              do NOT
- * So "one task per milestone, or split smaller?" fires, while the same fork
- * phrased "follow the milestones as-is, or split more granularly?" does not —
- * the breakdown half matches, the plural unit does not.
+ * BOTH halves must hold — a breakdown phrase AND a plan-unit noun, singular or
+ * plural. The plural used to be excluded, which left "follow the milestones
+ * as-is, or split more granularly?" unmatched: the same fork, redrawn in the
+ * plural, went to the user (or the triage) after the host had already settled it.
+ * Number is not a signal about what the question decides.
  */
 export function isPlanShapeQuestion(question) {
     const q = question.toLowerCase();
@@ -101,7 +101,7 @@ export function isPlanShapeQuestion(question) {
     if (!aboutBreakdown)
         return false;
     // …and offer a coarse/fine choice over the plan's own units.
-    return /\b(milestone|section|step|phase|task|tasks)\b/.test(q);
+    return /\b(milestones?|sections?|steps?|phases?|tasks?)\b/.test(q);
 }
 /**
  * BELT — the host's own answer to that fork, recorded in the clarify transcript in

package/dist/task/env-notes.d.ts

@@ -1,48 +1,94 @@
-/** One recorded fact plus the origin task that established it (may be ''). */
+/**
+ * One recorded fact, the origin task that established it, the run it belongs to,
+ * and the SUBJECT it is about.
+ *
+ * The subject is the ledger key, and that is the whole point: twenty children
+ * re-measuring one database's reachability wrote twenty slots of one fact, and the
+ * oldest, least true of them was as loud as the newest. Under a subject key the
+ * latest measurement REPLACES its predecessor, which is also the only retraction
+ * mechanism a fact cache has.
+ */
 export interface EnvNote {
     fact: string;
     origin: string;
+    /** The run that recorded it; '' for a file written before runs were stamped. */
+    runId: string;
+    subject: string;
+    /** The task that retracted this claim. A resolved note stays as an audit line
+     *  and is never carried into another child's prompt. */
+    resolvedBy?: string;
 }
-/**
- * Parse the stored file into fact+origin records. A line with no separator parses
- * with an empty origin rather than being dropped, so a cache written before
- * provenance existed still reads — and `buildEnvNotesBlock` renders those as
- * "origin unrecorded" instead of silently claiming an author.
- */
+/** Stored line: `fact TAB origin TAB runId TAB subject TAB resolvedBy`, where every
+ *  field after the fact may be absent — a one- or two-field line is what earlier
+ *  versions wrote, and it still reads. */
 export declare function parseEnvNotes(raw: string): EnvNote[];
 export declare function envNotesFile(cwd: string): string;
 /** The raw stored file ('' when none were recorded yet). Parse with parseEnvNotes. */
 export declare function readEnvNotes(cwd: string): Promise<string>;
 /**
- * Pull `ENV-NOTE: <fact>` lines out of a child's answer text: trimmed,
- * deduplicated case-insensitively, and dropped when empty or over
- * MAX_NOTE_LENGTH. Run: a `VERDICT:` line and even a near-miss `ENV-NOTES:` line
+ * The subject of a fact the child did not name one for.
+ *
+ * A fact identifies what it is ABOUT by naming it first, and three rungs cover
+ * what an environment fact names: the SERVICE it reached (a URL authority), the
+ * COMMAND it ran (the first code span, by its basename so a tool named by path is
+ * the same tool), or — for the rest — its leading words.
+ *
+ * Measured against the 40-note cache a real 21-task run left behind, where 34
+ * slots restate two facts: it resolves them to nine subjects, so the twelfth
+ * re-measurement of one database replaces the eleventh instead of joining it.
+ */
+export declare function deriveSubject(fact: string): string;
+/** One thing a child shared: a fact, or the retraction of one. */
+export interface EmittedNote {
+    subject: string;
+    fact: string;
+    /** The child observed this subject's recorded claim to be no longer true. */
+    resolved?: true;
+}
+/**
+ * Pull the facts out of a child's answer text. Three forms are accepted:
+ * `ENV-NOTE[<subject>]: <fact>` (what the instruction asks for), the bare
+ * `ENV-NOTE: <fact>` whose subject the host derives, and
+ * `ENV-NOTE-RESOLVED[<subject>]: <what was observed>`, which retracts a recorded
+ * claim. Facts are trimmed, deduped case-insensitively, and dropped when empty or
+ * over MAX_NOTE_LENGTH. A `VERDICT:` line and even a near-miss `ENV-NOTES:` line
  * match nothing, so a verdict cannot leak into the fact cache.
  */
-export declare function extractEnvNotes(text: string): string[];
+export declare function extractEnvNotes(text: string): EmittedNote[];
 /** True when a fact reads like a standing excuse (see EXCUSE_PATTERNS). */
 export declare function isExcuseNote(fact: string): boolean;
 /**
- * Append newly discovered facts to the cache, deduplicated against what is
- * already there (case-insensitive fact match), keeping the newest MAX_NOTES.
- * Each new fact is stamped with the `origin` task that recorded it; a fact already
- * present keeps its ORIGINAL origin, so provenance traces to whoever first
- * established it. Confirmed by re-appending the same fact under a different task:
- * one entry survives, still carrying the first writer.
+ * Store what a child shared, keyed by SUBJECT: a fresh statement about a subject
+ * REPLACES the one the cache held, so the newest measurement is the one later
+ * children read and a stale fact cannot outlive its correction. Each note is
+ * stamped with the `origin` task and the `runId` that recorded it — the run is
+ * what the prompt block scopes on, the task is the provenance a reader is told to
+ * re-validate against.
+ *
+ * A retraction stores the observation that closed the subject and marks it
+ * RESOLVED, so it stays as an audit line without being carried into another
+ * child's prompt.
  *
  * Tabs in an emitted fact are normalised to spaces before storage, which is what
  * keeps the separator unambiguous. The cap holds too — sixty further facts leave
  * MAX_NOTES stored. Failures are swallowed: the cache is a sharpener, never a
  * blocker.
  */
-export declare function appendEnvNotes(cwd: string, notes: string[], origin?: string): Promise<void>;
+export declare function appendEnvNotes(cwd: string, notes: readonly EmittedNote[], origin?: string, runId?: string): Promise<void>;
 /**
  * The prompt block a gate child receives when notes exist. Two things are
  * load-bearing: the no-waiver caveat (facts save re-discovery time but grant no
  * license to prepare/repair) and the trust discipline (a note is second-hand
  * until re-validated; an EXCUSE-CLASS note may not wave off a failure without a
  * live re-check; a grep of a generated artifact is not evidence of absence).
+ *
+ * THIS RUN leads. A fact measured by a sibling task minutes ago describes the tree
+ * the child is standing in; one from a run last week describes a tree that has
+ * moved since, and reading the two as one list is how a stale fact gets cited as
+ * current. Resolved subjects are dropped from both lists: a retracted claim is
+ * exactly the thing that must not be carried forward. `runId` '' (a cache written
+ * before runs were stamped) reads as an earlier run.
  */
-export declare function buildEnvNotesBlock(raw: string): string;
+export declare function buildEnvNotesBlock(raw: string, runId?: string): string;
 /** The emit instruction appended to bash-capable gate-child prompts. */
 export declare const ENV_NOTE_EMIT_INSTRUCTION: string;