@mjasnikovs/pi-task 0.40.50 → 0.42.0

package/dist/task/constraint-policy.d.ts

@@ -0,0 +1,52 @@
+/**
+ * constraint-policy — how much a constraint's PROVENANCE is worth, as one table
+ * both gate children render from.
+ *
+ * The verify child was told a spec constraint is unwaivable, full stop. The
+ * resolution judge was told to judge by function and treat over-literal wording
+ * as a false alarm. Neither was wrong on its own; together they made the gate's
+ * answer depend on which child happened to speak. 0043 is what that costs: a
+ * constraint a grill AUTO-ANSWER invented ("do NOT touch `test/ct/template/
+ * index.html`") was held as unwaivable as one the user typed, and the task failed
+ * on it.
+ *
+ * A constraint a human stated, or one the refined task carried in, BINDS. A
+ * constraint some automation produced — an auto-answer, a YOLO pick, an untagged
+ * line the composer wrote itself — is ADVISORY: it sharpens the work, and it
+ * fails a gate only when an ACCEPTANCE bullet also fails. Acceptance is the bar;
+ * an advisory constraint is a hint about how to clear it.
+ *
+ * One table, one renderer, two call sites (verify rule 4b, the judge's rules).
+ */
+import type { Constraint, ConstraintProvenance } from './spec-model.js';
+export type ConstraintWeight = 'binding' | 'advisory';
+/**
+ * What each provenance is worth. A new `ConstraintProvenance` member is a compile
+ * error until it declares its weight — which is the point, since the cheapest way
+ * back to 0043 is a new automated kind quietly defaulting to `binding`.
+ *
+ * `accepted` binds because a human read the recommendation and took it; `typed`
+ * and `host-set` for the same reason at either end (a person's own words, and a
+ * decision the host makes deterministically rather than leaving to a model).
+ * Everything else was produced by automation reasoning about the task, and
+ * automation may not mint an unwaivable rule.
+ */
+export declare const CONSTRAINT_WEIGHTS: Record<ConstraintProvenance, ConstraintWeight>;
+export declare function constraintWeight(provenance: ConstraintProvenance): ConstraintWeight;
+/** The weight marker a child sees on a constraint line, and probes match on. */
+export declare function weightTag(provenance: ConstraintProvenance): string;
+/** Does this collection of findings name at least one BINDING constraint? */
+export declare function anyBinding(findings: readonly string[]): boolean;
+/**
+ * The spec's CONSTRAINTS, annotated with each line's weight, for a child that
+ * must judge them. Returns null when the spec states none — the caller then emits
+ * no block rather than an empty heading.
+ */
+export declare function annotateConstraints(constraints: readonly Constraint[]): string | null;
+/**
+ * The policy, as prompt lines. ONE renderer: the verify pass and the resolution
+ * judge cite the same paragraph, so the two children cannot hold opposite
+ * policies again. `heading` differs because the two prompts number their rules
+ * differently — that is the only thing a call site may vary.
+ */
+export declare function renderConstraintPolicy(heading: string): string[];

package/dist/task/constraint-policy.js

@@ -0,0 +1,66 @@
+/**
+ * What each provenance is worth. A new `ConstraintProvenance` member is a compile
+ * error until it declares its weight — which is the point, since the cheapest way
+ * back to 0043 is a new automated kind quietly defaulting to `binding`.
+ *
+ * `accepted` binds because a human read the recommendation and took it; `typed`
+ * and `host-set` for the same reason at either end (a person's own words, and a
+ * decision the host makes deterministically rather than leaving to a model).
+ * Everything else was produced by automation reasoning about the task, and
+ * automation may not mint an unwaivable rule.
+ */
+export const CONSTRAINT_WEIGHTS = {
+    typed: 'binding',
+    'host-set': 'binding',
+    spec: 'binding',
+    accepted: 'binding',
+    auto: 'advisory',
+    yolo: 'advisory',
+    'yolo-skip': 'advisory',
+    'auto-resolved': 'advisory',
+    derived: 'advisory'
+};
+export function constraintWeight(provenance) {
+    return CONSTRAINT_WEIGHTS[provenance];
+}
+/** The weight marker a child sees on a constraint line, and probes match on. */
+export function weightTag(provenance) {
+    return `[${constraintWeight(provenance)}: ${provenance}]`;
+}
+/** Does this collection of findings name at least one BINDING constraint? */
+export function anyBinding(findings) {
+    return findings.some(f => f.includes('[binding:'));
+}
+/**
+ * The spec's CONSTRAINTS, annotated with each line's weight, for a child that
+ * must judge them. Returns null when the spec states none — the caller then emits
+ * no block rather than an empty heading.
+ */
+export function annotateConstraints(constraints) {
+    if (constraints.length === 0)
+        return null;
+    return constraints.map(c => `- ${c.text} ${weightTag(c.provenance)}`).join('\n');
+}
+/**
+ * The policy, as prompt lines. ONE renderer: the verify pass and the resolution
+ * judge cite the same paragraph, so the two children cannot hold opposite
+ * policies again. `heading` differs because the two prompts number their rules
+ * differently — that is the only thing a call site may vary.
+ */
+export function renderConstraintPolicy(heading) {
+    return [
+        `${heading} A CONSTRAINT IS WORTH ITS PROVENANCE. Each CONSTRAINTS line is tagged with`,
+        '   its weight and where it came from:',
+        `   - ${weightTag('typed')} / ${weightTag('spec')} — BINDING. A person stated it, or the`,
+        '     task itself carried it in. Shipped work that violates one is a FAIL naming the',
+        '     constraint; you have no waiver authority over it, and "it works anyway" is exactly',
+        '     the waiver you do not have.',
+        `   - ${weightTag('auto')} / ${weightTag('derived')} — ADVISORY. Automation produced it`,
+        '     (an auto-answered question, an unattended pick, a line the composer wrote itself),',
+        '     so it records intent, not a contract. A violated advisory constraint is a FAIL only',
+        '     when an ACCEPTANCE bullet ALSO fails; on its own it is a note in your report and',
+        '     the verdict stands on the acceptance criteria.',
+        '   ACCEPTANCE is the bar in both cases. Never soften a binding constraint, and never',
+        '   fail work solely for an advisory one.'
+    ];
+}

package/dist/task/context-silence.d.ts

@@ -7,10 +7,11 @@
  *
  * TWO SILENT SHAPES ARE LOSSES, and both are recognisable from the output alone:
  *
- *   LOOP_DEGRADE: the worker thrashed the same call until the loop-killer fired,
- *     leaving the degrade banner in place of a section. research-worker.ts writes
- *     that banner as "stuck in a loop — called <tool>(<args>) ×<n> in the last <m>
- *     calls…", which is the substring this keys on.
+ *   LOOP_DEGRADE: the worker thrashed until a runaway guard fired, leaving the
+ *     degrade banner in place of a section. research-worker.ts writes that banner
+ *     from `describeLoopHit` (loop-detector.ts) — "stuck in a loop — called
+ *     <tool>(<args>) …" or "stopped covering new ground — …" — which is what
+ *     LOOP_BANNER keys on.
  *
  *   GENERATION_GARBAGE: the worker exited 0 and emitted a non-bullet fragment
  *     instead of context — a stray sentence, or a hallucinated system note.

package/dist/task/context-silence.js

@@ -7,10 +7,11 @@
  *
  * TWO SILENT SHAPES ARE LOSSES, and both are recognisable from the output alone:
  *
- *   LOOP_DEGRADE: the worker thrashed the same call until the loop-killer fired,
- *     leaving the degrade banner in place of a section. research-worker.ts writes
- *     that banner as "stuck in a loop — called <tool>(<args>) ×<n> in the last <m>
- *     calls…", which is the substring this keys on.
+ *   LOOP_DEGRADE: the worker thrashed until a runaway guard fired, leaving the
+ *     degrade banner in place of a section. research-worker.ts writes that banner
+ *     from `describeLoopHit` (loop-detector.ts) — "stuck in a loop — called
+ *     <tool>(<args>) …" or "stopped covering new ground — …" — which is what
+ *     LOOP_BANNER keys on.
  *
  *   GENERATION_GARBAGE: the worker exited 0 and emitted a non-bullet fragment
  *     instead of context — a stray sentence, or a hallucinated system note.
@@ -26,7 +27,14 @@
 export function countBullets(contextText) {
     return contextText.split('\n').filter(l => /^\s*[-*]\s+/.test(l)).length;
 }
-const LOOP_BANNER = /stuck in a loop/i;
+/**
+ * The runaway-degrade banner, in either wording: an exact-repeat loop, or the
+ * progress rule that kills a worker for covering no new ground
+ * (loop-detector.ts `describeLoopHit`). Both are the same loss — a worker killed
+ * mid-answer — and keying on the loop phrase alone filed the second as a
+ * hallucinated fragment.
+ */
+const LOOP_BANNER = /stuck in a loop|stopped covering new ground|tokens of tool output/i;
 /** Honest "nothing to surface" — the ONLY non-loss silent shape. */
 const EMPTY_DECLARATION = /^\s*(none|n\/a|no relevant (context|architectural)|nothing\b)/i;
 /**

package/dist/task/coverage-loop.d.ts

@@ -28,8 +28,8 @@
  * noun, no web-app assumption. A CLI, a data pipeline, a library, a refactor, a
  * docs task all flow through the same integers.
  */
-/** A scored plan candidate — the minimum the adoption rule needs. */
 import type { CoverageAccounting } from './requirements.js';
+/** A scored plan candidate — the minimum the adoption rule needs. */
 export interface CoveragePlan {
     titles: string[];
     /**
@@ -80,6 +80,8 @@ export interface AdoptionDecision {
     reason: string;
     /** Owned-requirement indices the retry would drop (for the debug trail). */
     dropped: number[];
+    /** No further round can improve on the current plan — stop reprompting. */
+    terminal?: boolean;
 }
 /**
  * Whether a coverage-retry should REPLACE the current plan.
@@ -91,9 +93,10 @@ export interface AdoptionDecision {
  *      guarantee; it holds regardless of how the un-ownable requirements were
  *      classified, so it backstops the cross-cutting classifier completely.
  *   2b. WITH requirement signal: reject a retry that grows the plan while covering
- *      NOTHING new — the tiebreak that makes "ship the best" also mean "ship the
- *      smallest among equals". Without it the guard is inert against the superset
- *      the reprompt asks for; see the long note at the branch.
+ *      NOTHING new, and mark the loop TERMINAL — the tiebreak that makes "ship the
+ *      best" also mean "ship the smallest among equals". Without it the guard is
+ *      inert against the superset the reprompt asks for; see the long note at the
+ *      branch.
  *   3. WITHOUT requirement signal: fall back to the count floor, and additionally
  *      refuse a retry that leaves MORE areas uncovered than the current plan — so
  *      the no-requirements path also ships the best, not the last.

package/dist/task/coverage-loop.js

@@ -28,133 +28,7 @@
  * noun, no web-app assumption. A CLI, a data pipeline, a library, a refactor, a
  * docs task all flow through the same integers.
  */
-// Ubiquitous words that carry no coverage signal: they appear across most task
-// titles and requirement quotes, so overlap on them would falsely connect a
-// requirement to any plan. Stopped so grounding keys on the DISTINCTIVE nouns
-// (json, dead-letter, serialize, symlink…) that actually name a deliverable.
-//
-// Confirmed: titles built only from these words own NOTHING, while titles naming
-// `JSON output` and `dead-letter queue` own the matching requirements.
-//
-// English function words + generic task verbs + generic project nouns — all
-// domain-agnostic.
-const COVERAGE_STOPWORDS = new Set([
-    // function words
-    'the',
-    'a',
-    'an',
-    'and',
-    'or',
-    'of',
-    'to',
-    'in',
-    'on',
-    'for',
-    'with',
-    'by',
-    'at',
-    'as',
-    'is',
-    'are',
-    'be',
-    'it',
-    'its',
-    'that',
-    'this',
-    'from',
-    'into',
-    'out',
-    'up',
-    'per',
-    'via',
-    'not',
-    'no',
-    'but',
-    'if',
-    'then',
-    'than',
-    'so',
-    'such',
-    'each',
-    'any',
-    'all',
-    'every',
-    'when',
-    'where',
-    'must',
-    'should',
-    'shall',
-    'may',
-    'can',
-    'will',
-    'end',
-    'new',
-    // generic task verbs
-    'add',
-    'implement',
-    'create',
-    'build',
-    'scaffold',
-    'setup',
-    'set',
-    'support',
-    'handle',
-    'apply',
-    'use',
-    'used',
-    'using',
-    'make',
-    'makes',
-    'made',
-    'enable',
-    'provide',
-    'ensure',
-    'allow',
-    'run',
-    'runs',
-    'get',
-    'gets',
-    'define',
-    'configure',
-    'init',
-    'update',
-    'manage',
-    // generic project nouns
-    'cli',
-    'tool',
-    'app',
-    'application',
-    'project',
-    'feature',
-    'task',
-    'tasks',
-    'user',
-    'users',
-    'mode',
-    'flag',
-    'flags',
-    'option',
-    'options',
-    'system',
-    'code',
-    'thing',
-    'things',
-    'work'
-]);
-/** Distinctive content tokens of a phrase: lowercased alphanumeric words ≥3 chars,
- *  minus the ubiquitous stopwords. `--json` → `json`, `dead-letter` → `dead`,`letter`.
- *  A single trailing `s` is stripped (len ≥4) so `scan`/`scans`, `file`/`files`,
- *  `serialize`/`serializes` match — plain plural/3rd-person, no full stemmer. */
-function contentTokens(s) {
-    const out = new Set();
-    for (const raw of s.toLowerCase().split(/[^a-z0-9]+/)) {
-        if (raw.length < 3 || COVERAGE_STOPWORDS.has(raw))
-            continue;
-        const w = raw.length >= 4 && raw.endsWith('s') && !raw.endsWith('ss') ? raw.slice(0, -1) : raw;
-        out.add(w);
-    }
-    return out;
-}
+import { contentTokens } from '../shared/content-tokens.js';
 /**
  * DETERMINISTIC owned-set for the monotonic guard — grounded in requirement↔title
  * token overlap, NOT the coverage-map model's `TASK n` verdict.
@@ -224,9 +98,10 @@ export function droppedCoverage(current, retry) {
  *      guarantee; it holds regardless of how the un-ownable requirements were
  *      classified, so it backstops the cross-cutting classifier completely.
  *   2b. WITH requirement signal: reject a retry that grows the plan while covering
- *      NOTHING new — the tiebreak that makes "ship the best" also mean "ship the
- *      smallest among equals". Without it the guard is inert against the superset
- *      the reprompt asks for; see the long note at the branch.
+ *      NOTHING new, and mark the loop TERMINAL — the tiebreak that makes "ship the
+ *      best" also mean "ship the smallest among equals". Without it the guard is
+ *      inert against the superset the reprompt asks for; see the long note at the
+ *      branch.
  *   3. WITHOUT requirement signal: fall back to the count floor, and additionally
  *      refuse a retry that leaves MORE areas uncovered than the current plan — so
  *      the no-requirements path also ships the best, not the last.
@@ -265,23 +140,26 @@ export function decideAdoption(current, retry, hasRequirements) {
         // always adopted; an independently-sampled one often is not — the guard has
         // power, just not against the shape the prompt requests).
         //
-        // REJECT, never break. Rejection keeps the smaller plan and lets the loop
-        // reprompt again; breaking here forfeits a later round that would have
-        // gained: a later round can add the requirement a tied round did not. "No gain this round" is not "no gain ever".
+        // TERMINAL, not merely rejected. The reprompt asks for every title the
+        // previous list had PLUS the missing areas, so the next round is drawn from
+        // the same instruction that just produced a superset covering nothing new;
+        // "reject and ask again" spends the remaining rounds re-asking a question
+        // already answered. The measured shape is a plan inflating round after
+        // round with the owned-set pinned, every step logged as "preserves owned
+        // coverage".
         //
         // Safety is structural, not statistical: this branch is reachable only when
         // the retry covers NO MORE than the current plan, so it can never decline a
-        // strictly better one. It removes plans inflated by a retry that added
-        // titles without adding coverage, and leaves coverage itself alone — the
-        // win is removing pathological
-        // inflation, not shrinking plans generally.
+        // strictly better one — and the plan that ships is the current one, which is
+        // the best seen.
         if (retry.covered.size <= current.covered.size
             && retry.titles.length > current.titles.length) {
             return {
                 adopt: false,
                 reason: `no coverage gain for +${retry.titles.length - current.titles.length} titles `
                     + `(${current.covered.size} owned, unchanged)`,
-                dropped: []
+                dropped: [],
+                terminal: true
             };
         }
         return { adopt: true, reason: 'preserves owned coverage', dropped: [] };

package/dist/task/debug-log.d.ts

@@ -22,13 +22,36 @@ export declare function debugLogLevel(getEnv?: (k: string) => string | undefined
  *  `off` writes nothing, `full` writes both kinds, `events` writes events and
  *  drops stream. */
 export declare function shouldLogDebug(kind: DebugLine, level: DebugLogLevel): boolean;
+/**
+ * Longest line the trail keeps. A tool result the child pasted whole, a minified
+ * bundle, a base64 blob — one of them can be most of the file, and past a
+ * paragraph or so nothing is being explained any more. The overflow is reported
+ * rather than dropped silently, so a truncated line still says it was truncated.
+ */
+export declare const DEBUG_LINE_LIMIT = 4096;
+/**
+ * What actually reaches the file: control characters stripped, every line capped.
+ *
+ * One NUL makes the whole file BINARY to grep, and the trail's only job is to be
+ * grepped — a 1.7 MB `verify-debug.log` full of terminal control bytes needed
+ * `grep -a` before it could be read at all. Newlines are the exception and stay:
+ * a multi-line message stays multi-line, with the timestamp on its first line.
+ */
+export declare function sanitizeDebugLine(msg: string): string;
+/**
+ * Timestamp, sanitise and append one trail line, fire-and-forget. Errors are
+ * swallowed — an unwritable trail must never fail the run it is describing.
+ *
+ * An injected `appendFile` owns its own directory: a fake has none, and mkdir-ing
+ * a test's imaginary path would write to the real filesystem.
+ */
+export declare function appendDebugLine(logPath: string, msg: string, appendFile?: (p: string, data: string) => Promise<unknown>): void;
 /**
  * A timestamped fire-and-forget appender for one trail file, level-gated.
  *
  * `kind` defaults to `'event'` so a new call site is quiet-by-default in the
  * useful direction: forgetting to classify a marker keeps it in the audit trail,
- * whereas forgetting to classify chatter would only make the log bigger. Errors
- * are swallowed — an unwritable trail must never fail the run it is describing.
+ * whereas forgetting to classify chatter would only make the log bigger.
  */
 export declare function makeDebugAppender(logPath: string, appendFile?: (p: string, data: string) => Promise<unknown>): (msg: string, kind?: DebugLine) => void;
 /**

package/dist/task/debug-log.js

@@ -1,13 +1,15 @@
 /**
- * One place that decides whether a `.pi-tasks/*-debug.log` line gets written.
+ * One place that decides whether a `*-debug.log` line gets written, and what
+ * reaches the file when it does. The files live in the run's state directory
+ * (state-dir.ts), outside the repository.
  *
  * THE TRAIL IS WRITE-ONLY in production. Nothing under src/ reads these files
  * back: `task-io.ts` globs `TASK_NNNN.md` and skips everything else, and
- * auto-commit's `snapshotTrail` copies the bytes across a `reset --hard` without
- * ever parsing them. Every producer is a `logDebug?.(…)` / `log(…)` side effect
- * whose return value is discarded. So this gate cannot change what a run DOES —
- * only what it can explain afterwards. (Tests do read the trail back, which is why
- * `flushPlanDebug` exists.)
+ * auto-commit's `snapshotTrail` copies `.pi-tasks/` across a `reset --hard`
+ * without ever parsing it. Every producer is a `logDebug?.(…)` / `log(…)` side
+ * effect whose return value is discarded. So this gate cannot change what a run
+ * DOES — only what it can explain afterwards. (Tests do read the trail back,
+ * which is why `flushPlanDebug` exists.)
  *
  * TWO KINDS OF LINE, and the distinction is the whole point of having three levels
  * rather than a boolean:
@@ -30,6 +32,7 @@
  * A machine-local `"debugLogs": "off"` still wins — this is a default, not a floor.
  */
 import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
 import { getConfig, sanitizeDebugLogs } from '../config/config.js';
 /**
  * Escape hatch for reproducing a user's bug without walking them through
@@ -66,19 +69,70 @@ export function shouldLogDebug(kind, level) {
         return true;
     return kind === 'event';
 }
+/**
+ * Longest line the trail keeps. A tool result the child pasted whole, a minified
+ * bundle, a base64 blob — one of them can be most of the file, and past a
+ * paragraph or so nothing is being explained any more. The overflow is reported
+ * rather than dropped silently, so a truncated line still says it was truncated.
+ */
+export const DEBUG_LINE_LIMIT = 4096;
+const CONTROL_CHARS = /\p{Cc}/gu;
+function capLine(line) {
+    const over = line.length - DEBUG_LINE_LIMIT;
+    return over > 0 ? `${line.slice(0, DEBUG_LINE_LIMIT)}…+${over} chars` : line;
+}
+/**
+ * What actually reaches the file: control characters stripped, every line capped.
+ *
+ * One NUL makes the whole file BINARY to grep, and the trail's only job is to be
+ * grepped — a 1.7 MB `verify-debug.log` full of terminal control bytes needed
+ * `grep -a` before it could be read at all. Newlines are the exception and stay:
+ * a multi-line message stays multi-line, with the timestamp on its first line.
+ */
+export function sanitizeDebugLine(msg) {
+    return msg
+        .split('\n')
+        .map(line => capLine(line.replace(CONTROL_CHARS, '')))
+        .join('\n');
+}
+const ensuredDirs = new Map();
+/** A run's state directory does not exist until its first line — mkdir once per
+ *  directory rather than once per line. */
+function ensureDir(dir) {
+    let made = ensuredDirs.get(dir);
+    if (!made) {
+        made = fsp.mkdir(dir, { recursive: true }).catch(() => { });
+        ensuredDirs.set(dir, made);
+    }
+    return made;
+}
+async function appendToTrail(p, data) {
+    await ensureDir(path.dirname(p));
+    await fsp.appendFile(p, data);
+}
+/**
+ * Timestamp, sanitise and append one trail line, fire-and-forget. Errors are
+ * swallowed — an unwritable trail must never fail the run it is describing.
+ *
+ * An injected `appendFile` owns its own directory: a fake has none, and mkdir-ing
+ * a test's imaginary path would write to the real filesystem.
+ */
+export function appendDebugLine(logPath, msg, appendFile = appendToTrail) {
+    const line = `${new Date().toISOString()} ${sanitizeDebugLine(msg)}\n`;
+    void appendFile(logPath, line).catch(() => { });
+}
 /**
  * A timestamped fire-and-forget appender for one trail file, level-gated.
  *
  * `kind` defaults to `'event'` so a new call site is quiet-by-default in the
  * useful direction: forgetting to classify a marker keeps it in the audit trail,
- * whereas forgetting to classify chatter would only make the log bigger. Errors
- * are swallowed — an unwritable trail must never fail the run it is describing.
+ * whereas forgetting to classify chatter would only make the log bigger.
  */
-export function makeDebugAppender(logPath, appendFile = (p, data) => fsp.appendFile(p, data)) {
+export function makeDebugAppender(logPath, appendFile = appendToTrail) {
     return (msg, kind = 'event') => {
         if (!shouldLogDebug(kind, debugLogLevel()))
             return;
-        void appendFile(logPath, `${new Date().toISOString()} ${msg}\n`).catch(() => { });
+        appendDebugLine(logPath, msg, appendFile);
     };
 }
 /**

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

@@ -1,8 +1,16 @@
+import { type Block, type SpecDoc } from './spec-doc.js';
+export interface GroundedSource {
+    /** The citation as the model wrote it. */
+    quote: string;
+    /** The document block it grounded in — null when it matches only ACROSS block
+     *  boundaries (a model quoting two consecutive bullets as one line). */
+    block: Block | null;
+}
 export interface SourcedTitle {
     /** The title with every source clause stripped. */
     base: string;
     /** The cited spec lines, in order, keeping only those GROUNDED in the doc. */
-    sources: string[];
+    sources: GroundedSource[];
 }
 /**
  * Split a decompose title into its base and its GROUNDED source citations.
@@ -22,9 +30,9 @@ export interface SourcedTitle {
  * An absent clause yields no sources; a fabricated (ungrounded) one is dropped
  * — exactly like keepGroundedContracts rejects a paraphrased quote.
  */
-export declare function extractTitleSource(title: string, sourceDoc: string): SourcedTitle;
+export declare function extractTitleSource(title: string, sourceDoc: string | SpecDoc): SourcedTitle;
 /**
- * The `+`-joined trailing constraint fragments of `sourceLine` whose words are
+ * 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
@@ -32,8 +40,13 @@ export declare function extractTitleSource(title: string, sourceDoc: string): So
  * ("+ 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 declare function findDroppedPlusFragments(sourceLine: string, title: string): string[];
+export declare function findDroppedPlusFragments(source: Block | string, title: string): string[];
+/** 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 declare function renderFragments(fragments: string[]): string;
 export interface TitleRestoration {
     /** Index into the reconciled titles array. */
     index: number;